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)"
95 lines
5.5 KiB
Markdown
95 lines
5.5 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
|
|
│ ├── .ai-instructions.conf ← managed by apply.sh, gitignored
|
|
│ ├── scripts/
|
|
│ │ ├── setup-project.sh ← creates ai-context.md + architecture.md
|
|
│ │ └── symlink-ai.sh ← creates .ai/ symlink in target project
|
|
│ ├── .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 synced
|
|
│
|
|
└── 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. `ai-superpower` itself is always excluded. All found projects, including nested ones, receive a symlink.
|
|
|
|
**`scripts/symlink-ai.sh`** — creates `project/.ai` → `ai-superpower/.ai/` as an absolute symlink. If `.ai/` already exists and is a valid symlink, it is left untouched. If it is broken or missing, it is (re)created.
|
|
|
|
**`scripts/setup-project.sh`** — handles per-project context setup:
|
|
1. Creates `docs/ai-context.md` from template if missing
|
|
2. Checks for `docs/architecture.md` — warns and offers to create if missing
|
|
|
|
**`.ai-instructions.conf`** — written and maintained by `apply.sh`. Lives inside this repo, gitignored. Stores which projects have been set up. Treated as a runtime log — the developer does not edit it.
|
|
|
|
## 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 by setup-project.sh if missing
|
|
└── architecture.md ← created if developer confirms
|
|
```
|
|
|
|
`.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.
|
|
|
|
**`.ai-instructions.conf` as a runtime artifact** — the script maintains this file like a log. Lives inside this repo but is gitignored — it is personal to the developer and not shared with others who clone this repo.
|
|
|
|
**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.
|
|
|