a6eb4da214
- .ai/ instruction set (root, behavior, skills, constraints) - apply.sh workflow documentation (apply.md) - architecture documentation (docs/architecture.md) - .github/copilot-instructions.md for VS Code auto-load - .gitignore (tmp/, .ai-instructions.conf)"
63 lines
2.8 KiB
Markdown
63 lines
2.8 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 and persists state in `.ai-instructions.conf` so repeat runs are fast and non-interactive.
|
|
|
|
## How apply.sh works
|
|
|
|
Run `apply.sh` from anywhere:
|
|
|
|
```bash
|
|
./ai-superpower/apply.sh
|
|
```
|
|
|
|
The script resolves dev root as its own parent directory. On first run it detects all projects and runs per-project setup. On subsequent runs it reads `.ai-instructions.conf` to skip projects already set up, making repeat runs fast.
|
|
|
|
## Project detection
|
|
|
|
The script recursively scans dev root for directories containing `.git`. `ai-superpower` itself is excluded. All found projects are presented as an interactive checklist — the developer selects which ones to apply to.
|
|
|
|
## Per-project actions
|
|
|
|
For each selected project, the script runs the project setup scripts:
|
|
|
|
1. Creates `.ai/` symlink → `ai-superpower/.ai/` if missing or broken
|
|
2. Adds `.ai` to the project's `.gitignore` if not already present
|
|
3. Checks for `docs/ai-context.md` — if missing, creates it from a template
|
|
4. Checks for `docs/architecture.md` — if missing, warns and offers to create one
|
|
|
|
## 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. Existing `docs/` files 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, run `apply.sh` — it detects the new project and includes it in the selection. 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?
|
|
|