@apogeelabs/the-agency 0.8.0 → 0.10.0

package/README.md

@@ -1,82 +1,91 @@
 # @apogeelabs/the-agency
 
-Centralized Claude Code agents, commands, and workflows. Install once, sync to any project.
+A multi-agent development toolkit for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It gives your project a team of specialized AI agents — architect, developer, reviewer, test hardener, and more — that collaborate through the filesystem to take features from idea to implementation.
 
-## Install
+Install the package, sync the files, and your Claude Code sessions gain access to structured workflows that turn vague requirements into build plans and build plans into tested, review-ready code.
+
+## Quick Start
 
 ```bash
+# Install
 npm install -D @apogeelabs/the-agency
-```
-
-## Usage
 
-```bash
-# Sync all agents, commands, and AI context files to your project
+# Sync agents, commands, and AI context files into your project
 npx the-agency sync
 
-# Choose which files to sync
+# Or pick specific files to sync
 npx the-agency sync --pick
+```
 
-# Install optional review check plugins
-npx the-agency install-review-plugins
+This copies files into `.claude/agents/`, `.claude/commands/`, and `.ai/` in your project. You'll be prompted before overwriting existing files.
+
+## The Workflow
+
+The core workflow is a pipeline that moves from requirements to shipped code:
+
+```
+/pm  -->  product brief  -->  /architect  -->  build plan  -->  /build or /auto-build
 ```
 
-Files are copied to `.claude/agents/`, `.claude/commands/`, and `.ai/` in the target project. If destination files already exist, you'll be prompted before overwriting.
+- **`/pm`** — Interactive session that produces a product brief (`docs/briefs/[feature].md`)
+- **`/architect`** — Interactive session that produces a build plan (`docs/build-plans/[feature].md`)
+- **`/build`** — Orchestrates dev, review, and test agents with manual gates between stages
+- **`/auto-build`** — Fully autonomous pipeline: build, commit, and draft PR with no human intervention
+
+After a build completes, use **`/retrospective`** to consolidate lessons from pipeline reports into reusable patterns.
+
+Agents communicate only through the filesystem. No shared context windows. This is intentional — it forces each agent to write down its reasoning, which makes the whole pipeline auditable.
+
+See `.ai/workflow.md` after syncing for the full workflow guide.
 
 ## What's Included
 
 ### Agents (`.claude/agents/`)
 
-Autonomous subagents that run in isolated context windows and communicate through files.
+Autonomous subagents that run in isolated context windows.
 
 | Agent             | Purpose                                                    |
 | ----------------- | ---------------------------------------------------------- |
 | **architect**     | Designs technical approach, produces build plans           |
+| **auto-prep-pr**  | Non-interactive PR preparation and draft creation          |
 | **dev**           | Implements features from build plans, task by task         |
 | **explorer**      | Maps and documents unfamiliar codebases (read-only)        |
 | **pm**            | Produces product briefs from requirements                  |
+| **retrospective** | Extracts patterns from pipeline reports into retro files   |
 | **reviewer**      | Adversarial code review with pass/fail verdict (read-only) |
-| **test-hardener** | Writes edge case tests, tries to break things              |
+| **test-hardener** | Writes edge-case tests, tries to break things              |
 
 ### Commands (`.claude/commands/`)
 
 Slash commands invoked in Claude Code sessions.
 
-| Command           | Purpose                                            |
-| ----------------- | -------------------------------------------------- |
-| `/architect`      | Interactive architecture design session            |
-| `/build`          | Orchestrates the full dev → review → test pipeline |
-| `/pm`             | Interactive product requirements discovery         |
-| `/prep-pr`        | Pre-submission PR prep and draft creation          |
-| `/review-pr`      | Structured PR review briefing                      |
-| `/weekly-summary` | Weekly synthesis of merged PRs                     |
-| `/dnd-alignment`  | D&D alignment chart from commit history            |
+| Command           | Purpose                                                        |
+| ----------------- | -------------------------------------------------------------- |
+| `/architect`      | Interactive architecture design session                        |
+| `/auto-build`     | Fully autonomous build + commit + draft PR pipeline            |
+| `/auto-prep-pr`   | Non-interactive PR prep via auto-prep-pr agent                 |
+| `/build`          | Orchestrates the dev → review → test pipeline (manually-gated) |
+| `/pm`             | Interactive product requirements discovery                     |
+| `/prep-pr`        | Pre-submission PR prep and draft creation                      |
+| `/retrospective`  | Interactive consolidation of retro files into lessons-learned  |
+| `/review-pr`      | Structured PR review briefing                                  |
+| `/weekly-summary` | Weekly synthesis of merged PRs                                 |
+| `/dnd-alignment`  | D&D alignment chart from commit history                        |
 
 ### AI Context (`.ai/`)
 
 Reference material automatically available to Claude Code.
 
