all-hands-cli 0.1.0

package/docs/flows/spec-planning.md

@@ -0,0 +1,162 @@
+---
+description: "Type-aware spec lifecycle from engineer ideation through codebase grounding, spec creation, and planning -- milestone specs get deep planning with jury review, exploratory specs get lightweight scoping with seed prompts"
+---
+
+# Spec Planning
+
+Spec planning is the harness's front door. Before any prompt is written or any code is generated, an engineer's intent must be captured, grounded in codebase reality, and structured into an actionable plan. Milestone specs go through a full ideation session; all other spec types enter through type-specific scoping flows. Both paths converge at spec persistence, after which the spec `type` field drives planning depth.
+
+## Ideation-to-Execution Lifecycle
+
+```mermaid
+flowchart TD
+    A[Engineer arrives with initiative] --> B{Spec type?}
+    B -->|milestone| C[Ideation Session]
+    B -->|other types| SC[Type-Specific Scoping]
+    C --> D[Codebase Grounding + Interview]
+    D --> E[Write Spec]
+    SC --> E
+    E --> F[Persist Spec + Create Branch]
+    F --> G{Start now?}
+    G -->|No| H[Saved for later]
+    G -->|Yes| I{Spec type?}
+    I -->|milestone| J[Milestone Planning]
+    I -->|exploratory| K[Exploratory Planning]
+    J --> L[Deep Research + Interview + Jury]
+    L --> M[5-15 Prompts Ready]
+    K --> N[Focused Research + Seed Prompts]
+    N --> O[0-3 Prompts Ready]
+```
+
+## Phase 1: Ideation Session (Milestone Only)
+
+[ref:.allhands/flows/IDEATION_SESSION.md::4eddba4]
+
+The ideation session is an interview-driven process grounded in the principle of **Ideation First**: front-load exploration to prevent low-level decision fatigue during implementation. Non-milestone specs bypass ideation and enter through [type-specific scoping flows](type-specific-scoping-flows.md) instead.
+
+### Parallel Grounding
+
+While the interview proceeds, parallel subtasks run codebase and research exploration:
+
+| Subtask Type | Flow | Purpose |
+|-------------|------|---------|
+| Codebase grounding (1-3 tasks) | [ref:.allhands/flows/shared/IDEATION_CODEBASE_GROUNDING.md::ff98c47] | Discover existing implementations, roadmap dependencies, and hard constraints |
+| Research (0-2 tasks) | [ref:.allhands/flows/shared/RESEARCH_GUIDANCE.md::eb9185c] | Find high-level solution approaches for novel problems |
+
+The grounding subtask overlays codebase findings against the roadmap, distinguishing between what exists now and what is planned -- because ideation must account for future state, not just current state.
+
+### Interview Dimensions
+
+The interview elicits six dimensions: goals, motivations, concerns, desires, capabilities, and expectations. Each has dedicated deep-dive categories (UX, data/state, technical, scale, integrations, security) with knowledge gap detection signals that trigger deeper probing.
+
+Key design decision: questions are asked **one at a time**. This prevents cognitive overload and allows the agent to adapt each question based on prior answers -- a deliberate application of **Context is Precious** to the human side.
+
+### Preference Language
+
+Specs use calibrated language that preserves engineer intent fidelity:
+
+| Engineer Signal | Spec Language |
+|----------------|---------------|
+| Strong preference | "Engineer desires X" / "Engineer expects X" |
+| Flexible preference | "Engineer likes X but open to alternatives" |
+| Just an idea | "Engineer proposes X, open-ended for architect" |
+| No opinion | Left in Open Questions |
+
+This matters because downstream planning agents use this language to determine how much latitude they have.
+
+## Spec Creation and Persistence
+
+[ref:.allhands/flows/shared/CREATE_SPEC.md::e145081]
+
+The spec is written to `specs/roadmap/{name}.spec.md`, persisted via `ah specs persist`, and its branch is created. The roadmap is reindexed so future ideation sessions can discover this spec as a dependency.
+
+### Spec Variants
+
+Not all specs follow the ideation interview. Several specialized spec types exist:
+
+| Spec Type | Flow | Trigger |
+|-----------|------|---------|
+| Harness improvement | [ref:.allhands/flows/shared/CREATE_HARNESS_SPEC.md::c486457] | Compounding identifies systemic harness issues |
+| Validation tooling | [ref:.allhands/flows/shared/CREATE_VALIDATION_TOOLING_SPEC.md::9750183] | Gap analysis reveals missing validation infrastructure |
+| Investigation | [ref:.allhands/flows/INVESTIGATION_SCOPING.md::4eddba4] | Engineer scopes a hypothesis-driven diagnosis |
+| Optimization | [ref:.allhands/flows/OPTIMIZATION_SCOPING.md::4eddba4] | Engineer scopes a performance improvement |
+| Refactor | [ref:.allhands/flows/REFACTOR_SCOPING.md::4eddba4] | Engineer scopes a structural transformation |
+| Documentation | [ref:.allhands/flows/DOCUMENTATION_SCOPING.md::4eddba4] | Engineer scopes a documentation effort |
+| Triage | [ref:.allhands/flows/TRIAGE_SCOPING.md::4eddba4] | Engineer scopes an externally-signaled issue |
+
+Harness and validation specs follow `CREATE_SPEC.md` for persistence but have distinct interview formats. The five scoping flows (investigation through triage) each conduct a type-specific interview before delegating to `CREATE_SPEC.md`. See [type-specific-scoping-flows](type-specific-scoping-flows.md) for details.
+
+### Optional: Flow Analysis
+
+[ref:.allhands/flows/shared/SPEC_FLOW_ANALYSIS.md::513806f]
+
+For user-facing features with multiple paths, the spec can be analyzed for user flow completeness. This identifies missing flows, ambiguous transitions, undefined error states, and scope boundaries -- all presented as questions, not mandates.
+
+## Planning Depth by Spec Type
+
+[ref:.allhands/flows/SPEC_PLANNING.md::cc0b192]
+
+Per **Frontier Models are Capable**, the spec `type` field determines planning depth. This branching happens after spec persistence, when planning begins:
+
+| Spec Type | Planning Path | Research Depth | Interview | Jury | Output |
+|-----------|--------------|----------------|-----------|------|--------|
+| `milestone` (or missing) | Milestone Planning | 1-4 deep subtasks | Full decision interview | Yes | 5-15 prompts + detailed alignment doc |
+| `investigation` | Exploratory Planning | 1-2 focused subtasks | Open questions only (skippable) | No | 0-3 seed prompts + problem-focused alignment doc |
+| `optimization` | Exploratory Planning | 1-2 focused subtasks | Open questions only (skippable) | No | 0-3 seed prompts + problem-focused alignment doc |
+| `refactor` | Exploratory Planning | 1-2 focused subtasks | Open questions only (skippable) | No | 0-3 seed prompts + problem-focused alignment doc |
+| `documentation` | Exploratory Planning | 1-2 focused subtasks | Open questions only (skippable) | No | 0-3 seed prompts + problem-focused alignment doc |
+| `triage` | Exploratory Planning | 1-2 focused subtasks | Open questions only (skippable) | No | 0-3 seed prompts + problem-focused alignment doc |
+
+## Phase 2: Spec Planning -- Milestone Path
+
+Planning transforms the spec into executable prompts. This is where **Quality Engineering** takes over: the question shifts from "what does the engineer want?" to "which implementation approach is best?"
+
+### Research Before Options
+
+Planning spawns parallel research subtasks before presenting any options:
+
+| Research Type | Flow | Purpose |
+|--------------|------|---------|
+| Codebase understanding (1-4 tasks) | [ref:.allhands/flows/shared/CODEBASE_UNDERSTANDING.md::b10cce8] | Ground implementation approaches in existing patterns |
+| Solution research (0-3 tasks) | [ref:.allhands/flows/shared/RESEARCH_GUIDANCE.md::eb9185c] | Isolate optimal solutions for novel problems |
+| External tech (as needed) | [ref:.allhands/flows/shared/EXTERNAL_TECH_GUIDANCE.md::9766b03] | Acquire documentation and implementation guidance |
+
+### Disposable Variant Architecture
+
+When the engineer selects multiple approaches for the same decision point, the planning agent creates variant prompts that execute in parallel behind feature flags. This is a direct application of **Quality Engineering**: software is cheap, so multiple variants can be tested rather than debated.
+
+The planning agent is the only agent authorized to architect variant prompt structures. This prevents downstream agents from creating uncoordinated variants.
+
+### Plan Verification
+
+Before jury review, the planner self-verifies across five dimensions: requirement coverage, task completeness, key links planned (components wiring together), scope sanity (2-3 tasks per prompt, fewer than 7 files), and validation coverage.
+
+### Plan Review Jury
+
+The plan passes through a jury of four specialized reviewers before execution begins. See the [plan-review-jury documentation](plan-review-jury.md) for details on this pre-execution review gate.
+
+## Phase 2: Spec Planning -- Exploratory Path
+
+Exploratory planning is intentionally lightweight. Per **Frontier Models are Capable**, exploratory specs leave room for hypothesis-driven discovery by the emergent planner rather than pre-specifying all work upfront.
+
+### Focused Research
+
+1-2 targeted research subtasks grounded in the specific problem domain. External research is only spawned if the spec references external tools or novel approaches.
+
+### Engineer Scope Narrowing
+
+Open questions from the spec are presented to the engineer via `AskUserQuestion`. Each question can be answered to narrow scope or skipped -- skipped questions remain open for hypothesis-driven discovery. The interview is kept brief; exploratory specs intentionally leave room for discovery.
+
+### Seed Prompt Creation
+
+0-3 seed prompts created as testable hypotheses grounded in research findings. These target the most concrete, immediately actionable aspects of the spec. Remaining open questions are left for the emergent planner to design experiments around.
+
+### Exploratory Alignment Doc
+
+The alignment doc for exploratory specs emphasizes the problem space over the solution:
+
+- **Overview**: Problem statement, evidence, context, and unresolved questions -- the emergent planner reads these to design experiments
+- **Hard User Requirements**: Success criteria and constraints
+- **Engineer Decisions**: Only deviations from recommendations
+
+Unresolved questions (skipped interview questions, open spec questions) are documented prominently. Per **Knowledge Compounding**, this enables the emergent planner to discover and test answers through hypothesis-driven work.

