172bfa78e9
Remove QUICK-REFERENCE.md from .ai/ — it contained kube-log project-specific content (hardcoded paths, OpenShift/ArgoCD config) that was leaking into all projects via the symlink. Update docs to match the actual apply.sh implementation: - apply.md: rewrite to reflect curl-only invocation, bootstrap/local phases, factory-reset marker behaviour; remove .ai-instructions.conf and interactive checklist references - architecture.md: remove scripts/ subdirectory and .ai-instructions.conf that were never implemented - apply-usecases.md: remove INSTALL subgraph (rm -rf + cp -r was never done), fix symlink targets to SCRIPT_DIR/.ai - apply-requirements.md: NFR-1 corrected (TTY-gated prompt exists), NFR-4 updated to <150 lines, .ai-instructions.conf removed from out-of-scope list
66 lines
3.2 KiB
Markdown
66 lines
3.2 KiB
Markdown
# apply.sh — how it works
|
|
|
|
How `apply.sh` sets up and maintains AI instructions across all projects. See [README.md](README.md) for context and [docs/architecture.md](docs/architecture.md) for design decisions.
|
|
|
|
## Design constraints
|
|
|
|
`.ai/` is a symlink in every project, pointing back to `ai-superpower/.ai/`. No files are copied. There are no manually maintained project lists. The script discovers projects automatically by scanning for `.git` directories. Every run is a full scan — idempotent and stateless.
|
|
|
|
## How apply.sh works
|
|
|
|
`apply.sh` **must be run via `curl | bash`** from the dev root. Direct invocation is blocked:
|
|
|
|
```bash
|
|
curl -fsSL https://gitea.nikos-dev.keskikuja.site/niko/ai-superpower/raw/branch/main/apply.sh | bash
|
|
```
|
|
|
|
**Bootstrap phase** — when piped through bash, `BASH_SOURCE[0]` is empty. The script uses this to detect the bootstrap context, then clones (or pulls) the repo and re-execs the local `apply.sh --bootstrapped DEV_ROOT`.
|
|
|
|
**Local phase** — runs with `--bootstrapped` flag. Scans dev root recursively for `.git` directories and runs per-project setup for each one found.
|
|
|
|
## Project detection
|
|
|
|
The script scans dev root recursively (`-maxdepth 4`) for directories containing `.git`. Any project with a `.ai-superpower` marker file in its root is excluded — this identifies the ai-superpower repo itself regardless of what the directory is named.
|
|
|
|
## Per-project actions
|
|
|
|
For each discovered project:
|
|
|
|
1. Creates `project/.ai` → `ai-superpower/.ai/` symlink if missing or broken
|
|
2. Appends `.ai` to `project/.gitignore` if not already present (creates the file if needed)
|
|
3. If `docs/` is missing and stdin is a TTY: asks `[y/N]` before creating it
|
|
4. Creates `docs/ai-context.md` from template if missing; refreshes if factory-reset marker is still on line 1
|
|
5. Creates `docs/architecture.md` from template if missing; refreshes if factory-reset marker is still on line 1
|
|
|
|
## Keeping instructions up to date
|
|
|
|
When instructions in this repo change, just pull:
|
|
|
|
```bash
|
|
cd ~/koodi/ai-superpower
|
|
git pull
|
|
```
|
|
|
|
Because `.ai/` is a symlink, all projects see the updated instructions immediately — no re-run of `apply.sh` needed. Run `apply.sh` only when adding new projects or repairing broken symlinks.
|
|
|
|
`apply.sh` is idempotent — safe to run as many times as needed. Customised `docs/` files (factory-reset marker absent) are never overwritten.
|
|
|
|
## Adding a new project
|
|
|
|
The project must be a git repository — `git init` must have been run first. Without a `.git` folder, `apply.sh` will not detect it.
|
|
|
|
Once initialised, re-run via `curl | bash` from the dev root — it detects the new project automatically. No other configuration needed.
|
|
|
|
## Project context (ai-context.md)
|
|
|
|
`docs/ai-context.md` is the AI's window into the project. The script creates a blank template if the file is missing, but the content must reflect the actual project.
|
|
|
|
Use the AI to create or update it. Open the project in your editor and prompt:
|
|
|
|
> Read the codebase and create `docs/ai-context.md`. Cover: what this project does, the technology stack, architecture overview, key decisions, and anything the AI needs to know to work here effectively.
|
|
|
|
For updates after significant changes:
|
|
|
|
> Review `docs/ai-context.md` against the current codebase. What is outdated or missing?
|
|
|