all-hands-cli 0.1.0

package/concerns.md

@@ -0,0 +1,7 @@
+1. When we implement a parallel task implementation mode (not for a while) we will need to figure out a few things:
+ A: How to have two EMERGENT_REFINEMENT tasks not choose to work on the exact same thing? (do we cap these to just 1 at a time?) (how do we merge their work if this is the case?)
+ B: Reserving specific single instance infrastructure from validation tooling. (Do we just work to make it so that all vliadation tools can be run in a completely seperate instance? Ideally yes...)
+
+
+ 2. When prompt loops are in effect, we should have a globally session stored flag that shows that there are prompts are currently being implemented. This will be used to stop:
+  A: Switching current spec

package/docs/README.md

@@ -0,0 +1,41 @@
+---
+description: "Top-level documentation index covering all four domains of the all-hands framework: harness CLI, agent flows, agent configurations, and the sync CLI."
+---
+
+# All-Hands Documentation
+
+Engineering knowledge for the all-hands agentic development framework. Documentation exposes code intent, key decisions, and system relationships via file references for semantic discovery.
+
+## Domains
+
+### Harness
+
+The core CLI tool powering agent orchestration. Commands for planning, knowledge search, schema validation, spec management, agent spawning, MCP tooling, observability, and more. Includes the TUI, event loop, hook system, and test infrastructure.
+
+`docs/harness/README.md`
+
+### Flows
+
+Workflow definitions that guide agents through tasks. Covers the full lifecycle: ideation, spec planning, prompt execution, judge reviewing, emergent refinement, compounding, coordination, and documentation generation.
+
+`docs/flows/README.md`
+
+### Agents
+
+Agent configuration profiles and initiative orchestration. Defines agent types (planning, execution, quality review, orchestration, knowledge), the YAML configuration system, and how initiative types and settings.json shape agent behavior.
+
+`docs/agents/README.md`
+
+### Sync CLI
+
+CLI for distributing the all-hands framework to other repositories. Handles framework syncing with conflict resolution, upstream contribution via GitHub fork/PR, manifest-based file filtering, and interactive terminal prompts.
+
+`docs/sync-cli/README.md`
+
+## Cross-Domain Relationships
+
+- **Agents reference Flows**: Each agent profile in `docs/agents/README.md` points to a flow file that defines its behavior from `docs/flows/README.md`
+- **Harness executes Agents**: The spawn command `docs/harness/cli/spawn-command.md` loads agent profiles, and the event loop `docs/harness/event-loop.md` orchestrates prompt dispatch
+- **Hooks enforce Flows**: Context hooks `docs/harness/hooks/context-hooks.md` and validation hooks `docs/harness/hooks/validation-hooks.md` enforce flow directives at the tool level
+- **Sync distributes Harness**: The sync CLI `docs/sync-cli/README.md` packages and distributes the harness to target repositories
+- **Knowledge connects everything**: The knowledge command `docs/harness/cli/knowledge-command.md` indexes docs, solutions, and memories for semantic discovery across all domains

package/docs/agents/README.md

@@ -0,0 +1,24 @@
+---
+description: "Index of agent domain documentation covering the configuration system, agent categories (planning, execution, quality, orchestration, knowledge), and initiative orchestration."
+---
+
+# Agents
+
+Agent profiles define types, behaviors, and TUI integration via YAML configuration. Agents are grouped by their role in the development lifecycle.
+
+## Configuration
+
+| Topic | Doc |
+|---|---|
+| YAML schema, validation, template variables | `docs/agents/agent-configuration-system.md` |
+| Hypothesis domains and initiative types | `docs/agents/workflow-agent-orchestration.md` |
+
+## Agent Categories
+
+| Category | Agents | Doc |
+|---|---|---|
+| Planning | ideation, planner, emergent (hypothesis planner) | `docs/agents/planning-agents.md` |
+| Execution | executor | `docs/agents/execution-agents.md` |
+| Quality & Review | judge, pr-reviewer, e2e-test-planner | `docs/agents/quality-review-agents.md` |
+| Orchestration | coordinator | `docs/agents/orchestration-agent.md` |
+| Knowledge | compounder, documentor | `docs/agents/knowledge-agents.md` |

package/docs/agents/agent-configuration-system.md

