# 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 to the generic instructions; project-specific knowledge stays in that project's own `docs/ai-context.md`.

`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 — `sync.sh` is plain bash, no dependencies
- Markdown — all instruction files use `.instructions.md` format
- Git — version control for instructions; change history is first-class

## Key decisions

- **Plain file copy over git submodules** — keeps project repos simple, no cross-repo plumbing
- **No projects.txt** — sync discovers git projects automatically by scanning for `.git` dirs in the dev root
- **`.ai/` in gitignore in target projects** — instructions are not owned by the target project, they are distributed to it. This repo is the exception: `.ai/` is the product and is committed here.
- **`docs/ai-context.md` is never synced** — project-specific context is the project team's responsibility
- **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