ai-superpower/docs/ai-context.md

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