@@ -0,0 +1,86 @@
+---
+description: "Zod-based agent profile schema that validates YAML agent definitions, enforces template variable contracts, and normalizes configs for TUI integration"
+---
+
+# Agent Configuration System
+
+Agent profiles are YAML declarations that define how agents are spawned, what context they receive, and how the TUI presents them. The system uses Zod schemas for runtime validation, replacing static YAML schema files with type-safe, self-documenting validation.
+
+## Profile Schema Fields
+
+Every agent YAML file is validated against [ref:.allhands/harness/src/lib/schemas/agent-profile.ts:RawAgentProfileSchema:fb892e5], which enforces this contract:
+
+| Field | Type | Default | Purpose |
+|-------|------|---------|---------|
+| `name` | string (required) | -- | Agent identifier, doubles as tmux window name |
+| `flow` | string (required) | -- | Flow file relative to `.allhands/flows/` |
+| `prompt_scoped` | boolean | `false` | When true, multiple instances spawn (one per prompt) |
+| `message_template` | string | -- | Template with `${VAR}` interpolation for launch context |
+| `template_vars` | array | `[]` | Required variables declared for the template |
+| `tui_action` | string | -- | TUI action name that triggers this agent |
+| `tui_label` | string | -- | Display label in TUI (falls back to capitalized name) |
+| `tui_requires_spec` | boolean | `false` | Gates TUI action behind active spec selection |
+| `non_coding` | boolean | `false` | Marks agent as non-coding, affecting downstream behaviors |
+
+## Template Variable System
+
+Template variables are the mechanism through which agents receive runtime context at spawn. The variable registry lives in [ref:.allhands/harness/src/lib/schemas/template-vars.ts:TemplateVars:730f114] and defines four categories:
+
+**Path variables** -- resolve to filesystem locations:
+- `SPEC_PATH`, `ALIGNMENT_PATH`, `PROMPTS_FOLDER`, `PROMPT_PATH`, `OUTPUT_PATH`, `PLANNING_FOLDER`
+
+**Identifier variables** -- resolve to names or numbers:
+- `SPEC_NAME`, `PROMPT_NUMBER` (validated as two-digit string via regex)
+
+**Branch/context variables** -- resolve to runtime state:
+- `BRANCH` (current git branch name)
+
+**Spec metadata variables** -- resolve to spec properties:
+- `SPEC_TYPE` (spec type from frontmatter: milestone, investigation, optimization, refactor, documentation, triage)
+
+**Emergent planner variables** -- resolve to settings-driven context:
+- `HYPOTHESIS_DOMAINS` (comma-separated list of hypothesis domains from `settings.json`)
+
+> **Change note**: `WORKFLOW_TYPE` has been removed. It was replaced by `SPEC_TYPE`, which reads directly from spec frontmatter rather than from workflow YAML files (which have been deleted). `PROMPT_NUMBER` is no longer used by the emergent agent but remains in the registry for other agents.
+
+Template resolution validates that every `${VAR}` in `message_template` maps to a registered variable name in [ref:.allhands/harness/src/lib/schemas/template-vars.ts:TEMPLATE_VAR_NAMES:730f114], and that the runtime context provides non-empty values for all declared `template_vars`.
+
+## Validation Pipeline
+
+Profile validation happens in two stages:
+
+```mermaid
+flowchart LR
+    YAML["YAML Parse"] --> Schema["Zod Schema\nValidation"]
+    Schema --> Normalize["normalizeProfile()"]
+    Normalize --> Semantic["validateProfileSemantics()"]
+    Semantic --> Valid["Ready to Spawn"]
+```
+
+1. **Schema validation** -- [ref:.allhands/harness/src/lib/schemas/agent-profile.ts:RawAgentProfileSchema:fb892e5] checks types, applies defaults, and rejects unknown fields
+2. **Normalization** -- [ref:.allhands/harness/src/lib/schemas/agent-profile.ts:normalizeProfile:fb892e5] transforms snake_case YAML fields to camelCase TypeScript, producing the [ref:.allhands/harness/src/lib/schemas/agent-profile.ts:AgentProfile:fb892e5] interface
+3. **Semantic validation** -- [ref:.allhands/harness/src/lib/schemas/agent-profile.ts:validateProfileSemantics:fb892e5] performs cross-field checks:
+   - Every `${VAR}` in `message_template` must exist in `template_vars`
+   - Every entry in `template_vars` must be referenced in `message_template`
+   - Template variables must be registered in [ref:.allhands/harness/src/lib/schemas/template-vars.ts:TemplateVars:730f114]
+
+Semantic validation returns warnings (not errors) for unused variables, allowing forward-compatible profiles.
+
+## Non-Coding Agents
+
+Three agents are configured with `non_coding: true`:
+
+| Agent | Role |
+|-------|------|
+| Coordinator | Cross-phase orchestration |
+| Judge | Milestone quality gate |
+| Emergent | Hypothesis planning (plan-only, creates prompt files for executors) |
+
+The emergent agent was rearchitected from a coding execution agent to a non-coding planning agent. It is `prompt_scoped: true` but `non_coding: true` -- multiple instances spawn to create prompt files across hypothesis domains, but none write code directly.
+
+## Key Design Decisions
+
+- **Snake_case YAML, camelCase TypeScript**: Agent configs are authored in YAML-idiomatic snake_case. The normalization layer bridges to TypeScript conventions, keeping both sides natural.
+- **Closed variable registry**: Only variables registered in [ref:.allhands/harness/src/lib/schemas/template-vars.ts:TEMPLATE_VAR_NAMES:730f114] can be used. This prevents typos and ensures every variable has a documented purpose via Zod `.describe()`.
+- **Prompt-scoped multiplexing**: The `prompt_scoped` flag distinguishes singleton agents (planner, judge, coordinator) from parallelizable agents (executor, emergent). The TUI uses this to spawn N instances for N prompts. Note that prompt-scoped does not imply coding -- the emergent agent is prompt-scoped but non-coding.
+- **TUI as first-class concern**: The `tui_action`, `tui_label`, and `tui_requires_spec` fields embed presentation logic directly in the profile, avoiding a separate UI configuration layer.

