99d13e6e4a
- apply.sh: direct-run guard (only curl | bash allowed) - apply.sh: DEV_ROOT passed as explicit arg from bootstrap - apply.sh: .ai/ copied to dev root as real folder; projects symlink there - apply.sh: counters + detailed summary (version prev→new, templated, refreshed, no-docs) - apply.sh: find errors silenced, no crash on empty dev root - .ai-superpower: added warning comment about deletion side effects - .gitignore: .ai-instructions.conf → .ai-superpower.version - scripts/: removed (hello.sh, scan-projects-with-git.sh, verify-docs-folder.sh, add-ai-context-to-docs-folder.sh) - templates: monorepo sections split into AI instructions + developer instructions - README.md: rewritten to match current architecture and behaviour - docs/apply-requirements.md: FR-2.4, FR-3, FR-5, FR-6, FR-7, FR-8 updated - docs/apply-usecases.md: full detailed Mermaid flowchart replacing placeholder
46 lines
2.6 KiB
Markdown
46 lines
2.6 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 `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
|