# 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.