all-hands-cli 0.1.0

package/.allhands/flows/shared/IDEATION_CODEBASE_GROUNDING.md

@@ -0,0 +1,49 @@
+<goal>
+Ground ideation in state-of-the-world codebase reality. Per **Ideation First**, understand both what is implemented AND what is planned for implementation to inform the ideation interview.
+</goal>
+
+<inputs>
+- Collection of seed information/queries from engineer's initial ideation prompt
+</inputs>
+
+<outputs>
+- Relevant codebase files with details, use cases, and engineering knowledge
+- List of milestone dependencies by name
+- Per dependency: key features to ASSUME EXISTS, or open decisions to ASSUME AT LEAST ONE OF EXISTS
+</outputs>
+
+<constraints>
+- MUST search roadmap first to identify planned dependencies
+- MUST overlay codebase findings against roadmap to account for future changes
+- MUST use LSP before file reads for referenced symbols
+</constraints>
+
+## Roadmap Search
+
+Run roadmap queries in parallel first:
+- Run `ah knowledge roadmap search "<query>"` for each input query
+- Identify planned work that ideation will build on top of
+- These become milestone dependencies
+
+## Codebase Search
+
+For existing implementation understanding:
+- Run `ah knowledge docs search "<query>"` for each input query (parallel)
+- Extract patterns, solutions, and engineer reasoning
+- Use LSP to navigate referenced symbols FIRST
+- Only read files if LSP not possible
+
+## Synthesis
+
+Combine roadmap and codebase findings:
+- Account for codebase patterns that may change when dependencies are implemented
+- Identify which current patterns will remain vs. be superseded
+
+## Output Formatting
+
+Provide:
+- Codebase files with most relevant details for ideation interview
+- Milestone dependencies by name
+- Per dependency:
+  - Features to ASSUME EXISTS (definite implementations)
+  - Features to ASSUME AT LEAST ONE OF EXISTS (open approach decisions)

package/.allhands/flows/shared/PLAN_DEEPENING.md