package/docs/flows/type-specific-scoping-flows.md

@@ -0,0 +1,49 @@
+---
+description: "Type-specific scoping flows for the unified initiative system -- five interview-driven flows that capture engineer intent for investigation, optimization, refactor, documentation, and triage specs before delegating to the shared spec creation pipeline"
+---
+
+# Type-Specific Scoping Flows
+
+The harness supports six spec types: milestone, investigation, optimization, refactor, documentation, and triage. Milestone specs enter through the ideation session (see [spec-planning](spec-planning.md)). The remaining five types each have a dedicated scoping flow that interviews the engineer and delegates to the shared spec creation pipeline.
+
+## Shared Pattern
+
+All five scoping flows follow a two-phase structure:
+
+1. **Scoping Interview** -- Ask targeted questions via `AskUserQuestion`, one at a time. Per **Frontier Models are Capable**, the agent adapts depth based on engineer responses -- probing vague answers, skipping questions already addressed.
+2. **Spec Creation** -- Synthesize interview answers into spec content (Motivation, Goals, Technical Considerations, Open Questions), set the `type` field in spec frontmatter, and delegate to [ref:.allhands/flows/shared/CREATE_SPEC.md::e145081] for persistence.
+
+The interview dimensions differ per type because each problem class has distinct information needs. An investigation needs evidence and symptoms; an optimization needs baselines and targets.
+
+## Per-Type Interview Dimensions
+
+| Spec Type | Flow | Questions | Key Dimensions |
+|-----------|------|-----------|----------------|
+| Investigation | [ref:.allhands/flows/INVESTIGATION_SCOPING.md::4eddba4] | 5 | Symptom description, evidence/reproduction, success criteria, constraints, suspected root causes |
+| Optimization | [ref:.allhands/flows/OPTIMIZATION_SCOPING.md::4eddba4] | 5 | Bottleneck identification, performance targets, measurement approach, baseline metrics, constraints |
+| Refactor | [ref:.allhands/flows/REFACTOR_SCOPING.md::4eddba4] | 5 | Scope boundaries, invariants to preserve, target architecture, migration strategy, constraints |
+| Documentation | [ref:.allhands/flows/DOCUMENTATION_SCOPING.md::4eddba4] | 4 | Coverage areas, target audience, existing docs state, format and location |
+| Triage | [ref:.allhands/flows/TRIAGE_SCOPING.md::4eddba4] | 3 | External signals, impact and urgency, desired outcome (stub) |
+
+### Triage: Stub Status
+
+The triage scoping flow is a manual-input stub. Full external source integration (PostHog, Sentry, PagerDuty) is deferred to a future spec. Engineers paste or summarize external signals rather than the harness pulling them automatically.
+
+## Branch Prefix Convention
+
+Each spec type maps to a default branch prefix when the spec does not specify one explicitly. The `branch` field on the spec is always the source of truth.
+
+| Spec Type | Branch Prefix |
+|-----------|---------------|
+| `milestone` (or missing) | `feature/` |
+| `investigation` | `fix/` |
+| `optimization` | `optimize/` |
+| `refactor` | `refactor/` |
+| `documentation` | `docs/` |
+| `triage` | `triage/` |
+
+These conventions are defined in [ref:.allhands/flows/shared/CREATE_SPEC.md::e145081] and applied during `ah specs persist`.
+
+## Downstream Impact
+
+Scoped specs flow into type-aware planning. Per [spec-planning](spec-planning.md), milestone specs receive deep planning with jury review (5-15 prompts), while all other types receive exploratory planning (1-2 research subtasks, 0-3 seed prompts). The spec `type` field set during scoping drives this branching.

