93b859f508
curl ... | bash -s -- --update pulls the latest .ai/ files and exits without scanning projects or touching docs templates. Bootstrap captures the pre-pull commit hash and forwards it to local mode; local mode compares with HEAD and either reports "already up to date" or prints new commit messages with git log --oneline. FR-1.5 added to apply-requirements.md. README and apply.md updated.
74 lines
3.6 KiB
Markdown
74 lines
3.6 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`, forwarding any flags.
|
|
|
|
**`--update` flag** — pass `--update` to skip all project setup and only pull the latest instructions:
|
|
|
|
```bash
|
|
curl -fsSL .../apply.sh | bash -s -- --update
|
|
```
|
|
|
|
The git pull still runs in bootstrap; local mode detects the flag at `$3`, prints the commit hash, and exits immediately. No projects are scanned, no docs touched.
|
|
|
|
**Local phase** — runs with `--bootstrapped` flag (without `--update`). 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?
|
|
|