172bfa78e9
Remove QUICK-REFERENCE.md from .ai/ — it contained kube-log project-specific content (hardcoded paths, OpenShift/ArgoCD config) that was leaking into all projects via the symlink. Update docs to match the actual apply.sh implementation: - apply.md: rewrite to reflect curl-only invocation, bootstrap/local phases, factory-reset marker behaviour; remove .ai-instructions.conf and interactive checklist references - architecture.md: remove scripts/ subdirectory and .ai-instructions.conf that were never implemented - apply-usecases.md: remove INSTALL subgraph (rm -rf + cp -r was never done), fix symlink targets to SCRIPT_DIR/.ai - apply-requirements.md: NFR-1 corrected (TTY-gated prompt exists), NFR-4 updated to <150 lines, .ai-instructions.conf removed from out-of-scope list
90 lines
5.1 KiB
Markdown
90 lines
5.1 KiB
Markdown
# Architecture
|
|
|
|
AI instructions live in one place. Every project symlinks to them — so a `git pull` here instantly updates all projects. This document describes how the parts fit together.
|
|
|
|
## Overview
|
|
|
|
```
|
|
dev_root/
|
|
├── ai-superpower/ ← this repo
|
|
│ ├── apply.sh ← single entry point
|
|
│ ├── templates/ ← ai-context.md and architecture.md templates
|
|
│ ├── .ai/ ← instruction source, symlinked from all projects
|
|
│ └── docs/ ← this project's own documentation
|
|
│
|
|
├── project-a/
|
|
│ ├── .ai/ ← symlink → ai-superpower/.ai/
|
|
│ └── docs/
|
|
│ └── ai-context.md ← project-specific, never overwritten once customised
|
|
│
|
|
└── some-folder/
|
|
└── project-b/ ← nested projects discovered automatically
|
|
└── .ai/
|
|
```
|
|
|
|
One entry point: `apply.sh`. It handles first-time setup and repair. Each project gets a symlink `project/.ai` → `ai-superpower/.ai/`. A `git pull` here updates all projects instantly — no re-run needed for content changes.
|
|
|
|
## Instruction loading
|
|
|
|
Instructions are not loaded automatically. The AI must be explicitly told to read `.ai/ai-root-instructions.md` — this is done via the editor's system prompt or custom instructions setting. Without that configuration, the `.ai/` folder has no effect.
|
|
|
|
**Acknowledgment** — every AI response must begin with `✅ ai-root-instructions.md READ`. This is the only mechanism to verify that the AI has actually read the file. If the acknowledgment is missing, the AI has not loaded the instructions for that response.
|
|
|
|
**Routing** — `ai-root-instructions.md` does not load all instruction files on every request. It routes to relevant files based on the task:
|
|
|
|
| Category | When loaded | Contents |
|
|
|---|---|---|
|
|
| `behavior/` | Always | How the AI approaches work: analysis before action, minimal changes, project context, required document structure |
|
|
| `skills/` | When relevant | Task-specific rules: git policy, file editing, documentation workflow, diagrams |
|
|
| `constraints/` | When relevant | Hard limits: what the AI cannot do, user responsibilities, debugging boundaries |
|
|
|
|
This modular structure keeps context small and focused. Loading all instruction files on every request would dilute attention and waste context window on irrelevant rules.
|
|
|
|
## How apply.sh works
|
|
|
|
`apply.sh` is a setup and repair tool, not a distribution tool. Content updates happen via `git pull` — the symlinks ensure all projects see the change immediately.
|
|
|
|
**Project discovery** — recursively scans dev root for `.git` directories up to 4 levels deep. Projects containing a `.ai-superpower` marker file are excluded — this identifies the ai-superpower repo itself regardless of directory name.
|
|
|
|
**Symlink creation** — creates `project/.ai` → `ai-superpower/.ai/` as an absolute symlink. If already correct, skipped silently. If broken or missing, recreated.
|
|
|
|
**Per-project docs setup** — handles context file setup directly in `apply.sh`:
|
|
1. If `docs/` is missing and stdin is a TTY: asks `[y/N]` before creating it
|
|
2. Creates `docs/ai-context.md` and `docs/architecture.md` from templates if missing
|
|
3. Refreshes template files if the factory-reset marker is still on line 1
|
|
4. Skips files that have been customised (marker absent)
|
|
|
|
## Per-project structure
|
|
|
|
After setup, each project has:
|
|
|
|
```
|
|
project-x/
|
|
├── .ai/ ← symlink → ai-superpower/.ai/
|
|
│ ├── ai-root-instructions.md
|
|
│ └── instructions/
|
|
│ ├── behavior/
|
|
│ ├── skills/
|
|
│ └── constraints/
|
|
└── docs/
|
|
├── ai-context.md ← created from template if missing
|
|
└── architecture.md ← created from template if missing
|
|
```
|
|
|
|
`.ai/` is a symlink — gitignored in target projects, pointing back to the single source in `ai-superpower`. `docs/` is committed and owned by the project team.
|
|
|
|
## Design decisions
|
|
|
|
**Symlinks over file copies** — one source of truth, no distribution step for content changes, no version drift across projects. `git pull` in `ai-superpower` instantly updates all projects.
|
|
|
|
**No projects.txt** — a manually maintained list goes stale. Discovering projects by `.git` presence is always accurate and requires no upkeep.
|
|
|
|
**One entry point** — `apply.sh` handles setup and repair for all projects. No configuration questions, no mode selection — it always creates symlinks.
|
|
|
|
**Bash over Python or Node** — no runtime to install, works on macOS, Linux, and Windows via WSL. The scripts do file operations and terminal interaction — bash is the right tool.
|
|
|
|
**`docs/ai-context.md` is never synced** — project-specific knowledge is owned by the project team, not this repo. Syncing it would overwrite work the team has done.
|
|
|
|
**`architecture.md` as a required document** — the setup script warns and offers to create it if missing. A project without an architecture document is a project where the AI cannot understand structure or decisions, and where humans will struggle too.
|
|
|