all-hands-cli 0.1.0

package/docs/flows/compounding.md

@@ -0,0 +1,126 @@
+---
+description: "Post-spec knowledge extraction flow that captures learnings, solutions, memories, and harness improvements from completed specifications, with type-aware completion assessment for milestone vs exploratory specs"
+---
+
+# Compounding Flow
+
+The compounding flow exists to close the feedback loop after a spec completes. Without it, knowledge gained during implementation -- decisions, failures, workarounds, engineer preferences -- evaporates between sessions. Per **Knowledge Compounding**, everything feeds forward.
+
+This flow runs after all prompts in a spec have been executed and reviewed. It is intentionally the last step before a spec is considered fully closed.
+
+## Lifecycle Position
+
+```mermaid
+flowchart LR
+    A[Spec Planning] --> B[Prompt Execution Loop]
+    B --> C[PR Review]
+    C --> D[Compounding]
+    D --> E[Spec Closed]
+    D -->|harness issues| F[Harness Improvement Spec]
+```
+
+The flow is idempotent -- running it again on a spec with no new changes produces no output.
+
+## Phase Progression
+
+The flow progresses through ordered phases, each building on the previous. Completion Assessment runs early to establish the evaluation frame for the spec type. The final phase (Harness Improvement) is intentionally last so that all other compounding artifacts are complete before any diversion into structural changes.
+
+```mermaid
+flowchart TD
+    CG[Context Gathering] --> CA[Completion Assessment]
+    CA --> SA[Signal Analysis]
+    SA --> ME[Memory Extraction]
+    SA --> SD[Solution Documentation]
+    ME --> SF[Spec Finalization]
+    SD --> SF
+    SF --> HI[Harness Improvement Handling]
+```
+
+## Completion Assessment by Spec Type
+
+Per **Frontier Models are Capable**, completion means different things depending on the spec type:
+
+| Spec Type | Completion Criteria |
+|-----------|-------------------|
+| **Milestone** (or missing) | Spec acceptance criteria met, all prompts complete, thorough knowledge extraction |
+| **Exploratory** (investigation, optimization, refactor, documentation, triage) | Problem resolution assessed against original hypothesis, learnings extracted from experiment outcomes, unresolved questions documented for future work |
+
+Milestone completion is binary -- acceptance criteria are either met or not. Exploratory completion is evaluated against hypothesis outcomes: did the experiments answer the questions posed? What was learned? What remains open? This distinction shapes how subsequent Signal Analysis interprets prompt results.
+
+## Signal Analysis
+
+The core analytical phase reads all spec artifacts and identifies patterns across four signal categories:
+
+| Signal Category | What It Reveals | Key Indicators |
+|----------------|-----------------|----------------|
+| Prompt Signals | Execution and planning quality | Failed prompts, patch counts, blocker learnings |
+| Tooling Signals | Skill and validation suite effectiveness | Per-tool impact map of what each tool caught vs. missed |
+| Decision Signals | Engineer intent and preferences | Rejections, overrides, compromise patterns |
+| Emergent Work Signals | Quality control preferences | Kept vs. reverted emergent work |
+
+The tooling signals phase produces a **per-tool impact map** that cross-references every prompt's skills and validation suites against its summary (Limitations, Decisions, Learnings). This map becomes evidence for harness improvement specs.
+
+### Crystallization Evaluation
+
+Per **Agentic Validation Tooling**, the tooling signals phase also evaluates each validation suite for **crystallization** opportunities. For each suite used during execution:
+
+- What stochastic patterns were discovered during exploratory validation?
+- Which patterns are stable and repeatable enough to crystallize into deterministic checks?
+- Should new deterministic tests be added to the suite's Deterministic Integration section?
+- Are there stochastic exploration patterns that should be documented for future agents?
+
+This evaluation feeds directly into the Harness Improvement phase as evidence for suite refinement per [ref:.allhands/flows/shared/CREATE_VALIDATION_TOOLING_SPEC.md::9750183].
+
+A key design decision: emergent prompts are never framed as "scope creep." Per **Quality Engineering**, emergent work discovers valuable variants. Reverted emergent work is expected experimentation cost per **Software is Cheap**.
+
+## Knowledge Outputs
+
+The flow produces three distinct knowledge artifacts:
+
+| Artifact | Location | Purpose |
+|----------|----------|---------|
+| Memories | `docs/memories.md` | Lightweight learnings searchable via `ah memories search` |
+| Solutions | `docs/solutions/<category>/` | Detailed problem-solution documentation for non-trivial issues |
+| Spec Finalization | `.planning/<spec>/spec.md` | Historical record with implementation reality vs. original plan |
+
+### Memory Categories
+
+Memories are captured across five categories when signals exist: technical learnings, engineer preference memories, systemic validation signals, harness behavior patterns. Each memory is tagged with domain and source (`user-steering` vs `agent-inferred`) for relevance scoring in future recall.
+
+### Solution Documentation
+
+Solutions target problems that required multiple investigation attempts, had non-obvious resolutions, or involve agentic anti-patterns. Trivial fixes are explicitly excluded. After writing, solutions are cross-referenced against existing solutions via `ah solutions search` to build a connected knowledge graph.
+
+## Harness Improvement Classification
+
+The final phase classifies detected issues and requires engineer interview before action:
+
+```mermaid
+flowchart TD
+    I[Classified Issues] --> Q{Type?}
+    Q -->|Skill gaps| A[Update skill file inline]
+    Q -->|Validation suite gaps| B[Update suite file inline]
+    Q -->|Missing validation suite| C{Engineer decision}
+    Q -->|Structural: flows/commands/hooks| D{Engineer decision}
+    C -->|Create| E[CREATE_HARNESS_SPEC]
+    C -->|Defer| F[Document in memories]
+    D -->|Create| E
+    D -->|Defer| F
+```
+
+Inline updates (skills, validation suites) require engineer approval. Structural changes always go through a spec. Deferred items are documented in `docs/memories.md` under "Deferred Harness Improvements."
+
+### Crystallization Promotion
+
+Per [ref:.allhands/flows/COMPOUNDING.md::905aed8], validation suite refinements include **crystallization promotion**: stable stochastic patterns discovered during execution are promoted into deterministic checks in the suite's Deterministic Integration section. This shifts stochastic exploration to the frontier -- agents no longer need to rediscover patterns that have been automated. The crystallization lifecycle ensures validation compounds across spec executions.
+
+## Key Design Decisions
+
+- **Engineer interview is mandatory** before finalizing the compounding summary -- the flow must not finalize without sign-off on classified issues
+- **Harness modification requires first principle justification** -- changes must trace back to principles in [ref:.allhands/principles.md::0610b13]
+- **Spec finalization preserves original Goals and Non-Goals** unmodified for historical contrast against the new Implementation Reality section
+- **The per-tool impact map is evidence, not a stored artifact** -- it feeds directly into harness improvement specs rather than being persisted separately
+
+## Source Flow
+
+[ref:.allhands/flows/COMPOUNDING.md::905aed8]