-| File                      | Purpose                                   |
-| ------------------------- | ----------------------------------------- |
-| **UnitTestGeneration.md** | TypeScript/Jest unit testing style guide  |
-| **UnitTestExamples.md**   | Working examples for the test style guide |
-| **workflow.md**           | Multi-agent development workflow guide    |
-
-## The Workflow
-
-```
-/pm → docs/briefs/[feature].md → /architect → docs/build-plans/[feature].md → /build
-```
-
-- **`/pm`** and **`/architect`** are interactive — back-and-forth conversations that produce documents
-- **`/build`** is autonomous — orchestrates dev, review, and test agents with automatic fix loops
-- Agents communicate only through the filesystem. No shared context. This is intentional.
-
-See `.ai/workflow.md` after syncing for the full workflow guide.
+| File                      | Purpose                                         |
+| ------------------------- | ----------------------------------------------- |
+| **UnitTestGeneration.md** | TypeScript/Jest unit testing style guide        |
+| **UnitTestExamples.md**   | Working examples for the test style guide       |
+| **workflow.md**           | Multi-agent development workflow guide          |
+| **lessons-learned.md**    | Accumulated lessons from retrospective analysis |
 
 ## Review Checks (`.ai/review-checks/`)
 
-The `/review-pr` command supports pluggable tribal knowledge checks. Place markdown files in `.ai/review-checks/` in your repo, and the review command discovers and evaluates them automatically.
+The `/review-pr` command supports pluggable tribal-knowledge checks. Place markdown files in `.ai/review-checks/` in your repo, and the review command discovers and evaluates them automatically.
 
 ### Check File Format
 