package/docs/agents/execution-agents.md

@@ -0,0 +1,50 @@
+---
+description: "Executor agent that implements prompt files as code changes -- the sole execution agent, one instance per prompt for parallel implementation"
+---
+
+# Execution Agents
+
+The executor is the only agent that produces code changes from pre-authored prompt files. It is **prompt-scoped** (`prompt_scoped: true`), meaning the harness spawns multiple parallel instances -- one per prompt. This is the core parallelism mechanism in the harness.
+
+> **Note**: The emergent agent was previously grouped here as an execution agent. It has been rearchitected to a plan-only hypothesis planner (`non_coding: true`) and now belongs with the planning agents. See [docs/agents/planning-agents.md](planning-agents.md).
+
+## Executor Configuration
+
+[ref:.allhands/agents/executor.yaml::a0ae2f8]
+
+| Field | Value |
+|-------|-------|
+| Flow | `PROMPT_TASK_EXECUTION.md` |
+| Prompt scoped | Yes |
+| Non-coding | No |
+| TUI action | `executor` |
+| Requires spec | Yes |
+| Template vars | `PROMPT_PATH`, `ALIGNMENT_PATH` |
+
+The executor is the workhorse. It receives a single prompt file path and an alignment doc, then implements exactly what the prompt specifies. Its simplicity is deliberate:
+
+- **One prompt, one executor** -- clear ownership and bounded context per **Context is Precious**
+- **No domain selection** -- the planner already decided what to build
+- **Alignment doc as guardrail** -- provides project-level conventions without bloating the prompt
+
+The executor's template injects only `PROMPT_PATH` and `ALIGNMENT_PATH`. All task scoping comes from the prompt file content itself. The first line of its message template is `DO NOT ask for any user input for this task.` -- it is fully autonomous.
+
+## Prompt-Scoped Parallelism
+
+```mermaid
+flowchart TD
+    TUI["TUI Spawn"] --> |"N prompts"| E1["Executor 1\nPrompt 01"]
+    TUI --> E2["Executor 2\nPrompt 02"]
+    TUI --> E3["Executor 3\nPrompt 03"]
+```
+
+Because `prompt_scoped: true`, the TUI multiplexes executor instances across available prompt files. Each executor maps 1:1 to an existing prompt, ensuring clear ownership boundaries. The planner determines what to build; executors determine how.
+
+## Relationship to Planning Phase
+
+Executors cannot begin until planning produces prompt files. The upstream agents that generate prompts are:
+
+- **Planner** -- decomposes specs into ordered prompt files during the planning phase
+- **Emergent** -- creates `type:emergent` prompt files during the hypothesis planning phase (see [planning-agents.md](planning-agents.md))
+
+Both produce prompt files that executors consume. The executor makes no distinction between planner-authored and emergent-authored prompts -- it implements whatever the prompt file specifies.

package/docs/agents/knowledge-agents.md