package/docs/flows/validation-and-skills-integration.md

@@ -0,0 +1,145 @@
+---
+description: "Validation practice model (stochastic vs deterministic dimensions, crystallization lifecycle, suite existence threshold), suite discovery, domain skills extraction, and TDD methodology during prompt execution"
+---
+
+# Validation and Skills Integration
+
+These three shared flows form the quality infrastructure that prompt curation and execution depend on. They are invoked as sub-flows -- typically from prompt curation -- to ensure every prompt carries the right validation suites, domain expertise, and testing methodology.
+
+## Two-Dimensional Validation Practice Model
+
+Per **Agentic Validation Tooling**, every validation domain has two first-class dimensions:
+
+| Dimension | Nature | Phase | Purpose |
+|-----------|--------|-------|---------|
+| **Stochastic** | Agent-driven exploratory testing using model intuition | During implementation | Probe edge cases, test user flows, verify quality beyond deterministic checks |
+| **Deterministic** | Binary pass/fail gating | Acceptance criteria | CI/CD-enforceable commands that gate completion |
+
+These dimensions map to suite body sections: **Stochastic Validation** teaches agents how to explore; **Deterministic Integration** provides the commands that gate acceptance criteria.
+
+### Suite Existence Threshold
+
+A validation suite MUST have a meaningful stochastic dimension to justify existing. Per [ref:.allhands/principles.md::0610b13], deterministic-only tools (type checking, linting, formatting) are test commands referenced directly in acceptance criteria and CI/CD -- they are NOT suites.
+
+### Crystallization Lifecycle
+
+Stochastic exploration and deterministic gating are connected by a compounding lifecycle:
+
+```mermaid
+stateDiagram-v2
+    [*] --> StochasticExploration: Agent discovers patterns
+    StochasticExploration --> PatternStabilization: Repeatable pattern emerges
+    PatternStabilization --> DeterministicCheck: Crystallization promotion
+    DeterministicCheck --> CICD: Entrenched in pipeline
+    CICD --> StochasticExploration: Exploration shifts to frontier
+```
+
+Per [ref:.allhands/flows/COMPOUNDING.md::905aed8], the compounding flow evaluates crystallization during its Tooling Signals phase and promotes stable stochastic patterns into deterministic checks during Harness Improvement.
+
+---
+
+## How These Flows Connect
+
+```mermaid
+flowchart TD
+    PC[Prompt Curation] -->|"What validation applies?"| VT[Utilize Validation Tooling]
+    PC -->|"What domain expertise applies?"| SE[Skill Extraction]
+    PE[Prompt Execution] -->|"How to implement?"| TDD[TDD Workflow]
+
+    VT -->|validation_suites frontmatter| PF[Prompt File]
+    SE -->|skills frontmatter + embedded guidance| PF
+    TDD -->|test-first implementation| Code[Implementation]
+
+    VT -.- VTN["Programmatic acceptance criteria"]
+    SE -.- SEN["Domain expertise for executor"]
+    TDD -.- TDDN["RED → GREEN → REFACTOR"]
+```
+
+---
+
+## Validation Tooling Discovery
+
+[ref:.allhands/flows/shared/UTILIZE_VALIDATION_TOOLING.md::1df56ac]
+
+This flow matches implementation tasks to existing validation suites. Per **Agentic Validation Tooling**, programmatic validation replaces human supervision for routine checks.
+
+### Discovery Pipeline
+
+1. **Discover**: Run `ah validation-tools list` to get available suites (name, description, globs, file path, `tools`)
+2. **Match**: Two parallel approaches:
+   - Glob pattern matching against files being touched
+   - Semantic inference from suite descriptions against task nature
+   - The `tools` field identifies which tooling each suite wraps -- useful for matching against available MCP tools and installed CLI commands
+3. **Read**: For each matched suite, read its body sections:
+   - **Stochastic Validation** -- how agents explore quality during implementation
+   - **Deterministic Integration** -- CI-gated commands for acceptance criteria
+4. **Integrate**: Derive acceptance criteria from **Deterministic Integration** commands; use **Stochastic Validation** during implementation. Add suite paths to `validation_suites` frontmatter.
+5. **Gap analysis**: Document unmatched validation needs for future `CREATE_VALIDATION_TOOLING`
+
+### Validation Ordering
+
+Acceptance criteria (deterministic dimension) are ordered progressively to fail fast:
+
+> Compiles --> Unit tests --> Integration tests --> E2E
+
+Stochastic exploration during implementation is not ordered -- agents follow model intuition to probe quality.
+
+---
+
+## Skill Extraction
+
+[ref:.allhands/flows/shared/SKILL_EXTRACTION.md::03a6816]
+
+This flow finds and distills domain expertise from skill files into actionable prompt guidance. Per **Knowledge Compounding**, skills are "how to do it right" -- expertise that compounds across prompts.
+
+### Extraction Pipeline
+
+1. **Discover**: Run `ah skills list` to get available skills (name, description, globs, file path)
+2. **Match**: Same dual approach as validation -- glob patterns and semantic inference
+3. **Read**: Extract key patterns, best practices, and references from each `.allhands/skills/<name>/SKILL.md`
+4. **Synthesize**: Distill task-relevant knowledge (not full skill file copies)
+5. **Embed**: Add skill paths to `skills` frontmatter and embed guidance in prompt Tasks section
+
+### Key Distinction from Validation
+
+| Aspect | Validation Suites | Skills |
+|--------|------------------|--------|
+| What they provide | Commands to verify correctness | Knowledge to implement correctly |
+| When they apply | After implementation (checking) | During implementation (guiding) |
+| Output location | `validation_suites` frontmatter | `skills` frontmatter + prompt body |
+| Who consumes them | Validation runners | Prompt executors |
+
+---
+
+## TDD Workflow
+
+[ref:.allhands/flows/shared/TDD_WORKFLOW.md::8d9b5d8]
+
+This flow applies test-driven development to prompt execution. Per **Agentic Validation Tooling**, tests written first create clear acceptance criteria and prevent scope drift.
+
+### The Cycle
+
+```
+RED --> GREEN --> REFACTOR
+ |        |          |
+ |        |          +-- Improve code quality (tests still pass)
+ |        +-- Write minimal code to pass tests
+ +-- Write failing tests from acceptance criteria
+```
+
+### When to Apply
+
+| Context | TDD Depth |
+|---------|-----------|
+| High-risk domains (auth, payments, data) | Full -- every acceptance criterion tested first |
+| Core business logic | Full -- tests define behavior |
+| UI components | Light -- key interactions tested |
+| Integration glue code | Light -- happy path + error cases |
+| Scripts/utilities | Optional -- judgment call |
+| Exploratory/spike work | Skip -- write tests after if keeping |
+| Pure UI layout changes | Skip -- visual review sufficient |
+| Configuration changes | Skip -- integration test coverage |
+
+### Test Evidence
+
+TDD produces test evidence tables that map acceptance criteria to specific tests and their pass/fail status. This evidence feeds into prompt summaries and ultimately into the compounding flow for knowledge extraction.