@@ -102,8 +111,6 @@ Install review plugins interactively:
 npx the-agency install-review-plugins
 ```
 
-This presents a multi-select of available plugins and copies your selections to `.ai/review-checks/`.
-
 | Plugin                | Targets                                             | Checks                                                                                               |
 | --------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
 | **react-frontend.md** | `.tsx`, `.jsx`, `.css`, `.scss`, `.styled.ts` files | Hard-coded colors, missing `data-cy` attributes, accessibility gaps                                  |
@@ -119,8 +126,8 @@ The sync does **not** copy `settings.local.json` or `settings.json` — those ar
 
 - Node.js >= 22
 - Claude Code
-- GitHub CLI (`gh`) — required for `/review-pr` and PR-related operations
+- GitHub CLI (`gh`) — required for `/review-pr`, `/prep-pr`, and PR-related operations
 
 ## Development
 
-See the [DEVELOP readme](./DEVELOP.md) for information on how to develop within this repo.
+See [DEVELOP.md](./DEVELOP.md) for setup, build, test, and publishing workflows.

package/dist/manifest.js

@@ -4,22 +4,43 @@ const manifest = {
     { file: "dev.md", description: "Implements features from build plans" },
     { file: "explorer.md", description: "Explores and maps unfamiliar codebases" },
     { file: "pm.md", description: "Produces product briefs from requirements" },
+    {
+      file: "auto-prep-pr.md",
+      description: "Non-interactive PR preparation and draft creation"
+    },
     { file: "reviewer.md", description: "Adversarial code review with pass/fail verdict" },
-    { file: "test-hardener.md", description: "Hardens test coverage, finds edge cases" }
+    { file: "test-hardener.md", description: "Hardens test coverage, finds edge cases" },
+    {
+      file: "retrospective.md",
+      description: "Extracts patterns from pipeline reports into per-feature retro files"
+    }
   ],
   commands: [
     { file: "architect.md", description: "Interactive architecture design sessions" },
-    { file: "build.md", description: "Build orchestrator pipeline" },
+    {
+      file: "auto-build.md",
+      description: "Fully autonomous build + commit + draft PR pipeline"
+    },
+    { file: "auto-prep-pr.md", description: "Non-interactive PR prep via auto-prep-pr agent" },
+    { file: "build.md", description: "Build orchestrator pipeline (manually-gated)" },
     { file: "pm.md", description: "Interactive product requirements discovery" },
     { file: "prep-pr.md", description: "Pre-submission PR prep and draft creation" },
     { file: "review-pr.md", description: "Structured PR review briefing" },
     { file: "weekly-summary.md", description: "Weekly synthesis of merged PRs" },
-    { file: "dnd-alignment.md", description: "D&D alignment chart from commit history" }
+    { file: "dnd-alignment.md", description: "D&D alignment chart from commit history" },
+    {
+      file: "retrospective.md",
+      description: "Interactive consolidation of retro files into lessons-learned"
+    }
   ],
   ai: [
     { file: "UnitTestGeneration.md", description: "TypeScript/Jest unit testing style guide" },
     { file: "UnitTestExamples.md", description: "Reference examples for the test style guide" },
-    { file: "workflow.md", description: "Multi-agent development workflow guide" }
+    { file: "workflow.md", description: "Multi-agent development workflow guide" },
+    {
+      file: "lessons-learned.md",
+      description: "Accumulated lessons from retrospective analysis"
+    }
   ],
   reviewPlugins: [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apogeelabs/the-agency",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Centralized Claude Code agents, commands, and workflows",
   "type": "module",
   "bin": {

package/src/templates/.ai/UnitTestGeneration.md

@@ -10,9 +10,9 @@ Before generating any tests, complete these steps in order:
 
 1. **Branch analysis** (Coverage-Driven Test Planning): Read the source, enumerate every branch, map each to a test scenario.
 2. **Superfluous test check** (Superfluous Test Prevention): Verify each planned scenario covers a distinct branch, not the same branch with different values.
-3. **Execution location check** (CRITICAL RULE #1): Execute methods under test in `beforeEach()`, not in `it()` blocks.
-4. **Mock configuration check** (CRITICAL RULE #2): Configure mock behavior in `beforeEach`, not at module level.
-5. **Callback invocation check** (CRITICAL RULE #3): Use `mockImplementation` for callbacks, not `mock.calls[N][M]()`.
+3. **Execution location check** (CRITICAL RULE 1): Execute methods under test in `beforeEach()`, not in `it()` blocks.
+4. **Mock configuration check** (CRITICAL RULE 2): Configure mock behavior in `beforeEach`, not at module level.
+5. **Callback invocation check** (CRITICAL RULE 3): Use `mockImplementation` for callbacks, not `mock.calls[N][M]()`.
 
 Once tests are generated:
 
@@ -21,7 +21,7 @@ Once tests are generated:
 
 ---
 
-## CRITICAL RULE #1: Test Execution Location
+## CRITICAL RULE 1: Test Execution Location
 
 ⚠️ **NON-NEGOTIABLE RULE** ⚠️
 
@@ -97,7 +97,7 @@ Before writing any test suite, verify:
 
 ---
 
-## CRITICAL RULE #2: Mock Configuration Location
+## CRITICAL RULE 2: Mock Configuration Location
 
 ⚠️ **NON-NEGOTIABLE RULE** ⚠️
 
@@ -152,7 +152,7 @@ const mockLuxon = {
 
 ---
 
-## CRITICAL RULE #3: Callback Invocation via mockImplementation
+## CRITICAL RULE 3: Callback Invocation via mockImplementation
 
 ⚠️ **NON-NEGOTIABLE RULE** ⚠️
 
@@ -329,7 +329,7 @@ describe("when status is inactive", () => {
     - Inner `describe` blocks handle specific scenarios ("when X condition")
 - **Test descriptions**:
     - `describe` blocks handle the "when" conditions/scenarios
-    - `it` blocks focus purely on "should" assertions (no conditions). See **CRITICAL RULE #1** above.
+    - `it` blocks focus purely on "should" assertions (no conditions). See **CRITICAL RULE 1** above.
     - Avoid redundancy - don't repeat conditions in both `describe` and `it`
 - **Grouping logic**:
     - Group related test cases under shared setup scenarios
@@ -366,7 +366,7 @@ describe("when status is inactive", () => {
 - **State initialization**: Variables initialized in `beforeEach`
 - **Fresh state guarantee**:
     - Call `jest.clearAllMocks()` and `jest.resetModules()` in outer `beforeEach`
-    - **Do NOT use `jest.resetAllMocks()`** in the outer `beforeEach` — it wipes implementations, which breaks module-level `mockReturnThis()` chains (see CRITICAL RULE #2 exception)
+    - **Do NOT use `jest.resetAllMocks()`** in the outer `beforeEach` — it wipes implementations, which breaks module-level `mockReturnThis()` chains (see CRITICAL RULE 2 exception)
     - Use `mockReset()` on **individual mocks** when a nested `beforeEach` needs to replace behavior already configured by an outer `beforeEach`
     - **Never use `mockRestore()`** — it only applies to `jest.spyOn`, which this codebase does not use
 
@@ -385,14 +385,14 @@ Am I in the **outer** `beforeEach`?
 
 ## Mocking Strategy
 
-- **Module-level mock declarations**: Dependencies mocked above test suites with bare `jest.fn()` — see **CRITICAL RULE #2** for configuration rules
+- **Module-level mock declarations**: Dependencies mocked above test suites with bare `jest.fn()` — see **CRITICAL RULE 2** for configuration rules
 - **Mock behavior configuration**: Configured per scenario in `beforeEach` blocks
 - **Mock naming**: Consistent mock prefix (e.g., `mockLogger`, `mockGetMessageBroker`)
 - **Selective mocking**: Mock only the methods being used unless it significantly raises complexity
 - **Mock verification**: Always verify mock calls when behavior depends on them
 - **Mock realism**: Ensure mocks behave like real implementations (same async patterns, error types)
 - **Mock methods**:
-    - Use `mockImplementation` when invoking callbacks passed to the mocked function — see **CRITICAL RULE #3**
+    - Use `mockImplementation` when invoking callbacks passed to the mocked function — see **CRITICAL RULE 3**
     - Use `mockResolvedValue` for async returns
     - Use `mockReturnValue` for sync returns
     - Prefer "Once" versions when appropriate (`mockResolvedValueOnce`, etc.)

package/src/templates/.ai/lessons-learned.md

@@ -0,0 +1,9 @@
+# Lessons Learned
+
+## Review Patterns
+
+## Common Fix Loop Triggers
+
+## Test Coverage Priorities
+
+## Code Patterns

package/src/templates/.ai/workflow.md

@@ -34,30 +34,46 @@ mkdir -p docs/{briefs,build-plans,reports}
                    (handoff via files)
                             │
 ┌─────────────────────────────────────────────────────────────────┐
-│  AUTONOMOUS AGENTS (isolated context, file-based communication) │
+│  BUILD PIPELINE (choose your level of autonomy)                 │
 │                                                                 │
-│  These are the SAME PERSONAS as above, but autonomous.          │
-│  Use when you trust the output pattern.                         │
+│  /build       ──→  manual gates between phases                  │
+│  /auto-build  ──→  fully autonomous: build + commit + draft PR  │
 │                                                                 │
-│  pm agent  ──→  docs/briefs/feature.md                          │
-│  architect agent  ──→  docs/build-plans/feature.md              │
+│  Both orchestrate the same agent pipeline:                      │
 │                                                                 │
-│  ┌──────────┐   ┌──────────┐   ┌──────────┐                   │
-│  │ dev      │──→│ reviewer  │──→│ test-    │                   │
-│  │ agent    │   │ agent     │   │ hardener │                   │
-│  │          │   │           │   │ agent    │                   │
-│  │ Writes   │   │ Read-only │   │ Writes   │                   │
-│  │ code +   │   │ review    │   │ tests    │                   │
-│  │ tests    │   │           │   │ only     │                   │
-│  └────┬─────┘   └────┬─────┘   └────┬─────┘                   │
+│  ┌──────────┐   ┌───────────┐   ┌──────────┐                    │
+│  │ dev      │──→│ reviewer  │──→│ test-    │                    │
+│  │ agent    │   │ agent     │   │ hardener │                    │
+│  │          │   │           │   │ agent    │                    │
+│  │ Writes   │   │ Read-only │   │ Writes   │                    │
+│  │ code +   │   │ review    │   │ tests    │                    │
+│  │ tests    │   │           │   │ only     │                    │
+│  └────┬─────┘   └────┬──────┘   └────┬─────┘                    │
 │       ▼              ▼              ▼                           │
 │   dev-report    review-report   test-report                     │
 │                                                                 │
-│   ◄── fix loops if review/test fail ──►                        │
+│   ◄── fix loops if review/test fail ──►                         │
+│                                                                 │
+│  /auto-build also runs:                                         │
+│  auto-prep-pr agent  ──→  pushes branch + creates draft PR      │
+└─────────────────────────────────────────────────────────────────┘
+                            │
+                   (reports land in docs/reports/)
+                            │
+┌─────────────────────────────────────────────────────────────────┐
+│  STANDALONE AGENTS & COMMANDS                                   │
 │                                                                 │
+│  pm agent  ──→  docs/briefs/feature.md                          │
+│  architect agent  ──→  docs/build-plans/feature.md              │
 │  explorer agent  ──→  docs/codebase-map.md                      │
+│  auto-prep-pr agent  ──→  pushes branch + creates draft PR      │
+│  retrospective agent  ──→  .ai/retro/retro-[feature].md         │
 │                                                                 │
-│  /build  ──→  orchestrates: dev → review → test                 │
+│  /retrospective  ──→  consolidates retros into lessons-learned  │
+│  /prep-pr        ──→  interactive PR prep and draft creation    │
+│  /auto-prep-pr   ──→  non-interactive PR prep via agent         │
+│  /review-pr      ──→  structured PR review briefing             │
+│  /weekly-summary ──→  weekly synthesis of merged PRs            │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
@@ -65,24 +81,33 @@ mkdir -p docs/{briefs,build-plans,reports}
 
 ### Interactive Commands (`.claude/commands/`)
 
-| Command      | What it does                              | Entry point for             |
-| ------------ | ----------------------------------------- | --------------------------- |
-| `/pm`        | Collaborative requirements discovery      | Defining what to build      |
-| `/architect` | Collaborative technical design            | Designing how to build it   |
-| `/build`     | Orchestrates the agent execution pipeline | Running dev → review → test |
+| Command           | What it does                                       | Entry point for                   |
+| ----------------- | -------------------------------------------------- | --------------------------------- |
+| `/pm`             | Collaborative requirements discovery               | Defining what to build            |
+| `/architect`      | Collaborative technical design                     | Designing how to build it         |
+| `/build`          | Orchestrates dev → review → test with manual gates | Controlled pipeline execution     |
+| `/auto-build`     | Fully autonomous build + commit + draft PR         | Hands-off pipeline execution      |
+| `/prep-pr`        | Interactive PR prep and draft creation             | Getting a branch ready for review |
+| `/auto-prep-pr`   | Non-interactive PR prep via auto-prep-pr agent     | Automated PR creation             |
+| `/review-pr`      | Structured PR review briefing                      | Reviewing an open PR              |
+| `/retrospective`  | Consolidates retro files into lessons-learned      | Learning from pipeline runs       |
+| `/weekly-summary` | Weekly synthesis of merged PRs                     | Team status updates               |
+| `/dnd-alignment`  | D&D alignment chart from commit history            | Fun                               |
 
 ### Autonomous Agents (`.claude/agents/`)
 
-| Agent           | Tools                               | Context  | What it does                                   |
-| --------------- | ----------------------------------- | -------- | ---------------------------------------------- |
-| `pm`            | Read, Write, Edit, Glob, Grep       | Isolated | Drafts a product brief from notes              |
-| `architect`     | Read, Write, Edit, Glob, Grep, Bash | Isolated | Drafts a build plan from a brief or notes      |
-| `dev`           | Read, Write, Edit, Glob, Grep, Bash | Isolated | Implements build plan, writes happy-path tests |
-| `reviewer`      | Read, Glob, Grep, Bash              | Isolated | Read-only code review, produces verdict        |
-| `test-hardener` | Read, Write, Edit, Glob, Grep, Bash | Isolated | Writes edge case & failure mode tests          |
-| `explorer`      | Read, Glob, Grep, Bash              | Isolated | Maps and documents the codebase (read-only)    |
+| Agent           | Tools                               | Context  | What it does                                      |
+| --------------- | ----------------------------------- | -------- | ------------------------------------------------- |
+| `pm`            | Read, Write, Edit, Glob, Grep       | Isolated | Drafts a product brief from notes                 |
+| `architect`     | Read, Write, Edit, Glob, Grep, Bash | Isolated | Drafts a build plan from a brief or notes         |
+| `dev`           | Read, Write, Edit, Glob, Grep, Bash | Isolated | Implements build plan, writes happy-path tests    |
+| `reviewer`      | Read, Glob, Grep, Bash              | Isolated | Read-only code review, produces verdict           |
+| `test-hardener` | Read, Write, Edit, Glob, Grep, Bash | Isolated | Writes edge case & failure mode tests             |
+| `explorer`      | Read, Glob, Grep, Bash              | Isolated | Maps and documents the codebase (read-only)       |
+| `auto-prep-pr`  | Read, Glob, Grep, Bash              | Isolated | Pushes branch, creates draft PR (non-interactive) |
+| `retrospective` | Read, Write, Glob, Bash             | Isolated | Extracts patterns from reports into retro files   |
 
-Note: `reviewer` and `explorer` are deliberately read-only — they can't modify project code.
+Note: `reviewer`, `explorer`, and `auto-prep-pr` are deliberately read-only — they can't modify project code.
 
 ## Workflows
 
@@ -101,7 +126,7 @@ claude> /architect
 # ... back-and-forth until plan is right
 # Output: docs/build-plans/feature.md
 
-# Session 3: Execute the pipeline
+# Session 3: Execute the pipeline with manual gates
 claude> /build
 # ... confirms once, then runs dev → review → test automatically
 # ... only stops if fix loops are exhausted
@@ -126,15 +151,16 @@ claude> /build
 
 ### Full Autonomous (Trust the Pipeline)
 
-When you've done this enough to trust the drafts:
+When you've done this enough to trust the whole thing:
 
 ```bash
 # Autonomous brief and plan
 claude> Use the pm agent to draft a brief, then the architect agent to create a build plan
 # Review both docs, edit if needed
 
