all-hands-cli 0.1.0

package/.allhands/README.md

@@ -0,0 +1,75 @@
+# All Hands CLI
+
+Internal CLI for the All Hands agentic harness.
+
+## Installation
+
+```bash
+cd .allhands/harness
+npm install
+```
+
+The `ah` command is automatically installed to `~/.local/bin/ah` when you run `npx all-hands init`. This shim finds and executes the project-local `.allhands/harness/ah` from any subdirectory.
+
+For local development, copy the shim to your PATH:
+```bash
+cp .allhands/harness/ah ~/.local/bin/ah
+```
+
+### Universal Ctags (for `ah docs` command)
+
+```bash
+# macOS
+brew install universal-ctags
+
+# Ubuntu/Debian
+sudo apt install universal-ctags
+```
+
+### AST-grep (for advanced code search)
+
+```bash
+# macOS
+brew install ast-grep
+
+# cargo
+cargo install ast-grep --locked
+```
+
+### Desktop Notifications (macOS)
+
+```bash
+brew install --cask notifier
+```
+
+## Language Servers (for LSP tool)
+
+```bash
+npm install -g typescript-language-server typescript pyright
+brew install swift  
+```
+
+## Environment Variables
+
+Check `.env.ai.example` for what you should populate `.env.ai` with.
+
+
+## Quick Start
+
+```bash
+ah <command>
+```
+
+The `ah` command works from any directory within an all-hands project.
+
+
+## Project Settings
+
+Project-specific configuration lives in `.allhands/settings.json`:
+
+```json
+{
+  "$schema": "./harness/src/schemas/settings.schema.json",
+}
+```
+

package/.allhands/agents/compounder.yaml

@@ -0,0 +1,15 @@
+name: compounder
+flow: COMPOUNDING.md
+prompt_scoped: false
+tui_action: compound
+tui_label: Compounder
+tui_requires_spec: true
+non_coding: false
+message_template: |
+  Spec path: ${SPEC_PATH}
+  Alignment doc path: ${ALIGNMENT_PATH}
+  Prompt files path: ${PROMPTS_FOLDER}
+template_vars:
+  - SPEC_PATH
+  - ALIGNMENT_PATH
+  - PROMPTS_FOLDER

package/.allhands/agents/coordinator.yaml

@@ -0,0 +1,17 @@
+name: coordinator
+flow: COORDINATION.md
+prompt_scoped: false
+tui_action: coordinator
+tui_label: Coordinator
+tui_requires_spec: true
+non_coding: true
+message_template: |
+  Coordinating milestone: ${SPEC_NAME}
+  Spec: ${SPEC_PATH}
+  Alignment doc: ${ALIGNMENT_PATH}
+  Prompts folder: ${PROMPTS_FOLDER}
+template_vars:
+  - SPEC_NAME
+  - SPEC_PATH
+  - ALIGNMENT_PATH
+  - PROMPTS_FOLDER

package/.allhands/agents/documentor.yaml

@@ -0,0 +1,15 @@
+name: documentor
+flow: DOCUMENTATION.md
+prompt_scoped: false
+tui_action: compound
+tui_label: Documentor
+tui_requires_spec: true
+non_coding: false
+message_template: |
+  Spec path: ${SPEC_PATH}
+  Alignment doc path: ${ALIGNMENT_PATH}
+  Prompt files path: ${PROMPTS_FOLDER}
+template_vars:
+  - SPEC_PATH
+  - ALIGNMENT_PATH
+  - PROMPTS_FOLDER

package/.allhands/agents/e2e-test-planner.yaml

@@ -0,0 +1,17 @@
+name: e2e-test-planner
+flow: E2E_TEST_PLAN_BUILDING.md
+prompt_scoped: false
+tui_action: e2e-test-planner
+tui_label: E2E Tests
+tui_requires_spec: true
+non_coding: false
+message_template: |
+  Planning folder: ${PLANNING_FOLDER}
+  Spec path: ${SPEC_PATH}
+  Alignment doc path: ${ALIGNMENT_PATH}
+  E2E Test Plan Output Path: ${OUTPUT_PATH}
+template_vars:
+  - PLANNING_FOLDER
+  - SPEC_PATH
+  - ALIGNMENT_PATH
+  - OUTPUT_PATH