@@ -0,0 +1,152 @@
+<goal>
+Enhance planning artifacts with parallel research and skill application. Per **Knowledge Compounding**, surface relevant learnings and best practices before implementation begins.
+</goal>
+
+<inputs>
+- Alignment doc path
+- Prompts folder path
+- Spec doc path
+</inputs>
+
+<outputs>
+- Enhanced prompts with research insights sections
+- Updated alignment doc with discovered considerations
+- Conflict report (if research conflicts with current plan)
+</outputs>
+
+<constraints>
+- MUST preserve original prompt content (only add research insights)
+- MUST use existing schemas from `.allhands/schemas/`
+- NEVER modify prompt task scope
+- NEVER add tasks or change acceptance criteria
+</constraints>
+
+## Context Analysis
+
+Read planning artifacts to understand enhancement targets:
+- Read all prompts in the prompts folder
+- Read alignment doc for current decisions
+- Read spec doc for original intent
+- Identify technology domains, components, and patterns mentioned
+
+## Research Spawning
+
+Spawn parallel subtasks for each research area:
+
+### Skill Application
+
+Per **Frontier Models are Capable**, match skills to plan content:
+- Run `ah skills list` to discover available skills
+- For each domain in the plan, spawn subtask:
+  - Read matched skill's SKILL.md
+  - Apply skill patterns to relevant prompts
+  - Return best practices and gotchas
+
+### Solutions Search
+
+Per **Knowledge Compounding**, check for relevant past solutions:
+- Run `ah solutions search "<domain keywords>"` for each technology area
+- Run `ah memories search "<domain keywords>"` for relevant learnings and engineer preferences
+- For high-scoring matches, extract:
+  - Key insights that apply
+  - Gotchas to avoid
+  - Patterns to follow
+
+### Codebase Patterns
+
+- Spawn subtasks to read `.allhands/flows/shared/CODEBASE_UNDERSTANDING.md`
+- Target: existing implementations of similar patterns
+- Return: file references and conventions discovered
+
+### External Research (if needed)
+
+For novel technologies or high-risk domains:
+- Spawn subtasks to read `.allhands/flows/shared/RESEARCH_GUIDANCE.md`
+- Target: best practices, edge cases, performance considerations
+
+## Synthesis
+
+After all research completes:
+
+### Group by Prompt
+
+For each prompt, collect:
+- Relevant skill patterns
+- Applicable solutions from docs/solutions/
+- Codebase pattern references
+- External research findings
+
+### Conflict Detection
+
+Identify conflicts between:
+- Research findings and current plan
+- Different research sources
+- Skills and codebase patterns
+
+Flag conflicts for engineer review - do not resolve automatically.
+
+## Enhancement
+
+For each prompt with research findings:
+
+### Add Research Insights Section
+
+Append to prompt body (after existing content):
+
+```markdown
+---
+
+## Research Insights
+
+**Skills Applied**: [List of skills that informed this section]
+
+**Best Practices**:
+- [Concrete recommendation from research]
+- [Pattern to follow]
+
+**Gotchas to Avoid**:
+- [Past solution reference: docs/solutions/...] - [Key insight]
+- [Potential pitfall from research]
+
+**Codebase References**:
+- [path/to/file.ts:42] - [Pattern to follow]
+
+**External References**:
+- [URL] - [Key takeaway]
+```
+
+### Update Alignment Doc
+
+If research revealed considerations not in current plan:
+- Add "Research Insights" section to alignment doc
+- Document discovered risks, patterns, or decisions needed
+- Flag items requiring engineer input
+
+## Validation
+
+After enhancement:
+- Verify original prompt content unchanged
+- Verify only additive changes made
+- Check for any unresolved conflicts
+
+## Completion
+
+Present summary to engineer:
+```
+## Plan Deepening Summary
+
+### Prompts Enhanced
+- [Prompt X]: [Skills/solutions applied]
+- [Prompt Y]: [Skills/solutions applied]
+
+### Key Discoveries
+- [Important finding that may affect approach]
+
+### Conflicts Identified
+- [Conflict description] -> [Options for resolution]
+
+### Alignment Doc Updates
+- [Sections added or updated]
+```
+
+Per **Quality Engineering**, engineer decides how to proceed with conflicts.

package/.allhands/flows/shared/PROMPT_TASKS_CURATION.md