@@ -0,0 +1,61 @@
+---
+description: "Compounder and documentor agents that extract and persist engineering knowledge from completed milestone work into reusable artifacts"
+---
+
+# Knowledge Agents
+
+Knowledge agents run **after execution completes**. They do not produce features -- they produce understanding. Both the compounder and documentor transform completed work into durable knowledge artifacts, operationalizing the **Knowledge Compounding** principle: everything feeds forward.
+
+## Agent Comparison
+
+| Aspect | Compounder | Documentor |
+|--------|------------|------------|
+| Config | [ref:.allhands/agents/compounder.yaml::c9f0e13] | [ref:.allhands/agents/documentor.yaml::b4246b9] |
+| Flow | `COMPOUNDING.md` | `DOCUMENTATION.md` |
+| TUI label | Compounder | Documentor |
+| TUI action | `compound` | `compound` |
+| Requires spec | Yes | Yes |
+| Prompt scoped | No | No |
+| Non-coding | No | No |
+
+Both agents share identical template variables:
+- `SPEC_PATH` -- the completed spec for retrospective analysis
+- `ALIGNMENT_PATH` -- project conventions and accumulated decisions
+- `PROMPTS_FOLDER` -- completed prompt files containing implementation history
+
+## Shared TUI Action
+
+Both agents use `tui_action: compound`. This groups them as a single user-facing capability -- the compounding phase -- even though they run distinct flows. The TUI presents them as related operations on the same completed work.
+
+## Compounder Agent
+
+The compounder extracts **decisions, patterns, pivots, and limitations** from completed prompt work. Its output compounds the organization's knowledge base, making future planning and execution benefit from past work.
+
+What the compounder captures:
+- Why decisions were made (not just what was built)
+- Patterns that emerged during implementation
+- Limitations discovered that affect future specs
+- Best practices validated or invalidated by execution results
+
+This directly serves **Knowledge Compounding** -- decisions, pivots, limitations, disagreements, realizations, and best practices all feed forward.
+
+## Documentor Agent
+
+The documentor produces **documentation artifacts** from completed work. Where the compounder extracts tacit knowledge, the documentor produces explicit documentation tied to the codebase.
+
+The distinction matters: compounding captures organizational learning that lives in the harness knowledge base, while documentation produces artifacts (docs, READMEs, architecture decision records) that live alongside the code.
+
+## Lifecycle Position
+
+```mermaid
+flowchart LR
+    Judge["Judge\n(pass verdict)"] --> Knowledge["Knowledge Phase"]
+    Knowledge --> Compounder["Compounder\n(extract learnings)"]
+    Knowledge --> Documentor["Documentor\n(produce docs)"]
+    Compounder --> KB["Knowledge Base"]
+    Documentor --> Docs["Code Documentation"]
+    KB --> Future["Future Planning\n& Execution"]
+    Docs --> Future
+```
+
+Knowledge agents are the terminal phase of the milestone lifecycle. They run after the judge has approved the work, ensuring they operate on validated output rather than in-progress code. Their artifacts compound value for every subsequent milestone.

package/docs/agents/orchestration-agent.md

@@ -0,0 +1,57 @@
+---
+description: "Coordinator agent for milestone-level non-coding orchestration, managing spec work progression across planning, execution, and review phases"
+---
+
+# Orchestration Agent
+
+The coordinator is the only agent explicitly designed for **cross-phase orchestration**. It operates at the milestone level, tracking spec progression without writing code itself.
+
+## Configuration
+
+[ref:.allhands/agents/coordinator.yaml::27a9130]
+
+| Field | Value |
+|-------|-------|
+| Flow | `COORDINATION.md` |
+| TUI action | `coordinator` |
+| Non-coding | **Yes** |
+| Prompt scoped | No |
+| Requires spec | Yes |
+
+## Template Context
+
+The coordinator receives the broadest template context of any singleton agent:
+
+- `SPEC_NAME` -- the milestone being coordinated
+- `SPEC_PATH` -- full spec for requirement awareness
+- `ALIGNMENT_PATH` -- project conventions and decisions
+- `PROMPTS_FOLDER` -- visibility into prompt file state (planned, in-progress, completed)
+
+This four-variable context gives the coordinator full situational awareness across the spec's lifecycle without requiring it to read execution outputs directly.
+
+## Why Non-Coding Orchestration
+
+The coordinator is one of three `non_coding: true` agents (alongside the judge and emergent). This constraint is architectural, not incidental:
+
+- **Separation of concerns** -- coordination decisions (what to run next, what's blocked, what's done) must not be entangled with implementation
+- **Context preservation** -- a non-coding agent avoids accumulating code-level context that would dilute its orchestration judgment, per **Context is Precious**
+- **Role clarity** -- executors implement, the coordinator sequences; mixing these creates agents that do both poorly
+
+## Relationship to Other Agents
+
+```mermaid
+flowchart TD
+    Coordinator["Coordinator\n(non-coding)"]
+    Coordinator -->|"triggers"| Planner["Planner"]
+    Coordinator -->|"monitors"| Executors["Executors"]
+    Coordinator -->|"monitors output"| Emergent["Emergent Planner\n(creates prompts)"]
+    Coordinator -->|"triggers"| Judge["Judge"]
+
+    Planner -->|"produces"| Prompts["Prompt Files"]
+    Emergent -->|"produces"| Prompts
+    Prompts -->|"consumed by"| Executors
+    Executors -->|"complete"| Coordinator
+    Judge -->|"verdict"| Coordinator
+```
+
+The coordinator is the hub that connects phases. It does not directly control other agents -- the TUI handles spawning -- but it provides the decision-making layer for when phases transition. The coordinator monitors the emergent planner's output (new prompt files appearing in the prompts folder) rather than monitoring it as an executor, since the emergent agent now produces planning artifacts, not code changes. This maps to the **Quality Engineering** principle: the coordinator's role is judgment about sequencing, not implementation.

