all-hands-cli 0.1.0

package/.allhands/flows/CORE.md

@@ -0,0 +1,87 @@
+<goal>
+Core harness integration for all agents. Per **Context is Precious**
+</goal>
+
+
+## Flow Delegation
+
+Per **Context is Precious**, when a flow instructs you to delegate a sub-flow to a subtask (e.g., "tell them to read", "spawn subtask to read"):
+- Tell the subtask to read the flow file — do NOT read it yourself first
+- The sub-flow's content is intended for the subtask's context, not yours
+- You only need to know what the subtask will accomplish, not how the sub-flow instructs it
+
+**MUST use `ah knowledge docs search <descriptive_query>` for code search tied to crucial project knowledge for any codebase discovery needs**
+
+**You MUST use `tldr` tooling when retrieving codebase / file context using the following rules:**
+
+## Must start with:
+- `tldr semantic search <descriptive_query_of_functionality>` 
+
+## Must follow up with:
+
+```bash
+# Core analysis
+tldr tree [path]                    # File tree
+tldr structure [path] --lang <lang> # Code structure (codemaps)
+tldr search <pattern> [path]        # Search files
+tldr extract <file>                 # Full file info
+tldr context <entry> --project .    # LLM-ready context
+
+# Flow analysis
+tldr cfg <file> <function>          # Control flow graph
+tldr dfg <file> <function>          # Data flow graph
+tldr slice <file> <func> <line>     # Program slice
+tldr calls [path]                   # Cross-file call graph
+
+# Codebase analysis
+tldr impact <func> [path]           # Who calls this function? (reverse call graph)
+tldr dead [path]                    # Find unreachable/dead code
+tldr arch [path]                    # Detect architectural layers
+
+# Import analysis
+tldr imports <file>                 # Parse imports from a file
+tldr importers <module> [path]      # Find all files that import a module
+
+# Quality & testing (NEW)
+tldr diagnostics <file|path>        # Type check + lint (pyright/ruff)
+```
+
+## When to Use
+
+- **Before reading files**: Run `tldr structure .` to see what exists
+- **Finding code**: Use `tldr search "pattern"` instead of grep for structured results
+- **Understanding functions**: Use `tldr cfg` for complexity, `tldr dfg` for data flow
+- **Debugging**: Use `tldr slice file.py func 42` to find what affects line 42
+- **Context for tasks**: Use `tldr context entry_point` to get relevant code
+- **Impact analysis**: Use `tldr impact func_name` before refactoring to see what would break
+- **Dead code**: Use `tldr dead src/` to find unused functions for cleanup
+- **Architecture**: Use `tldr arch src/` to understand layer structure
+- **Import tracking**: Use `tldr imports file.py` to see what a file imports
+- **Reverse imports**: Use `tldr importers module_name src/` to find who imports a module
+- **Before tests**: Use `tldr diagnostics .` to catch type errors before running tests
+
+## Languages
+
+Supports: `python`, `typescript`, `go`, `rust`
+
+## Example Workflow
+
+```bash
+# 1. See project structure
+tldr tree src/ --ext .py
+
+# 2. Find relevant code
+tldr search "process_data" src/
+
+# 3. Get context for a function
+tldr context process_data --project src/ --depth 2
+
+# 4. Understand control flow
+tldr cfg src/processor.py process_data
+
+# 5. Before refactoring - check impact
+tldr impact process_data src/ --depth 3
+
+# 6. Find dead code to clean up
+tldr dead src/ --entry main cli
+```

package/.allhands/flows/DOCUMENTATION.md