-# Execute
-claude> /build
+# Fully autonomous: build, commit, and draft PR
+claude> /auto-build
+# You get a draft PR at the end, or a failure report
 ```
 
 ### CTO-Hands-You-a-Napkin
@@ -165,15 +191,32 @@ claude> /build
 claude> Use the reviewer agent to review the auth module changes
 ```
 
+### Post-Build: Learn From What Happened
+
+After one or more builds complete, extract patterns and build institutional memory:
+
+```bash
+# Step 1: Extract patterns from pipeline reports (per feature)
+claude> Use the retrospective agent for the user-auth feature
+# Output: .ai/retro/retro-user-auth.md
+
+# Step 2: Consolidate retros into shared lessons (interactive)
+claude> /retrospective
+# ... walk through findings, decide what to keep
+# Output: .ai/lessons-learned.md
+```
+
 ## How Fix Loops Work
 
-The `/build` orchestrator handles failures:
+The `/build` and `/auto-build` orchestrators handle failures:
 
 1. **Review fails** (🔴) → extracts must-fix items → fresh dev agent reads only the fixes file → commits fixes → re-runs review → max 2 loops
 2. **Test hardening fails** (🐛) → same pattern for bugs
 
 The user approves once at the start of the pipeline. After that, fix loops run automatically, capped at 2 per phase. The only mid-pipeline interruption is escalation when a fix loop is exhausted.
 
