all-hands-cli 0.1.0

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

@@ -0,0 +1,82 @@
+<goal>
+Review implementation for YAGNI (You Ain't Gonna Need It) violations. Per **Quality Engineering**, identify over-engineering that exceeds task requirements.
+</goal>
+
+<inputs>
+- Git diff to base (implementation files)
+- Alignment doc path (for engineer decisions)
+- Prompts folder path (for task scope)
+</inputs>
+
+<outputs>
+- YAGNI violations in implementation
+- Simplification recommendations, ordered by priority
+</outputs>
+
+<constraints>
+- MUST use git diff to base for implementation review
+- MUST give leniency to explicit engineer decisions
+- MUST still object to unnecessary complexity even post-planning decisions
+- MUST distinguish agentic over-engineering from engineer-requested features
+</constraints>
+
+## Context Gathering
+
+- Review all implementation changes from base branch
+- Read prompt summaries for task scope
+- Read alignment doc for engineer decisions
+- Identify patch prompts and emergent prompts (post-planning decisions)
+
+## YAGNI Detection in Implementation
+
+Look for code that:
+
+| Pattern | Description |
+|---------|-------------|
+| Beyond Scope | Implementation exceeds prompt tasks (note: `type: emergent` prompts explore extensions by design per **Quality Engineering** - YAGNI applies to implementation efficiency within the prompt, not to the emergent hypothesis itself) |
+| Unused Code | Functions/classes not called anywhere |
+| Over-Abstraction | Abstractions for single use cases |
+| Feature Flags | Configuration for features not requested |
+| Error Handling | Catching impossible error conditions |
+| Premature Optimization | Performance work without proven need |
+| Orphaned Artifacts | Files created but not wired into the system |
+| Dead Exports | Functions exported but never imported |
+| Defensive Overkill | Validation for scenarios that can't happen in internal code |
+
+## Decision Source Tracking
+
+| Source | Priority |
+|--------|----------|
+| Agentic over-reach | P1 - Agents often add unnecessary complexity |
+| Post-planning engineer decision | P2 - Still offer perspective, lower priority |
+| Original planning decision | P3 - Already reviewed, lowest priority |
+
+## Review Process
+
+For each implementation change:
+- Was this in the prompt's task scope?
+- Is this simpler than necessary?
+- Does this exceed requirements?
+- Who decided this (agent or engineer)?
+
+## Output Format
+
+Return findings ordered by priority:
+
+```
+## YAGNI Implementation Review
+
+### P1 (Agentic Over-Engineering)
+- [File]: [What's unnecessary] -> [What was actually needed] -> [Remove/simplify]
+
+### P2 (Exceeds Post-Planning Decisions)
+- [File]: [What was added] -> [Beyond what engineer clarified] -> [Consider removing]
+
+### P3 (Worth Reconsidering)
+- [File]: [Engineer-decided but still YAGNI perspective] -> [Alternative if desired]
+
+## Summary
+- [Lines of unnecessary code]
+- [Complexity hotspots]
+- [Simplification opportunities]
+```

package/.allhands/flows/wip/DEBUG_INVESTIGATION.md

@@ -0,0 +1,162 @@
+<goal>
+Structured investigation for complex bugs with unclear root causes. Per **Agentic Validation Tooling**, systematic debugging beats random exploration.
+</goal>
+
+<inputs>
+- Symptom description (error message, unexpected behavior, failing test)
+- Optional: suspected area of codebase
+</inputs>
+
+<outputs>
+- Root cause identification with evidence
+- Recommended fix approach
+- Optional: prompt file for fix implementation
+</outputs>
+
+<constraints>
+- MUST gather symptoms before hypothesizing
+- MUST verify hypotheses with evidence before concluding
+- MUST document investigation path for knowledge compounding
+- NEVER guess at root cause without verification
+</constraints>
+
+## STATUS: Work In Progress
+
+This flow is under development. Integration points with milestone workflow TBD.
+
+Potential integration approaches:
+1. Patch prompt type: `type: debug` prompts following this flow
+2. Pre-implementation phase: When initial execution fails
+3. Emergent debug: When emergent refinement hits blockers
+4. Coordinator service: "Debug Investigation" option in COORDINATION.md
+
+---
+
+## Phase 1: Symptom Gathering
+
+Collect all observable evidence:
+
+| Evidence Type | How to Gather |
+|---------------|---------------|
+| Error messages | Exact text, stack traces |
+| Reproduction steps | Minimal sequence to trigger |
+| When it started | Recent commits, config changes |
+| What changed | Git diff, dependency updates |
+| Frequency | Always, intermittent, specific conditions |
+
+```yaml
+symptoms:
+  error: "<exact error message>"
+  reproduction: ["<step 1>", "<step 2>", "..."]
+  frequency: always | intermittent | conditional
+  conditions: "<when it occurs>"
+  recent_changes: ["<commit>", "<config change>"]
+```
+
+## Phase 2: Hypothesis Formation
+
+Based on symptoms, form 2-3 ranked hypotheses:
+
+```yaml
+hypotheses:
+  - id: H1
+    description: "<what you think is wrong>"
+    confidence: high | medium | low
+    evidence_for: ["<symptom that supports>"]
+    evidence_against: ["<symptom that contradicts>"]
+    verification_method: "<how to confirm/deny>"
+
+  - id: H2
+    description: "<alternative explanation>"
+    ...
+```
+
+## Phase 3: Investigation
+
+For each hypothesis (highest confidence first):
+
+### 3.1 Targeted Search
+
+- Read `.allhands/flows/shared/CODEBASE_UNDERSTANDING.md` for search approach
+- Focus on areas suggested by hypothesis
+- Use claim verification: read actual code before concluding
+
+### 3.2 Evidence Collection
+
+```yaml
+investigation:
+  hypothesis: H1
+  files_examined: ["<path>"]
+  findings:
+    - location: "file.ts:42"
+      observation: "<what you found>"
+      supports_hypothesis: true | false
+  conclusion: confirmed | refuted | inconclusive
+```
+
+### 3.3 Iteration
+
+If inconclusive:
+- Refine hypothesis with new evidence
+- Move to next hypothesis
+- Expand search scope
+
+## Phase 4: Root Cause Confirmation
+
+Before declaring root cause:
+
+```yaml
+root_cause:
+  description: "<what's actually wrong>"
+  location: "file.ts:42"
+  evidence:
+    - "<specific finding 1>"
+    - "<specific finding 2>"
+  why_other_hypotheses_wrong:
+    H2: "<why H2 was not the cause>"
+  reproduction_confirmed: true
+```
+
+## Phase 5: Fix Recommendation
+
+```yaml
+fix:
+  approach: "<how to fix>"
+  files_affected: ["<paths>"]
+  risk_level: low | medium | high
+  testing_approach: "<how to verify fix>"
+  regression_concerns: ["<what could break>"]
+```
+
+## Phase 6: Documentation
+
+For knowledge compounding:
+
+### Investigation Summary (for prompt file)
+```markdown
+## Debug Investigation
+
+**Symptom**: <brief description>
+**Root Cause**: <what was wrong>
+**Investigation Path**: H1 (refuted) → H2 (confirmed)
+**Key Finding**: <location and evidence>
+```
+
+## Common Debug Patterns
+
+| Symptom Pattern | Likely Cause | First Check |
+|-----------------|--------------|-------------|
+| "Works locally, fails in CI" | Environment diff | Env vars, paths, deps |
+| "Intermittent failures" | Race condition | Async timing, shared state |
+| "Started after deploy" | Recent changes | Git diff from last working |
+| "Only affects some users" | Data-dependent | User data differences |
+| "Works sometimes on refresh" | Caching | Cache invalidation logic |
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Why It's Bad | Instead |
+|--------------|--------------|---------|
+| Shotgun debugging | Wastes time, creates noise | Form hypothesis first |
+| Assuming error message is cause | Often symptom, not root | Trace back to origin |
+| Skipping reproduction | Can't verify fix | Always reproduce first |
+| Fixing without understanding | Creates new bugs | Understand before changing |

package/.allhands/flows/wip/MEMORY_RECALL.md

@@ -0,0 +1,62 @@
+<goal>
+Query the simple memory file for relevant learnings from past sessions. Per **Knowledge Compounding**, memories enable reuse of solutions without re-discovery.
+</goal>
+
+<inputs>
+- Query keywords or domain
+</inputs>
+
+<outputs>
+- Relevant memories with their domains and sources
+</outputs>
+
+<constraints>
+- MUST use memories from `docs/memories.md` only
+- MUST filter by domain relevance when provided
+- NEVER fabricate memories - only return what exists in the file
+</constraints>
+
+## Memory File Format
+
+The memory file uses a simple table format:
+
+```
+| Name | Domain | Source | Description |
+```
+
+- **Name**: Short identifier for the memory
+- **Domain**: `planning`, `validation`, `implementation`, `harness-tooling`, `ideation`
+- **Source**: `user-steering` (engineer directed) or `agent-inferred` (discovered during work)
+- **Description**: 1-3 sentences of self-contained learning
+
+## Recall Process
+
+1. Read `docs/memories.md`
+2. If domain filter provided, narrow to matching rows
+3. Scan descriptions for keyword relevance
+4. Return matching memories with context
+
+## Usage Contexts
+
+| Caller Flow | Query Focus |
+|-------------|-------------|
+| `SPEC_PLANNING.md` | Planning patterns, past decisions |
+| `PROMPT_TASK_EXECUTION.md` | Implementation approaches, solutions |
+| `IDEATION_SCOPING.md` | Similar initiatives, prior engineer preferences |
+| `COMPOUNDING.md` | Verify memory doesn't already exist before adding |
+
+## Relevance Scoring
+
+Prioritize memories by:
+1. **Domain match** - Same domain as current work
+2. **Keyword overlap** - Description contains query terms
+3. **Source authority** - `user-steering` > `agent-inferred` for preference-based queries
+
+## Integration with Solutions
+
+For more detailed technical solutions, also run:
+```bash
+ah solutions search "<keywords>"
+```
+
+Memories are lightweight learnings; solutions are detailed problem-solution documentation.

package/.allhands/harness/ah

@@ -0,0 +1,131 @@
+#!/bin/bash
+# all-hands: Agentic harness CLI for model-first software development
+#
+# This script provides the `ah` CLI entry point:
+# - Auto-installs dependencies if missing
+# - Loads environment from .env.ai
+# - Routes hook commands through CLI daemon if TUI is running (fast path)
+# - Falls back to TypeScript CLI via tsx (slow path)
+
+set -e
+
+# SCRIPT_DIR = .allhands/harness/
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# ALLHANDS_DIR = .allhands/
+ALLHANDS_DIR="$(dirname "$SCRIPT_DIR")"
+# PROJECT_ROOT = parent of .allhands/
+PROJECT_ROOT="$(dirname "$ALLHANDS_DIR")"
+
+# Export project root so TypeScript code can resolve paths correctly
+# even when the caller's cwd is different from the project directory.
+# Preserves CLAUDE_PROJECT_DIR if already set by Claude Code.
+export CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PROJECT_ROOT}"
+
+# Load .env.ai from project root if exists
+if [ -f "$PROJECT_ROOT/.env.ai" ]; then
+    set -a
+    . "$PROJECT_ROOT/.env.ai"
+    set +a
+fi
+
+# Also check git root for .env.ai (may be different in worktrees)
+GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "$PROJECT_ROOT")
+if [ -f "$GIT_ROOT/.env.ai" ] && [ "$GIT_ROOT" != "$PROJECT_ROOT" ]; then
+    set -a
+    . "$GIT_ROOT/.env.ai"
+    set +a
+fi
+
+# Auto-install if node_modules missing or package.json changed
+if [ ! -d "$SCRIPT_DIR/node_modules" ] || ! cmp -s "$SCRIPT_DIR/package.json" "$SCRIPT_DIR/node_modules/.package.json.cache" 2>/dev/null; then
+    echo "Installing/updating allhands dependencies..." >&2
+    if ! npm install --prefix "$SCRIPT_DIR" --legacy-peer-deps 2>/dev/null; then
+        echo "ERROR: npm install failed for allhands CLI" >&2
+        exit 1
+    fi
+    cp "$SCRIPT_DIR/package.json" "$SCRIPT_DIR/node_modules/.package.json.cache" 2>/dev/null || true
+fi
+
+# CLI daemon socket path
+DAEMON_SOCKET="$SCRIPT_DIR/.cache/cli-daemon.sock"
+SETTINGS_FILE="$ALLHANDS_DIR/settings.json"
+
+# Check if daemon is enabled in settings (default: true)
+DAEMON_ENABLED=true
+if [ -f "$SETTINGS_FILE" ]; then
+    # Check daemon.enabled in settings.json using jq if available
+    if command -v jq >/dev/null 2>&1; then
+        # Use explicit check since jq's // operator treats false as falsy
+        if [ "$(jq -r 'if .daemon.enabled == false then "false" else "true" end' "$SETTINGS_FILE" 2>/dev/null)" = "false" ]; then
+            DAEMON_ENABLED=false
+        fi
+    else
+        # Fallback: look for "daemon".*"enabled": false pattern
+        if grep -zoP '"daemon"\s*:\s*\{[^}]*"enabled"\s*:\s*false' "$SETTINGS_FILE" >/dev/null 2>&1; then
+            DAEMON_ENABLED=false
+        fi
+    fi
+fi
+
+# Fast path: Route hook commands through daemon if enabled and socket exists
+# Format: ah hooks <category> <name> (e.g., ah hooks context tldr-inject)
+#
+# Use DISABLE_DAEMON=true to force slow path for hooks that need agent env vars
+# (e.g., lifecycle hooks need PROMPT_SCOPED, AGENT_ID which daemon doesn't have)
+if [ "$1" = "hooks" ] && [ "$DAEMON_ENABLED" = "true" ] && [ -S "$DAEMON_SOCKET" ] && [ "$DISABLE_DAEMON" != "true" ]; then
+    CATEGORY="$2"
+    NAME="$3"
+
+    if [ -n "$CATEGORY" ] && [ -n "$NAME" ]; then
+        # Mark this as a daemon-routed execution
+        export AH_VIA_DAEMON=1
+
+        # Read stdin (hook input JSON)
+        INPUT=$(cat)
+
+        # Build daemon command (use quoted default to avoid bash expansion issue with braces)
+        CMD=$(printf '{"cmd":"hook","category":"%s","name":"%s","input":%s}\n' "$CATEGORY" "$NAME" "${INPUT:-"{}"}")
+
+        # Send to daemon via nc (netcat)
+        # Use || true to prevent set -e from exiting on nc failure (stale socket)
+        NC_OK=0
+        RESPONSE=$(printf '%s' "$CMD" | nc -U "$DAEMON_SOCKET" 2>/dev/null) || NC_OK=$?
+
+        if [ $NC_OK -eq 0 ] && [ -n "$RESPONSE" ]; then
+            # Parse response using jq for proper JSON handling
+            if command -v jq >/dev/null 2>&1; then
+                SUCCESS=$(echo "$RESPONSE" | jq -r '.success // false' 2>/dev/null)
+                OUTPUT=$(echo "$RESPONSE" | jq -r '.output // empty' 2>/dev/null)
+
+                if [ "$SUCCESS" = "true" ]; then
+                    if [ -n "$OUTPUT" ]; then
+                        echo "$OUTPUT"
+                    fi
+                    exit 0
+                fi
+            else
+                # Fallback: basic parsing for simple outputs (may fail on complex JSON)
+                OUTPUT=$(echo "$RESPONSE" | sed -n 's/.*"output":"\([^"]*\)".*/\1/p')
+                if [ -n "$OUTPUT" ]; then
+                    echo "$OUTPUT" | sed 's/\\n/\n/g; s/\\"/"/g'
+                    exit 0
+                fi
+                if echo "$RESPONSE" | grep -q '"success":true'; then
+                    exit 0
+                fi
+            fi
+        fi
+        # Fall through to slow path if daemon failed
+    fi
+fi
+
+# Slow path: Use tsx for direct TypeScript execution
+# If daemon path was entered but failed, $INPUT holds the consumed stdin - replay it
+if [ -n "$INPUT" ]; then
+    # Daemon path was entered but failed - replay consumed stdin
+    # Use printf to avoid echo interpreting escape sequences in JSON
+    printf '%s' "$INPUT" | "$SCRIPT_DIR/node_modules/.bin/tsx" "$SCRIPT_DIR/src/cli.ts" "$@"
+else
+    # Normal slow path - stdin is still available
+    exec "$SCRIPT_DIR/node_modules/.bin/tsx" "$SCRIPT_DIR/src/cli.ts" "$@"
+fi