package/docs/flows/coordination.md

@@ -0,0 +1,72 @@
+---
+description: "Engineer-facing orchestration agent for managing active prompt loops, agent health, and mid-execution interventions"
+---
+
+# Coordination Flow
+
+The coordination flow provides an engineer-facing orchestration layer during active prompt execution. It exists because prompt loops are autonomous -- once started, agents execute prompts independently. The engineer needs a control plane to intervene, patch, and steer without breaking the execution model.
+
+Per **Frontier Models are Capable**, this agent orchestrates without implementing. It modifies only harness-managed files (prompts, alignment docs) and never writes implementation code.
+
+## Coordination Services
+
+The flow presents six services to the engineer, each addressing a different intervention need:
+
+| Service | Purpose | Delegation |
+|---------|---------|------------|
+| Quick Patch | Deterministic fix for a specific issue | [ref:.allhands/flows/shared/PROMPT_TASKS_CURATION.md::1abf30b] |
+| Interjection | Insert new prompt into active dependency graph | Internal (see below) |
+| Emergent Surgery | Triage emergent refinement prompts | [ref:.allhands/flows/shared/EMERGENT_REFINEMENT_ANALYSIS.md::f3f4914] |
+| Prompt Edit | Modify prompts given engineer concerns | [ref:.allhands/flows/shared/PROMPT_TASKS_CURATION.md::1abf30b] |
+| Agent Status | Check tmux windows and agent health | Tmux patterns |
+| Kill/Restart | Terminate broken agents and fix prompts | Tmux + prompt edit |
+
+## Prompt Interjection
+
+Interjection is the most architecturally significant service. It inserts new prompts into the active dependency graph mid-loop without renumbering existing prompts. The event loop detects new prompt files automatically -- sequencing is controlled entirely through dependency mapping.
+
+```mermaid
+flowchart LR
+    subgraph Before
+        P1[Prompt 1] --> P2[Prompt 2]
+        P2 --> P3["Prompt 3 (deps: [1])"]
+    end
+    subgraph After
+        P1b[Prompt 1] --> P2b[Prompt 2]
+        P2b --> P7["Prompt 7 (deps: [2])"]
+        P7 --> P3b["Prompt 3 (deps: [1, 7])"]
+    end
+```
+
+The interjection process:
+
+1. Engineer specifies "run after" and "run before" prompts
+2. Coordinator assigns next available prompt number (append-only, never renumber)
+3. New prompt gets `dependencies` set to "run after" prompts
+4. "Run before" prompts get their `dependencies` patched to include the new prompt
+5. Per **Ideation First**, resulting execution order is confirmed with the engineer before writing files
+
+When an interjection fixes prior execution issues, the prompt is additionally marked as a user-patch.
+
+## User-Patch Prompts
+
+A cross-cutting concern shared between services. Whenever a prompt is created to fix issues from prior execution:
+
+- Frontmatter includes `type: user-patch` and `patches_prompts: [X, Y]`
+- Body documents what went wrong, engineer feedback, and specific issues
+- Per **Knowledge Compounding**, this metadata enables the compounding flow to trace failures back to root causes and improve skills/validation suites
+
+## Decision Documentation
+
+Per **Knowledge Compounding**, the coordination flow captures engineer contributions in two locations:
+
+- **Prompt files**: Expectations, compromises, decisions
+- **Alignment doc**: Engineer steering appended to agent summaries (summaries are never deleted)
+
+## Conversational Approach
+
+Per **Ideation First**, the coordinator always clarifies before acting. It asks what the engineer wants to accomplish, presents options with tradeoffs, confirms understanding before modifying files, and surfaces relevant context from prompts and the alignment doc. This is an interactive agent, not a fire-and-forget automation.
+
+## Source Flow
+
+[ref:.allhands/flows/COORDINATION.md::607d330]