@@ -0,0 +1,113 @@
+<goal>
+Create, edit, and maintain Prompt Task files - the atomic unit of work. Per **Prompt Files as Units of Work**, prompts ARE the tasks, distributed for parallel execution with strict validation gates.
+</goal>
+
+<inputs>
+- Path to the prompts directory
+- Planning session number
+</inputs>
+
+<outputs>
+- Prompt file(s) at specified path following naming convention
+</outputs>
+
+<constraints>
+- MUST run `ah schema prompt` for frontmatter and body structure
+- MUST include `skills` and `validation_suites` in frontmatter
+- MUST include `patches_prompts: [X, Y]` for user-patch prompts
+- NEVER modify `status: done` prompts unless explicitly requested
+- NEVER create prompt summary entries in the alignment doc's `## Prompt Summaries` section. Per **Prompt Files as Units of Work**, those entries are written exclusively by executor agents after prompt completion — they document decisions made and work done, which don't exist yet at creation time.
+</constraints>
+
+## Schema Reference
+
+- Run `ah schema prompt` for frontmatter and body structure
+- Run `ah schema prompt body` for success/failure summary formats
+
+## Core Principles
+
+### Never Modify Completed Prompts
+- `status: done` prompts are immutable unless explicitly requested
+- Create new prompts to extend or fix completed work
+
+### Write Implementation-Ready Prompts
+- Include specific file paths, function names, and code references
+- Provide enough detail that implementors don't waste context searching
+- Reference relevant existing patterns in the codebase
+
+### Design Intuitive Dependencies
+- Map `dependencies: [X, Y]` so prompts execute in correct succession
+- Minimize blocking chains - parallelize where possible
+- Each prompt should be completable once dependencies are met
+
+## Skills Integration
+
+Skills embed domain expertise into prompts - "how to do it right."
+
+Read `.allhands/flows/shared/SKILL_EXTRACTION.md` and:
+- Run `ah skills list` to discover available skills
+- Match skills to the prompt's domain (by globs and description)
+- Read matched skill files for patterns, best practices, guidelines
+- Extract relevant knowledge and embed in Tasks section
+- Add matched skill file paths to `skills` frontmatter
+
+Skills provide: code patterns, library preferences, common pitfalls, domain-specific best practices.
+
+If no skill matches: proceed without skill-derived guidance, note the gap.
+
+## Validation Tooling Integration
+
+Per **Agentic Validation Tooling**, each prompt needs explicit validation.
+
+Read `.allhands/flows/shared/UTILIZE_VALIDATION_TOOLING.md` and:
+- Run `ah validation-tools list` to discover available suites
+- Match suites to the prompt's domain (by globs and description)
+- Read matched suite files for specific commands and success criteria
+- Add matched suite file paths to `validation_suites` frontmatter
+
+Acceptance criteria must be:
+- Specific enough for programmatic validation
+- Written with the same rigor a test engineer would apply
+- Achievable without human intervention until final E2E
+- Derived from validation commands in referenced suites
+
+If no suite matches: note gap, flag for CREATE_VALIDATION_TOOLING follow-up, use basic validation.
+
+**Testing is validation, not prompts**:
+- Do NOT create standalone "E2E testing" or "write tests" prompts
+- Tests are created as part of feature prompts OR via validation suite setup
+- Validation suites (Playwright, pytest, etc.) are attached to prompts via `validation_suites` field
+- If no validation suite exists, prompt should create test infrastructure as part of feature work
+
+## Context Budget (Critical)
+
+Per **Context is Precious**, agents degrade with context. Hard limits:
+
+| Context Usage | Quality | Claude's State |
+|---------------|---------|----------------|
+| 0-30% | PEAK | Thorough, comprehensive |
+| 30-50% | GOOD | Solid work |
+| 50-70% | DEGRADING | Efficiency mode |
+| 70%+ | POOR | Rushed, minimal |
+
+**Scope Limits:**
+- **Target ~50% context max**
+- 0-3 files modified = small (~15%)
+- 4-6 files modified = medium (~25%)
+- 7+ files modified = large - SPLIT the prompt
+
+## Task Breakdown Guidelines
+
+- 2-6 tasks per prompt (validatable as a unit)
+- Each prompt ends with meaningful validation checkpoint
+- Order tasks to derisk critical paths first
+- Compound refinement: each prompt builds on prior validated work
+- **Plan wiring, not just artifacts** - ensure tasks connect components (API calls, imports, state flow), not just create files in isolation
+
+## Writing the Prompt File
+
+- Write to the prompts directory path
+- Naming convention: `<two_digit_number>-<prompt_type>-<title>["-DONE"].prompt.md`
+- Include `skills: [.allhands/skills/skill-1/SKILL.md, ...]` in frontmatter
+- Include `validation_suites: [.allhands/validation/suite-1.md, ...]` in frontmatter
+- For user-patch prompts, include `patches_prompts: [X, Y]`

package/.allhands/flows/shared/PROMPT_VALIDATION_REVIEW.MD