@@ -0,0 +1,218 @@
+<goal>
+Orchestrate documentation creation and maintenance. Per **Knowledge Compounding**, docs expose engineering knowledge via file references and LSP symbols for semantic discovery. Per **Context is Precious**, delegate discovery and writing to sub-agents.
+
+Engineering knowledge comes from prompts, commit messages, and alignment docs when available (Incremental mode), otherwise inferred from the code itself (Fill-the-Gaps mode).
+
+**Execute immediately** - detect mode and proceed. Do not ask for clarification unless domain confirmation is needed.
+</goal>
+
+<constraints>
+- MUST verify clean working tree before proceeding (see Pre-flight Check)
+- MUST confirm domains with user before spawning discovery agents
+- MUST run `ah docs validate --json` at start of both modes to identify gaps
+- MUST run `ah knowledge docs reindex` on completion
+- NEVER spawn more than 10 writer agents per run
+- NEVER write command/installation guides - those belong in README.md files
+- NEVER write code snippets or examples - use `[ref:file:Symbol]` file references instead
+- NEVER write to `docs/solutions/` or `docs/memories.md` - those are owned by the Compounding flow
+</constraints>
+
+## Pre-flight Check
+
+Before any documentation work, verify the git working tree is clean:
+
+```bash
+git status --porcelain
+```
+
+If output is non-empty, **abort with error**:
+> "Uncommitted changes detected. Documentation requires a clean working tree because file references use git commit hashes. Please commit or stash your changes before running documentation."
+
+**Why this matters:**
+- File references use `[ref:file:symbol:hash]` format where hash comes from git
+- Uncommitted files have no git hash → finalize fails
+- Modified files get stale hashes → refs become invalid immediately after commit
+
+## Mode Detection
+
+Check the message for template variables passed by the documentor agent:
+
+```
+├─ ALIGNMENT_PATH + PROMPTS_FOLDER provided? → Incremental Mode (feature branch)
+└─ Variables empty or not provided? → Fill-the-Gaps Mode (cold start or refresh)
+```
+
+The documentor agent passes `SPEC_PATH`, `ALIGNMENT_PATH`, and `PROMPTS_FOLDER` when invoked from a spec context. Empty values mean no spec is selected.
+
+**Default behavior**: If no message/prompt is provided and no context variables are set, proceed directly with Fill-the-Gaps mode. Do not ask the user what to do - just start documenting.
+
+## Config Resolution
+
+Documentation config uses a **local-first** resolution — the same pattern as `.claude/settings.local.json`:
+
+```
+.allhands/docs.local.json  →  exists? use it (repo-specific, never distributed)
+.allhands/docs.json         →  fallback (ships to target repos on --init)
+```
+
+Read whichever file resolves. All subsequent reads and writes in this flow use that resolved path. When persisting detected domains or exclusions, write back to the same file that was read.
+
+---
+
+## Fill-the-Gaps Mode
+
+Full documentation effort for new repos or out-of-sync docs.
+
+### Initialization
+
+1. **Initial Validation** - Run `ah docs validate --json` to identify:
+   - Invalid refs (gaps in documentation)
+   - Stale refs (out-of-sync with code)
+   - Missing frontmatter
+
+2. **Domain Detection**
+   - Resolve docs config per **Config Resolution** above (optional — projects don't need either file)
+   - Load `domains` and `exclude` glob patterns from the resolved config
+   - If domains not declared, infer:
+     - Run `tldr structure .` or `ah complexity .` on project root
+     - Check for monorepo markers: `pnpm-workspace.yaml`, `lerna.json`, `turbo.json`, `nx.json`
+     - If monorepo: each workspace package is a domain, plus root-level coordination docs
+     - Otherwise: identify main product areas from directory structure
+   - Present detected domains to user for confirmation
+   - Persist confirmed domains (and any existing `exclude` patterns) back to the resolved config file. Always write this file, whether user adjusted or accepted defaults — it codifies the domain map for future incremental runs.
+
+3. **Proceed to Core Flow** with:
+   ```yaml
+   mode: "fill-gaps"
+   domains: [<confirmed domains>]
+   exclude: [<glob patterns from resolved config>]  # may be empty
+   validation_issues: <from initial validation>
+   existing_docs: []
+   session_knowledge: null
+   ```
+
+---
+
+## Incremental Mode
+
+Feature branch documentation with session knowledge.
+
+### Initialization
+
+1. **Context Gathering**
+   - Read alignment doc at `ALIGNMENT_PATH` for milestone context and key decisions
+   - Read prompt files in `PROMPTS_FOLDER` for task details and learnings
+   - Resolve docs config per **Config Resolution** above for `exclude` glob patterns
+   - Run `git diff $(git merge-base HEAD main)..HEAD --name-only` for changed files
+   - Filter changed files against `exclude` patterns — excluded files are not documented even if changed
+
+2. **Initial Validation** - Run `ah docs validate --json` to identify current staleness
+
+3. **Impact Analysis**
+   - Run `ah knowledge docs search` with changed file paths (post-exclusion) to find related docs
+   - Categorize changes:
+     - **Edit**: existing docs reference changed code
+     - **Create**: new functionality without doc coverage
+     - **Stale**: validation found outdated refs
+
+4. **Proceed to Core Flow** with:
+   ```yaml
+   mode: "incremental"
+   domains: [<affected domains only>]
+   exclude: [<glob patterns from resolved config>]  # may be empty
+   validation_issues: <from initial validation>
+   existing_docs: [<docs needing edits>]
+   session_knowledge:
+     commit_messages: "<relevant commits>"
+     alignment_summary: "<key decisions>"
+     prompt_learnings: "<deviations and discoveries>"
+   ```
+
+---
+
+## Core Flow
+
+Shared pipeline for both modes after initialization.
+
+### 1. Discovery Phase
+
+Per **Context is Precious**, spawn discovery sub-agents:
+
+- One sub-agent per domain
+- Instruct each to read `.allhands/flows/shared/DOCUMENTATION_DISCOVERY.md`
+- Provide each:
+  ```yaml
+  domain: "<domain-name>"
+  source_paths: ["<path/to/domain>"]  # or changed files in incremental
+  exclude: ["<glob>", ...]  # from docs.json, may be empty
+  mode: "<fill-gaps|incremental>"
+  session_context: "<summary from alignment doc>"  # incremental only
+  ```
+- Await all discovery results
+
+### 2. Aggregate and Plan
+
+- Merge approach lists from all discovery agents
+- Filter out approaches with `existing_coverage: "full"`
+- Group approaches into writer assignments:
+  - Each writer handles **5-15 approaches** (one domain or related subset)
+  - Group by domain and subdirectory
+- Use `ah knowledge docs search` to verify no redundant coverage
+- Target 5-10 writers total; if discovery returned too many approaches, push back
+
+### 3. Writing Phase
+
+- Spawn writer sub-agents per assignment (each handles **multiple approaches**)
+- Instruct each to read `.allhands/flows/shared/DOCUMENTATION_WRITER.md`
+- Provide each:
+  ```yaml
+  domain: "<domain-name>"
+  approaches:  # Multiple approaches per writer
+    - { name: "<approach>", group: "<subdir or null>", files: [...], symbols: [...] }
+  doc_directory: "docs/<domain>/"
+  existing_docs: [<paths to edit>]  # from initialization
+  session_knowledge: <from initialization>  # null in fill-gaps
+  ```
+- Use `group` field to determine file paths:
+  - `group: "cli"` → `docs/<domain>/cli/<approach>.md`
+  - `group: null` → `docs/<domain>/<approach>.md`
+
+### 4. Post-Processing
+
+#### README Generation
+
+Per **Knowledge Compounding**, write README.md files that expose cross-domain relationships for semantic discovery. The orchestrator writes these directly — writers lack cross-domain context.
+
+- Write `docs/README.md` — top-level overview:
+  - List all domains with one-line descriptions
+  - Explain cross-domain relationships (e.g., type pipeline from backend → frontend)
+  - Link to domain READMEs via backtick paths (e.g., `docs/<domain>/README.md`)
+- Write `docs/<domain>/README.md` for each domain:
+  - Overview of the domain's purpose and scope
+  - List approaches grouped by subdirectory
+  - Cross-references to related domains
+  - Link to approach docs via backtick paths (e.g., `docs/<domain>/<approach>.md`)
+- Write `docs/<domain>/<group>/README.md` for each subdirectory with 3+ docs:
+  - Brief overview of the group's scope
+  - List contained approach docs
+
+README.md files MUST use plain backtick relative paths (e.g., `docs/harness/README.md`) instead of `[ref:...]` references when linking to other docs. Per **Knowledge Compounding**, the knowledge index would recursively include referenced docs inside READMEs, inflating search results with duplicate content.
+
+All README.md files MUST have frontmatter with `description` (per `ah schema documentation`) for semantic indexing.
+
+#### Finalize and Validate
+
+- Run `ah docs finalize` (finalizes all docs in docs/)
+- Run `ah docs validate --json`
+- If issues exist:
+  - Spawn writer sub-agents to fix (provide stale/invalid refs)
+  - Re-run finalize and validate until clean
+- Run `ah knowledge docs reindex`
+
+---
+
+## Completion
+
+- Verify `ah docs validate` returns clean
+- Run `ah knowledge docs reindex`
+- Report summary: docs created, edited, domains covered

package/.allhands/flows/E2E_TEST_PLAN_BUILDING.md

@@ -0,0 +1,140 @@
+<goal>
+Build an E2E test plan that convinces the engineer of milestone implementation efficacy. Per **Agentic Validation Tooling**, engineers are excluded from prompt-by-prompt validation - this plan provides comprehensive proof the milestone works as expected through deterministic tests, infrastructure setup, and manual verification flows.
+</goal>
+
+<inputs>
+- Alignment doc path
+- E2E test plan output path
+</inputs>
+
+<outputs>
+- E2E test plan document at specified output path (with `last_commit` frontmatter for incremental updates)
+</outputs>
+
+<constraints>
+- MUST derive infrastructure setup from implementation artifacts (commits, summaries, code, existing docs)
+- MUST prioritize manual verification flows over reiterating already-run automated tests
+- NEVER duplicate step-by-step test cases that deterministic suites already cover
+</constraints>
+
+## Update Mode (if test plan exists)
+
+If the E2E test plan already exists:
+- Read existing test plan and extract `last_commit` from frontmatter
+- Run `git log --oneline <last_commit>..HEAD` to see commits since last update
+- Run `git diff <last_commit>..HEAD --stat` to see affected files
+- Compare alignment doc prompt summaries against test plan's covered prompts
+- Focus context gathering on delta changes only
+- Append new scenarios rather than rewriting existing coverage
+
+## Context Gathering
+
+- Read the alignment doc for goal, objectives, acceptance criteria, and prompt execution summaries
+- Review changed files from base branch (avoid information overload on full diffs)
+- Run `ah validation-tools list` to identify available validation suites — the `tools` field in suite output helps identify which tooling is available for both stochastic and deterministic dimensions
+- Examine implementation artifacts for infrastructure setup information:
+  - Commit messages describing setup/configuration changes
+  - Prompt summaries mentioning services, dependencies, or environment setup
+  - Existing documentation (recognize it may be outdated if implementation changed it)
+  - Code comments, READMEs, and configuration files
+
+## E2E Test Plan Structure
+
+Per **Context is Precious**, structure the plan as progressive sections - each building on the previous.
+
+### Section 1: Deterministic Test Summary
+
+This section corresponds to the **Deterministic Integration** dimension of referenced validation suites. Commands here should be drawn from suite Deterministic Integration sections where suites are referenced.
+
+Per **Context is Precious**, present as a concise command list with inline comments:
+
+```bash
+# API endpoint tests (CRUD, validation, 404s)
+cd backend && pytest -v
+
+# Component tests (Vitest + SolidJS)
+cd frontend && npm test
+
+# Playwright E2E (task flows, filtering, search)
+cd frontend && npm run test:e2e
+```
+
+- Comment above each command, separated by blank lines
+- Group related commands if logical (e.g., backend, frontend, E2E)
+- NO detailed breakdowns, file listings, or coverage percentages
+- Engineer can run individual commands or chain them all
+
+### Section 2: Infrastructure Setup
+
+Per **Knowledge Compounding**, derive setup from implementation artifacts (commits, summaries, code, existing docs).
+
+```bash
+# Install dependencies
+npm install && cd backend && pip install -r requirements.txt
+
+# Set up environment (copy and configure)
+cp .env.example .env
+
+# Start database (if applicable)
+docker-compose up -d postgres
+
+# Start backend service
+cd backend && python main.py
+
+# Start frontend dev server
+cd frontend && npm run dev
+```
+
+- Comment above each command, separated by blank lines
+- Cover: dependencies, environment, database, services, dev servers
+- Include cloud branch tooling if available (e.g., Supabase branches, preview deployments)
+
+**Variant Awareness**: Per **Quality Engineering**, if implementation introduced disposable variants (A/B implementations, backend alternatives, experimental features):
+- Document how to switch between variants (feature flags, env vars, infrastructure flags)
+- Show setup commands for each variant that needs testing
+- Example: `BACKEND=flask npm run dev` vs `BACKEND=fastapi npm run dev`
+
+This section validates documentation quality - if setup cannot be derived from implementation artifacts, it signals inadequate documentation. The subsequent documentation phase will face the same challenge.
+
+### Section 3: AI-Coordinated Validation (Conditional)
+
+This section corresponds to the **Stochastic Validation** dimension. Agent-driven validation tasks here should reference suite Stochastic Validation playbooks for structured exploration patterns.
+
+**Only include if validation tooling supports agentic testing.** Types of tooling that qualify:
+- UI automation (Playwright MCP, agent-browser, simulator automation, browser MCPs)
+- Load testing tools (k6, artillery, locust with agent coordination)
+- Performance profiling (flamegraphs, memory profilers, bundle analyzers)
+- Database inspection/scripting (query tools, migration validators, data generators)
+- API testing tools (curl automation, Postman/Insomnia MCPs)
+
+Provide example prompts engineers can give to agent sessions:
+- "Use Playwright MCP to complete checkout with expired card, then retry with valid payment"
+- "Run load test against /api/tasks with 100 concurrent users, report p95 latency"
+- "Profile the task list render with 1000 items, identify components over 16ms"
+- "Inspect database after bulk import, verify foreign key integrity and index usage"
+
+Purpose: Engineers spin up agents to test flows based on concerns they describe - agent coordinates the tooling.
+
+If no such tooling exists for this project, skip this section entirely and note which tooling categories would be valuable.
+
+### Section 4: Manual E2E Flows
+
+The core "convince the engineer" section with real product behavior:
+- Define explicit user flows to walk through with spun-up infrastructure
+- Cover happy paths, edge cases, and regression scenarios
+- Include tooling for inspection (profiling, network inspection, logs)
+- Reference specific UI paths, API endpoints, CLI commands to exercise
+- Cover domains that automated testing cannot adequately verify
+
+This section provides broad product coverage through direct engineer interaction - the final proof that implementation meets expectations.
+
+## Completion
+
+Write the E2E test plan to the output path with frontmatter:
+```yaml
+---
+last_commit: <current HEAD SHA>
+covered_prompts: [<prompt numbers included>]
+updated: <ISO date>
+---
+```

package/.allhands/flows/EMERGENT_PLANNING.md

@@ -0,0 +1,57 @@
+<goal>
+Plan hypotheses as prompt files for executors to implement. Per **Quality Engineering**, this agent discovers which improvements are valuable — separation of concerns keeps planning and execution independent, each bounded in context. A two-phase model ensures core goals are solidified before exploring tangential improvements.
+</goal>
+
+<constraints>
+- MUST NOT execute any implementation — only create prompt files
+- MUST set `type: emergent` in prompt frontmatter — both phases use the same type
+- MUST create non-overlapping hypotheses that don't conflict with prior prompts
+- NEVER terminate with 0 prompts — per **Knowledge Compounding**, each round compounds work
+- NEVER pursue tangential exploration while `core_consolidation: pending`
+- MUST respect `max_tangential_hypotheses` cap from workflow domain config
+</constraints>
+
+## Context Gathering
+
+- Read the alignment doc for: goals, prior prompt summaries, unresolved questions, learnings
+- Read `core_consolidation` from alignment doc frontmatter (default: `pending` if missing)
+- Read the workflow domain config at `WORKFLOW_DOMAIN_PATH` for `max_tangential_hypotheses`
+- Identify gaps between current state (completed work) and desired state (spec goals + success criteria)
+- Run `ah memories search "<hypothesis terms>"` for relevant prior insights
+
+## Phase Determination
+
+Per **Quality Engineering**, core goals must be convincingly met before exploring adjacent work.
+
+**Phase 1 — Core Consolidation** (`core_consolidation: pending`):
+- Focus hypotheses exclusively on verifying, solidifying, and compounding the implementation to meet core initiative goals
+- Assess gaps between current implementation state (prompt summaries, completed work) and the alignment doc's stated goals and expectations
+- Do NOT pursue tangential exploration — all hypotheses must directly address spec goals, acceptance criteria, or known gaps
+- After each hypothesis round, assess whether all core goals are convincingly met based on: alignment doc goals, prompt summaries, implementation state
+
+**Phase 2 — Tangential Exploration** (`core_consolidation: complete`):
+- Hypotheses extend the implementation with ideas adjacent to but not explicitly requested in initial goals
+- Feature ideas, consolidation, future-proofing, edge case coverage
+- Track tangential hypothesis count across rounds — enforce `max_tangential_hypotheses` cap from the workflow domain config
+- If cap is reached, stop — no further emergent work
+
+**Transition**: When core consolidation is convincingly met, set `core_consolidation: complete` in the alignment doc frontmatter. This is a judgment call based on alignment doc goals, prompt summaries, and implementation state. Subsequent runs enter Phase 2.
+
+## Hypothesis Formation
+
+- Select hypothesis domains from provided `HYPOTHESIS_DOMAINS` list, diversifying from prior work
+- Formulate each hypothesis: implementation approach → intended outcome
+- Verify uniqueness via `ah knowledge docs search <query>` against existing prompts
+- Phase 1: hypotheses target core goal gaps and verification
+- Phase 2: hypotheses explore adjacent improvements and novel experiments (behind feature flags)
+
+## Prompt Creation
+
+- Read `.allhands/flows/shared/UTILIZE_VALIDATION_TOOLING.md` to discover validation suites for hypothesis domains
+- Read `.allhands/flows/shared/PROMPT_TASKS_CURATION.md` for prompt structure and guidance
+- Create 1-N prompt files in the prompts folder:
+  - Set `type: emergent` in frontmatter
+  - Target 2-5 tasks per prompt, each a non-overlapping hypothesis
+  - Add discovered validation suites to `validation_suites` frontmatter
+  - If Phase 2: note feature flag requirement in tasks
+- Stop — executors pick up prompts via the loop

package/.allhands/flows/IDEATION_SCOPING.md

@@ -0,0 +1,154 @@
+<goal>
+Exploratory co-creation that surfaces the problem and solution space. Per **Ideation First**, the engineer controls depth and direction. Per **Frontier Models are Capable**, the agent brings its own research, proposals, and critical analysis — not just question-asking. The domain config provides domain-specific substance; this flow provides the generative conversation structure.
+</goal>
+
+<constraints>
+- MUST read the workflow domain config at `WORKFLOW_DOMAIN_PATH` before any interview
+- MUST ask all questions listed in the domain config's `required_ideation_questions`, unless the answer is already clear from codebase exploration
+- MUST ask ONE question at a time
+- NEVER batch all questions together
+- MUST ground in codebase reality before asking the engineer codebase-answerable questions
+- MUST bring its own proposals and alternatives — never be a passive interviewer
+- NEVER ask questions answerable from codebase exploration
+</constraints>
+
+## Active Spec Revision Mode
+
+**Check first**: If `SPEC_PATH` is non-empty and the file exists at that path, enter **revision mode** instead of the normal flow below.
+
+### Revision Mode
+
+1. Read the existing spec file at `SPEC_PATH`
+2. Read the workflow domain config at `WORKFLOW_DOMAIN_PATH`
+3. Present the existing spec content to the engineer as grounding:
+   - Summarize the current spec scope, goals, and key decisions
+   - State: "This spec already exists. I'll focus on what you want to change or add."
+4. Conduct a focused revision interview:
+   - Ask what aspects of the spec need changing, extending, or refining
+   - Reference existing spec content — do not ask about things already covered unless the engineer wants to revise them
+   - Apply domain config's `required_ideation_questions` only where they surface gaps in the revision context
+   - ONE question at a time, as with normal ideation
+5. After the engineer signals readiness:
+   - Revise the existing spec file in place — update and append, do not replace wholesale
+   - Preserve unchanged sections; modify only what the revision touches
+6. **After spec revision is written**: reset planning artifacts since existing plans are now stale:
+   ```bash
+   ah planning reset
+   ```
+   This deletes all prompts and the alignment doc, and resets status to `planning` stage.
+7. Report to the engineer: "Spec revised. Planning artifacts cleared — the planning flow will re-trigger to produce new prompts aligned with the updated spec."
+8. **Stop** — do not continue to the normal Initiation flow below.
+
+---
+
+**If `SPEC_PATH` is empty or the file does not exist**: proceed with the normal flow below.
+
+## Initiation
+
+- Run `ah specs list --domains-only` for roadmap visibility (may return empty)
+- If specific spec name not provided:
+  - List available domains to the engineer
+  - Ask which initiative domain this spec belongs to (can be new)
+  - Infer spec name from the engineer's initial ideation prompt
+- Ask the engineer for their initial ideation prompt
+
+## Context Gathering
+
+- Read the workflow domain config file at `WORKFLOW_DOMAIN_PATH`
+- Ground using `ah knowledge docs search` across ROADMAP then DOCS indexes (in that order)
+- Run `ah specs list --roadmap --domain <domain_name>` for domain milestone visibility
+- Read dependent milestone specs
+- Spawn 1-3 subtasks: tell them to read `.allhands/flows/shared/CODEBASE_UNDERSTANDING.md` to deeply understand codebase reality
+- Spawn 0-2 research subtasks: tell them to read `.allhands/flows/shared/RESEARCH_GUIDANCE.md` for high-level tech solution approaches
+- Spawn additional research subtasks as new concepts emerge during interview
+
+## Exploratory Interview
+
+The interview has two phases. The boundary between them is organic — divergence naturally gives way to convergence as the solution space clarifies.
+
+### Divergent Phase: Expanding the Solution Space
+
+Open the space. The goal is to understand the problem deeply and surface every viable direction before narrowing.
+
+- Ask all `required_ideation_questions` from the domain config frontmatter, one at a time
+- Per **Ideation First**, reflect back understanding before moving on — probe vague responses, skip questions already answered
+- Apply the domain config's Domain Knowledge sections as they become relevant:
+  - If category deep dives are defined: work through relevant categories based on scope
+  - Follow probe guidance for depth calibration
+- Spawn research subtasks as new concepts emerge
+- **Propose alternative approaches** grounded in codebase understanding and research results — present options the engineer hasn't considered
+- **Surface non-obvious considerations** — tradeoffs, limitations, second-order effects, assumptions that might not hold under pressure
+- **Challenge assumptions** where codebase evidence or research contradicts them — respectfully, with evidence
+
+### Convergent Phase: Narrowing Toward Intent
+
+Collapse the space. The goal is to synthesize explored directions into a coherent solution intent.
+
+- Synthesize the explored solution space into candidate directions
+- Present feasibility feedback grounded in exploration results
+- If the domain config includes guiding principles synthesis guidance: synthesize and validate with engineer
+- Respect output section structure from the domain config for content synthesis
+- Converge on the direction the engineer wants to pursue
+
+## Core Ideation Behaviors
+
+These behaviors apply throughout the entire interview, regardless of domain. Domain configs may layer domain-specific signals on top.
+
+### Knowledge Gap Detection
+
+Watch for these universal signals requiring deeper probing:
+
+| Signal | Action |
+|--------|--------|
+| Hedging language ("I think...", "Maybe...") | Probe deeper — offer to research |
+| Passive agreement ("That sounds good") | Verify they understand implications, not just deferring |
+| Oversimplification ("Just simple/basic X") | Challenge — define what simple means concretely |
+| Buzzwords without context | Ask what they think it does and why it fits |
+| Conflicting requirements | Surface the conflict explicitly — ask which takes priority |
+
+If the domain config defines additional gap detection signals, apply those too.
+
+### Conviction Spectrum
+
+Capture how strongly the engineer feels about each direction. This preserves intent fidelity through downstream flows:
+
+| Engineer Input | Spec Language | Downstream Effect |
+|----------------|---------------|-------------------|
+| Strong preference | "Engineer desires X" / "Engineer expects X" | Planning respects as constraint |
+| Flexible | "Engineer likes X but open to alternatives" | Planning can propose alternatives |
+| Just an idea | "Engineer proposes X, open-ended for architect" | Planning researches freely |
+| No opinion | Captured in Open Questions | Planning decides |
+
+### Open Questions
+
+Not everything resolves during ideation. Open questions are a first-class output, not a failure of the interview.
+
+- **Close yourself**: Answerable from codebase exploration or gathered context — don't burden the engineer
+- **Resolve together**: Tradeoffs where engineer input genuinely matters — present options with evidence
+- **Leave open for planning**: Needs deep research, architect expertise, or engineer explicitly delegates
+- **Actively offer the choice**: "Do you want to decide this now, or leave it for planning?"
+
+### Roadmap-Aware Assumptions
+
+When the spec depends on functionality from unimplemented roadmap items, use "Assuming X exists..." or "Assuming any of X, Y, Z exist..." to express the dependency. Never cross-reference unimplemented milestone specs directly.
+
+## Transition to Spec Creation
+
+- Propose transitioning when the conversation reaches natural saturation — when new questions yield diminishing insight
+- Frame it as a summary: "Here's what's well-understood, here's what's still open — want to explore further or leave the open items for planning?"
+- If the domain config defines completeness criteria, use them as internal guidance for what "well-understood" means — but don't present them as a gate
+- The engineer decides when to move on
+
+## Spec Creation
+
+- Synthesize answers into spec content using the domain config's output section structure
+- Write `initial_workflow_domain: <domain_name>` to spec frontmatter (from the config's `name` field)
+- Set `type: <domain_type>` in spec frontmatter (from the config's `type` field)
+- If the domain config includes "Building on Unimplemented Milestones" guidance: use "Assuming X exists..." pattern for dependencies
+- Follow `.allhands/flows/shared/CREATE_SPEC.md` to write, create, and optionally activate the spec
+
+### Optional: Spec Flow Analysis
+
+- If the domain config's Ideation Guidance mentions spec flow analysis: offer it for complex features
+  - Ask: "Would you like me to analyze this spec for user flow coverage and gaps?"
+  - If yes: read `.allhands/flows/shared/SPEC_FLOW_ANALYSIS.md` and follow instructions