all-hands-cli 0.1.0

package/.allhands/flows/INITIATIVE_STEERING.md

@@ -0,0 +1,110 @@
+<goal>
+Structured, domain-aware mid-execution scope adjustment. Per **Quality Engineering**, initiative steering provides deep replanning when ad-hoc coordinator patches are insufficient. Per **Frontier Models are Capable**, the workflow domain config drives what to explore and what to ask — the agent deduces how to steer from domain knowledge and current execution state.
+</goal>
+
+<constraints>
+- MUST read the workflow domain config, active spec, alignment doc, and all current prompt files before steering
+- MUST NOT add prompt summaries for created prompts — per **Prompt Files as Units of Work**, summaries are written by executing agents after completion
+- MUST reset `core_consolidation` to `pending` in alignment doc frontmatter when initiative goals change
+- MUST follow append-only numbering and dependency patching patterns for all prompt changes
+- MUST NOT ask for human intervention during execution (aside from the Steering Interview phase)
+- MUST set `stage: 'steering'` on `status.yaml` on entry and restore `stage: 'executing'` on exit
+</constraints>
+
+## Stage Management — Entry
+
+Pause prompt spawning before any analysis. Per **Quality Engineering**, active executors continue but no new prompts are picked up during steering.
+
+- Derive `status.yaml` path from `ALIGNMENT_PATH` (same directory, replace `alignment.md` with `status.yaml`)
+- Read `status.yaml` and record the current `stage` value
+- Set `stage: 'steering'` in `status.yaml`
+
+## Context Gathering
+
+Ground against current execution state — this is the core difference from spec planning, which grounds against the spec alone.
+
+- Read the workflow domain config at `WORKFLOW_DOMAIN_PATH`
+- Read the active spec at `SPEC_PATH`
+- Read the alignment doc at `ALIGNMENT_PATH` — note Overview goals, prior prompt summaries, engineer decisions, any existing steering amendments
+- List and read all prompt files in `PROMPTS_FOLDER`:
+  - Categorize by status: `done`, `in_progress`, `pending`, `blocked`
+  - Note dependency graph and identify the execution frontier
+- Assess implementation state:
+  - Check `git diff` and `git log` on `BRANCH` for recent commits
+  - Compare completed work (prompt summaries) against spec goals
+  - Identify gaps, risks, and drift between plan and reality
+- Run `ah solutions search "<steering context keywords>"` for relevant past solutions
+- Run `ah memories search "<steering context keywords>"` for relevant learnings
+
+## Deep Grounding
+
+Per **Context is Precious**, focus research on the problem area driving the steering session.
+
+- Spawn 1-2 research subtasks: tell them to read `.allhands/flows/shared/CODEBASE_UNDERSTANDING.md` to understand the specific area under discussion
+- Use implementation diffs, completed prompt summaries, and pending prompt tasks as heuristics for current state
+- Consolidate findings before proceeding to interview
+
+## Steering Interview
+
+Per **Ideation First**, the engineer drives scope; the domain config drives what to surface.
+
+- Ask domain-specific questions driven by the workflow domain config's Domain Knowledge and Ideation Guidance sections, framed at implementation level against current execution state
+- The steering domain (`WORKFLOW_DOMAIN_PATH`) can differ from the spec's `initial_workflow_domain` — e.g., a milestone spec encounters a bug, engineer steers with investigation domain config
+- Present researched options with recommended approaches using `AskUserQuestion`
+- Ask ONE question at a time — adapt subsequent questions based on previous answers
+- Cover at minimum:
+  - What is driving the need for steering? (scope change, blocking issue, new information, quality concern)
+  - Which areas of the current plan are affected?
+  - What is the desired outcome?
+
+## Prompt Modification
+
+Based on interview outcomes, produce prompt insertions, modifications, and/or deletions.
+
+### Creating New Prompts
+
+- Read `.allhands/flows/shared/PROMPT_TASKS_CURATION.md` for prompt creation guidance
+- Read `.allhands/flows/shared/UTILIZE_VALIDATION_TOOLING.md` to assign validation suites to new prompts
+- Assign the next available prompt number — append-only, NEVER renumber existing prompts
+  - Use `getNextPromptNumber()` or derive from highest existing prompt number + 1
+
+### Modifying Existing Prompts
+
+- Only modify prompts with status `pending` or `blocked` — per **Prompt Files as Units of Work**, `done` and `in_progress` prompts are immutable unless engineer explicitly requests
+- Update tasks, acceptance criteria, or dependencies as needed
+- Document what changed and why in the prompt body
+
+### Deleting Prompts
+
+- Mark prompts for deletion by setting `status: deleted` in frontmatter (preserve audit trail)
+- Update dependency references on any prompts that depended on deleted prompts
+
+### Dependency Patching
+
+When inserting between existing prompts, patch the dependency graph:
+- New prompt's `dependencies` = the "run after" prompt numbers
+- Patch each "run before" prompt's `dependencies` to include the new prompt number
+- Verify the resulting execution order is consistent and acyclic
+
+## Alignment Doc Amendment
+
+Per **Knowledge Compounding**, append-only amendments preserve the audit trail.
+
+- Append a `## Steering Amendment` section to the alignment doc (NEVER rewrite existing sections)
+- Record in the amendment:
+  - **Steering domain**: the workflow domain config used (may differ from spec's `initial_workflow_domain`)
+  - **Trigger**: what drove the steering session
+  - **User inputs**: engineer decisions from the interview
+  - **Prompt changes**: insertions (new prompt numbers and titles), modifications (what changed), deletions (which prompts and why)
+- If initiative goals changed:
+  - Update the Overview section with new goal context
+  - Reset `core_consolidation` to `pending` in alignment doc frontmatter
+- Do NOT update the spec's `initial_workflow_domain` field — the steering domain is tracked in the amendment, preserving the spec's original identity
+- Do NOT write prompt summaries for newly created prompts
+
+## Stage Management — Exit
+
+Restore prompt spawning after steering is complete.
+
+- Set `stage: 'executing'` in `status.yaml`
+- Stop

package/.allhands/flows/JUDGE_REVIEWING.md

@@ -0,0 +1,79 @@
+<goal>
+Orchestrate a jury of specialized reviewers to judge implementation against planning files and spec. Per **Quality Engineering**, the question is "which variant is best?" - reviewers identify issues, engineer chooses which to address.
+</goal>
+
+<inputs>
+- Alignment doc path
+- Spec doc path
+- Prompts folder path
+</inputs>
+
+<constraints>
+- MUST spawn parallel jury subtasks for comprehensive review
+- MUST present engineer with actionable options, not mandates
+- MUST create `type: review-fix` prompts for accepted fixes
+- NEVER read jury review files (`.allhands/flows/shared/jury/*`) directly - subtasks load their own flows per **Context is Precious**
+</constraints>
+
+## Context Gathering
+
+Read these files to understand what's being reviewed:
+- Read the alignment doc
+- Read the spec doc
+- Run `ls <prompts_folder_path>` to see all prompts
+
+## Jury Orchestration
+
+Spawn parallel review subtasks, providing each with alignment doc, spec doc, and prompts folder paths:
+
+### Domain Best Practices
+For each domain touched by implementation:
+- Spawn subtask to read `.allhands/flows/shared/jury/BEST_PRACTICES_REVIEW.md`
+- Domains include: expo/react-native, trpc/serverless, database/drizzle/supabase, web/tanstack/nextjs, dev tooling, CI/CD
+- Each covers performance, security, and code quality best practices
+
+### Expectations Fit
+- Spawn subtask to read `.allhands/flows/shared/jury/EXPECTATIONS_FIT_REVIEW.md`
+- Ensures alignment doc + prompts document engineer decisions and fit original spec expectations
+
+### Security
+- Spawn subtask to read `.allhands/flows/shared/jury/SECURITY_REVIEW.md`
+- Ensures implementation doesn't introduce security risks
+
+### YAGNI
+- Spawn subtask to read `.allhands/flows/shared/jury/YAGNI_REVIEW.md`
+- Ensures implementation avoids over-engineering and unnecessary complexity
+
+### Maintainability
+- Spawn subtask to read `.allhands/flows/shared/jury/MAINTAINABILITY_REVIEW.md`
+- Identifies agentic anti-patterns, simplification opportunities, LOC reduction
+
+### Architecture
+- Spawn subtask to read `.allhands/flows/shared/jury/ARCHITECTURE_REVIEW.md`
+- Verifies SOLID principles, component boundaries, pattern compliance
+
+### Claim Verification
+- Spawn subtask to read `.allhands/flows/shared/jury/CLAIM_VERIFICATION_REVIEW.md`
+- Verifies factual claims in prompts/alignment against actual codebase state
+
+## Feedback Synthesis
+
+After all jury subtasks complete:
+- Read `.allhands/flows/shared/REVIEW_OPTIONS_BREAKDOWN.md` for structuring feedback into P1/P2/P3 ranked options
+- Deduplicate and elevate repeated concerns across jury members
+- For each item: describe the issue, explain importance, suggest implementation
+- Group by priority and effort
+- Present actionable options to engineer with tradeoffs, not mandates
+
+## Engineer Decision
+
+- Present ranked options and let engineer choose which to accept and which to decline
+- Track both accepted AND declined items with engineer's reasoning
+- Per **Quality Engineering**, engineer effort goes to quality control of variants
+
+## Prompt Creation
+
+For accepted fixes:
+- Read `.allhands/flows/shared/PROMPT_TASKS_CURATION.md` for prompt creation guidance
+- Create `type: review-fix` prompts for each accepted issue
+- Include review context and specific fix requirements in prompt body

package/.allhands/flows/PROMPT_TASK_EXECUTION.md

@@ -0,0 +1,68 @@
+<goal>
+Execute prompt tasks with full context, validate thoroughly, and document your work. Per **Prompt Files as Units of Work**, the prompt IS the task - complete it as a self-contained unit.
+</goal>
+
+<constraints>
+- MUST read prompt file and alignment doc before implementation
+- MUST pass validation before committing
+- MUST append summary to prompt file on completion
+- NEVER commit without passing validation review
+</constraints>
+
+## Context Gathering
+
+- Read the prompt file for tasks and acceptance criteria
+  - If FAILURE SUMMARY sections exist, adapt to their redirections / learnings
+- Read the alignment doc for milestone context, prior prompt summaries, and key decisions
+  - Read any relevant dependency prompt files
+- Only if additional context is needed (likely not needed):
+  - Run `ah knowledge docs search <descriptive_query>` for codebase information as needed
+  - Run `ah solutions search "<keywords>"` for relevant past solutions
+  - Run `ah memories search "<keywords>"` for relevant learnings and engineer preferences
+
+## Implementation
+
+- Follow tasks and break them down into Todos if necessary
+- After implementation,
+  - Read `validation_suites` frontmatter entries. During implementation, follow the **Stochastic Validation** section for exploratory validation — use model intuition to probe edge cases, test user flows, and verify quality beyond what deterministic checks cover.
+  - Use validation tooling to acquire test data meeting acceptance criteria
+
+### Deviation Handling
+
+Per **Frontier Models are Capable**, handle deviations automatically without engineer steering:
+
+| Deviation Type | Action |
+|----------------|--------|
+| Bugs/errors | Fix immediately, document in summary |
+| Missing critical functionality (validation, error handling, security) | Add immediately, document in summary |
+| Blocking issues (missing deps, broken imports, config errors) | Fix to unblock, document in summary |
+| Architectural changes (new DB tables, major schema changes, new services) | Stop and document in prompt - requires planning |
+
+If architectural deviation is needed, document the blocker and set `status: blocked` rather than proceeding.
+
+## Validation
+
+- Acceptance criteria validation uses the **Deterministic Integration** section of referenced suites — these are binary pass/fail commands that gate completion. Stochastic exploration during implementation informs quality but does not replace deterministic acceptance criteria.
+- Spawn subtask to read `.allhands/flows/shared/PROMPT_VALIDATION_REVIEW.md` and follow its instructions
+  - Include validation results and `validation_suites` file paths in subtask inputs
+- Act on feedback until it passes
+- If at prompt attempt > 2 with real limitations, communicate compromises - reviewer may still reject
+
+## Completion
+
+**CRITICAL: Follow this exact order to prevent race conditions with parallel agents.**
+
+1. Run `ah schema prompt` for summary format
+2. Append success summary to prompt file
+   - Include any deviations handled during implementation
+   - If blockers required engineer steering, document as learnings to prevent recurrence
+3. Run `ah schema alignment body` for alignment doc summary format
+4. Append prompt summary to alignment doc's "## Prompt Summaries" section
+   - Per **Knowledge Compounding**, this enables other agents to see completed work without reading each prompt
+   - If section doesn't exist, create it
+5. Commit all changes (implementation only - alignment and prompt files are NOT git tracked)
+6. Set frontmatter `status: done` - **MUST be after summaries are written**
+7. Rename prompt file to include `-DONE` suffix
+8. Stop
+
+**Note**: Alignment files and prompt files are NOT git tracked. Only commit implementation changes. Do not mention prompts or prompt numbers in commit messages.

package/.allhands/flows/PR_REVIEWING.md

@@ -0,0 +1,43 @@
+<goal>
+Process PR review feedback into actionable prompts. Per **Knowledge Compounding**, engineer decisions on what NOT to address are as important as what they accept.
+</goal>
+
+<constraints>
+- MUST use gh CLI to read PR comments
+- MUST document declined review items in alignment doc
+- MUST create `type: review-fix` prompts for accepted items
+</constraints>
+
+## Context Gathering
+
+- Run `gh pr view --comments` to read PR review comments
+- Aggregate all feedback from reviewers
+
+## Feedback Synthesis
+
+- Read `.allhands/flows/shared/REVIEW_OPTIONS_BREAKDOWN.md` for structuring feedback
+- Present actionable options to engineer
+- Group by severity and effort
+
+## Engineer Decision
+
+- Present options and let engineer choose which to address
+- Track both accepted AND declined items
+
+## Decision Documentation
+
+Per **Knowledge Compounding**, declined items matter for future context:
+- Run `ah schema alignment` to review alignment doc structure
+- Add declined review items to alignment doc (captures engineer's reasoning)
+- This prevents future agents from re-suggesting rejected approaches
+
+## Prompt Creation
+
+For accepted items:
+- Read `.allhands/flows/shared/PROMPT_TASKS_CURATION.md` for guidance
+- Create `type: review-fix` prompts for each accepted item
+- Include PR comment context in prompt body
+
+## Completion
+
+Stop once prompts created and alignment doc updated.

package/.allhands/flows/SPEC_PLANNING.md

@@ -0,0 +1,216 @@
+<goal>
+Transform the spec into executable prompts with domain-appropriate planning depth. Per **Quality Engineering**, deep domains get full planning with variant architecture and jury review. Per **Frontier Models are Capable**, focused domains get lightweight scoping that leaves room for hypothesis-driven discovery. The workflow domain config at `WORKFLOW_DOMAIN_PATH` drives planning behavior.
+</goal>
+
+<inputs>
+- Spec doc path
+- Alignment doc path
+- Prompts folder path
+- `WORKFLOW_DOMAIN_PATH` — path to the workflow domain config file
+</inputs>
+
+<constraints>
+- MUST read the workflow domain config before planning — `planning_depth` determines the planning path
+- MUST present recommended approach for each decision point
+- MUST NOT re-ask questions already solidified by the spec — the spec represents resolved decisions from ideation
+- MUST NOT ask questions with obvious answers derivable from spec context or research findings
+- MUST leverage research findings to propose alternatives, challenge approaches, and surface unforeseen constraints — never enter the interview uninformed
+- MUST include jury review when domain config sets `jury_required: true`
+- NEVER read jury review files (`.allhands/flows/shared/jury/*`) directly — subtasks load their own flows per **Context is Precious**
+- Focused planning domains MUST document unresolved questions in alignment doc for emergent planner consumption
+- Prompts MUST be fully autonomous — no human intervention during execution
+- Testing is NOT a prompt — validation happens via validation_suites attached to prompts
+</constraints>
+
+## Context Gathering
+
+- Read the spec doc
+- Read the workflow domain config at `WORKFLOW_DOMAIN_PATH`
+  - **Defensive fallback**: If `WORKFLOW_DOMAIN_PATH` is empty or the file does not exist, default to deep planning behavior (`planning_depth: deep`, `jury_required: true`). Per **Knowledge Compounding**, this handles backward compatibility with specs created before domain config was active.
+  - Note `planning_depth`, `jury_required`, and the Planning Considerations section
+- Read the alignment doc for existing prompts that may impact planning (if exists)
+- Read codebase files referenced in spec for initial grounding
+- Ensure your branch is up to date with base branch
+- Search documented solutions with `ah solutions search "<keywords>"` for relevant past learnings
+- Search memories with `ah memories search "<keywords>"` for engineer preferences and prior spec insights
+
+## Idempotency Check
+
+Per **Knowledge Compounding**, detect existing planning artifacts and offer modes:
+
+- Check if the prompts folder contains existing prompt files and/or an alignment doc exists
+- If no existing artifacts — proceed directly to Planning Depth
+- If existing artifacts detected, ask the engineer using `AskUserQuestion`:
+  - **Start fresh** — Clear prompts and alignment doc, replan from spec
+  - **Amend** — Read existing alignment doc and prompts, produce amendments without re-litigating existing decisions
+- In amend mode:
+  - Use **reference integrity check** for staleness: decisions referencing prompts that no longer exist or have been significantly modified are flagged as stale and re-presented to the engineer
+  - Decisions whose referenced prompts still exist and are structurally intact are preserved
+  - Focus research and interview on new/changed areas only
+
+## Planning Depth
+
+Per **Frontier Models are Capable**, the domain config's `planning_depth` determines the planning path — deduce appropriate behavior:
+
+| Planning Depth | Planning Path | Research | Interview | Jury | Output |
+|----------------|--------------|----------|-----------|------|--------|
+| `deep` (or fallback) | Deep Planning | 1-4 deep subtasks | Full decision interview | Gated by `jury_required` | 5-15 prompts + detailed alignment doc |
+| `focused` | Focused Planning | 1-2 focused subtasks | Open questions only (skippable) | No | 0-3 seed prompts + problem-focused alignment doc |
+
+The domain config's **Planning Considerations** section drives domain-specific behavior within each path — surface its constraints, limitations, and edge cases during research and interview phases.
+
+## Deep Planning
+
+### Deep Research
+
+Spawn parallel subtasks to ground recommendations before the engineer interview:
+- 1-4 Tasks: Tell them to read `.allhands/flows/shared/CODEBASE_UNDERSTANDING.md` to understand relevant implementation approaches
+- 0-3 Tasks: Tell them to read `.allhands/flows/shared/RESEARCH_GUIDANCE.md` to isolate optimal solutions (if necessary)
+- Apply domain config's Planning Considerations to focus research scope and priorities
+
+After research completes, synthesize findings to identify: approach alternatives the spec didn't consider, constraints or limitations the spec may not account for, edge cases surfaced by codebase reality, and feasibility concerns with stated approaches. Bring these to the interview — don't wait for the engineer to ask.
+
+### Engineer Interview
+
+The interview covers genuinely open decisions — not re-litigation of spec content. The spec represents resolved ideation outcomes; respect them. Per **Quality Engineering**, come to the interview with a researched perspective and present it using `AskUserQuestion`:
+
+- **Only ask about open decisions**: Do not re-ask what the spec has decided. Do not ask questions whose answers are obvious from spec context or research findings. Focus on implementation approach decisions that genuinely require engineer input.
+- **Bring your own analysis**: For each decision point, present what research revealed — alternatives the spec didn't consider, constraints discovered in the codebase, tradeoffs between approaches, edge cases that need handling. The engineer should be responding to informed proposals, not generating options from scratch.
+- Ask ONE decision point at a time — do not batch all questions together
+- Each implementation approach becomes a set of options (2-4 per question)
+- Engineer can choose one OR many (disposable variants)
+- When selecting many, create parallel variant prompts behind feature flags if they can't work together at the same time
+- If variant prompts used, engineer MUST choose a **convention** when selecting multiple approaches
+- Each option MUST have a recommended approach (mark with "(Recommended)" suffix)
+- Adapt subsequent questions based on previous answers when logical dependencies exist
+- Use domain config's Planning Considerations to inform approach evaluation criteria
+
+Keep interview concise and actionable.
+
+### Disposable Variant Architecture
+
+When engineer selects multiple approaches:
+- Create variant prompts that can execute in parallel
+- Each variant hidden behind feature flag
+- Variants are cheap to implement and test
+- Planning agent is the only agent who architects variant prompt structures
+- Pass variant knowledge to prompt creation phase
+
+### External Technology Implementation Usage Research
+
+Spawn subtasks to read `.allhands/flows/shared/EXTERNAL_TECH_GUIDANCE.md`:
+- Typically run after understanding the implementation approach and the external technology required
+- Can inform the engineer interview where beneficial
+- Consolidate approach against actual documentation
+- Derive specific implementation steps
+
+### Prompt Creation
+
+- Read `.allhands/flows/shared/PROMPT_TASKS_CURATION.md` for prompt creation guidance
+- Transform researched approaches into executable prompts
+- Read `.allhands/flows/shared/UTILIZE_VALIDATION_TOOLING.md` to discover and assign existing validation suites to prompts
+- For high-risk domains (auth, payments, data), note TDD approach requirement in prompt
+  - Reference `.allhands/flows/shared/TDD_WORKFLOW.md` for TDD execution guidance
+
+### Deep Alignment Doc
+
+- Run `ah schema alignment` for format
+- Create alignment doc with Overview + Hard User Requirements sections
+- Document engineer decisions ONLY when they deviate from recommendations:
+  - Record: what you recommended, what they chose instead, their stated reasoning
+  - Do NOT record when engineer accepts the recommended approach
+  - Purpose: future agents need to know where human judgment overrode AI suggestions
+- Do NOT write prompt summaries — those are appended by executor after prompt completion
+
+### Plan Verification
+
+Before jury review (if applicable), self-verify plans achieve goals:
+
+| Dimension | Check |
+|-----------|-------|
+| Requirement Coverage | Every spec requirement has task(s)? |
+| Task Completeness | Every prompt has clear acceptance criteria? |
+| Key Links Planned | Components wire together (API → UI)? |
+| Scope Sanity | 2-3 tasks per prompt? <7 files per prompt? |
+| Validation Coverage | Prompts reference available validation suites where applicable? |
+
+Fix issues before proceeding.
+
+### Plan Review Jury
+
+**Gated by `jury_required` from domain config.** If `jury_required: false` — skip this section entirely.
+
+Spawn parallel review subtasks (provide alignment doc, spec doc, prompts folder paths):
+
+| Jury Member | Flow | Focus |
+|-------------|------|-------|
+| Expectations Fit | `.allhands/flows/shared/jury/PROMPTS_EXPECTATIONS_FIT.md` | Alignment + prompts fit spec expectations |
+| Flow Analysis | `.allhands/flows/shared/jury/PROMPTS_FLOW_ANALYSIS.md` | Prompt dependencies, variant ordering, importance |
+| YAGNI | `.allhands/flows/shared/jury/PROMPTS_YAGNI.md` | Holistic over-engineering check |
+| Premortem | `.allhands/flows/shared/jury/PROMPT_PREMORTEM.md` | Risk analysis — Tigers, Elephants, failure modes |
+
+After jury returns:
+- Read `.allhands/flows/shared/REVIEW_OPTIONS_BREAKDOWN.md` for feedback synthesis
+- Premortem Tigers become P1/P2 review items; Elephants become discussion points
+- Present actionable options to engineer (including risk acceptance decisions)
+- Amend prompts based on engineer choices, respecting PROMPT_TASKS_CURATION limits:
+  - Do NOT pack substantial refinements into existing prompts
+  - Create NEW prompts for additions that exceed scope limits (tasks, files)
+  - Update prompt dependencies when inserting new prompts
+- Document only deviations from recommendations (including accepted risks that were flagged)
+
+### Plan Deepening (Optional)
+
+Per **Knowledge Compounding**, offer to deepen the plan:
+
+Ask engineer: "Would you like to deepen this plan with comprehensive research?"
+
+If yes:
+- Read `.allhands/flows/shared/PLAN_DEEPENING.md` and follow instructions
+- Applies available skills to each plan section
+- Searches solutions for relevant past learnings
+- Enhances prompts with research insights
+- Preserves original content, only adds research findings
+
+Recommended for complex architectural decisions, high-risk domains, novel technologies, or large specs with many unknowns.
+
+## Focused Planning
+
+### Focused Research
+
+Spawn 1-2 targeted research subtasks grounded in the problem area:
+- Tell them to read `.allhands/flows/shared/CODEBASE_UNDERSTANDING.md` focused on the specific problem domain
+- Only spawn external research (`.allhands/flows/shared/RESEARCH_GUIDANCE.md`) if the spec references external tools or novel approaches
+- Apply domain config's Planning Considerations to focus research direction
+
+### Engineer Scope Narrowing
+
+Present spec open questions and concerns to the engineer using `AskUserQuestion`:
+- Each open question becomes a question — engineer can answer to narrow scope or skip
+- For each question, present what research revealed and your recommended resolution — the engineer should be responding to an informed proposal, not an open-ended prompt
+- Skipped/unanswered questions remain open for hypothesis-driven discovery
+- Keep interview brief — focused domains intentionally leave room for discovery
+
+### Seed Prompt Creation
+
+- Read `.allhands/flows/shared/PROMPT_TASKS_CURATION.md` for prompt creation guidance
+- Create 0-3 seed prompts as testable hypotheses grounded in research findings
+- Read `.allhands/flows/shared/UTILIZE_VALIDATION_TOOLING.md` to discover and assign validation suites
+- Seed prompts target the most concrete, immediately actionable aspects of the spec
+- Remaining open questions are left for the emergent planner to design experiments around
+
+### Focused Alignment Doc
+
+- Run `ah schema alignment` for format — use the same schema sections with type-appropriate content:
+  - **Overview**: Problem statement, evidence, context, and unresolved questions — the emergent planner reads these to design experiments
+  - **Hard User Requirements**: Success criteria and constraints
+  - **Engineer Decisions**: Only deviations from recommendations (same as deep planning)
+- Document unresolved questions (skipped interview questions, open spec questions) prominently in Overview — per **Knowledge Compounding**, this enables emergent planner to discover and test answers
+- Document concerns and limitations as context for hypothesis formation
+- Do NOT write prompt summaries — those are appended by executor after prompt completion
+
+## Completion
+
+- Finalize prompts and alignment doc
+- Edit `.planning/<branch>/status.yaml` to set `stage: executing` — this signals the event loop to begin picking up prompts for execution
+- Stop

package/.allhands/flows/harness/WRITING_HARNESS_FLOWS.md

@@ -0,0 +1,27 @@
+<goal>
+Guide agents through flow authoring with harness conventions. Per **Context is Precious**, flows are thin entry points that route to skill references for domain knowledge.
+</goal>
+
+<inputs>
+- Flow file path
+- Flow purpose and target audience
+</inputs>
+
+<outputs>
+- Flow file following harness conventions (XML tags, progressive disclosure, principle citations)
+</outputs>
+
+<constraints>
+- MUST cite First Principles by name when they motivate a flow directive
+- MUST use XML tags per flow writing conventions
+- MUST keep flows brief — progressive disclosure over monolithic docs
+</constraints>
+
+## Execution
+
+- Read `.allhands/principles.md` for first principle context
+- Run `ah skills list` to discover the `harness-maintenance` skill
+- Read the skill's `references/writing-flows.md` for flow authoring patterns
+- Author the flow using conventions: `<goal>`, `<inputs>`, `<outputs>`, `<constraints>`, action-verb bullets
+- Verify flow follows progressive disclosure — reference sub-flows rather than inlining complexity
+- Ensure line count stays within 20-40 lines per **Context is Precious**

package/.allhands/flows/harness/WRITING_HARNESS_KNOWLEDGE.md

@@ -0,0 +1,27 @@
+<goal>
+Guide agents through knowledge compounding infrastructure — docs, solutions, memories, knowledge indexes. Per **Knowledge Compounding**, everything feeds forward: decisions, pivots, limitations, realizations.
+</goal>
+
+<inputs>
+- Knowledge type: docs, solutions, memories, or indexes
+- Content to compound and its domain
+</inputs>
+
+<outputs>
+- Knowledge artifact following compounding conventions and schema compliance
+</outputs>
+
+<constraints>
+- MUST follow schema for the specific knowledge type
+- MUST ensure knowledge compounds — future tasks benefit from all past work
+- NEVER create isolated knowledge that doesn't feed forward
+</constraints>
+
+## Execution
+
+- Read `.allhands/principles.md` for first principle context
+- Run `ah skills list` to discover the `harness-maintenance` skill
+- Read the skill's `references/knowledge-compounding.md` for schemas and compounding patterns
+- Create or update the knowledge artifact following type-specific conventions
+- Ensure proper indexing for discoverability via `ah knowledge docs search` or `ah solutions search`
+- Verify schema compliance for the knowledge type

package/.allhands/flows/harness/WRITING_HARNESS_ORCHESTRATION.md

@@ -0,0 +1,27 @@
+<goal>
+Guide agents through orchestration layer changes — TUI lifecycle, event loop, agent profiles, workflows. Per **Frontier Models are Capable**, understand architectural invariants before modifying interconnected systems.
+</goal>
+
+<inputs>
+- Orchestration domain: TUI, event loop, agent profiles, or workflows
+- Change purpose and affected components
+</inputs>
+
+<outputs>
+- Working orchestration changes preserving architectural invariants
+</outputs>
+
+<constraints>
+- MUST understand lifecycle implications before modifying TUI or event loop
+- MUST validate with `ah validate agents` after agent profile changes
+- NEVER break graceful degradation for optional dependencies
+</constraints>
+
+## Execution
+
+- Read `.allhands/principles.md` for first principle context
+- Run `ah skills list` to discover the `harness-maintenance` skill
+- Read the skill's `references/core-architecture.md` for architecture, schemas, and lifecycle patterns
+- Implement changes preserving architectural invariants (graceful degradation, semantic validation, in-memory state)
+- Validate with `ah validate agents` after profile modifications
+- Test lifecycle behavior end-to-end

package/.allhands/flows/harness/WRITING_HARNESS_SKILLS.md

@@ -0,0 +1,27 @@
+<goal>
+Guide agents through skill creation and maintenance. Per **Context is Precious**, skills follow the hub-and-spoke model — a compact routing hub with domain-specific reference docs.
+</goal>
+
+<inputs>
+- Skill domain and purpose
+- Reference docs needed for the skill's knowledge areas
+</inputs>
+
+<outputs>
+- Skill following hub-and-spoke conventions with schema-compliant SKILL.md and reference docs
+</outputs>
+
+<constraints>
+- MUST follow hub-and-spoke pattern — SKILL.md routes, references teach
+- MUST comply with skill schema (frontmatter, globs, version)
+- NEVER duplicate knowledge across reference docs
+</constraints>
+
+## Execution
+
+- Read `.allhands/principles.md` for first principle context
+- Run `ah skills list` to discover the `harness-maintenance` skill
+- Read the skill's `references/harness-skills.md` for skill schema, discovery mechanism, and conventions
+- Create or update the skill following hub-and-spoke pattern
+- Ensure glob coverage matches the skill's domain files
+- Verify schema compliance and reference doc cross-linking

package/.allhands/flows/harness/WRITING_HARNESS_TOOLS.md

@@ -0,0 +1,27 @@
+<goal>
+Guide agents through adding or modifying harness tools (CLI commands, hooks, MCP servers). Per **Knowledge Compounding**, tools follow the auto-discovery pattern — agents find them via `--help`, docs teach motivations.
+</goal>
+
+<inputs>
+- Tool type: command, hook, or MCP integration
+- Tool purpose and trigger conditions
+</inputs>
+
+<outputs>
+- Working tool integrated into the harness with auto-discovery support
+</outputs>
+
+<constraints>
+- MUST follow the auto-discovery pattern — commands self-document via `--help`
+- MUST validate with `ah validate agents` after changes affecting agent profiles
+- NEVER add tools without clear first principle justification
+</constraints>
+
+## Execution
+
+- Read `.allhands/principles.md` for first principle context
+- Run `ah skills list` to discover the `harness-maintenance` skill
+- Read the skill's `references/tools-commands-mcp-hooks.md` for tool architecture and patterns
+- Implement the tool following auto-discovery conventions
+- Validate with `ah validate agents` if agent profiles are affected
+- Test hook behavior with Claude Code runner if adding hooks