@@ -0,0 +1,99 @@
+<goal>
+Review prompt implementation for validation pass/fail. Per **Agentic Validation Tooling**, be critical of validation quality while balancing speed to production.
+</goal>
+
+<inputs>
+- Prompt file path
+- Validation tooling results and checks
+- Validation methods used (include validation-suite file paths)
+- Work done to account for any previous validation failures
+</inputs>
+
+<outputs>
+- Verdict: PASS | FAIL
+- What it will take to pass (if fail): implementation issues, validation tooling adjustments, or additional convincing results needed
+</outputs>
+
+<constraints>
+- MUST check git diff of uncommitted work
+- MUST be critical of validation quality, not just results
+- MUST consider prior failure attempts when evaluating
+- NEVER fail for being overly strict when iteration shows genuine progress
+</constraints>
+
+## Review Process
+
+### Diff Analysis
+- Run `git diff` to review uncommitted work
+- Look for immediately noticeable issues
+
+### Goal-Backward Verification
+
+Per **Quality Engineering**, task completion ≠ goal achievement. Verify work is substantive:
+
+| Level | Check |
+|-------|-------|
+| Existence | Files were created/modified |
+| Substantive | Implementation is real, not placeholder |
+| Wired | Components are connected (API calls, imports, state rendering) |
+
+### Stub Detection
+
+Scan for placeholder patterns that indicate incomplete work:
+
+| Pattern | Red Flags |
+|---------|-----------|
+| Placeholder content | `TODO`, `FIXME`, `placeholder`, `coming soon`, `will be here` |
+| Empty implementations | `return null`, `return {}`, `return []`, `=> {}` |
+| Stub handlers | `onClick={() => {}}`, `onSubmit={(e) => e.preventDefault()}` only |
+| Orphaned code | Files created but not imported/used anywhere |
+| Unconnected APIs | API calls exist but responses not used |
+
+### Validation Quality Critique
+
+Per **Knowledge Compounding**, bad validation methods should not persist:
+
+| Check | Red Flag |
+|-------|----------|
+| Mock tests | Do they test real implementation or just pass? |
+| Test scope | Is validation curated to this prompt to LOOK like it passes? |
+| Product efficacy | Does validation prove actual product stability? |
+| Redundancy | Are tests duplicative without adding confidence? |
+
+### Scenario Exploration
+
+Consider edge cases and failure scenarios:
+
+| Scenario | Check |
+|----------|-------|
+| Happy Path | Normal operation with valid inputs |
+| Invalid Inputs | Null, empty, malformed data handling |
+| Boundary Conditions | Min/max values, empty collections |
+| Concurrent Access | Race conditions, deadlocks |
+| Network Issues | Timeouts, partial failures |
+| Error Recovery | Graceful degradation, retry logic |
+
+Focus on scenarios that could cause data corruption, security issues, or user-facing failures.
+
+### Prior Failure Context
+
+If previous failures are documented:
+- Consider work done to address them
+- Recognize genuine progress vs. superficial fixes
+- Being overly strict wastes cycles - balance rigor with velocity
+
+## Verdict
+
+### PASS Criteria
+- Implementation meets acceptance criteria
+- Validation proves product efficacy (not just test passing)
+- No immediately noticeable issues in diff
+
+### FAIL Response
+Provide actionable feedback:
+- Implementation issues needing resolution
+- Validation tooling adjustments needed
+- Additional convincing results required
+- Strong implementation examples where helpful
+
+Per **Knowledge Compounding**, feedback should compound - prevent misuse of validation and bad implementation patterns in future prompts.

package/.allhands/flows/shared/QUICK_PREMORTEM.md

@@ -0,0 +1,70 @@
+<goal>
+Fast risk check for single prompts before execution. Per **Quality Engineering**, even lightweight tasks benefit from brief failure mode consideration.
+</goal>
+
+<inputs>
+- Single prompt file path
+- Optional: alignment doc path for context
+</inputs>
+
+<outputs>
+- Brief risk assessment (2-3 minutes max)
+- Go/adjust/block recommendation
+</outputs>
+
+<constraints>
+- MUST complete in under 3 minutes
+- MUST verify findings before flagging
+- NEVER block without high-severity verified Tiger
+</constraints>
+
+## Quick Questions
+
+Answer these five questions for the prompt:
+
+| # | Question | If Yes → |
+|---|----------|----------|
+| 1 | What's the single biggest thing that could go wrong? | Flag as Tiger if unmitigated |
+| 2 | Any external dependencies that could fail? | Flag as Tiger if no fallback |
+| 3 | Is rollback possible if this breaks? | Flag as Elephant if unclear |
+| 4 | Edge cases not covered in acceptance criteria? | Note for prompt amendment |
+| 5 | Unclear requirements that could cause rework? | Flag as Tiger if blocking |
+
+## Output Format
+
+```yaml
+quick_premortem:
+  prompt: "<number or name>"
+  duration: "<minutes>"
+
+  recommendation: go | adjust | block
+
+  tigers:  # Only verified, high-impact
+    - risk: "<brief description>"
+      action: "<specific fix>"
+
+  notes:  # Lower severity, awareness only
+    - "<observation>"
+
+  adjustment_needed:  # If recommendation is "adjust"
+    - "<what to add/change in prompt>"
+```
+
+## When to Use
+
+| Context | Use Quick Premortem |
+|---------|---------------------|
+| Emergent refinement prompts | Before execution |
+| Judge-produced review-fix prompts | Before execution |
+| PR-review produced prompts | Before execution |
+| Single deterministic fix | Optional |
+
+For full milestone prompt sets, use `.allhands/flows/shared/jury/PROMPT_PREMORTEM.md` instead.
+
+## Recommendation Thresholds
+
+| Recommendation | Criteria |
+|----------------|----------|
+| **Go** | No Tigers, or Tigers have clear mitigations already |
+| **Adjust** | Tigers exist but fixable with prompt amendment |
+| **Block** | High-severity Tiger requiring engineer decision |

