all-hands-cli 0.1.0

package/.allhands/flows/shared/SPEC_FLOW_ANALYSIS.md

@@ -0,0 +1,119 @@
+<goal>
+Analyze spec for user flow completeness without prescribing implementation. Per **Ideation First**, specs capture intent - this validates intent coverage, not implementation detail.
+</goal>
+
+<inputs>
+- Spec doc path
+</inputs>
+
+<outputs>
+- User flow overview (what the spec enables)
+- Gap identification (what's missing or ambiguous)
+- Clarifying questions for engineer
+</outputs>
+
+<constraints>
+- MUST respect spec as intent document, not requirements doc
+- MUST keep analysis high-level (user-observable, not implementation)
+- MUST ask, not prescribe - engineer decides what to address
+- NEVER add implementation details to spec
+</constraints>
+
+## Flow Discovery
+
+Read the spec and identify:
+
+### Primary User Journeys
+
+| Element | Extract |
+|---------|---------|
+| User types | Who are the actors? (end users, admins, systems) |
+| Entry points | How do users start this flow? |
+| Goals | What are users trying to accomplish? |
+| Exit conditions | How do users know they're done? |
+| Success criteria | What defines a successful outcome? |
+
+### Implicit Flows
+
+Look for unstated but necessary flows:
+- Error recovery paths
+- Edge cases mentioned in concerns
+- Dependencies on other features
+- State transitions implied by descriptions
+
+## Gap Analysis
+
+For each discovered flow, check:
+
+| Dimension | Question |
+|-----------|----------|
+| Entry | How does user start this? Is it clear? |
+| Happy Path | Is the main success path defined? |
+| Error States | What if things go wrong? |
+| Edge Cases | First-time user? Concurrent access? Partial completion? |
+| Exit | How does user know they succeeded? |
+
+### Gap Categories
+
+| Category | Description |
+|----------|-------------|
+| Missing Flow | A necessary journey not mentioned |
+| Ambiguous Transition | Unclear what happens between states |
+| Undefined Error | No guidance on failure handling |
+| Scope Boundary | Unclear where this feature ends |
+
+## Output Format
+
+Present findings as questions, not mandates:
+
+```
+## User Flows Identified
+
+### Flow 1: [Name]
+- **Actor**: [Who]
+- **Goal**: [What they want]
+- **Path**: [High-level steps]
+- **Success**: [How they know it worked]
+
+### Flow 2: [Name]
+...
+
+## Gaps Found
+
+### Missing Flows
+- [Gap]: [Why it matters] → **Question**: [What should happen?]
+
+### Ambiguities
+- [Unclear element]: [What's ambiguous] → **Question**: [Clarify X or Y?]
+
+### Error Handling
+- [Scenario]: [What could fail] → **Question**: [How should user recover?]
+
+## Clarifying Questions
+
+Prioritized by impact:
+
+### Critical (blocks understanding)
+1. [Question that must be answered]
+
+### Important (affects scope)
+2. [Question that clarifies boundaries]
+
+### Nice-to-have (edge cases)
+3. [Question about rare scenarios]
+
+## Recommendations
+
+Based on analysis:
+- [Suggestion for spec improvement]
+- [Area that may need more ideation]
+```
+
+## Completion
+
+Per **Ideation First**, present gaps as questions and let engineer decide:
+- Which gaps to address in this spec
+- Which gaps to leave for planning phase
+- Which gaps are out of scope
+
+Do not modify the spec directly - present findings and await engineer direction.

package/.allhands/flows/shared/TDD_WORKFLOW.md

@@ -0,0 +1,109 @@
+<goal>
+Apply test-driven development principles to prompt execution. Per **Agentic Validation Tooling**, tests written first create clear acceptance criteria and prevent scope creep.
+</goal>
+
+<inputs>
+- Prompt file with tasks and acceptance criteria
+- Validation tooling reference (if any)
+</inputs>
+
+<outputs>
+- Failing tests that define success
+- Implementation that passes tests
+- No production code without corresponding test
+</outputs>
+
+<constraints>
+- MUST write failing tests before implementation
+- MUST implement minimal code to pass tests
+- NEVER add untested functionality
+</constraints>
+
+## TDD Cycle
+
+```
+RED → GREEN → REFACTOR
+ │      │        │
+ │      │        └─ Improve code quality (tests still pass)
+ │      └─ Write minimal code to pass tests
+ └─ Write failing tests from acceptance criteria
+```
+
+## When to Apply TDD
+
+| Context | TDD Approach |
+|---------|--------------|
+| High-risk domains (auth, payments, data) | Full TDD - every acceptance criterion tested first |
+| Core business logic | Full TDD - tests define behavior |
+| UI components | Light TDD - key interactions tested |
+| Integration glue code | Light TDD - happy path + error cases |
+| Scripts/utilities | Optional - judgment call |
+
+## TDD for Prompts
+
+### Phase 1: RED (Write Failing Tests)
+
+From prompt acceptance criteria, write tests that:
+- Define expected behavior precisely
+- Cover edge cases mentioned in criteria
+- Fail meaningfully (not just "not implemented")
+
+```
+Acceptance Criteria: "User can reset password via email"
+→ Test: "sends reset email when valid email provided"
+→ Test: "returns error for unknown email"
+→ Test: "rate limits reset requests"
+→ Test: "token expires after 1 hour"
+```
+
+### Phase 2: GREEN (Minimal Implementation)
+
+Implement only what's needed to pass tests:
+- No extra features
+- No "while I'm here" improvements
+- No premature optimization
+
+### Phase 3: REFACTOR (Improve Quality)
+
+With passing tests as safety net:
+- Extract common code
+- Improve naming
+- Simplify logic
+- Tests must still pass
+
+## Integration with Prompt Execution
+
+When executing prompts with TDD approach:
+
+1. Read acceptance criteria from prompt
+2. Generate test cases that prove criteria met
+3. Run tests (should fail - RED)
+4. Implement minimal code (GREEN)
+5. Refactor if needed
+6. Run validation review with test evidence
+
+## Test Evidence for Validation
+
+Include in prompt summary:
+```markdown
+## Test Evidence
+
+| Acceptance Criterion | Test | Status |
+|---------------------|------|--------|
+| User can reset password | `test_password_reset_happy_path` | PASS |
+| Invalid email rejected | `test_password_reset_invalid_email` | PASS |
+| Rate limited | `test_password_reset_rate_limit` | PASS |
+```
+
+## When NOT to Use Full TDD
+
+- Exploratory/spike work (write tests after if keeping)
+- Pure UI layout changes (visual review sufficient)
+- Configuration changes (integration test coverage)
+- Documentation only
+
+## TDD Philosophy
+
+> "No production code without a failing test first."
+
+The test defines the contract. The implementation fulfills it. The refactor improves it. Never reverse this order.

package/.allhands/flows/shared/UTILIZE_VALIDATION_TOOLING.md

@@ -0,0 +1,84 @@
+<goal>
+Find and apply existing validation tooling to build strong acceptance criteria. Per **Agentic Validation Tooling**, matching the right suite to the task ensures programmatic validation without engineer intervention.
+</goal>
+
+<inputs>
+- Files/domains involved in the implementation task
+- Nature of the changes (UI, backend, database, etc.)
+</inputs>
+
+<outputs>
+- Matched suite file paths for `validation_suites` frontmatter
+- Acceptance criteria derived from suite commands
+</outputs>
+
+<constraints>
+- MUST run `ah validation-tools list` to discover available suites
+- MUST match suites via both glob patterns AND description inference
+- MUST document gaps for CREATE_VALIDATION_TOOLING follow-up
+- MUST order validation progressively (compiles → unit tests → integration → E2E)
+</constraints>
+
+## Step 1: Discover Available Suites
+
+- Run `ah validation-tools list`
+- Returns JSON with: `name`, `description`, `globs`, `file` path, `tools`
+
+## Step 2: Identify Relevant Suites
+
+Match suites using two approaches:
+
+**Glob pattern matching** (programmatic):
+- Compare files you're touching against each suite's `globs`
+- Suites with matching patterns are likely relevant
+
+**Description inference** (semantic):
+- Read suite descriptions
+- Match against task nature (UI, DB migrations, API endpoints, etc.)
+
+Select all suites that apply to implementation scope.
+
+## Step 3: Read Suite Documentation
+
+For each relevant suite:
+- Run `cat .allhands/validation/<suite-name>.md`
+
+Understand:
+- **Purpose**: What quality aspects it validates
+- **Tooling**: What tools are needed and how to install/configure them
+- **Stochastic Validation**: How to use the suite for exploratory agent-driven validation during implementation
+- **Deterministic Integration**: What CI-gated commands to run for acceptance criteria
+
+## Step 4: Integrate into Acceptance Criteria
+
+Per **Agentic Validation Tooling**, use each dimension at the right phase:
+
+- **During implementation**: Follow the **Stochastic Validation** section — use model intuition to probe edge cases, test user flows, and verify quality beyond deterministic checks
+- **For acceptance criteria**: Reference the **Deterministic Integration** section — these are binary pass/fail commands that gate completion
+- Stochastic exploration informs quality during the work but is not an acceptance criterion — acceptance criteria must be deterministic
+
+Order validation progressively when writing acceptance criteria:
+
+Example:
+```markdown
+## Acceptance Criteria
+- [ ] Code compiles without errors
+- [ ] `npx vitest run --coverage` passes with >80% coverage on changed files
+- [ ] `npx playwright test auth.spec.ts` passes all auth flow scenarios
+- [ ] No regressions in existing test suites
+```
+
+## Step 5: Note Gaps
+
+If validation needs have no matching suite:
+- Document the gap explicitly
+- Flag for CREATE_VALIDATION_TOOLING follow-up
+- Proceed with available validation (compiles, type checks, basic tests)
+
+## For Prompt Curation
+
+When used via PROMPT_TASKS_CURATION:
+- Add suite file paths to prompt's `validation_suites` frontmatter
+- Use the `file` field from `ah validation-tools list` output
+- Makes validation approach explicit and reviewable
+- Executors can read referenced suite files directly

package/.allhands/flows/shared/WRITING_HARNESS_FLOWS.md

@@ -0,0 +1,11 @@
+<goal>
+Flow authoring conventions for the All Hands harness. Per **Knowledge Compounding**, comprehensive flow-writing knowledge is centralized in the harness-maintenance skill.
+</goal>
+
+## Start Here
+
+- Run `ah skills list` to discover the `harness-maintenance` skill
+- Read the skill's routing table — select `references/writing-flows.md` for flow authoring patterns
+- For execution, follow `.allhands/flows/harness/WRITING_HARNESS_FLOWS.md`
+
+Per **Context is Precious**, this file redirects to two canonical sources — the skill reference for domain knowledge, the harness flow for execution — rather than duplicating content.

package/.allhands/flows/shared/WRITING_HARNESS_MCP_TOOLS.md

@@ -0,0 +1,84 @@
+<goal>
+Add a new MCP server integration to the harness. Per **Agentic Validation Tooling**, MCP servers extend the harness with external tool capabilities that enable programmatic validation.
+</goal>
+
+<inputs>
+- MCP package name or npmjs/GitHub URL
+- Purpose: what capability this MCP enables (e.g., "Supabase database validation")
+</inputs>
+
+<outputs>
+- Config file at `.allhands/harness/src/mcp/<server-name>.ts`
+- Environment requirements documentation
+- Validation status report
+</outputs>
+
+<constraints>
+- MUST research package before building config
+- MUST NOT add environment variable values - only document requirements
+- MUST validate server discovery after config creation
+- MUST run as sub-agent to avoid blocking main thread
+</constraints>
+
+## Phase 1: Research
+
+Investigate the MCP package requirements:
+
+**Find the package**:
+- Run `ah tavily search "<mcp_name> MCP server npm"` for package details
+
+**Read documentation**:
+- Run `ah context7 search "<mcp_name>"` for official docs
+- Run `ah tavily extract "<doc_url>"` for specific pages
+
+**Identify requirements**:
+- Transport type (stdio, http, sse)
+- Command/args for stdio
+- URL for http/sse
+- Environment variables needed
+- Authentication method (API key, OAuth, etc.)
+
+## Phase 2: Build Config
+
+- Copy template: `cp .allhands/harness/src/mcp/_template.ts .allhands/harness/src/mcp/<server-name>.ts`
+
+Edit the config file with researched values:
+- `name`: Short identifier (used in `ah tools <name>:tool`)
+- `description`: What the server does
+- `type`: Transport type ('stdio', 'http', 'sse')
+- `command`/`args`: For stdio transport
+- `url`: For http/sse transport
+- `env`: Environment variables (use `${VAR_NAME}` syntax)
+- `stateful`: Set to `true` if server maintains session state
+- `toolHints`: Add helpful hints for key tools
+
+Add comment with source URL (npm/GitHub).
+
+## Phase 3: Environment Setup
+
+If MCP requires authentication or API keys:
+
+- Check if env var exists: `grep "VAR_NAME" .env.ai 2>/dev/null || echo "Not found"`
+- Document required variables (do NOT add values):
+  - Variable name
+  - Where to obtain (signup URL, dashboard location)
+  - Expected format (API key, bearer token, etc.)
+
+## Phase 4: Validation
+
+- Build harness: `cd .allhands/harness && npm run build`
+- List servers: `ah tools --list` (verify new server appears)
+- List tools: `ah tools <server-name>` (verify tools discovered)
+- Test a tool call (choose read-only/safe tool): `ah tools <server-name>:<tool> --<param>=<value>`
+
+If call fails due to missing auth, document and proceed.
+
+## Completion
+
+Report back with:
+- Config file created: `.allhands/harness/src/mcp/<server-name>.ts`
+- Available tools: List with brief descriptions
+- Environment requirements (if any)
+- Validation status: "Ready to use" or "Pending auth setup"
+
+Main thread can proceed knowing MCP is (or will be) available.

package/.allhands/flows/shared/jury/ARCHITECTURE_REVIEW.md

@@ -0,0 +1,91 @@
+<goal>
+Review implementation for architectural compliance and system design quality. Per **Quality Engineering**, ensure changes align with established patterns and maintain proper component boundaries.
+</goal>
+
+<inputs>
+- Git diff to base (implementation files)
+- Alignment doc path (for architectural decisions)
+</inputs>
+
+<outputs>
+- Architectural compliance assessment
+- SOLID principle violations
+- Component boundary issues
+- Recommendations ordered by priority
+</outputs>
+
+<constraints>
+- MUST use git diff to base for implementation review
+- MUST compare against documented and implicit architecture
+- MUST verify component boundaries are respected
+</constraints>
+
+## Context Gathering
+
+- Review all implementation changes from base branch
+- Run `ah knowledge docs search "architecture"` for established patterns
+- Read alignment doc for architectural decisions made during planning
+
+## Architectural Analysis
+
+### Component Relationships
+
+| Check | Question |
+|-------|----------|
+| Dependency Direction | Do dependencies flow toward stable abstractions? |
+| Circular Dependencies | Are there any import cycles introduced? |
+| Layer Violations | Does UI import from data layer directly? |
+| Boundary Crossing | Are module boundaries respected? |
+
+### SOLID Principles
+
+| Principle | Check |
+|-----------|-------|
+| Single Responsibility | Does each module/class have one reason to change? |
+| Open/Closed | Can new behavior be added without modifying existing code? |
+| Liskov Substitution | Are derived types truly substitutable? |
+| Interface Segregation | Are interfaces minimal and focused? |
+| Dependency Inversion | Do high-level modules depend on abstractions? |
+
+### Pattern Compliance
+
+For each changed file:
+- Identify expected architectural patterns from existing codebase
+- Compare implementation against those patterns
+- Flag deviations that aren't justified in alignment doc
+
+## Review Process
+
+For each changed file:
+- Map its role in the architecture (UI, service, data, infrastructure)
+- Check import statements for dependency direction
+- Verify naming follows established conventions
+- Ensure abstraction level matches its layer
+
+## Output Format
+
+Return findings ordered by priority:
+
+```
+## Architecture Review
+
+### P1 (Critical - Architectural Violations)
+- [File]: [Violation] -> [Impact] -> [Fix]
+
+### P2 (Important - Pattern Deviations)
+- [File]: [Deviation] -> [Expected pattern] -> [Recommendation]
+
+### P3 (Suggestions - Minor Improvements)
+- [File]: [Observation] -> [Improvement opportunity]
+
+## SOLID Analysis
+- [Principle violations found with specific examples]
+
+## Boundary Assessment
+- [Component boundaries respected/violated]
+- [Coupling concerns identified]
+
+## Summary
+- [Overall architectural health]
+- [Key risks introduced]
+```

package/.allhands/flows/shared/jury/BEST_PRACTICES_REVIEW.md

@@ -0,0 +1,80 @@
+<goal>
+Review implementation for domain best practices compliance. Per **Knowledge Compounding**, findings feed back to improve skills and documentation.
+</goal>
+
+<inputs>
+- Alignment doc path
+- Spec doc path
+- Specific domain to focus on (e.g., react-native/expo, trpc/serverless, database/drizzle/supabase, web/tanstack/nextjs, dev tooling, CICD)
+</inputs>
+
+<outputs>
+- Critical review of best practices compliance
+- Improvements needed, ordered by priority
+- Summary of violations (for compounding to encode back into harness)
+</outputs>
+
+<constraints>
+- MUST extract skills using SKILL_EXTRACTION.md subtask
+- MUST search codebase knowledge for established patterns
+- MUST use research tools if no skill findings exist for the domain
+- MUST order issues by priority for fixing
+</constraints>
+
+## Context Gathering
+
+- Read the alignment doc for prompt summaries
+- Identify domain-relevant implementation files changed from base branch
+- Identify and read prompts that touched this domain
+
+## Best Practices Extraction
+
+Spawn subtask to read `.allhands/flows/shared/SKILL_EXTRACTION.md`:
+- Provide the domain files as input
+- Extract patterns, preferences, and pitfalls for this domain
+
+Search codebase knowledge:
+- Run `ah knowledge docs search "<domain> best practices"` for established patterns
+- Run `ah knowledge docs search "<domain> architecture"` for design decisions
+
+### Fallback: No Skill Findings
+
+Per **Knowledge Compounding**, skills are our maintained source of domain best practices. If skill extraction and knowledge search yield no findings:
+
+- Read `.allhands/flows/shared/RESEARCH_GUIDANCE.md` and research current best practices for the domain
+- LLM training data risks staleness without maintained skills - web research fills the gap
+
+## Review Process
+
+Compare implementation against extracted best practices:
+
+| Check | Question |
+|-------|----------|
+| Patterns | Does implementation follow established code patterns? |
+| Preferences | Are library/approach preferences honored? |
+| Pitfalls | Does implementation avoid known pitfalls? |
+| Consistency | Is style consistent with codebase conventions? |
+| Wiring | Are components properly connected (imports, API calls, state flow)? |
+| Completeness | Is implementation substantive or placeholder-heavy? |
+
+## Output Format
+
+Return findings ordered by priority:
+
+```
+## Domain: <domain-name>
+
+### P1 (Blocking)
+- [Issue]: [What violates] -> [How to fix]
+
+### P2 (Important)
+- [Issue]: [What violates] -> [How to fix]
+
+### P3 (Minor)
+- [Issue]: [What violates] -> [How to fix]
+
+## Compounding Notes
+- [What should be encoded into skills/docs to prevent recurrence]
+```
+
+Compounding agent will use this to update harness based on engineer decisions.

package/.allhands/flows/shared/jury/CLAIM_VERIFICATION_REVIEW.md

@@ -0,0 +1,101 @@
+<goal>
+Verify claims made in prompts and alignment docs against actual codebase state. Per **Quality Engineering**, unverified claims lead to incorrect implementations.
+</goal>
+
+<inputs>
+- Alignment doc path
+- Prompts folder path
+</inputs>
+
+<outputs>
+- List of unverified claims requiring attention
+- Verified claims confirmed accurate
+- Corrections for false claims
+</outputs>
+
+<constraints>
+- MUST read actual files before confirming/denying claims
+- MUST check multiple search patterns before claiming absence
+- NEVER trust grep results alone for existence claims
+</constraints>
+
+## Claim Extraction
+
+Scan alignment doc and prompts for factual assertions about:
+- What exists ("there is a retry mechanism in...")
+- What doesn't exist ("no current handling for...")
+- How things work ("the auth flow uses...")
+- File/function locations ("located at src/...")
+
+## Verification Process
+
+For each extracted claim:
+
+### Step 1: Categorize
+
+| Claim Type | Verification Method |
+|------------|---------------------|
+| Existence | Read the referenced file/symbol |
+| Absence | Search with multiple patterns, check likely locations |
+| Behavior | Read the code, trace the logic |
+| Location | Verify file exists and contains referenced content |
+
+### Step 2: Verify
+
+```yaml
+claim: "<extracted claim>"
+source: "<prompt number or alignment doc section>"
+
+verification:
+  method: read | search | trace
+  files_checked: ["<paths>"]
+  patterns_tried: ["<if search>"]
+  context_lines: "<±N lines read>"
+
+result: verified | false | partially_true | unverifiable
+correction: "<if false, what's actually true>"
+```
+
+### Step 3: Output
+
+Structure findings for REVIEW_OPTIONS_BREAKDOWN:
+
+```yaml
+claim_verification:
+  verified_claims:
+    - claim: "<claim text>"
+      source: "<prompt/alignment>"
+      evidence: "<file:line or brief explanation>"
+
+  false_claims:
+    - claim: "<claim text>"
+      source: "<prompt/alignment>"
+      actual: "<what's actually true>"
+      impact: high | medium | low
+      suggested_fix: "<how to correct in source>"
+
+  unverifiable_claims:
+    - claim: "<claim text>"
+      source: "<prompt/alignment>"
+      reason: "<why unverifiable>"
+      recommendation: "<what to do>"
+```
+
+## Impact Assessment
+
+| Impact | Criteria |
+|--------|----------|
+| **High** | False claim would cause implementation failure |
+| **Medium** | False claim causes rework but not failure |
+| **Low** | False claim is cosmetic or non-blocking |
+
+## Common Verification Failures
+
+| Pattern | Why It's Risky |
+|---------|---------------|
+| "Based on the search results..." | Search may have missed files |
+| "As we discussed earlier..." | Memory may be inaccurate |
+| "The standard pattern here is..." | May not match actual codebase |
+| "Similar to X, Y does..." | Assumption without verification |
+
+**When in doubt, read the code.**