package/.allhands/agents/emergent.yaml

@@ -0,0 +1,22 @@
+name: emergent
+flow: EMERGENT_PLANNING.md
+prompt_scoped: true
+tui_action: emergent
+tui_label: Emergent
+tui_requires_spec: true
+non_coding: true
+message_template: |
+  DO NOT ask for any user input for this task.
+  Alignment doc: ${ALIGNMENT_PATH}
+  Prompts folder: ${PROMPTS_FOLDER}
+  Workflow domain config: ${WORKFLOW_DOMAIN_PATH}
+  Branch: ${BRANCH}
+
+  Available hypothesis domains for this workflow:
+  ${HYPOTHESIS_DOMAINS}
+template_vars:
+  - ALIGNMENT_PATH
+  - PROMPTS_FOLDER
+  - WORKFLOW_DOMAIN_PATH
+  - HYPOTHESIS_DOMAINS
+  - BRANCH

package/.allhands/agents/executor.yaml

@@ -0,0 +1,14 @@
+name: executor
+flow: PROMPT_TASK_EXECUTION.md
+prompt_scoped: true
+tui_action: executor
+tui_label: Executor
+tui_requires_spec: true
+non_coding: false
+message_template: |
+  DO NOT ask for any user input for this task.
+  Your prompt file: ${PROMPT_PATH}
+  Alignment doc: ${ALIGNMENT_PATH}
+template_vars:
+  - PROMPT_PATH
+  - ALIGNMENT_PATH

package/.allhands/agents/ideation.yaml

@@ -0,0 +1,11 @@
+name: ideation
+flow: IDEATION_SCOPING.md
+prompt_scoped: false
+tui_action: ideation
+tui_label: Ideation
+tui_requires_spec: false
+non_coding: false
+message_template: |
+  Workflow domain config: ${WORKFLOW_DOMAIN_PATH}
+template_vars:
+  - WORKFLOW_DOMAIN_PATH

package/.allhands/agents/initiative-steering.yaml

@@ -0,0 +1,19 @@
+name: initiative-steering
+flow: INITIATIVE_STEERING.md
+prompt_scoped: false
+tui_action: initiative-steering
+tui_label: Steer Initiative
+tui_requires_spec: true
+non_coding: true
+message_template: |
+  Spec Path: ${SPEC_PATH}
+  Alignment doc: ${ALIGNMENT_PATH}
+  Prompts folder: ${PROMPTS_FOLDER}
+  Workflow domain config: ${WORKFLOW_DOMAIN_PATH}
+  Branch: ${BRANCH}
+template_vars:
+  - SPEC_PATH
+  - ALIGNMENT_PATH
+  - PROMPTS_FOLDER
+  - WORKFLOW_DOMAIN_PATH
+  - BRANCH

package/.allhands/agents/judge.yaml

@@ -0,0 +1,13 @@
+name: judge
+flow: JUDGE_REVIEWING.md
+prompt_scoped: false
+tui_action: review-jury
+tui_label: Review Jury
+tui_requires_spec: true
+non_coding: true
+message_template: |
+  Reviewing milestone: ${SPEC_NAME}
+  Alignment doc: ${ALIGNMENT_PATH}
+template_vars:
+  - SPEC_NAME
+  - ALIGNMENT_PATH

package/.allhands/agents/planner.yaml

@@ -0,0 +1,19 @@
+name: planner
+flow: SPEC_PLANNING.md
+prompt_scoped: false
+tui_action: planner
+tui_label: Planner
+tui_requires_spec: true
+non_coding: false
+message_template: |
+  Spec: ${SPEC_NAME}
+  Spec Path: ${SPEC_PATH}
+  Alignment doc: ${ALIGNMENT_PATH}
+  Prompts Folder: ${PROMPTS_FOLDER}
+  Workflow domain config: ${WORKFLOW_DOMAIN_PATH}
+template_vars:
+  - SPEC_NAME
+  - SPEC_PATH
+  - ALIGNMENT_PATH
+  - PROMPTS_FOLDER
+  - WORKFLOW_DOMAIN_PATH

package/.allhands/agents/pr-reviewer.yaml