package/docs/agents/planning-agents.md

@@ -0,0 +1,84 @@
+---
+description: "Ideation, planner, and emergent agents that handle upstream work: free-form exploration, structured spec decomposition, and hypothesis-driven prompt planning"
+---
+
+# Planning Agents
+
+Planning agents operate upstream of execution. They translate human intent into machine-executable prompt files -- the fundamental unit of work in the harness. Three agents divide this responsibility: ideation explores the problem space freely, the planner decomposes a spec into ordered prompts, and the emergent agent creates hypothesis-driven prompt files across quality domains.
+
+## Agent Comparison
+
+| Aspect | Ideation | Planner | Emergent |
+|--------|----------|---------|----------|
+| Config | [ref:.allhands/agents/ideation.yaml::faf0f2d] | [ref:.allhands/agents/planner.yaml::9013364] | [ref:.allhands/agents/emergent.yaml::9b6a9d4] |
+| Flow | `IDEATION_SESSION.md` | `SPEC_PLANNING.md` | `EMERGENT_PLANNING.md` |
+| Requires spec | No | Yes | Yes |
+| Prompt scoped | No | No | Yes |
+| Non-coding | No | No | **Yes** |
+| Template vars | None | `SPEC_NAME`, `SPEC_PATH`, `PROMPTS_FOLDER` | `ALIGNMENT_PATH`, `PROMPTS_FOLDER`, `HYPOTHESIS_DOMAINS`, `BRANCH` |
+| TUI action | `new-initiative` | `planner` | `emergent` |
+| TUI label | Ideation | Planner | Emergent |
+
+## Ideation Agent
+
+The ideation agent is the only agent that requires **no spec context**. It runs the `IDEATION_SESSION.md` flow with an empty message template, making it a blank-slate exploration tool. This aligns with the **Ideation First** principle -- front-loading exploration prevents low-level decision fatigue during implementation and discovers limitations before they block progress.
+
+Key characteristics:
+- No `template_vars` and empty `message_template` -- the agent receives no pre-structured context
+- Not prompt-scoped -- runs as a singleton session
+- Produces specs and roadmap artifacts as output, feeding downstream agents
+- TUI action `new-initiative` routes through the ideation agent with a flow override for non-milestone spec types
+
+## Planner Agent
+
+The planner operates on a selected spec, decomposing it into prompt files within the spec's prompts folder. It receives three template variables that scope its work:
+
+- `SPEC_NAME` -- identifies the initiative being planned
+- `SPEC_PATH` -- the spec file containing requirements and acceptance criteria
+- `PROMPTS_FOLDER` -- the target directory where prompt files are written
+
+The planner embodies **Prompt Files as Units of Work** -- its sole output is an ordered set of prompt files that executors will pick up. Each prompt file scopes 3-5 tasks with clear validation requirements, keeping downstream context bounded per **Context is Precious**.
+
+## Emergent Agent (Hypothesis Planner)
+
+The emergent agent creates hypothesis-driven prompt files across quality domains. Unlike the planner (which decomposes a spec top-down), the emergent agent identifies quality gaps and generates `type:emergent` prompt files that executors later implement. It is the only planning agent that is both **prompt-scoped** and **non-coding**:
+
+- `non_coding: true` -- creates prompt files but does not write code
+- `prompt_scoped: true` -- multiple instances spawn in parallel, each exploring a different hypothesis domain
+- Flow: `EMERGENT_PLANNING.md` -- a plan-only flow (not an execution flow)
+
+Template variables provide the planning context:
+- `ALIGNMENT_PATH` -- project-level conventions and decisions
+- `PROMPTS_FOLDER` -- where to write new prompt files
+- `HYPOTHESIS_DOMAINS` -- available quality domains from `settings.json` (e.g., `testing, stability, performance, feature, ux, integration`)
+- `BRANCH` -- current git branch for scoping
+
+The emergent agent's message template instructs it to **select a domain that diversifies from prior prompts**, always producing at least one prompt file. It operates in three progressive work modes:
+
+1. **Core Goal Work** -- domains directly supporting the spec's acceptance criteria
+2. **Adjacent Improvements** -- domains that strengthen surrounding code quality
+3. **Novel Experiments** -- tangential domains that require feature flags, exploring beyond the spec's boundaries
+
+As core goals are met, the agent shifts progressively toward more tangential work. This creates a self-organizing planning cycle where each instance explores a different facet of quality, producing prompt files that executors consume downstream.
+
+> **Key decision**: "Emergent" is the canonical agent name; "hypothesis planner" describes its functional role. The agent was rearchitected from a combined plan-and-execute agent (previously `non_coding: false`, flow `EMERGENT_REFINEMENT_EXECUTION.md`) to a plan-only agent. It no longer uses `PROMPT_NUMBER` -- prompt numbering is handled by the prompts folder conventions.
+
+## Lifecycle Position
+
+```mermaid
+flowchart LR
+    Ideation["Ideation\n(explore)"] --> Spec["Spec Created"]
+    Spec --> Planner["Planner\n(decompose)"]
+    Planner --> Prompts["Prompt Files"]
+    Spec --> Emergent["Emergent\n(hypothesis plan)"]
+    Emergent --> EPrompts["type:emergent\nPrompt Files"]
+    Prompts --> Execution["Executor"]
+    EPrompts --> Execution
+```
+
+Ideation is optional and human-initiated. The planner and emergent agent both produce prompt files, but through different mechanisms:
+
+- **Planner** -- deterministic top-down decomposition of a spec into ordered prompts
+- **Emergent** -- hypothesis-driven exploration of quality gaps, creating emergent prompts
+
+Executors make no distinction between planner-authored and emergent-authored prompts. Both are consumed identically. This means all three planning agents feed into the same execution phase, with the emergent agent providing lateral quality coverage that the planner's structured decomposition may miss.