package/docs/flows/wip/wip-flows.md

@@ -0,0 +1,102 @@
+---
+description: "Work-in-progress flows for structured debug investigation and memory recall, not yet integrated into the milestone workflow"
+---
+
+# Work-in-Progress Flows
+
+These flows are under active development. They define useful capabilities but lack finalized integration points with the milestone workflow. Both are usable standalone but their invocation paths from other flows are TBD.
+
+---
+
+## Debug Investigation
+
+[ref:.allhands/flows/wip/DEBUG_INVESTIGATION.md::8d96611]
+
+A structured investigation methodology for complex bugs with unclear root causes. Per **Agentic Validation Tooling**, systematic debugging beats random exploration.
+
+### Investigation Phases
+
+```mermaid
+flowchart TD
+    S[Symptom Gathering] --> H[Hypothesis Formation]
+    H --> I[Investigation]
+    I -->|confirmed| RC[Root Cause Confirmation]
+    I -->|inconclusive| H
+    I -->|refuted| H
+    RC --> F[Fix Recommendation]
+    F --> D[Documentation]
+```
+
+The flow enforces a discipline: gather symptoms before hypothesizing, verify hypotheses with evidence before concluding, never guess at root cause without verification.
+
+### Hypothesis-Driven Approach
+
+Each investigation cycle produces structured evidence:
+
+| Phase | Output |
+|-------|--------|
+| Symptom Gathering | Error messages, reproduction steps, frequency, recent changes |
+| Hypothesis Formation | 2-3 ranked hypotheses with confidence, supporting/contradicting evidence, verification method |
+| Investigation | Per-hypothesis file examination, findings, and conclusion (confirmed / refuted / inconclusive) |
+| Root Cause | Description, location, evidence chain, explanation of why other hypotheses were wrong |
+
+### Common Debug Patterns
+
+The flow includes a reference table mapping symptom patterns to likely causes:
+
+| Symptom | First Check |
+|---------|-------------|
+| Works locally, fails in CI | Environment diff: vars, paths, deps |
+| Intermittent failures | Race condition: async timing, shared state |
+| Started after deploy | Recent changes: git diff from last working |
+| Only affects some users | Data-dependent: user data differences |
+| Works sometimes on refresh | Caching: cache invalidation logic |
+
+### Potential Integration Approaches
+
+Integration with the milestone workflow is under consideration via four paths:
+1. Patch prompt type (`type: debug`) following this flow
+2. Pre-implementation phase when initial execution fails
+3. Emergent debug when emergent refinement hits blockers
+4. Coordinator service option in the coordination flow
+
+---
+
+## Memory Recall
+
+[ref:.allhands/flows/wip/MEMORY_RECALL.md::38dd927]
+
+A query interface for the simple memory file at `docs/memories.md`. Per **Knowledge Compounding**, memories enable reuse of solutions without re-discovery.
+
+### Memory Format
+
+Memories use a table format with four columns:
+
+| Column | Values |
+|--------|--------|
+| Name | Short identifier |
+| Domain | `planning`, `validation`, `implementation`, `harness-tooling`, `ideation` |
+| Source | `user-steering` (engineer directed) or `agent-inferred` (discovered during work) |
+| Description | 1-3 sentences of self-contained learning |
+
+### Recall Process
+
+1. Read `docs/memories.md`
+2. Filter by domain if provided
+3. Scan descriptions for keyword relevance
+4. Return matching memories with context
+
+### Relevance Scoring
+
+Memories are prioritized by domain match, keyword overlap, and source authority (`user-steering` outranks `agent-inferred` for preference-based queries).
+
+### Caller Flows
+
+| Flow | Query Focus |
+|------|-------------|
+| Spec Planning | Planning patterns, past decisions |
+| Prompt Execution | Implementation approaches, solutions |
+| Ideation Session | Similar initiatives, prior engineer preferences |
+| Compounding | Verify memory doesn't already exist before adding |
+
+For detailed technical solutions beyond lightweight memories, the recall flow also directs callers to `ah solutions search`.