package/docs/flows/core-harness-integration.md

@@ -0,0 +1,63 @@
+---
+description: "Core tooling directives shared by all agents, establishing tldr and ah knowledge as the foundation for context-efficient codebase discovery"
+---
+
+# Core Harness Integration
+
+Every agent in the harness loads [ref:.allhands/flows/CORE.md::ae9924a] as its foundation. This flow exists because of a single principle: **Context is Precious**. Agents degrade with large context windows, so codebase discovery must be targeted and structured rather than brute-force file reading.
+
+## Two Mandatory Discovery Tools
+
+The core integration enforces two tools for all codebase interaction:
+
+| Tool | Purpose | When |
+|------|---------|------|
+| `ah knowledge docs search` | Semantic search over documented project knowledge | Any discovery task tied to crucial project understanding |
+| `tldr` | Structured code analysis (trees, codemaps, control flow, data flow) | Retrieving file-level and function-level codebase context |
+
+These replace ad-hoc file reads. The constraint is deliberate: agents that read files directly consume context on content that may be irrelevant. Structured tools return only what matters.
+
+## Discovery Protocol
+
+The mandated sequence reflects a progressive disclosure pattern -- start broad, narrow to specifics:
+
+```mermaid
+flowchart TD
+    A[Codebase Question] --> B[tldr semantic search]
+    B --> C{Need deeper analysis?}
+    C -->|Structure| D[tldr structure / tree]
+    C -->|Search| E[tldr search]
+    C -->|Function behavior| F[tldr cfg / dfg]
+    C -->|Impact of change| G[tldr impact]
+    C -->|What affects line N| H[tldr slice]
+    C -->|Cross-file calls| I[tldr calls]
+    C -->|Quality check| J[tldr diagnostics]
+```
+
+## tldr Capability Categories
+
+### Core Analysis
+
+File trees, code structure maps, pattern search, full file extraction, and LLM-ready context bundles. These are the building blocks agents use before reading raw files.
+
+### Flow Analysis
+
+Control flow graphs, data flow graphs, program slices, and cross-file call graphs. These enable agents to understand function behavior without reading every line -- critical for keeping context budgets low.
+
+### Codebase Analysis
+
+Reverse call graphs (`impact`), dead code detection (`dead`), and architectural layer detection (`arch`). These support refactoring decisions and cleanup tasks.
+
+### Import Analysis
+
+Forward imports (`imports`) and reverse import tracking (`importers`). These answer "what does this file depend on?" and "who depends on this module?" -- essential for understanding blast radius.
+
+### Quality and Testing
+
+Type checking and linting via `diagnostics`. Agents run this before tests to catch errors without consuming test execution context.
+
+## Why This Exists as a Shared Flow
+
+Per **Knowledge Compounding**, centralizing these directives in a single flow prevents every agent-specific flow from repeating the same tooling instructions. All agents inherit codebase discovery capability from this one file, and improvements to discovery practices propagate to every agent simultaneously.
+
+The flow is deliberately terse -- per **Frontier Models are Capable**, agents deduce how to combine these tools for their specific tasks. The flow provides the "what tools exist and when to use them" while trusting agents to figure out the "how" for their domain.

