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

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:

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:

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?