package/docs/harness/README.md

@@ -0,0 +1,23 @@
+---
+description: "Harness domain documentation covering the ah CLI commands, hook system, TUI, event loop, agent profiles, CLI daemon, and test infrastructure."
+---
+
+# Harness
+
+The `ah` CLI is the core tool for agent orchestration. It provides commands, hooks, a terminal UI, and supporting systems.
+
+## CLI Commands
+
+Commands registered via filesystem auto-discovery. See `docs/harness/cli/README.md` for the full list.
+
+## Hooks
+
+Pre/post tool hooks that inject context, validate schemas, enforce rules, and manage agent lifecycle. See `docs/harness/hooks/README.md`.
+
+## Systems
+
+- **TUI** — Blessed-based terminal interface with three-pane layout, modal system, and vim-style navigation: `docs/harness/tui.md`
+- **Event Loop** — Background polling for prompt dispatch, agent monitoring, PR review detection, and branch state: `docs/harness/event-loop.md`
+- **Agent Profiles** — YAML profile loading, template resolution, and invocation building: `docs/harness/agent-profiles.md`
+- **CLI Daemon** — Unix socket server for fast hook execution, bypassing CLI startup overhead: `docs/harness/cli-daemon.md`
+- **Test Harness** — E2E test infrastructure with fixtures, runners, and assertions: `docs/harness/test-harness.md`