package/.allhands/flows/shared/RESEARCH_GUIDANCE.md

@@ -0,0 +1,38 @@
+<goal>
+Pick the right research tool and depth for the need. Per **Context is Precious**, use targeted tools to gather external knowledge efficiently.
+</goal>
+
+<constraints>
+- MUST determine discovery level before researching
+- MUST use `gh` CLI for GitHub content, not research tools
+- NEVER use WebSearch or WebFetch tools since the tooling here is much better
+- If any tool fails, you MUST try another tool from the decision tree.
+</constraints>
+
+## Decision Tree
+
+```
+├─ Broad synthesis, deep research with citations? → `ah perplexity research "<query>"`
+├─ Same + X/Twitter community insights? → `ah perplexity research "<query>" --grok-challenge`
+├─ Find sources, discover URLs? → `ah tavily search "<query>"`
+├─ Full content from known URL? → `ah tavily extract "<url1>" "<url2>"`
+├─ Challenge findings with social signals? → `ah perplexity research "<query>" --challenge`
+└─ GitHub content? → Use `gh` CLI directly
+```
+
+## When to Use What
+
+| Need | Tool | Why |
+|------|------|-----|
+| "Best ways to solve X?" | perplexity | Synthesizes multiple sources |
+| "Best ways to solve X for agentic developers?" | perplexity --grok-challenge | Synthesis + X/Twitter community challenge |
+| "Find articles about X" | tavily search | Returns URLs to explore |
+| "Get content from this doc" | tavily extract | Full page content |
+| "Challenge research with developer sentiment" | perplexity --challenge | Validates findings via X/Twitter |
+
+## Combination Strategy
+
+When unsure which tool is best:
+- Use multiple tools in parallel
+- Compare result quality for your use case
+- Remember which gives best results for similar future queries

package/.allhands/flows/shared/REVIEW_OPTIONS_BREAKDOWN.md