package/docs/agents/quality-review-agents.md

@@ -0,0 +1,67 @@
+---
+description: "Judge, PR reviewer, and E2E test planner agents that validate milestone quality: judge reviews holistically, PR reviewer processes feedback, test planner builds verification plans"
+---
+
+# Quality and Review Agents
+
+Three agents handle validation and review at different stages of the lifecycle. They share a common purpose -- ensuring work meets acceptance criteria -- but operate at different scopes and produce different outputs.
+
+## Agent Overview
+
+| Aspect | Judge | PR Reviewer | E2E Test Planner |
+|--------|-------|-------------|------------------|
+| Config | [ref:.allhands/agents/judge.yaml::597e87f] | [ref:.allhands/agents/pr-reviewer.yaml::631b3e9] | [ref:.allhands/agents/e2e-test-planner.yaml::89753a5] |
+| Flow | `JUDGE_REVIEWING.md` | `PR_REVIEWING.md` | `E2E_TEST_PLAN_BUILDING.md` |
+| TUI label | Review Jury | Review PR | E2E Tests |
+| Non-coding | **Yes** | No | No |
+| Requires spec | Yes | Yes | Yes |
+| Prompt scoped | No | No | No |
+
+## Judge Agent
+
+The judge is the milestone-level quality gate. It reviews completed work against the spec's acceptance criteria, operating as a **non-coding** agent (`non_coding: true`). This distinction matters: the judge evaluates but does not modify code.
+
+Template variables:
+- `SPEC_NAME` -- identifies what milestone is being judged
+- `ALIGNMENT_PATH` -- provides project conventions for evaluation context
+
+The TUI action `review-jury` signals its role as an adjudicator. The judge embodies **Agentic Validation Tooling** -- programmatic validation that makes human supervision redundant for routine quality checks. Its output determines whether a milestone proceeds to merge or returns for rework.
+
+## PR Reviewer Agent
+
+The PR reviewer translates external PR feedback (GitHub comments, review threads) into actionable prompt-level work. Unlike the judge, it **is a coding agent** -- it can create new prompt files or modify existing ones based on review feedback.
+
+Template variables:
+- `SPEC_NAME` -- the milestone under review
+- `ALIGNMENT_PATH` -- project conventions
+- `PROMPTS_FOLDER` -- where to write remediation prompts if needed
+
+This agent bridges the gap between human PR review and the prompt-based execution model. Rather than expecting developers to manually address review comments, the PR reviewer converts feedback into the harness's native work format.
+
+## E2E Test Planner Agent
+
+The E2E test planner produces structured test plans from spec requirements. It receives the richest template context of the three review agents:
+
+- `PLANNING_FOLDER` -- the `.planning/{branch}` directory for test plan artifacts
+- `SPEC_PATH` -- full spec for requirement extraction
+- `ALIGNMENT_PATH` -- project conventions including testing patterns
+- `OUTPUT_PATH` -- explicit output location for the generated test plan
+
+This agent operationalizes the **Agentic Validation Tooling** principle by creating verification infrastructure. Its test plans feed back into execution agents as validation requirements, closing the loop between "what should we test" and "is it working."
+
+## Review Lifecycle Position
+
+```mermaid
+flowchart TD
+    Execution["Execution Complete"] --> Judge["Judge\n(milestone review)"]
+    Judge -->|"Pass"| PR["PR Created"]
+    Judge -->|"Fail"| Rework["Back to Execution"]
+    PR --> PRReview["PR Reviewer\n(feedback triage)"]
+    PRReview -->|"Remediation prompts"| Execution
+
+    Spec["Spec Created"] --> E2E["E2E Test Planner"]
+    E2E -->|"Test plan"| Validation["Validation Artifacts"]
+    Validation --> Judge
+```
+
+The judge sits at the convergence point: it consumes execution output and test plan artifacts to render a verdict. The PR reviewer operates post-merge-request, handling the external feedback loop. The E2E test planner can run early -- as soon as a spec exists -- producing validation criteria that inform both execution and judgment.