@@ -0,0 +1,15 @@
+name: pr-reviewer
+flow: PR_REVIEWING.md
+prompt_scoped: false
+tui_action: review-pr
+tui_label: Review PR
+tui_requires_spec: true
+non_coding: false
+message_template: |
+  Reviewing PR feedback for: ${SPEC_NAME}
+  Alignment doc: ${ALIGNMENT_PATH}
+  Prompts folder: ${PROMPTS_FOLDER}
+template_vars:
+  - SPEC_NAME
+  - ALIGNMENT_PATH
+  - PROMPTS_FOLDER

package/.allhands/docs.json

@@ -0,0 +1,5 @@
+{
+  "$schema": ".allhands/harness/src/schemas/docs.schema.json",
+  "domains": [],
+  "exclude": []
+}

package/.allhands/docs.local.json

@@ -0,0 +1,26 @@
+{
+  "$schema": ".allhands/harness/src/schemas/docs.schema.json",
+  "domains": [
+    {
+      "name": "harness",
+      "path": ".allhands/harness",
+      "description": "Core CLI tool with commands, hooks, TUI, MCP integration, and schema validation"
+    },
+    {
+      "name": "flows",
+      "path": ".allhands/flows",
+      "description": "Workflow definitions guiding agents through tasks"
+    },
+    {
+      "name": "agents",
+      "path": ".allhands/agents",
+      "description": "Agent configuration YAML files defining agent types and behaviors"
+    },
+    {
+      "name": "sync-cli",
+      "path": "src",
+      "description": "CLI for syncing the all-hands framework to other repositories"
+    }
+  ],
+  "exclude": []
+}

package/.allhands/flows/COMPOUNDING.md