package/docs/flows/documentation-orchestration.md

@@ -0,0 +1,98 @@
+---
+description: "Two-mode documentation pipeline with discovery sub-agents, writer sub-agents, and validation for creating and maintaining engineering knowledge docs"
+---
+
+# Documentation Orchestration
+
+The documentation flow creates and maintains engineering knowledge docs that expose code through file references and LSP symbols. Per **Knowledge Compounding**, docs enable semantic discovery of code through compounded understanding of use cases, intent, and key decisions.
+
+Per **Context is Precious**, the orchestrator delegates discovery and writing to sub-agents rather than performing all work in a single context window.
+
+## Mode Detection
+
+The flow operates in two modes, selected automatically based on context variables:
+
+```mermaid
+flowchart TD
+    Start[Flow Invoked] --> Check{ALIGNMENT_PATH + PROMPTS_FOLDER provided?}
+    Check -->|Yes| Inc[Incremental Mode]
+    Check -->|No| FTG[Fill-the-Gaps Mode]
+    Inc --> Core[Core Flow]
+    FTG --> Core
+```
+
+| Mode | Trigger | Scope | Knowledge Source |
+|------|---------|-------|-----------------|
+| Fill-the-Gaps | Cold start or refresh, no spec context | All domains, full repo scan | Inferred from code |
+| Incremental | Feature branch with spec context | Affected domains only | Prompts, commits, alignment docs |
+
+If no message or context variables are provided, the flow defaults directly to Fill-the-Gaps without asking.
+
+## Pre-flight Requirement
+
+A clean git working tree is mandatory. File references include a git commit hash component -- uncommitted files have no hash, and modified files produce stale hashes that break immediately after the next commit.
+
+## Fill-the-Gaps Initialization
+
+1. Run `ah docs validate --json` to identify invalid refs, stale refs, and missing frontmatter
+2. Detect domains: read `docs.json` or infer from project structure (checking monorepo markers like `pnpm-workspace.yaml`, `turbo.json`, `nx.json`)
+3. Present detected domains to user for confirmation
+4. Persist confirmed domains to `docs.json` for future incremental runs
+
+## Incremental Initialization
+
+1. Read alignment doc and prompt files for session knowledge
+2. Run `git diff` against merge base for changed files
+3. Run `ah docs validate --json` for current staleness
+4. Impact analysis via `ah knowledge docs search` to find related docs
+5. Categorize changes: **Edit** (existing docs reference changed code), **Create** (new functionality), **Stale** (outdated refs)
+
+## Core Pipeline
+
+Both modes converge into a shared four-phase pipeline:
+
+```mermaid
+flowchart TD
+    D[Discovery Phase] --> A[Aggregate & Plan]
+    A --> W[Writing Phase]
+    W --> P[Post-Processing]
+
+    D -.- D1[1 sub-agent per domain]
+    W -.- W1[5-10 writer sub-agents]
+    W1 -.- W2[5-15 approaches per writer]
+    P -.- P1[README generation + validation loop]
+```
+
+### Discovery Phase
+
+One discovery sub-agent per domain, each following [ref:.allhands/flows/shared/DOCUMENTATION_DISCOVERY.md::f3f2716]. Discovery identifies all documentable approaches/features, groups them intelligently, and checks existing coverage. Key constraint: stay under 20 approaches per domain, grouping aggressively.
+
+### Aggregate and Plan
+
+The orchestrator merges discovery results, filters out fully-covered approaches, and groups remaining approaches into writer assignments. Target: 5-10 writers total, each handling 5-15 approaches from one domain or related subset.
+
+### Writing Phase
+
+Writer sub-agents follow [ref:.allhands/flows/shared/DOCUMENTATION_WRITER.md::8447f47]. Each writer receives its approaches with file lists, symbols, the target directory, any existing docs to edit, and session knowledge (in incremental mode). The `group` field controls subdirectory placement.
+
+### Post-Processing
+
+The orchestrator handles cross-domain concerns that individual writers lack context for:
+
+- **README generation**: Top-level `docs/README.md`, per-domain `docs/<domain>/README.md`, and per-group READMEs for subdirectories with 3+ docs
+- **Finalize and validate loop**: Run `ah docs finalize`, then `ah docs validate --json`. If issues exist, spawn fixup writers and repeat until clean
+- **Reindex**: Run `ah knowledge docs reindex` to update semantic search
+
+## Ownership Boundaries
+
+| Artifact | Owner |
+|----------|-------|
+| Approach docs | Writer sub-agents |
+| README.md files | Orchestrator (cross-domain context) |
+| `docs/solutions/`, `docs/memories.md` | Compounding flow (never written by documentation) |
+
+## Source Flows
+
+- [ref:.allhands/flows/DOCUMENTATION.md::dc3e5c6]
+- [ref:.allhands/flows/shared/DOCUMENTATION_DISCOVERY.md::f3f2716]
+- [ref:.allhands/flows/shared/DOCUMENTATION_WRITER.md::8447f47]

