# ai-superpower — project context

## What this project does

Centralised AI instruction management for a developer who works across many projects. Instead of maintaining `.ai/` instructions per project, they live here and are distributed via symlinks. Each project gets a symlink `project/.ai → ai-superpower/.ai/`. A `git pull` here updates all projects instantly — no re-run of `apply.sh` needed for content changes.

`ai-superpower` must live directly in the dev root — the script uses its own location to determine where to look for projects.

Expected structure:

```
dev_root/
├── ai-superpower/       ← this repo, must be here
├── project-a/
├── project-b/
└── some-folder/
    ├── project-c/
    └── project-d/
```

The script scans dev root recursively for directories containing `.git`. `ai-superpower` itself is always excluded.

## Tech stack

- Bash — `apply.sh` is a single bash script, no dependencies beyond `git`, `bash`, `find`
- Markdown — all instruction files use `.instructions.md` format
- Git — version control for instructions; change history is first-class

## Key decisions

- **Symlinks over file copies** — one source of truth, no distribution step for content changes, no version drift
- **No projects.txt** — `apply.sh` discovers git projects automatically by scanning for `.git` dirs
- **`.ai/` in gitignore in target projects** — instructions are not owned by the target project. This repo is the exception: `.ai/` is the product and is committed here.
- **`docs/ai-context.md` and `docs/architecture.md` created from template** — `apply.sh` creates both if missing; templates contain inline instructions on how to fill them in
- **`docs/ai-context.md` is never overwritten** — project-specific context is the project team's responsibility
- **No harnesses** — no CLAUDE.md, AGENTS.md, .cursor/rules/; system prompt is the reliable mechanism
- **AI writes only with explicit instruction** — zero-trust output model; human reviews and owns everything

## How AI should work here

- Always read `.ai/ai-root-instructions.md` first and confirm with `✅ ai-root-instructions.md READ`
- Follow the documentation workflow in `skills/documentation.instructions.md` — abstract first, then section by section, stop and wait between sections
- Before any git operation, read `skills/git.instructions.md`
- When asked to create or update `docs/ai-context.md` in any project: read the codebase, infer what the project does, and draft — do not ask the user to fill in a template themselves
- Architecture changes require `docs/architecture.md` to be updated in the same commit