# 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?