a6eb4da214
- .ai/ instruction set (root, behavior, skills, constraints) - apply.sh workflow documentation (apply.md) - architecture documentation (docs/architecture.md) - .github/copilot-instructions.md for VS Code auto-load - .gitignore (tmp/, .ai-instructions.conf)"
44 lines
2.3 KiB
Markdown
44 lines
2.3 KiB
Markdown
# 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
|