ai-superpower/apply.md

apply.sh — how it works

How apply.sh sets up and maintains AI instructions across all projects. See README.md for context and 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:

./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:

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?