diff --git a/src/agents/hephaestus/AGENTS.md b/src/agents/hephaestus/AGENTS.md
new file mode 100644
index 000000000..faf355d18
--- /dev/null
+++ b/src/agents/hephaestus/AGENTS.md
@@ -0,0 +1,34 @@
+# src/agents/hephaestus/ -- Autonomous Deep Worker
+
+**Generated:** 2026-04-11
+
+## OVERVIEW
+
+6 files. Hephaestus agent -- autonomous deep worker powered by GPT-5.4. Goal-oriented: give it objectives, not step-by-step instructions. "The Legitimate Craftsman."
+
+## FILES
+
+| File | Purpose |
+|------|---------|
+| `agent.ts` | `createHephaestusAgent()` factory, model-variant routing |
+| `gpt.ts` | Base GPT prompt: discipline rules, delegation, verification |
+| `gpt-5-4.ts` | GPT-5.4-native prompt with XML-tagged blocks, entropy-reduced |
+| `gpt-5-3-codex.ts` | GPT-5.3 Codex variant with task discipline sections |
+| `index.ts` | Barrel exports |
+
+## KEY BEHAVIORS
+
+- Mode: `primary` (respects UI model selection)
+- Requires OpenAI-compatible provider (no fallback chain)
+- NEVER trusts subagent self-reports -- always verifies
+- NEVER uses `background_cancel(all=true)`
+- Delegates exploration to background agents, never sequential
+- Uses `run_in_background=true` for explore/librarian
+
+## MODEL VARIANTS
+
+| Model | Prompt Source | Optimizations |
+|-------|-------------|---------------|
+| gpt-5.4 | `gpt-5-4.ts` | XML-tagged blocks, 8 sections |
+| gpt-5.3-codex | `gpt-5-3-codex.ts` | Task discipline, 549 LOC prompt |
+| Other GPT | `gpt.ts` | Base prompt, 507 LOC |
diff --git a/src/agents/prometheus/AGENTS.md b/src/agents/prometheus/AGENTS.md
new file mode 100644
index 000000000..63a81b818
--- /dev/null
+++ b/src/agents/prometheus/AGENTS.md
@@ -0,0 +1,37 @@
+# src/agents/prometheus/ -- Strategic Planner
+
+**Generated:** 2026-04-11
+
+## OVERVIEW
+
+11 files. Prometheus agent -- interview-mode strategic planner. Reads codebase, questions user, builds detailed work plan before any code is written. Markdown-only output (enforced by `prometheus-md-only` hook).
+
+## FILES
+
+| File | Purpose |
+|------|---------|
+| `system-prompt.ts` | Composes full system prompt from sections |
+| `identity-constraints.ts` | FORBIDDEN actions, .md-only enforcement, path restrictions |
+| `interview-mode.ts` | Interview flow: gather requirements, clarify scope |
+| `plan-generation.ts` | Plan output structure and validation |
+| `plan-template.ts` | YAML plan template with task graph, dependencies, waves |
+| `behavioral-summary.ts` | Behavioral guidelines section |
+| `high-accuracy-mode.ts` | Enhanced accuracy mode for complex plans |
+| `gemini.ts` | Gemini-optimized prompt variant |
+| `gpt.ts` | GPT-optimized prompt variant |
+| `index.ts` | Barrel exports |
+
+## KEY CONSTRAINTS
+
+- May ONLY create/edit `.md` files (enforced by hook)
+- FORBIDDEN paths: `src/`, `package.json`, config files
+- Must explore codebase before planning (NEVER plan blind)
+- Plans saved to `.sisyphus/plans/`
+- Acceptance criteria requiring "user manually tests" are FORBIDDEN
+
+## PLAN OUTPUT FORMAT
+
+Plans use YAML with parallel task graph:
+- Waves (parallel execution groups)
+- Tasks with dependencies, category, skills
+- Each task has atomic scope + verification criteria
diff --git a/src/agents/sisyphus/AGENTS.md b/src/agents/sisyphus/AGENTS.md
new file mode 100644
index 000000000..15bdae2de
--- /dev/null
+++ b/src/agents/sisyphus/AGENTS.md
@@ -0,0 +1,29 @@
+# src/agents/sisyphus/ -- Orchestrator Variants
+
+**Generated:** 2026-04-11
+
+## OVERVIEW
+
+4 files. Model-specific prompt variants for the Sisyphus main orchestrator. Parent `sisyphus.ts` routes to the correct variant based on active model.
+
+## FILES
+
+| File | Purpose |
+|------|---------|
+| `default.ts` | Base/Claude variant: task management, delegation guides, 542 LOC |
+| `gemini.ts` | Gemini-optimized: stricter tool-usage rules, 5 NEVER rules |
+| `gpt-5-4.ts` | GPT-5.4-native: 8-block architecture, entropy-reduced, 449 LOC |
+| `index.ts` | Barrel exports |
+
+## VARIANT SELECTION
+
+Parent `sisyphus.ts` selects variant by model name:
+- Contains "gemini" -> `gemini.ts`
+- Contains "gpt-5.4" -> `gpt-5-4.ts`
+- Default -> `default.ts` (Claude, Kimi, GLM, etc.)
+
+## KEY EXPORTS
+
+Each variant exports:
+- `buildTaskManagementSection()` -- todo/task management prompt
+- `buildSisyphusPrompt()` or equivalent -- full prompt builder
diff --git a/src/features/builtin-skills/AGENTS.md b/src/features/builtin-skills/AGENTS.md
new file mode 100644
index 000000000..93e883b5f
--- /dev/null
+++ b/src/features/builtin-skills/AGENTS.md
@@ -0,0 +1,50 @@
+# src/features/builtin-skills/ -- 8 Built-in Skills
+
+**Generated:** 2026-04-11
+
+## OVERVIEW
+
+24 files. 8 built-in skills registered via `createBuiltinSkills()`. Each skill implements `BuiltinSkill` interface with name, description, content, and optional MCP config.
+
+## STRUCTURE
+
+```
+builtin-skills/
+├── index.ts              # Barrel exports
+├── skills.ts             # createBuiltinSkills() factory
+├── types.ts              # BuiltinSkill interface
+├── git-master/           # SKILL.md + resources
+├── frontend-ui-ux/       # SKILL.md
+├── agent-browser/        # SKILL.md
+├── dev-browser/          # SKILL.md
+└── skills/               # Skill implementations as .ts files
+    ├── git-master-sections/  # Git master prompt sections
+    ├── playwright.ts         # Playwright + agent-browser + playwright-cli + dev-browser
+    ├── frontend-ui-ux.ts     # Frontend UI/UX skill
+    ├── review-work.ts        # 5-agent parallel review orchestrator
+    └── ai-slop-remover.ts    # AI code smell remover
+```
+
+## SKILL CATALOG
+
+| Skill | LOC | MCP | Purpose |
+|-------|-----|-----|---------|
+| **git-master** | 1111 | -- | Atomic commits, rebase, history search |
+| **playwright** | 312 | @playwright/mcp | Browser automation via MCP |
+| **playwright-cli** | 268 | -- | Browser automation via CLI |
+| **agent-browser** | (in playwright.ts) | -- | Browser via agent-browser tool |
+| **dev-browser** | 221 | -- | Persistent page state browser |
+| **frontend-ui-ux** | 79 | -- | Design-first UI development |
+| **review-work** | ~500 | -- | 5-agent post-implementation review |
+| **ai-slop-remover** | ~300 | -- | Remove AI code patterns |
+
+## BROWSER VARIANT SELECTION
+
+Config `browser_automation_engine` selects which browser skill loads:
+- `"playwright"` (default) -> playwright with @playwright/mcp
+- `"playwright-cli"` -> CLI-based playwright
+- `"agent-browser"` -> agent-browser tool
+
+## SKILL LOADING
+
+Skills loaded by `opencode-skill-loader` with priority: project > opencode > user > builtin. User-installed skills with same name override built-ins.