package/docs/harness/agent-profiles.md

@@ -0,0 +1,84 @@
+---
+description: "YAML-defined agent profiles that configure how agents are spawned from the TUI, including template variable resolution, flow file binding, invocation building, and the OpenCode SDK runner for sub-agent execution."
+---
+
+# Agent Profiles
+
+Agent profiles are YAML declarations that define how agents are configured and spawned. They decouple agent behavior (what flows and system prompts to use) from orchestration (how and when to spawn). The TUI reads profiles to populate its action menu and build the correct invocation for each agent type.
+
+## Profile Loading
+
+Profiles live in the `.allhands/harness/agents/` directory as YAML files.
+
+[ref:.allhands/harness/src/lib/opencode/profiles.ts:loadAgentProfile:ef20442] loads a single profile by name: reads the YAML, validates it against `RawAgentProfileSchema` via Zod, normalizes it with `normalizeProfile`, and runs semantic validation with `validateProfileSemantics`. Returns `null` if the file is missing or validation fails.
+
+[ref:.allhands/harness/src/lib/opencode/profiles.ts:listAgentProfiles:ef20442] enumerates all `.yaml` / `.yml` files in the agents directory, returning profile names (filenames without extensions).
+
+[ref:.allhands/harness/src/lib/opencode/profiles.ts:loadAllProfiles:ef20442] loads every profile, collecting both valid profiles and per-profile error/warning lists. The TUI calls this at startup to validate the entire profile set and report issues in the activity log.
+
+## TUI Action Mapping
+
+[ref:.allhands/harness/src/lib/opencode/profiles.ts:getProfilesByTuiAction:ef20442] builds a `Map<string, AgentProfile[]>` keyed by TUI action ID (e.g., "coordinator", "planner", "ideation"). Each TUI action button can trigger one or more agent profiles -- for example, a "planner" action might spawn both a planning agent and a dependency-check agent.
+
+This mapping is what connects the TUI's action pane to actual agent configurations.
+
+## Template Resolution
+
+Profiles use template variables (e.g., `{{spec_name}}`, `{{branch}}`, `{{planning_dir}}`) in their system prompts, flow paths, and arguments. [ref:.allhands/harness/src/lib/opencode/profiles.ts:resolveTemplate:ef20442] performs string substitution using a `TemplateContext` object.
+
+The context is validated at invocation time via `validateContext` from the template-vars schema, ensuring all required variables are provided before spawning. Missing variables produce clear error messages rather than silently passing `{{undefined}}` tokens to agents.
+
+## Invocation Building
+
+[ref:.allhands/harness/src/lib/opencode/profiles.ts:buildAgentInvocation:ef20442] transforms a profile + context into a concrete `AgentInvocation` -- the fully resolved command, arguments, environment variables, and system prompt ready for tmux execution.
+
+[ref:.allhands/harness/src/lib/opencode/profiles.ts:buildAgentInvocationByName:ef20442] is a convenience wrapper that loads the profile by name and builds the invocation in one call.
+
+Before building, [ref:.allhands/harness/src/lib/opencode/profiles.ts:validateProfileFlowExists:ef20442] verifies that the flow file referenced by the profile actually exists on disk. Flow files live in [ref:.allhands/harness/src/lib/opencode/profiles.ts:getFlowsDir:ef20442] (`.allhands/flows/`). This catches stale profile-to-flow references at spawn time rather than mid-execution.
+
+## Agent Runner (OpenCode SDK)
+
+[ref:.allhands/harness/src/lib/opencode/runner.ts:AgentRunner:c3a3694] provides a different execution model: instead of spawning agents in tmux windows, it runs sub-agents programmatically via the OpenCode SDK. This is used for internal harness tasks (oracle analysis, knowledge aggregation) that need structured JSON output.
+
+### Execution Flow
+
+```mermaid
+sequenceDiagram
+    participant Caller
+    participant Runner as AgentRunner
+    participant SDK as OpenCode SDK
+    participant Agent
+
+    Caller->>Runner: run(config, userMessage)
+    Runner->>SDK: createOpencode({port: 0})
+    SDK-->>Runner: client + server
+    Runner->>SDK: session.create()
+    Runner->>SDK: session.prompt(systemPrompt, noReply)
+    Runner->>SDK: session.prompt(userMessage)
+    SDK->>Agent: Execute
+    Agent-->>SDK: Response (possibly with EXPAND: requests)
+
+    loop Expansion (max 3)
+        Runner->>Runner: hasExpansionRequest?
+        Runner->>Runner: readFiles(paths)
+        Runner->>SDK: session.prompt(expandedContent)
+    end
+
+    Runner->>Runner: parseStructuredOutput<T>()
+    Runner-->>Caller: AgentResult<T>
+    Runner->>SDK: server.close()
+```
+
+### Key Design Decisions
+
+**Port 0 allocation** -- Each `run()` call spawns a fresh OpenCode server on an OS-assigned port, enabling parallel sub-agent execution without port conflicts.
+
+**Expansion protocol** -- Agents can request file contents by including `EXPAND: path/to/file` lines in their response. The runner reads those files (with 1MB size limit) and sends them back, up to 3 expansion rounds. This lets agents pull in context incrementally rather than requiring all files upfront.
+
+**Structured output parsing** -- Responses are parsed as JSON, first trying code block extraction (`\`\`\`json ... \`\`\``), then raw parse. If parsing fails, the runner sends one retry prompt requesting JSON format before reporting failure.
+
+**Model resolution** -- Uses the profile's `config.model` if set, falls back to `settings.opencodeSdk.model`, then to the OpenCode SDK default. This three-tier precedence lets operators override models at the project level while profiles can pin specific models for specialized tasks.
+
+## Module Structure
+
+[ref:.allhands/harness/src/lib/opencode/index.ts::20598fd] is the barrel export that re-exports profile functions and the `AgentRunner` class. It also defines the shared type interfaces (`AgentConfig`, `AgentResult`, `McpServerConfig`, `SearchResult`, `AggregatorInput`, `AggregatorOutput`) used across the harness for agent communication.