package/docs/flows/e2e-test-plan-building.md

@@ -0,0 +1,83 @@
+---
+description: "Flow for building comprehensive E2E test plans with dimension-mapped sections: deterministic integration tests, infrastructure setup, stochastic AI-coordinated validation, and manual verification flows for milestone validation"
+---
+
+# E2E Test Plan Building
+
+The E2E test plan flow produces a document that convinces the engineer a milestone works as expected. Per **Agentic Validation Tooling**, engineers are excluded from prompt-by-prompt validation -- this plan provides the comprehensive proof they need through a single artifact.
+
+The plan is not a restatement of automated test output. It layers deterministic summaries, infrastructure setup, AI-coordinated validation, and manual flows into a progressive document the engineer can use to verify the milestone end-to-end.
+
+## Plan Structure
+
+The test plan follows a four-section progressive structure, where each section builds on the previous:
+
+```mermaid
+flowchart TD
+    S1["Section 1: Deterministic Test Summary"] --> S2["Section 2: Infrastructure Setup"]
+    S2 --> S3["Section 3: AI-Coordinated Validation"]
+    S3 --> S4["Section 4: Manual E2E Flows"]
+
+    S1 -.- N1["Concise command list with comments"]
+    S2 -.- N2["Derived from implementation artifacts"]
+    S3 -.- N3["Conditional — only if agentic tooling exists"]
+    S4 -.- N4["Core 'convince the engineer' section"]
+```
+
+### Dimension Mapping
+
+Per **Agentic Validation Tooling**, the test plan sections map to the two-dimensional validation model:
+
+| Section | Validation Dimension | Suite Body Section |
+|---------|---------------------|--------------------|
+| Section 1: Deterministic Test Summary | **Deterministic** | Commands drawn from suite **Deterministic Integration** sections |
+| Section 3: AI-Coordinated Validation | **Stochastic** | Agent exploration drawn from suite **Stochastic Validation** playbooks |
+| Section 2 & 4 | N/A | Infrastructure and manual flows are not dimension-mapped |
+
+### Section Design Decisions
+
+| Section | What It Contains | What It Avoids |
+|---------|-----------------|----------------|
+| Deterministic Test Summary | Runnable commands grouped by domain, inline comments | Detailed breakdowns, file listings, coverage percentages |
+| Infrastructure Setup | Dependencies, env, database, services, dev servers | Assumed knowledge; derives everything from artifacts |
+| AI-Coordinated Validation | Agent prompts for Playwright MCP, agent-browser, load testing, profiling | Inclusion when no agentic tooling exists for the project |
+| Manual E2E Flows | User flows, edge cases, regression scenarios | Duplicating what automated tests already cover |
+
+## Update Mode
+
+The plan supports incremental updates. When a test plan already exists at the output path:
+
+1. Extract `last_commit` from frontmatter
+2. Diff commits and files since that commit
+3. Compare alignment doc prompt summaries against covered prompts
+4. Append new scenarios rather than rewriting existing coverage
+
+This makes the plan a living document that grows with the milestone.
+
+## Variant Awareness
+
+Per **Quality Engineering**, implementation may produce disposable variants (A/B implementations, backend alternatives, experimental features). The infrastructure setup section documents how to switch between variants using feature flags, environment variables, or infrastructure flags, with setup commands for each testable variant.
+
+## Infrastructure as Documentation Quality Signal
+
+A key insight: if infrastructure setup cannot be derived from implementation artifacts (commits, summaries, code, existing docs), it signals inadequate documentation. The subsequent documentation phase will face the same challenge. This makes the E2E test plan an early warning system for documentation gaps.
+
+## AI-Coordinated Validation
+
+Section 3 is conditional -- it only appears when the project has tooling that supports agentic testing:
+
+- UI automation (Playwright MCP, agent-browser, simulator automation, browser MCPs)
+- Load testing tools (k6, artillery, locust)
+- Performance profiling (flamegraphs, memory profilers, bundle analyzers)
+- Database inspection/scripting
+- API testing tools (curl automation, Postman/Insomnia MCPs)
+
+When present, the section provides example prompts engineers can give to agent sessions to exercise specific flows. When absent, the section notes which tooling categories would be valuable.
+
+### Context Gathering for Tooling
+
+Per [ref:.allhands/flows/E2E_TEST_PLAN_BUILDING.md::aa87ec8], during context gathering the flow runs `ah validation-tools list` to identify available suites. The `tools` field in suite output identifies which tooling is available for both stochastic and deterministic dimensions -- this informs which Section 3 tooling categories the project can support and surfaces tooling that may not be obvious from code inspection alone.
+
+## Source Flow
+
+[ref:.allhands/flows/E2E_TEST_PLAN_BUILDING.md::aa87ec8]