package/docs/agents/workflow-agent-orchestration.md

@@ -0,0 +1,69 @@
+---
+description: "How hypothesis domains flow from settings.json to emergent planning agents, replacing the deleted workflow YAML system with initiative-type-driven orchestration"
+---
+
+# Workflow-Agent Orchestration
+
+Hypothesis domains shape how the emergent agent explores quality dimensions during planning. These domains were previously defined in workflow YAML files (`.allhands/workflows/milestone.yaml`, `.allhands/workflows/debugging.yaml`). That entire system has been deleted. Hypothesis domains now come from `settings.json` via `EmergentSettings`, and the concept of "workflow configurations" is replaced by **initiative types** -- six spec types that determine how work flows through the harness.
+
+## What Changed
+
+| Before | After |
+|--------|-------|
+| `.allhands/workflows/` directory with YAML files | **Deleted entirely** |
+| `milestone.yaml`, `debugging.yaml` configs | Hypothesis domains in `settings.json` |
+| `WORKFLOW_TYPE` template variable | `SPEC_TYPE` template variable |
+| Two workflow types (milestone, debugging) | Six initiative types via spec frontmatter |
+| Workflow loader (`workflow.ts`, `workflows.ts`) | Settings-based domain resolution |
+
+## Initiative Types
+
+The harness now supports six spec types, each representing a distinct initiative category:
+
+- `milestone` -- feature development with full planning-execution cycle
+- `investigation` -- exploratory analysis and research
+- `optimization` -- performance and efficiency improvements
+- `refactor` -- structural code improvements
+- `documentation` -- knowledge artifact production
+- `triage` -- issue diagnosis and resolution
+
+The spec type is parsed from frontmatter and made available via the [ref:.allhands/harness/src/lib/schemas/template-vars.ts:TemplateVars:730f114] `SPEC_TYPE` variable. Agents receive this at spawn, enabling type-aware behavior without separate workflow configuration files.
+
+## Hypothesis Domains
+
+Hypothesis domains remain the creative constraint mechanism for the emergent agent. Each domain represents a category of planning work the emergent agent can self-assign when creating prompt files.
+
+The domain list now comes from `settings.json` under `emergent.hypothesisDomains` (`EmergentSettings`), rather than from per-workflow YAML files. This centralizes domain configuration alongside other emergent agent settings.
+
+The emergent agent's [ref:.allhands/agents/emergent.yaml::9b6a9d4] template receives domains via the `HYPOTHESIS_DOMAINS` template variable. The agent selects a domain that diversifies from prior prompts, creating organic coverage across quality dimensions.
+
+## How Domains Flow to the Emergent Agent
+
+```mermaid
+flowchart TD
+    Settings["settings.json\nemergent.hypothesisDomains"] -->|"domain list"| TV["HYPOTHESIS_DOMAINS\ntemplate variable"]
+    Spec["Spec frontmatter\ntype field"] -->|"parsed"| ST["SPEC_TYPE\ntemplate variable"]
+    TV --> Emergent["Emergent Agent\n(non_coding, plan-only)"]
+    ST --> Emergent
+    Emergent -->|"creates"| Prompt["type:emergent\nPrompt File"]
+    Prompt -->|"consumed by"| Executor["Executor Agent"]
+```
+
+The emergent agent is now `non_coding: true` -- it creates prompt files but does not implement them. Executors pick up emergent-authored prompts the same way they pick up planner-authored prompts.
+
+## Domain Selection as Quality Engineering
+
+This architecture embodies **Quality Engineering (Not Quantity Engineering)**:
+
+- Domains are **constraints, not assignments** -- the emergent agent chooses within them, it does not receive directives
+- The domain list defines the **quality surface area** -- what dimensions matter for this initiative
+- Agents are instructed that **tangential domains require feature flags**, creating a natural risk gradient
+- The emergent agent's `BRANCH` template variable provides git context for scoping prompt files to the current work
+
+## Extending Initiative Types
+
+Adding a new initiative type means:
+1. Adding a spec type to the frontmatter schema
+2. Updating `SPEC_TYPE` validation to include the new type
+
+No agent profiles need to change. The emergent agent's template already interpolates `HYPOTHESIS_DOMAINS` and `SPEC_TYPE` generically -- it adapts to whatever the settings and spec provide. This separation of initiative concerns from agent definitions keeps the system composable per **Context is Precious**.

