@a-canary/pi-director 0.1.0

package/.pi/corrections.jsonl

@@ -0,0 +1,3 @@
+{"timestamp":"2026-03-17T14:57:22.799Z","failure":"Used \"aaron\" as author name in package.json instead of \"a-canary\" github username","correction":"Always use \"a-canary\" as author name — it's the github username for all packages","tokens_wasted":500,"source":"user","strength":"strong"}
+{"timestamp":"2026-03-17T15:10:39.460Z","failure":"Renumbered CHOICES.md IDs sequentially when adding new choices, causing cascading reference updates","correction":"CHOICES.md IDs are UIDs — never renumber. Position = priority, not ID number. New choices get next available ID.","tokens_wasted":2000,"source":"user","strength":"strong"}
+{"timestamp":"2026-03-17T16:35:37.017Z","failure":"Using \"aaron\" as git/npm author instead of \"a-canary\"","correction":"Always use GitHub username \"a-canary\" for all git commits, npm author fields, and attribution. Never use \"aaron\".","tokens_wasted":100,"source":"user","strength":"strong"}

package/CHOICES.md

@@ -0,0 +1,244 @@
+# CHOICES.md — Source of Plan
+
+All project choices in priority order. Higher choices constrain lower ones.
+Use `/choose-wisely:choose` to add, change, remove, or reorder choices.
+Use `/choose-wisely:choose-audit` to check for contradictions and structural issues.
+
+## Rules
+
+- **Position = Priority**: higher constrains lower, no exceptions
+- **Gravity rule**: changing a choice triggers cascading review
+- **Section order is fixed**: Mission > User Experiences > Features > Operations > Data > Architecture > Technology > Implementation
+- **Supports line required**: every choice (except top) lists IDs it directly supports
+- **Architecture is tool-agnostic**: Architecture describes patterns; Technology names tools
+- **No status values**: git diff is the change record
+
+### Choice Entry Format
+
+```
+### X-0001: Title of choice
+Supports: X-0000, Y-0000
+
+One to two lines of rationale. Not a spec. Just why this choice was made.
+```
+
+- ID format: `PREFIX-NNNN` (globally unique 4-digit number)
+- Prefixes: `M-` (Mission), `UX-` (User Experiences), `F-` (Features), `O-` (Operations), `D-` (Data), `A-` (Architecture), `T-` (Technology), `I-` (Implementation)
+
+---
+
+## Mission
+
+### M-0100: Priority ladder — UX Quality → Security → Scale → Efficiency
+
+All components follow a strict priority ladder. Higher priorities must never regress when pursuing lower ones. Each level is a release gate:
+1. **UX Quality** — prove it works well for users → UX testing gate
+2. **Security** — prove it's safe → beta release gate
+3. **Scale** — prove it handles growth → full release gate
+4. **Efficiency** — optimize cost/speed → ongoing
+
+### M-0001: Autonomous project development agent
+Supports: M-0100
+
+pi-director is the brain of pi-based development. It understands project intent, recommends what to do next, and executes development autonomously through specialized subagents. It replaces ad-hoc manual orchestration with a structured decision→plan→build loop.
+
+### M-0002: Installable npm package for any pi project
+Supports: M-0001
+
+Every pi project (pi-default, pi-admin, etc.) installs pi-director via npm. It brings the full director stack: agents, skills, and extensions. No manual ~/.pi/ setup needed.
+
+### M-0003: Data-driven decision making
+Supports: M-0001
+
+Recommendations come from evidence — session history, correction logs, code analysis, app output logs — not guesswork. The agent observes patterns and surfaces what matters.
+
+---
+
+## User Experiences
+
+### UX-0001: Three clear operations with distinct outputs
+Supports: M-0001
+
+The user has exactly three high-level commands: `/next` (what should I do?), `/choose` (clarify intent), `/build` (execute the plan). Each produces a distinct artifact: NEXT.md, CHOICES.md, PLAN.md.
+
+### UX-0002: CHOICES.md is user-steered intent
+Supports: UX-0001
+
+CHOICES.md represents what the user has decided through interviews and feedback. It is the user's voice. Agents may clean up language for coherence and clarity, but never change intent, add choices, remove choices, or reorder priorities without user direction.
+
+### UX-0003: NEXT.md surfaces agent-discovered issues outside CHOICES.md scope
+Supports: UX-0001, M-0003
+
+NEXT.md contains problems agents found that conflict with or expand beyond CHOICES.md. These require user approval before action — they represent scope changes, new concerns, or contradictions the user hasn't addressed yet.
+
+### UX-0004: Director acts autonomously within CHOICES.md scope
+Supports: UX-0002, UX-0003
+
+Any issue that falls within the scope of CHOICES.md — bugs, test failures, implementation gaps, refactors aligned with existing choices — the director fixes autonomously. No approval needed. Only issues outside CHOICES.md scope go to NEXT.md for user review.
+
+---
+
+## Features
+
+### F-0001: Next — Analysis and recommendation engine
+Supports: UX-0001, UX-0002
+
+Analyzes session history, correction logs (pi-upskill), code quality, test coverage, and app output logs. Produces NEXT.md with ranked, categorized recommendations: refactors, simplifications, scope changes, UX improvements, upskilling opportunities.
+
+### F-0002: Choose — Project intent clarification
+Supports: UX-0001
+
+Wraps pi-choose-wisely. Manages CHOICES.md through structured interview, bootstrap from existing docs, cascading audit on changes. Defines the WHY and WHAT.
+
+### F-0003: Build — TDD iterative development loop
+Supports: UX-0001, UX-0003
+
+Executes PLAN.md phases using the director pattern: establish gates → recon → refine plan → feasibility experiments → build/test/gate check. Marks phases complete, loops until done or blocked.
+
+### F-0004: Nightly analysis cron
+Supports: F-0001, M-0003
+
+Runs the analysis engine on a schedule (nightly or configurable). Produces fresh NEXT.md so the developer starts each day with prioritized recommendations.
+
+### F-0005: Parallel subagent delegation
+Supports: F-0003, M-0001
+
+Uses pi's subagent system to run independent tasks in parallel — scout + web-search simultaneously, multiple builders on independent files, reviewer while next phase plans.
+
+### F-0006: Replan — Gap analysis between CHOICES.md and current state
+Supports: F-0002, F-0003
+
+Wraps pi-choose-wisely's replan skill. Compares CHOICES.md against codebase reality, generates PLAN.md for next implementation phase. Bridge between intent and execution.
+
+---
+
+## Operations
+
+### O-0100: Four release gates matching priority ladder
+Supports: M-0100
+
+Each component progresses through gates in order. No gate may regress a prior one:
+1. **UX Testing** — prove UX quality with real usage → internal/alpha
+2. **Security Audit** — prove safety with review + hardening → beta publish
+3. **Scale Testing** — prove it handles load/growth → full publish
+4. **Efficiency Optimization** — reduce cost/latency → ongoing post-release
+
+### O-0001: Subagent model tiering via pi-model-router
+Supports: F-0005
+
+Model tiers routed by pi-model-router. Strategic is the most expensive tier and must be used sparingly — only for elevated reasoning with zero tool calls.
+
+### O-0101: Strategic models as thinking-only critics
+Supports: O-0001, M-0100
+
+Strategic models never receive tools. They are critics: given structured input curated by cheaper agents, they review, improve, and produce decision trees (max 8 leaves). This eliminates expensive tool-call loops and focuses strategic spend on pure reasoning at maximum thinking depth.
+
+### O-0102: Recon→Plan→Critique→Finalize→Build pipeline
+Supports: O-0101
+
+The standard execution pipeline:
+1. **Recon** (operational) — retrieve and summarize context, many tool calls
+2. **Plan** (tactical) — synthesize plan from context, few tool calls
+3. **Critique** (strategic) — review plan, provide improvements and/or decision tree, zero tool calls
+4. **Finalize** (tactical) — incorporate critique, resolve decision tree branches with tool calls
+5. **Build** (operational) — execute finalized plan
+
+A similar critique loop applies to implementation validation and phase gate results.
+
+### O-0002: Hard stop vs soft issue classification
+Supports: F-0003
+
+Hard stops (mission infeasible, security breach, external dep broken) require user input. Soft issues (API changed, test failure, review nits) are handled autonomously. Clear escalation policy.
+
+---
+
+## Data
+
+### D-0001: NEXT.md — Recommendation artifact
+Supports: F-0001
+
+Structured markdown with ranked recommendations. Categories: refactor, simplify, scope-change, ux-improvement, upskill, debt. Each item has rationale, effort estimate, and supporting evidence (source file, session, log line).
+
+### D-0002: Session and correction log analysis
+Supports: F-0001, M-0003
+
+Reads pi session history (.pi/agent/sessions/*.jsonl) and correction logs (.pi/corrections.jsonl) to identify patterns: repeated failures, wasted tokens, recurring manual fixes.
+
+### D-0003: CHOICES.md and PLAN.md as source of truth
+Supports: F-0002, F-0003
+
+CHOICES.md defines intent (managed by pi-choose-wisely). PLAN.md defines execution phases (managed by replan + director). Both are markdown, version-controlled, human-readable.
+
+---
+
+## Architecture
+
+### A-0100: Non-regression constraint across priority levels
+Supports: M-0100, O-0100
+
+Every change must pass a regression check: does this degrade UX quality? If pursuing security, does it make the UX worse? If pursuing scale, does it compromise security or UX? Gate checks in /build enforce this — no phase completes if a higher-priority concern regresses.
+
+### A-0001: Three-layer architecture
+Supports: M-0001
+
+Layer 1: Skills (next, choose, build) — user-facing operations invoked by commands.
+Layer 2: Agent definitions (director, builder, planner, reviewer, scout, writer) — specialized roles spawned as subagents.
+Layer 3: Analysis modules — data readers for sessions, logs, code metrics.
+
+### A-0002: Skills as orchestrators, agents as executors
+Supports: A-0001, F-0005
+
+Skills contain the workflow logic (what to do in what order). Agent .md files define persona and constraints. Skills spawn agents via pi's subagent system. Skills never implement code directly.
+
+### A-0003: Extension for nightly/scheduled analysis
+Supports: F-0004, A-0001
+
+A pi extension handles the cron/scheduling aspect. It invokes the `next` skill on a timer and writes NEXT.md. Follows the pi-pi.ts pattern for spawning analysis agents.
+
+### A-0004: Dependency on pi-choose-wisely for CHOICES.md operations
+Supports: F-0002, F-0006
+
+pi-director does not duplicate CHOICES.md logic. It depends on pi-choose-wisely as an npm peer dependency. The `choose` and `replan` skills are re-exported/wrapped.
+
+### A-0005: Dependency on pi-upskill for correction analysis
+Supports: F-0001, D-0002
+
+pi-director consumes pi-upskill's correction logs and analyze skill as input to the recommendation engine. pi-upskill remains a separate package.
+
+---
+
+## Technology
+
+### T-0001: Pi package format with npm distribution
+Supports: M-0002, A-0001
+
+Structured as a pi package (package.json with `pi.skills`, `pi.agents`, `pi.extensions`). Published to npm as `@a-canary/pi-director`. Installed per-project.
+
+### T-0002: TypeScript extension following pi-pi.ts patterns
+Supports: A-0003
+
+The scheduling extension is TypeScript using pi's ExtensionAPI. Spawns agents via `spawn("pi", ...)` like pi-pi.ts does. Uses TUI widgets for status display.
+
+### T-0003: Peer dependencies on pi-choose-wisely, pi-upskill, and pi-model-router
+Supports: A-0004, A-0005, O-0001
+
+`peerDependencies`: `@a-canary/pi-choose-wisely`, `@a-canary/pi-upskill`, `pi-model-router`, `@mariozechner/pi-coding-agent`. pi-model-router handles tier resolution so agents always get the right model for their role.
+
+---
+
+## Implementation
+
+### I-0001: Migrate agent definitions from ~/.pi/agent/agents/
+Supports: A-0001, M-0002
+
+Move director.md, builder.md, planner.md, reviewer.md, scout.md, writer.md from global ~/.pi/agent/agents/ into this package's agents/ directory. Update model references to use model groups.
+
+### I-0002: Skill files reference agent definitions relatively
+Supports: A-0002, I-0001
+
+Skills discover agents from the package's agents/ directory. No hardcoded paths. Agent discovery uses `ls` on known locations (package agents/, project .pi/agents/, global ~/.pi/agent/agents/).
+
+### I-0003: Test with vitest
+Supports: M-0002
+
+Unit tests for analysis modules (session parsing, recommendation ranking). Integration tests for skill workflows using mock sessions. Follows pi-model-router's test pattern.

package/PLAN.md

@@ -0,0 +1,108 @@
+# PLAN.md — Implementation Plan
+
+## Objective
+Implement pi-director as a functional pi package with three working operations (/next, /choose, /build) that orchestrate subagents autonomously.
+
+## Scope
+**In**: Agent discovery, model tiering, /next analysis engine, /build phase execution, /choose integration, nightly extension, tests.
+**Out**: Publishing to npm (separate step), UI/TUI beyond status widgets, multi-project orchestration.
+
+---
+
+## Phase 1: Agent Foundation — Model Tiering & Discovery
+Make agents use model groups instead of hardcoded models. Add relative discovery.
+
+### Steps
+- [x] 1.1 Update all agent .md frontmatter to use model groups (strategic/tactical/operational/scout) instead of hardcoded provider/model strings
+- [x] 1.2 Update director.md agent discovery to check package-relative agents/ dir, then project .pi/agents/, then ~/.pi/agent/agents/
+- [x] 1.3 Add director.md reference to the three skills (/next, /choose, /build) so it knows its operational modes
+- [x] 1.4 Create agents/README.md documenting model tier assignments and discovery order
+
+### Gates
+- [x] All agent .md files use model group names, not provider/model strings
+- [x] Director agent discovery section references package-relative path first
+
+---
+
+## Phase 2: /next — Session & Code Analysis Engine
+Build the data gathering and recommendation pipeline.
+
+### Steps
+- [x] 2.1 Create skills/next/lib/session-scanner.md — instructions for scout agent to parse .pi/agent/sessions/*.jsonl, extract failure patterns, token waste, repeated operations
+- [x] 2.2 Create skills/next/lib/code-scanner.md — instructions for scout agent to find complexity hotspots (files >300 lines, functions >50 lines, untested code, dead exports)
+- [x] 2.3 Create skills/next/lib/choice-scanner.md — instructions for scout agent to diff CHOICES.md against codebase, find unimplemented/stale choices
+- [x] 2.4 Create skills/next/lib/log-scanner.md — instructions for scout agent to parse app logs for recurring errors
+- [x] 2.5 Create skills/next/lib/ranker.md — ranking algorithm: impact × inverse-effort × evidence-strength
+- [x] 2.6 Update skills/next/SKILL.md to reference lib modules and define the parallel gather → analyze → rank → write workflow
+- [x] 2.7 Create templates/NEXT.md — template for generated recommendations file
+
+### Gates
+- [x] Each scanner module is a self-contained instruction set a scout agent can execute
+- [x] SKILL.md references all lib modules and describes parallel dispatch
+- [x] templates/NEXT.md exists with placeholder structure
+
+---
+
+## Phase 3: /build — Director Phase Execution
+Refine the build skill to be the canonical phase execution loop.
+
+### Steps
+- [x] 3.1 Extract the core loop from agents/director.md into skills/build/lib/phase-loop.md as reusable reference
+- [x] 3.2 Create skills/build/lib/regression-check.md — priority ladder regression verification
+- [x] 3.3 Create skills/build/lib/hard-stops.md — enumeration of hard vs soft issues with decision tree
+- [x] 3.4 Update skills/build/SKILL.md to reference lib modules
+- [x] 3.5 Slim down agents/director.md to reference build skill instead of duplicating the loop
+
+### Gates
+- [x] Director agent references build skill for phase execution
+- [x] Hard stop vs soft issue classification is documented in lib/hard-stops.md
+- [x] No duplication between director.md and build/SKILL.md
+
+---
+
+## Phase 4: /choose — pi-choose-wisely Integration
+Wire choose skill to delegate to pi-choose-wisely and bridge to replan.
+
+### Steps
+- [x] 4.1 Update skills/choose/SKILL.md with concrete delegation instructions: which pi-choose-wisely skill to invoke for each operation (bootstrap, audit, change, interview)
+- [x] 4.2 Add replan bridge: after CHOICES.md changes, auto-suggest regenerating PLAN.md
+- [x] 4.3 Add /next bridge: after CHOICES.md changes, note that /next should re-analyze
+- [x] 4.4 Document the CHOICES.md → replan → PLAN.md → /build pipeline in skills/choose/lib/pipeline.md
+- [x] 4.5 Define autonomy boundary: CHOICES.md (user-steered) vs NEXT.md (agent-discovered, out-of-scope)
+
+### Gates
+- [x] Choose skill has explicit delegation paths for all pi-choose-wisely operations
+- [x] Pipeline documentation shows complete flow from intent to execution
+
+---
+
+## Phase 5: Nightly Extension
+TypeScript extension for scheduled analysis.
+
+### Steps
+- [x] 5.1 Create extensions/nightly-analysis.ts following pi-pi.ts pattern — spawns pi with /next skill on configurable schedule
+- [x] 5.2 Add TUI widget showing last analysis time and top 3 recommendations from NEXT.md
+- [x] 5.3 Add /nightly-status command to show schedule and last run
+- [x] 5.4 Add configuration for schedule (default: daily at 2am, configurable via /nightly-set)
+
+### Gates
+- [ ] Extension loads without errors when pi starts
+- [x] /nightly-status command responds with schedule info
+- [x] Widget renders placeholder when no NEXT.md exists
+
+---
+
+## Phase 6: Tests & Validation
+Verify the package works end-to-end.
+
+### Steps
+- [x] 6.1 Create test/agents.test.ts — validate all agent .md files parse correctly (frontmatter, model groups, required fields)
+- [x] 6.2 Create test/skills.test.ts — validate all SKILL.md files exist and have required sections
+- [x] 6.3 Create test/package.test.ts — validate package.json pi config points to real directories
+- [x] 6.4 Create test/next-template.test.ts — validate NEXT.md template structure
+- [x] 6.5 Run full test suite, fix any failures — 72/72 pass
+- [x] 6.6 Update README.md with final structure and usage
+
+### Gates
+- [x] `npm test` passes with all tests green
+- [x] README.md reflects actual package contents

package/README.md

@@ -0,0 +1,97 @@
+# pi-director
+
+Autonomous project director for [pi](https://github.com/mariozechner/pi). Three operations, three artifacts:
+
+| Command | Operation | Artifact | Question |
+|---------|-----------|----------|----------|
+| `/next` | Analyze & Recommend | NEXT.md | What's outside scope? |
+| `/choose` | Clarify Intent | CHOICES.md | Why and what? |
+| `/build` | TDD Development | PLAN.md | How to implement? |
+
+## Autonomy Model
+
+- **CHOICES.md** — user-steered intent. Only the user modifies it (via interviews and feedback).
+- **Within CHOICES.md scope** — director acts autonomously. Bugs, gaps, refactors aligned with existing choices need no approval.
+- **Outside CHOICES.md scope** — surfaces in NEXT.md for user review. Scope changes, contradictions, and new concerns require user acceptance before action.
+
+## Priority Ladder
+
+All work follows: **UX Quality > Security > Scale > Efficiency**. Each level is a release gate. Higher priorities never regress when pursuing lower ones.
+
+## Install
+
+```bash
+npm install @a-canary/pi-director @a-canary/pi-choose-wisely @a-canary/pi-upskill
+```
+
+## Architecture
+
+```
+┌──────────────────────────────────────────┐
+│              pi-director                 │
+│  ┌───────┐  ┌────────┐  ┌──────┐        │
+│  │ /next │  │/choose │  │/build│        │
+│  └───┬───┘  └───┬────┘  └──┬───┘        │
+│      │          │          │             │
+│  ┌───▼──────────▼──────────▼──────┐      │
+│  │      Subagent Orchestration    │      │
+│  │  scout  planner  builder       │      │
+│  │  reviewer  writer              │      │
+│  └────────────────────────────────┘      │
+│                                          │
+│  ┌─────────────────────────────────┐     │
+│  │  Nightly Extension (cron)       │     │
+│  │  /nightly-status /nightly-run   │     │
+│  └─────────────────────────────────┘     │
+├──────────────────────────────────────────┤
+│  pi-choose-wisely   │   pi-upskill      │
+│  CHOICES.md mgmt    │   corrections     │
+└──────────────────────────────────────────┘
+```
+
+## Package Structure
+
+```
+pi-director/
+├── agents/                 # Subagent definitions
+│   ├── director.md         # strategic — orchestration
+│   ├── planner.md          # strategic — architecture
+│   ├── reviewer.md         # tactical — code review
+│   ├── builder.md          # operational — implementation
+│   ├── scout.md            # scout — fast recon
+│   └── writer.md           # operational — documentation
+├── skills/
+│   ├── next/               # /next — analysis engine
+│   │   ├── SKILL.md
+│   │   └── lib/            # scanner modules + ranker
+│   ├── build/              # /build — TDD phase loop
+│   │   ├── SKILL.md
+│   │   └── lib/            # phase-loop, hard-stops, regression-check
+│   └── choose/             # /choose — wraps pi-choose-wisely
+│       ├── SKILL.md
+│       └── lib/            # pipeline documentation
+├── extensions/
+│   └── nightly-analysis.ts # scheduled /next execution
+├── templates/
+│   └── NEXT.md             # recommendation output format
+├── CHOICES.md              # project intent
+├── PLAN.md                 # implementation phases
+└── package.json
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/next` | Analyze project data, generate recommendations |
+| `/choose` | Clarify project intent (wraps pi-choose-wisely) |
+| `/build` | Execute PLAN.md phases via TDD loop |
+| `/nightly-status` | Show analysis schedule and last run |
+| `/nightly-run` | Trigger analysis immediately |
+| `/nightly-set <hour>` | Set daily analysis hour (0-23) |
+
+## Dependencies
+
+- `@a-canary/pi-choose-wisely` — CHOICES.md management, replan
+- `@a-canary/pi-upskill` — Correction analysis, session learning
+- `@mariozechner/pi-coding-agent` — Pi runtime

package/agents/README.md

@@ -0,0 +1,42 @@
+# Agents
+
+Specialized subagent definitions for pi-director.
+
+## Model Tiers
+
+| Agent | Tier | Tools | Rationale |
+|-------|------|-------|-----------|
+| critic | strategic | **none** | Pure reasoning — reviews, improves, produces decision trees |
+| director | tactical | read, bash, grep, find, ls | Orchestrates pipeline, delegates to specialists |
+| planner | tactical | read, grep, find, ls | Synthesizes plans from recon context |
+| reviewer | tactical | read, grep, find, ls, bash | Code review for quality and security |
+| builder | operational | read, write, edit, bash, grep, find, ls | High-throughput implementation |
+| scout | scout | read, grep, find, ls, bash | Cheapest tier for fast read-only recon |
+| writer | operational | read, write, edit, grep, find, ls | Documentation updates |
+
+## Strategic Model Philosophy
+
+Strategic models are the most expensive. We maximize their value by:
+1. **Zero tools** — no tool-call loops burning tokens
+2. **Curated input** — cheaper agents gather and summarize context first
+3. **Structured output** — decision trees (max 8 leaves) that cheaper agents can evaluate and execute
+4. **Maximum thinking depth** — ultrathink/extended thinking for elevated reasoning
+
+### Standard Pipeline
+```
+operational (recon) → tactical (plan) → strategic (critique) → tactical (finalize) → operational (build)
+```
+
+Strategic activation happens exactly twice per phase: plan critique and gate critique.
+
+## Discovery Order
+
+1. **Package agents** — `@a-canary/pi-director/agents/` (always available)
+2. **Project agents** — `.pi/agents/` (project-specific overrides)
+3. **Global agents** — `~/.pi/agent/agents/` (user-level fallback)
+
+## Priority Ladder
+
+All agents operate under M-0100: **UX Quality > Security > Scale > Efficiency**
+
+No agent action may regress a higher-priority concern.

package/agents/builder.md

@@ -0,0 +1,37 @@
+---
+name: builder
+description: Implementation agent. Writes code, runs tests, commits incrementally.
+model: operational
+tools: read, write, edit, bash, grep, find, ls
+---
+You are a builder agent. Implement the requested changes. Write clean, minimal code. Follow existing patterns.
+
+## Process
+
+1. Read the plan or task description fully.
+2. Understand existing code patterns before writing.
+3. Make changes incrementally — smallest working step first.
+4. Run tests after each significant change.
+5. Fix any failures before moving on.
+
+## Rules
+
+- Follow existing code style and patterns in the project.
+- Write tests when the project has a test framework.
+- Keep functions under 50 lines.
+- No premature abstraction — three instances before extracting.
+- No speculative features — build what's asked, nothing more.
+
+## Output format
+
+## Completed
+What was done.
+
+## Files changed
+- `path/to/file.ts` — what changed
+
+## Tests
+{test results or "no test framework"}
+
+## Notes
+Anything the caller should know.

package/agents/critic.md

@@ -0,0 +1,74 @@
+---
+name: critic
+description: Strategic thinking-only reviewer. Zero tools. Produces structured feedback and decision trees from curated input.
+model: strategic
+tools:
+thinking: ultrathink
+---
+You are a critic agent. You receive structured input curated by other agents and produce elevated analysis. You have NO tools — your value is pure reasoning at maximum depth.
+
+## Input Format
+
+You receive a structured review request:
+```
+## Context
+{summarized codebase/project state from scout agents}
+
+## Proposal
+{plan, implementation, or gate results from tactical/operational agents}
+
+## Review Criteria
+{what to evaluate against — CHOICES.md decisions, priority ladder, etc.}
+```
+
+## Output Format
+
+Always produce structured output with decision tree when applicable:
+
+### Feedback
+
+```
+## Assessment
+{overall judgment: approve / improve / reject}
+
+## Strengths
+1. {what's good and why}
+
+## Issues
+1. {problem} — {impact} — {suggested fix}
+
+## Decision Tree
+When the correct approach depends on conditions the critic cannot verify (requires tool calls), produce a decision tree:
+
+IF {condition that needs tool verification}
+├── TRUE: {approach A — specific instructions}
+└── FALSE:
+    IF {second condition}
+    ├── TRUE: {approach B}
+    └── FALSE: {approach C}
+
+Max 8 leaf nodes. Each leaf must be self-contained and actionable.
+```
+
+## Rules
+
+- **Never request tool access.** If you need data, say what data and why — the calling agent will gather it.
+- **Decision trees for uncertainty.** When the right answer depends on runtime state, produce branching paths instead of guessing.
+- **Max 8 leaves** per decision tree. If more complex, decompose into sequential decisions.
+- **Priority ladder always.** Evaluate against M-0100: UX Quality > Security > Scale > Efficiency.
+- **Be specific.** Reference file paths, choice IDs, and concrete alternatives.
+- **Reject boldly.** If a proposal violates CHOICES.md or regresses a higher priority, say so clearly.
+
+## Use Cases
+
+### Plan Review
+Input: recon summary + proposed plan
+Output: improved plan + decision tree for unknowns
+
+### Implementation Review
+Input: code diff summary + test results + CHOICES.md context
+Output: approval/rejection + specific issues + fix approaches
+
+### Gate Review
+Input: phase gate results + exit criteria + regression check
+Output: pass/fail judgment + issues + remediation decision tree