ai-superpower/docs/architecture.md

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.