@@ -0,0 +1,203 @@
+<goal>
+Extract learnings from completed specs to improve the harness, skills, and validation tooling. Per **Knowledge Compounding**, everything feeds forward - decisions, pivots, limitations, and realizations become persistent improvements.
+</goal>
+
+<constraints>
+- MUST ask the engineer before modifying harness files
+- MUST write compounding summary to `.planning/<spec>/compounding_summary.md`
+- MUST write non-trivial solutions to `docs/solutions/<category>/`
+- MUST add Implementation Reality section to spec in-place before completing
+- NEVER set spec frontmatter `status` — spec lifecycle is engineer-controlled
+- MUST interview engineer before finalizing compounding summary
+- NEVER modify harness without first principle justification
+- NEVER frame emergent prompt work as "scope creep" - per **Quality Engineering**, emergent work discovers valuable variants
+</constraints>
+
+## Context Gathering
+
+Read these spec artifacts to understand what happened:
+- Read the alignment doc at `.planning/<spec>/alignment.md`
+- Read the spec doc at `.planning/<spec>/spec.md`
+- Read all prompt files in `.planning/<spec>/prompts/`
+- Run `git log --oneline` to review commit history for this branch
+
+## Completion Assessment by Spec Type
+
+Per **Frontier Models are Capable**, assess completion differently based on spec `type`:
+
+- **Milestone** (or missing): Spec acceptance criteria met, all prompts complete, knowledge extraction thorough
+- **Exploratory** (investigation, optimization, refactor, documentation, triage): Problem resolution assessed against original hypothesis, learnings extracted from experiment outcomes, unresolved questions documented for future work
+
+## Signal Analysis
+
+Identify patterns that indicate harness improvement opportunities:
+
+**Prompt Signals**:
+- Failed prompts (multiple attempts) → execution or planning issues
+- Patch prompts → check `patches_prompts` field to find root cause
+- Emergent refinement inclusions/exclusions → engineer intent signals
+- Review prompt count → planning or review quality issues
+- Blocker learnings in summaries → planning gaps that required engineer steering
+
+**Tooling Signals**:
+- Read ALL prompt files' `skills` and `validation_suites` frontmatter - not just patches
+- Cross-reference each prompt's summary (Limitations, Decisions, Learnings, Validation results) against the specific skills and validation suites it used
+- Build a per-tool impact map:
+  - **Per skill**: What did it catch? What did it miss? Did limitations or decisions reveal guidance gaps?
+  - **Per validation suite**: What issues did it surface? What escaped to review? Did it produce false positives?
+  - **Per validation suite — crystallization**: For each suite used during execution, evaluate:
+    - What stochastic patterns were discovered during exploratory validation?
+    - Which patterns are stable and repeatable enough to crystallize into deterministic checks?
+    - Should any new deterministic tests be added to the suite's Deterministic Integration section?
+    - Are there stochastic exploration patterns that should be documented in the suite's Stochastic Validation section for future agents?
+  - **Absent tooling**: What validation needs did prompts reveal that no existing suite covers?
+- Per **Agentic Validation Tooling**, this impact map feeds directly into harness improvement specs as evidence (not stored separately)
+
+**Decision Signals**:
+- Design decisions made given limitations
+- Engineer rejections and preference overrides (the preference itself is a compoundable learning)
+- Compromises between agentic suggestions and engineer preferences
+
+**Emergent Work Signals**:
+- Per **Quality Engineering**, emergent prompts are disposable extensions that discover which variants are valuable - they are not scope violations
+- Non-goal matches in emergent work are "non-goal violations" (specific exclusion was breached), never "scope creep" (scope was not changed - emergent work extends by design)
+- Reverted emergent work is expected quality control, not waste - per **Software is Cheap**, the cost of a revert is a valid cost of experimentation
+- Track: which emergent work was kept vs reverted, and why - this reveals engineer quality preferences
+
+## Memory Extraction
+
+Per **Knowledge Compounding**, capture learnings as memories:
+- Run `ah memories search <relevant terms>` to check for existing similar memories before writing duplicates
+- Write to `docs/memories.md` (searchable via `ah memories search`)
+- Format: `[Name] | [Domain] | [Source] | [Description]`
+  - Domains: `planning`, `validation`, `implementation`, `harness-tooling`, `ideation`
+  - Sources: `user-steering`, `agent-inferred`
+  - Description: 1-3 sentences of self-contained learning
+
+### Memory Capture Categories
+
+Ensure these categories are represented when signals exist:
+
+- **Technical learnings**: Patterns, anti-patterns, and solutions discovered during implementation
+- **Engineer preference memories**: When engineer overrides agent recommendation, capture the preference itself as a memory (the override is a signal of values and priorities)
+- **Systemic validation signals**: When review catches issues that implementation missed, capture as a validation coverage gap (e.g., "Review caught 6 issues no validation suite flagged")
+- **Harness behavior patterns**: Document specific thresholds, behaviors, and failure modes with concrete data - not just symptoms (e.g., "7 compaction continuations at >8 files touched" not just "context loss on long prompts")
+
+## Solution Documentation
+
+Per **Knowledge Compounding**, document non-trivial solved problems for institutional knowledge.
+
+### Identify Documentable Solutions
+
+From the signal analysis, identify problems that:
+- Required multiple investigation attempts
+- Had non-obvious solutions
+- Would benefit future sessions (similar issues likely to recur)
+- Involve agentic anti-patterns (hallucinations, duplications, miscommunications)
+
+Skip documentation for:
+- Simple typos or obvious syntax errors
+- Trivial fixes immediately resolved
+- One-off environment issues
+
+### Write Solution Files
+
+For each documentable solution:
+- Run `ah schema solution` for frontmatter and body section format
+- Determine `problem_type` and corresponding category directory
+- Generate filename: `<sanitized-symptom>-<component>-<YYYYMMDD>.md`
+- Create directory if needed: `mkdir -p docs/solutions/<category>`
+- Write solution file following schema
+- **Tag expansion**: Generate tags from anti-patterns, failed approaches, and adjacent search terms beyond the solution content - ask: "What would someone search for when about to hit this problem?"
+
+### Cross-Reference Solutions
+
+After all solutions are written, cross-reference related solutions:
+- Run `ah solutions list` then `ah solutions search` with terms from each new solution
+- For solutions sharing components, tags, or thematic overlap: add "## Related" section with links
+- Update existing similar solutions with cross-reference back to new solutions
+
+## Spec Finalization
+
+**MUST** update the original spec file in-place as a historical record. Per **Knowledge Compounding**, finalized specs become searchable via `ah knowledge docs search` - curate content for future retrieval value.
+
+- Add `## Implementation Reality` section documenting:
+  - What was actually implemented vs originally planned
+  - How engineer desires evolved during implementation (decisions, pivots, additions)
+  - Key technical decisions and their rationale
+- Keep content concise and decision-focused - this is indexed knowledge, not an operational dump
+- Preserve the original Goals and Non-Goals sections unmodified for contrast
+
+## Harness Improvement Handling [LAST PHASE]
+
+**Intentionally last** - complete all other compounding before diverting to harness work.
+
+### Classify and Interview
+
+Classify issues from Signal Analysis:
+
+| Signal Pattern | Action |
+|----------------|--------|
+| Skill guidance gaps or inaccuracies | Update skill file inline with approval |
+| Validation suite missed issues or needs strengthening | Update suite file inline with approval |
+| Missing validation suite for discovered need | Create via spec |
+| Flow/command/hook/planning issues | Structural - create spec |
+
+**MUST interview engineer before proceeding** - the compounding summary MUST NOT be finalized without engineer sign-off on classified issues:
+- Present all classified issues together
+- Walk through the per-tool impact map from Tooling Signals - for each skill and validation suite used, highlight where prompt-level learnings (limitations, decisions, workarounds) apply back to the tool itself
+- Per **Knowledge Compounding**, ask whether discoveries should be reflected in the skills or validation suites that were used, so future executions benefit
+- Ask about additional painpoints
+- Validate against `.allhands/principles.md`
+
+### Apply Changes
+
+**Skill refinements** (inline with approval):
+- Update skill body with learnings discovered during execution (new patterns, anti-patterns, missing reference material)
+- Add or correct guidance that would have prevented prompt failures or engineer steering
+
+**Validation suite refinements** (inline with approval):
+- Strengthen existing suites with newly discovered check patterns or edge cases
+- Update Stochastic Validation and Deterministic Integration sections with failure modes encountered during execution
+- **Crystallization**: Stable stochastic patterns discovered during execution should be promoted into deterministic checks in the suite's Deterministic Integration section, shifting stochastic exploration to the frontier
+
+**New validation suites**: Per **Agentic Validation Tooling**, if execution revealed validation gaps no existing suite covers:
+- **(A) Create spec** → Invoke `.allhands/flows/shared/CREATE_HARNESS_SPEC.md` with `domain_name: harness`
+- **(B) Defer** → Document in `docs/memories.md` under "Deferred Harness Improvements"
+
+**Structural changes** (flows, commands, hooks, planning):
+- Present all detected structural issues to the engineer
+- Ask which issues to include in a single harness improvement spec (multi-select)
+- Per **Frontier Models are Capable**, assume all engineer-confirmed issues belong in one spec - don't force individual scoping
+- Include the per-tool impact map as evidence in the spec
+- **(A) Create spec** → Invoke `.allhands/flows/shared/CREATE_HARNESS_SPEC.md` with `domain_name: harness` and all selected issues
+- **(B) Defer unselected** → Document in `docs/memories.md` under "Deferred Harness Improvements"
+
+## Completion
+
+Write `.planning/<spec>/compounding_summary.md`:
+```markdown
+# Compounding Summary
+
+## Detected Issues
+- [Patterns from patches, failures, feedback]
+
+## Tooling Refinements
+- [Skill file changes with rationale from prompt learnings]
+- [Validation suite changes with rationale from execution gaps]
+- [New validation suites created or deferred]
+
+## Flow Updates
+- [Flow file adjustments]
+
+## Memories Added
+- [References to docs/memories.md entries]
+
+## Solutions Documented
+- [docs/solutions/<category>/<filename>.md - brief description]
+
+## Engineer Feedback Addressed
+- [Specific concerns resolved]
+```
+
+This flow is idempotent - if run again without new changes, detect no work needed and stop.