@@ -0,0 +1,68 @@
+<goal>
+Organize unstructured review feedback into ranked, actionable options for engineer decision. Per **Knowledge Compounding**, both accepted and declined items must be documented.
+</goal>
+
+<inputs>
+- Unorganized list of review options from multiple sources/perspectives
+- Alignment doc path (if unfamiliar with contents)
+- Prompt path file for planned/completed implementation summaries
+</inputs>
+
+<outputs>
+- Engineer's choices (accept/decline per item)
+- Updated alignment doc with declined items documented
+</outputs>
+
+<constraints>
+- MUST present options ranked P1, P2, P3 (most to least important)
+- MUST allow engineer to explain why they decline items
+- MUST document declined items in alignment doc
+</constraints>
+
+## Analysis
+
+For each review item:
+- Understand relationship to other items
+- Combine duplicates and elevate repeated concerns (proves urgency)
+- Consider importance in context of spec doc goals and engineer desires
+
+### Premortem Integration
+
+When premortem findings are present in inputs:
+
+| Premortem Category | Maps To | Handling |
+|--------------------|---------|----------|
+| **Tigers** (high severity) | P1 | Require explicit accept or fix decision |
+| **Tigers** (medium severity) | P2 | Recommend addressing, allow skip |
+| **Elephants** | Discussion Points | Surface to engineer, document response |
+| **Paper Tigers** | Acknowledged | Note as acceptable risk in alignment doc |
+| **Checklist Gaps** | P2 or P3 | Prompt amendments to close gaps |
+
+Tigers with `mitigation_checked` field prove thorough analysis - weight these higher.
+
+## Priority Ranking
+
+| Priority | Criteria |
+|----------|----------|
+| P1 | Blocking issues, security concerns, core functionality |
+| P2 | Important improvements, consistency issues, best practices |
+| P3 | Nice-to-haves, polish, minor optimizations |
+
+## Engineer Presentation
+
+Present ranked options:
+- Order from most important (P1) to least important (P3)
+- For each: describe the issue, explain importance, suggest implementation
+- Ask engineer which to accept and which to decline
+- Always allow engineer to explain their reasoning
+
+## Decision Documentation
+
+Run `ah schema alignment` to identify where to track declined items.
+
+Document in alignment doc:
+- Which items were accepted (will become prompts)
+- Which items were declined AND engineer's reasoning
+- Accepted risks from premortem (Tigers acknowledged but not mitigated)
+- Paper Tigers noted as acceptable risk decisions
+- Per **Knowledge Compounding**, this prevents future re-suggestion of rejected approaches

package/.allhands/flows/shared/SKILL_EXTRACTION.md

@@ -0,0 +1,84 @@
+<goal>
+Find and extract domain expertise from skills to embed in prompt instructions. Per **Knowledge Compounding**, skills are "how to do it right" - expertise that compounds across prompts.
+</goal>
+
+<inputs>
+- Files/domains involved in the implementation task
+- Nature of the changes (UI, native code, deployment, etc.)
+</inputs>
+
+<outputs>
+- Extracted knowledge distilled for prompt embedding
+- Sources consulted (skill file paths)
+</outputs>
+
+<constraints>
+- MUST run `ah skills list` to discover available skills
+- MUST match skills via both glob patterns AND description inference
+- MUST extract task-relevant knowledge, not copy entire skill files
+- MUST list sources consulted in output
+</constraints>
+
+## Step 1: Discover Available Skills
+
+- Run `ah skills list`
+- Returns JSON with: `name`, `description`, `globs`, `file` path
+
+## Step 2: Identify Relevant Skills
+
+Match skills using two approaches:
+
+**Glob pattern matching** (programmatic):
+- Compare files you're touching against each skill's `globs`
+- Skills with matching patterns are likely relevant
+
+**Description inference** (semantic):
+- Read skill descriptions
+- Match against task nature (UI, deployment, native modules, etc.)
+
+Select all skills that apply to implementation scope.
+
+## Step 3: Read Skill Documentation
+
+For each relevant skill, read the full file:
+- Read `.allhands/skills/<skill-name>/SKILL.md`
+
+Extract:
+- **Key patterns**: Code patterns, library preferences, common pitfalls
+- **Best practices**: Guidelines specific to this domain
+- **References**: Sub-documents within the skill folder
+
+## Step 4: Extract Knowledge for Prompt
+
+Synthesize skill content into actionable prompt guidance:
+- Distill key instructions
+- Include specific examples where relevant
+- Reference sources
+- Avoid duplication - extract what's task-relevant
+
+## Step 5: Output with Sources
+
+Provide:
+
+```
+## Skill-Derived Guidance
+
+### From building-expo-ui:
+- Use `<Link.Preview>` for context menus
+- Prefer `contentInsetAdjustmentBehavior="automatic"` over SafeAreaView
+
+### From react-native-best-practices:
+- Profile with React DevTools before optimizing
+- Use FlashList for lists with >50 items
+
+## Sources Consulted
+- .allhands/skills/building-expo-ui/SKILL.md
+- .allhands/skills/react-native-best-practices/SKILL.md
+```
+
+## For Prompt Curation
+
+When used via PROMPT_TASKS_CURATION:
+- Add skill file paths to prompt's `skills` frontmatter
+- Embed extracted guidance in prompt's Tasks section
+- Makes domain expertise explicit and immediately available to executors