+With `/auto-build`, there is no mid-pipeline interruption at all — if fix loops are exhausted, it stops and writes a failure report.
+
 ## Git Workflow
 
 The pipeline manages git automatically:
@@ -183,6 +226,7 @@ The pipeline manages git automatically:
 3. **Test hardener** commits its new test files (`test:` prefix)
 4. **Fix loop commits** use `fix:` prefix and reference what was fixed
 5. **Orchestrator** commits reports at the end (`docs:` prefix)
+6. **`/auto-build` only**: auto-prep-pr agent pushes the branch and creates a draft PR
 
 The result is a branch with clean, atomic, per-task commits:
 
@@ -197,7 +241,7 @@ b4c5d6e DEV-2315 Add login endpoint with validation
 7f8e9d0 DEV-2315 Add user model and migration
 ```
 
-At completion, the orchestrator gives you the branch name and commit history. You choose how to land it — merge, squash, open a PR, whatever fits your workflow.
+At completion, the orchestrator gives you the branch name and commit history. With `/build`, you choose how to land it. With `/auto-build`, a draft PR is already waiting.
 
 ⚠️ **Protected branches**: The dev agent verifies it's on a feature branch before every commit. If it somehow finds itself on `main`/`master`/`develop`, it stops and reports the error rather than committing.
 
@@ -212,28 +256,43 @@ docs/reports/
   ├── review-report-[feature].md  ← Review agent output
   ├── review-fixes-[feature].md   ← Fix loop items (if triggered)
   └── test-report-[feature].md    ← Test agent output
+
+.ai/retro/retro-[feature].md      ← Retrospective agent output
+.ai/lessons-learned.md             ← /retrospective consolidation output
 ```
 
 ## Directory Structure
 
 ```
 .claude/
-├── commands/                # Interactive slash commands
+├── commands/                # Slash commands
 │   ├── pm.md               # /pm → conversational requirements
 │   ├── architect.md         # /architect → conversational design
-│   └── build.md             # /build → pipeline orchestrator
+│   ├── build.md             # /build → pipeline orchestrator (manual gates)
+│   ├── auto-build.md        # /auto-build → fully autonomous pipeline
+│   ├── prep-pr.md           # /prep-pr → interactive PR prep
+│   ├── auto-prep-pr.md      # /auto-prep-pr → non-interactive PR prep
+│   ├── review-pr.md         # /review-pr → PR review briefing
+│   ├── retrospective.md     # /retrospective → consolidate retros
+│   ├── weekly-summary.md    # /weekly-summary → merged PR synthesis
+│   └── dnd-alignment.md     # /dnd-alignment → commit alignment chart
 └── agents/                  # Autonomous subagents (isolated context)
     ├── pm.md                # Brief drafting
     ├── architect.md         # Build plan drafting
     ├── dev.md               # Implementation
     ├── reviewer.md          # Code review (read-only)
     ├── test-hardener.md     # Test hardening
-    └── explorer.md          # Codebase mapping (read-only)
+    ├── explorer.md          # Codebase mapping (read-only)
+    ├── auto-prep-pr.md      # PR creation (read-only)
+    └── retrospective.md     # Pattern extraction from reports
 
 .ai/
 ├── UnitTestGeneration.md    # Testing style guide
 ├── UnitTestExamples.md      # Testing examples
-└── workflow.md              # This file
+├── workflow.md              # This file
+├── lessons-learned.md       # Accumulated lessons from retrospectives
+└── retro/                   # Per-feature retrospective files
+    └── retro-[feature].md   # Output of retrospective agent
 
 docs/
 ├── briefs/                  # PM outputs
@@ -257,6 +316,8 @@ Use **autonomous agents** when:
 - You want a first draft to react to rather than building from scratch
 - You've used the interactive versions enough to know what good output looks like
 
+Use **`/build`** when you want manual gates between phases. Use **`/auto-build`** when you trust the pipeline end-to-end and want a draft PR at the finish line.
+
 ## Customization
 
 ### Things Worth Tuning
@@ -265,13 +326,14 @@ Use **autonomous agents** when:
 - **Review criteria** in `agents/reviewer.md` — tune must-fix vs. consider thresholds
 - **Test priorities** in `agents/test-hardener.md` — focus on your domain's risk areas
 - **Build plan template** in architect files — swap in your team's RFC/ADR format
-- **Fix loop cap** in `commands/build.md` — default is 2, adjust to taste
+- **Fix loop cap** in `commands/build.md` and `commands/auto-build.md` — default is 2, adjust to taste
 - **Model selection** in agent frontmatter — default is `sonnet`, bump to `opus` for critical phases
 
 ### Agent Tool Access
 
 Tools are intentionally restricted per agent:
 
-- `reviewer` and `explorer` are **read-only** (no Write/Edit) — they observe and report
+- `reviewer`, `explorer`, and `auto-prep-pr` are **read-only** (no Write/Edit) — they observe and report
 - `dev` and `test-hardener` have full access — they need to create and modify files
+- `retrospective` can write to `.ai/retro/` only
 - Adjust in the YAML frontmatter `tools:` field

package/src/templates/.claude/agents/architect.md

@@ -61,6 +61,12 @@ High-level description of the approach. 2-3 paragraphs max.
     - **Trade-off**: [What we're giving up]
     - **Assumption**: [If this decision rests on an assumption, flag it]
 
+## Scope Contract
+
+- **In scope**: [packages/dirs/layers that are fair game for this feature]
+- **Out of scope**: [packages/dirs/layers that must NOT be touched — e.g., core packages, unrelated modules]
+- **New dependencies**: [allowed / must be approved / none]
+
 ## Existing Patterns to Follow
 
 Patterns, conventions, or utilities already in the codebase that this feature should use.