package/docs/flows/emergent-refinement.md

@@ -0,0 +1,104 @@
+---
+description: "Hypothesis-driven emergent planning for continuous improvement beyond planned prompts -- a plan-only agent that creates typed prompt files for executors, with work mode diversification and post-refinement analysis"
+---
+
+# Emergent Refinement
+
+Planned prompts address known requirements. Emergent refinement addresses the unknown -- the improvements, extensions, and experiments that only become visible after initial implementation exists. Per **Quality Engineering**, emergent work discovers which variants are valuable, not just what was explicitly requested.
+
+## Core Concept: Hypothesis-Driven Planning
+
+Every emergent prompt starts with a hypothesis: "If I implement X, then Y outcome will result." This is fundamentally different from planned prompts, which start with "The spec requires X." The hypothesis framing forces agents to articulate expected outcomes, making success measurable and failure informative.
+
+The emergent agent is a **plan-only** agent -- it creates `type: emergent` prompt files but never executes them. Executors pick up these prompts through the standard execution loop. This separation of planning and execution keeps each concern bounded in its own context window.
+
+[ref:.allhands/flows/EMERGENT_PLANNING.md::4f1d9bf]
+
+## Planning Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> ContextGathering
+    ContextGathering --> GapAssessment
+    GapAssessment --> HypothesisFormation
+    HypothesisFormation --> PromptCreation
+    PromptCreation --> [*]
+
+    state ContextGathering {
+        [*] --> ReadAlignment
+        ReadAlignment --> SearchMemories
+        SearchMemories --> IdentifyGaps
+    }
+
+    state PromptCreation {
+        [*] --> DiscoverValidation
+        DiscoverValidation --> CreatePromptFiles
+        CreatePromptFiles --> Stop
+    }
+```
+
+The planner stops after creating prompt files. Executors handle implementation, and validation suites discovered by the planner are attached to prompts for executors to run.
+
+## Work Mode Diversification
+
+Emergent agents select from three work modes, cycling between them based on what prior prompts have already explored:
+
+```mermaid
+flowchart LR
+    CC[Core Goal Work] -->|reveals gaps| AI[Adjacent Improvements]
+    AI -->|exposes new core needs| CC
+    AI -->|stress-tests assumptions| NE[Novel Experiments]
+    NE -->|compounds back into| CC
+```
+
+| Mode | Purpose | Examples |
+|------|---------|---------|
+| Core Goal Work | Directly addresses spec goals, acceptance criteria, known gaps | Missing edge cases, error recovery paths |
+| Adjacent Improvements | Tangentially related enhancements that compound core work | Performance optimization, UX polish |
+| Novel Experiments | Creative extensions behind feature flags that stress-test assumptions | Alternative approaches, exploratory features |
+
+These are not sequential phases. An agent doing novel experiments may discover a core stability gap, returning to consolidation. Per **Knowledge Compounding**, each mode feeds the others -- adjacent work exposes core needs, novel work stress-tests assumptions.
+
+## Validation Discovery
+
+The planner discovers applicable validation suites during prompt creation and attaches them to prompt frontmatter via `validation_suites`. The planner does not run validation -- executors do when they pick up the prompts. This ensures emergent work meets the same quality bar as planned work without conflating planning with execution.
+
+## Completion Protocol
+
+The planner completes after creating prompt files. Each prompt includes the work mode type in its metadata so subsequent emergent planning rounds can diversify their mode selection. Alignment files and prompt files are not git tracked -- only implementation changes committed by executors are.
+
+The planner must always produce at least one prompt. If core goals are met, it creates adjacent improvements or novel experiments. Per **Knowledge Compounding**, each round compounds work.
+
+## Post-Refinement Analysis
+
+[ref:.allhands/flows/shared/EMERGENT_REFINEMENT_ANALYSIS.md::f3f4914]
+
+After a batch of emergent prompts completes, an analysis phase evaluates each one:
+
+### Classification Decision Tree
+
+```mermaid
+flowchart TD
+    EP[Emergent Prompt] --> E{Evaluate}
+    E -->|Strong hypothesis, effective, aligned| K[Keep]
+    E -->|Good hypothesis, execution gaps| I[Improve]
+    E -->|Hypothesis doesn't support goal| EL[Eliminate]
+
+    I --> IP[Create improvement patch prompt]
+    EL --> RP[Create reversion patch prompt]
+    K --> Done[No action needed]
+```
+
+| Classification | Criteria | Action |
+|---------------|----------|--------|
+| Keep | Strong hypothesis, effective execution, aligned with goals | None |
+| Improve | Good hypothesis, but execution gaps remain | Create `type: user-patch` improvement prompt |
+| Eliminate | Hypothesis doesn't support spec goal | Create `type: user-patch` reversion prompt using git hashes |
+
+### Engineer Decision Point
+
+The analysis presents findings holistically -- comparing emergent prompts against each other, highlighting patterns of effective versus ineffective hypotheses. The engineer accepts, adjusts, or overrides recommendations. Per **Knowledge Compounding**, all decisions and rationale are documented in the alignment doc to prevent future agents from re-proposing eliminated approaches.
+
+## Why Emergent Refinement Exists
+
+Per **Prompt Files as Units of Work**, novelty emerges from prompt tasking. Planned prompts capture what engineers know they want. Emergent refinement captures what they didn't know they wanted until the system existed. The separation of planning from execution ensures the planner can focus entirely on hypothesis quality while executors focus on implementation quality. The framing as "indefinite compounding" rather than "percentage complete" reflects the principle that there is always a next valuable iteration to discover.

package/docs/flows/flow-authoring-and-mcp-tools.md

@@ -0,0 +1,89 @@
+---
+description: "Guidelines for authoring harness flow files driven by first principles and adding MCP server integrations to extend harness capabilities"
+---
+
+# Flow Authoring and MCP Tool Integration
+
+Two complementary authoring guidelines: one for writing harness flows (the instruction layer), one for adding MCP server integrations (the tool layer). Both shape how agents receive direction and capability.
+
+---
+
+## Flow Authoring
+
+[ref:.allhands/flows/shared/WRITING_HARNESS_FLOWS.md::f39048c]
+
+### Principle-to-Directive Mapping
+
+Every flow directive traces back to a first principle from [ref:.allhands/principles.md::0610b13]. This mapping is the foundation of flow authoring:
+
+| First Principle | What It Means for Flows |
+|-----------------|------------------------|
+| **Context is Precious** | Be brief. Progressive disclosure. Reference rather than repeat. |
+| **Frontier Models are Capable** | Provide "why," trust agents to deduce "what" and "how." |
+| **Knowledge Compounding** | DRY -- centralize instructions, use decision trees that reference capability chunks. |
+
+When a flow instructs a behavior, it must cite the motivating principle by name. This teaches agents to think in terms of the harness philosophy, not just follow instructions.
+
+### Flow Anatomy
+
+Flows use XML tags for structural attention:
+
+| Tag | Purpose |
+|-----|---------|
+| `<goal>` | Motivations and contribution to the wider harness |
+| `<constraints>` | Hard rules (NEVER / MUST / ALWAYS) |
+| `<ownership>` | Files and domains the agent is restricted to |
+| `<success_criteria>` | Validation criteria for task completion |
+| `<inputs>` | Inputs required for the flow to execute |
+| `<outputs>` | Outputs expected from the flow |
+
+Body sections use `##` headers as capability phases (Context Gathering, Implementation, Validation, Completion). Bullet points start with action verbs. Paths and commands are backtick-wrapped. Conditionals use flat "If X - Y" patterns.
+
+### File Organization
+
+- `flows/` root: Agent default flows, disclosed immediately on agent startup
+- `flows/subdirectories/`: Progressively disclosed flows with `<inputs>` and `<outputs>` tags, invoked by other flows
+
+The northstar example flow is [ref:.allhands/flows/PROMPT_TASK_EXECUTION.md::9baf478].
+
+---
+
+## MCP Server Integration
+
+[ref:.allhands/flows/shared/WRITING_HARNESS_MCP_TOOLS.md::fad1587]
+
+### Integration Phases
+
+```mermaid
+flowchart LR
+    R[Research] --> B[Build Config]
+    B --> E[Environment Setup]
+    E --> V[Validation]
+```
+
+**Research**: Investigate the MCP package via `ah tavily search` and `ah context7 search`. Identify transport type (stdio, http, sse), command/args, environment variables, and authentication method.
+
+**Build Config**: Copy the template at `.allhands/harness/src/mcp/_template.ts` and populate with researched values -- name, description, transport config, environment variable references using `${VAR_NAME}` syntax, statefulness, and tool hints.
+
+**Environment Setup**: Document required variables (name, where to obtain, expected format) without adding actual values. Check `.env.ai` for existing variables.
+
+**Validation**: Build harness, verify server appears in `ah tools --list`, verify tools are discovered via `ah tools <server-name>`, and test a read-only tool call.
+
+### Config Structure
+
+Each MCP server config lives at `.allhands/harness/src/mcp/<server-name>.ts` and specifies:
+
+| Field | Purpose |
+|-------|---------|
+| `name` | Short identifier (used in `ah tools <name>:tool`) |
+| `description` | What the server provides |
+| `type` | Transport: `stdio`, `http`, or `sse` |
+| `command` / `args` | For stdio transport |
+| `url` | For http/sse transport |
+| `env` | Environment variable references |
+| `stateful` | Whether server maintains session state |
+| `toolHints` | Helpful hints for key tools |
+
+### Design Decision: Sub-agent Execution
+
+MCP integration runs as a sub-agent to avoid blocking the main thread. The main thread can proceed knowing the MCP server is (or will be) available, receiving a completion report with config path, available tools, environment requirements, and validation status.