package/.allhands/flows/COORDINATION.md

@@ -0,0 +1,89 @@
+<goal>
+Assist the engineer in coordinating the all-hands loop by providing visibility into milestone status, managing prompt-bound agents, and curating harness-managed files. Per **Frontier Models are Capable**, this agent orchestrates without implementing.
+</goal>
+
+<constraints>
+- NEVER write implementation code; only modify harness-managed files
+- MUST document engineer decisions in affected prompt files and alignment docs
+- MUST set `type: user-patch` and `patches_prompts: [X, Y]` when creating patch prompts
+- MUST ask clarifying questions when engineer intent is unclear
+</constraints>
+
+## Context Gathering
+
+On invocation, build situational awareness using the paths provided:
+- Read the spec doc (path provided in preamble)
+- Read the alignment doc (path provided in preamble)
+- List the prompts folder (path provided in preamble) to see all prompt files
+- Read prompt frontmatter to understand status, dependencies, and type
+
+## Coordination Services
+
+Present these options to the engineer:
+
+| Service | Description | Flow Reference |
+|---------|-------------|----------------|
+| **Quick Patch** | Create a deterministic fix prompt for a specific issue | `.allhands/flows/shared/PROMPT_TASKS_CURATION.md` |
+| **Interjection** | Insert a new prompt into the active loop between existing prompts | See [Prompt Interjection](#prompt-interjection) below |
+| **Emergent Surgery** | Triage emergent refinement prompts (keep/axe) | `.allhands/flows/shared/EMERGENT_REFINEMENT_ANALYSIS.md` |
+| **Prompt Edit** | Modify specific prompts given engineer concerns | `.allhands/flows/shared/PROMPT_TASKS_CURATION.md` |
+| **Agent Status** | Check tmux windows and agent health | Use harness tmux patterns |
+| **Kill/Restart** | Terminate broken agents and fix their prompts | Tmux + prompt edit |
+
+## Prompt Interjection
+
+Per **Prompt Files as Units of Work**, interjections are new prompts inserted into the active dependency graph mid-loop. The event loop detects new prompt files automatically — sequencing is controlled entirely through dependency mapping, not prompt numbers.
+
+Gather from the engineer:
+- **"Run after which prompt(s)?"** → these become `dependencies` on the new prompt
+- **"Run before which prompt(s)?"** → patch those prompts' `dependencies` arrays to include the new prompt number
+- The task description and acceptance criteria for the interjected work
+
+Steps:
+- Read all prompt frontmatter to understand the current dependency graph
+- Assign the next available prompt number (append-only — NEVER renumber existing prompts)
+- Create the new prompt file with `dependencies` set to the "run after" prompts
+- Patch each "run before" prompt's `dependencies` to include the new prompt number
+- Per **Ideation First**, confirm the resulting execution order with the engineer before writing files
+
+Example: inserting between prompts 2 and 3 when prompt 3 currently has `dependencies: [1]`:
+- Create prompt 7 with `dependencies: [2]`
+- Patch prompt 3: `dependencies: [1, 7]`
+- Resulting order: `1 → 2 → 7 → 3`
+
+If the interjection fixes prior execution issues, also follow the User-Patch Prompts section below.
+
+## User-Patch Prompts
+
+When creating prompts to fix issues from prior execution:
+- Set frontmatter `type: user-patch`
+- Include `patches_prompts: [X, Y]` listing prompt numbers being fixed
+- Document in body: what went wrong, engineer feedback, specific issues
+- Per **Knowledge Compounding**, this enables compounding to improve skills/validation-suites
+
+## Tmux Orchestration
+
+Use tmux commands consistent with `.allhands/harness/src/`:
+- Check session windows for agent status
+- Identify broken/stuck agents
+- Kill problematic agents
+- Coordinate restarts with fixed prompt files
+
+## Engineer Decision Documentation
+
+Per **Knowledge Compounding**, capture engineer contributions:
+- In prompt files: Document expectations, compromises, decisions
+- In alignment doc: Amend agent summaries with engineer steering (don't delete summaries)
+- Keep documentation concise but complete for compounding
+
+## Boundary with Initiative Steering
+
+Coordination is for **reactive, quick-action interventions**: quick patches, emergent triage, prompt surgery, agent management. For **structured, domain-aware deep replanning** that may change initiative goals and create/modify multiple prompts, use Initiative Steering (`INITIATIVE_STEERING.md`) via the TUI's "Steer Initiative" action instead.
+
+## Conversational Approach
+
+Per **Ideation First**, always clarify before acting:
+- Ask what the engineer wants to accomplish
+- Present options with tradeoffs
+- Confirm understanding before modifying files
+- Surface relevant context from prompts and alignment doc