package/docs/harness/cli/README.md

@@ -0,0 +1,24 @@
+---
+description: "Index of all ah CLI command documentation covering entry point, planning, knowledge, schema validation, specs, oracle, spawn, tools, search, docs, trace, and minor utilities."
+---
+
+# CLI Commands
+
+All commands are auto-discovered from the filesystem and registered via Commander.js. See `docs/harness/cli/cli-entry-and-command-discovery.md` for the discovery mechanism.
+
+## Commands
+
+| Command Area | Doc |
+|---|---|
+| Entry point and command discovery | `docs/harness/cli/cli-entry-and-command-discovery.md` |
+| Planning directories and status | `docs/harness/cli/planning-command.md` |
+| Semantic knowledge search | `docs/harness/cli/knowledge-command.md` |
+| Schema and validation | `docs/harness/cli/schema-and-validation-commands.md` |
+| Spec file management | `docs/harness/cli/specs-command.md` |
+| LLM-powered PR and analysis | `docs/harness/cli/oracle-command.md` |
+| Agent spawning via tmux | `docs/harness/cli/spawn-command.md` |
+| MCP tool integration | `docs/harness/cli/tools-command.md` |
+| Solution, memory, and web search | `docs/harness/cli/search-commands.md` |
+| Documentation validation | `docs/harness/cli/docs-command.md` |
+| Observability and tracing | `docs/harness/cli/trace-command.md` |
+| Skills, notify, complexity | `docs/harness/cli/minor-cli-commands.md` |