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
│   ├── .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.