package/docs/flows/README.md

@@ -0,0 +1,44 @@
+---
+description: "Index of all flow documentation covering the agent workflow lifecycle from ideation through compounding, including review, research, coordination, and documentation flows."
+---
+
+# Flows
+
+Workflow definitions that guide agents through tasks. Flows follow a lifecycle from ideation through execution to knowledge compounding.
+
+## Lifecycle Flows
+
+| Phase | Flow | Doc |
+|---|---|---|
+| Foundation | Core harness integration | `docs/flows/core-harness-integration.md` |
+| Ideation | Spec planning (ideation + type-aware planning) | `docs/flows/spec-planning.md` |
+| Scoping | Type-specific scoping flows (5 initiative types) | `docs/flows/type-specific-scoping-flows.md` |
+| Pre-execution | Plan review jury | `docs/flows/plan-review-jury.md` |
+| Research | Plan deepening and research | `docs/flows/plan-deepening-and-research.md` |
+| Execution | Prompt task execution | `docs/flows/prompt-task-execution.md` |
+| Refinement | Emergent refinement (hypothesis planner, plan-only) | `docs/flows/emergent-refinement.md` |
+| Post-execution | Judge reviewing | `docs/flows/judge-reviewing.md` |
+| Feedback | PR reviewing | `docs/flows/pr-reviewing.md` |
+| Coordination | Coordination services | `docs/flows/coordination.md` |
+| Knowledge | Compounding | `docs/flows/compounding.md` |
+
+## Initiative Scoping Flows
+
+| Topic | Doc |
+|---|---|
+| Type-specific scoping (investigation, optimization, refactor, documentation, triage) | `docs/flows/type-specific-scoping-flows.md` |
+
+## Supporting Flows
+
+| Topic | Doc |
+|---|---|
+| Documentation pipeline | `docs/flows/documentation-orchestration.md` |
+| E2E test plan building | `docs/flows/e2e-test-plan-building.md` |
+| Validation suites and skills | `docs/flows/validation-and-skills-integration.md` |
+| Flow authoring and MCP tools | `docs/flows/flow-authoring-and-mcp-tools.md` |
+
+## Work in Progress
+
+| Topic | Doc |
+|---|---|
+| Debug investigation and memory recall | `docs/flows/wip/wip-flows.md` |