claude-all-hands 1.0.1 → 1.0.2

package/.claude/commands/plan.md

@@ -1,115 +1,212 @@
 ---
-description: Begin planning workflow for current feature branch
-argument-hint: [user-prompt]
+description: Begin planning workflow for feature or amendment
+argument-hint: [user-prompt] [--quick | --create | --refine]
 ---
 
 <objective>
-Start or continue structured planning workflow. Creates plan files for feature branches, gathers specialist context, and delegates to planner agent for plan creation/iteration.
+Orchestrate the full planning workflow: gather requirements, delegate to specialists for discovery, run research, create implementation plan, and hand off to /continue.
+
+Modes:
+- `--quick`: No questions, minimal inference, simple plan
+- `--create`: New feature planning (default if no existing plan)
+- `--refine`: Amend existing plan with new requirements
 </objective>
 
-<quick_start>
-1. Check plan status via `envoy plans frontmatter`
-2. Handle branch/status appropriately (draft/active/new)
-3. Gather specialist context if creating new plan
-4. Delegate to planner with all context
-</quick_start>
-
-<success_criteria>
-- Plan file exists at `.claude/plans/<branch>/plan.md`
-- Status is "active" (approved) or "draft" (awaiting approval)
-- User has approved plan OR explicitly declined planning
-</success_criteria>
+<context>
+Plan status: !`.claude/envoy/envoy plan check`
+</context>
 
 <process>
+<step name="parse_mode">
+Parse $ARGUMENTS for mode flags and user prompt:
+- If `--quick` present: quick_mode = true
+- If `--create` present: mode = "create"
+- If `--refine` present: mode = "refine"
+- Everything else = user_prompt
+</step>
+
+<step name="quick_mode" condition="quick_mode = true">
+**Quick Mode - No questions, minimal delegation**
+
+1. Call `envoy plan check` to get status
+2. **If plan exists (in_progress or completed)**:
+   - Append user prompt: `.claude/envoy/envoy plan append-user-input "<user_prompt>"`
+   - Delegate to **planner agent**:
+     * "Run `envoy plan protocol implementation` and follow the steps. INPUTS: `{ mode: 'quick', workflow_type: 'feature', feature_branch: <current_branch>, plan_status: <status> }`"
+   - AskUserQuestion: "Quick plan created. Ready to implement?"
+   - If yes: call /continue command
+3. **If no plan exists**:
+   - Create branch from user prompt context (infer name)
+   - Append user prompt: `.claude/envoy/envoy plan append-user-input "<user_prompt>"`
+   - Delegate to **planner agent**:
+     * "Run `envoy plan protocol implementation` and follow the steps. INPUTS: `{ mode: 'quick', workflow_type: 'feature', feature_branch: <current_branch> }`"
+   - AskUserQuestion: "Quick plan created. Ready to implement?"
+   - If yes: call /continue command
+4. **Exit** - quick mode complete
+</step>
+
+<step name="check_status" condition="quick_mode = false">
+Call `envoy plan check` and determine mode:
+
+| Condition | Action |
+|-----------|--------|
+| No plan, user_input.md has content | Read user_input.md, continue to input_gate |
+| No plan, fresh start | Create branch (infer name from prompt), set mode = "create" |
+| Plan exists, prompt unrelated | AskUserQuestion: "Existing plan found. Continue with it or start fresh?" |
+| Plan exists, prompt related | Set mode = "refine" |
+
+If user chooses "start fresh": create new branch off base, set mode = "create"
+</step>
+
+<step name="input_gate">
+**Progressive disclosure approach**
+
+1. **Type question** (if not inferred from prompt):
+   AskUserQuestion: "What type of change?"
+   Options: ["UI/Frontend", "Backend/API", "Full-stack", "Observability/Monitoring", "Developer Experience", "Infrastructure/DevOps", "Other"]
+
+2. **Constraints** (always ask):
+   AskUserQuestion: "Any additional constraints? (skip to infer from context)"
+
+3. **Domain-specific questions** (progressive):
+   Build questions from Feature Knowledge Bank below. Ask 3 at a time, offer "continue with current context" option.
+
+4. **Design materials** (if UI involved):
+   AskUserQuestion: "Include UI screenshots/design material? If yes, add them to filesystem and describe in manifest."
+</step>
+
+<step name="write_user_input">
+Append all gathered context to user_input.md:
+`.claude/envoy/envoy plan append-user-input "<all_gathered_context>"`
+</step>
+
+<step name="specialist_delegation">
+1. Extract atomic requirements from user prompt + answers
+2. Cluster requirements by primary domain
+3. For each cluster, determine specialist:
+   - If confidence lacking: AskUserQuestion: "Should I create a new specialist for [domain]? (/create-specialist)"
+   - If no specialist and user declines: use "surveyor" agent
+4. Delegate to specialists:
+   * "Run `envoy plan protocol discovery` and follow the steps. INPUTS: `{ agent_name: '<specialist_name>[_N]', segment_context: '<requirements_for_segment>' }`"
+   * Add `_N` suffix if multiple segments for same specialist
+   * OUTPUTS: `{ success: true }`
+</step>
+
+<step name="get_findings">
+Call `.claude/envoy/envoy plan get-findings` to get list of approaches
+</step>
+
+<step name="research_delegation">
+For each distinct research objective identified from approaches:
+* Delegate to **researcher agent**:
+  * "Run `envoy plan protocol discovery` and follow the steps. INPUTS: `{ agent_name: 'researcher[_N]', segment_context: '<research_objectives_with_approach_references>' }`"
+  * OUTPUTS: `{ success: true }`
+</step>
+
+<step name="findings_gate">
+1. Present all clarifying questions from approach documents to user
+2. AskUserQuestion: "Want to redirect specialists with specific requirements? (clears all findings)"
+   - If yes: clear findings, return to specialist_delegation step
+3. Call `.claude/envoy/envoy plan block-findings-gate`
+   - Returns: `{ thoughts, affected_approaches: [{ specialist_name, approach_number }] }`
+4. If affected_approaches exist:
+   - Re-delegate to affected specialists with thoughts context
+   - Rerun findings gate
+</step>
+
+<step name="planner_delegation">
+Delegate to **planner agent**:
+* "Run the planning-workflow. INPUTS: `{ mode: '<create|refine>', workflow_type: 'feature', feature_branch: '<current_branch>' }`"
+* OUTPUTS: `{ success: true }`
+</step>
+
+<step name="handoff">
+Call /continue command
+</step>
+</process>
 
-## Step 1: Status Check
-
-Run: `.claude/envoy/envoy plans frontmatter`
-
-
-- **{exists: false}**: Use AskUserQuestion:
-  - Question: "You're on a protected branch. How to proceed?"
-  - Options: ["Create a new branch", "Abandon planning mode"]
-  - On "Create a new branch" → Create new branch, re-run /plan
-  - On "Abandon planning mode" → Continue to address user prompt without planning
-
-- **draft**: Use AskUserQuestion:
-  - Question: "Draft plan exists. How to proceed?"
-  - Options: ["Continue drafting", "Start fresh (new branch)", "Decline planning"]
-  - On "Continue drafting" → Delegate to planner: "continue draft, incorporate prompt"
-  - On "Start fresh" → Create new branch, re-run /plan
-  - On "Decline" → Run `envoy plans set-status deactivated`, proceed without planning
-
-- **active**: Check if user's prompt aligns with plan specs.
-  - If aligned → Read plan, continue implementation (skip planner)
-  - If misaligned → Use AskUserQuestion:
-    - Question: "Active plan exists but prompt seems unrelated. Options?"
-    - Options: ["Add to plan", "New branch for this work", "Proceed without planning"]
-    - Handle each appropriately
-
-## Step 1.5: Intake Gate (New Plans Only)
-
-**Trigger**: When creating a new plan AND user prompt lacks specifics.
-
-**Skip if**: Continuing draft (context exists) or prompt already detailed.
-
-**Structured questioning** via AskUserQuestion:
-
-1. **Scope**: "What specifically needs to be built/changed?"
-   - Options based on inferred type: [Feature, Bug fix, Refactor, Research, Other]
-
-2. **Constraints**: "Any constraints or requirements?"
-   - Options: [Performance critical, Must maintain backwards compat, Specific tech stack, None/flexible]
-
-3. **Dependencies**: "Dependencies or blockers?"
-   - Options: [Depends on external API, Needs design review, Blocked by other work, None]
-
-4. **Success criteria**: "How will we know it's done?"
-   - Options: [Tests pass, User can X, Performance target, Manual verification]
-
-**Package intake answers** with original prompt for planner delegation.
-
----
-
-## Step 2: Gather Specialist Context
-
-Check agent descriptions for relevant specialists (exclude researcher/planner/explorer).
-
-- **Specialists found**: Use `/parallel-discovery` to dispatch specialists + explorer simultaneously
-  - Query specialists: "What repo context/patterns relevant to: {prompt}?"
-  - Query explorer: "What code structure/implementation relevant to: {prompt}?"
-- **None found**: Dispatch **explorer** agent to analyze relevant directories:
-  - Query: "Analyze codebase patterns relevant to: {prompt}"
-  - Explorer uses repomix-extraction to gather context
-  - Returns patterns/conventions for planner to incorporate
-
-## Step 3: Delegate to Planner
-
-Send to planner agent:
-- Directive: "create new plan" | "continue draft" | "add to plan"
-- User's original prompt
-- **Intake answers** (scope, constraints, dependencies, success criteria) if gathered
-- Current branch name
-- Specialist findings
-
-## Step 4: On Planner Return
-
-Planner returns with status:
-
-- **plan_ready**: Use AskUserQuestion:
-  - Question: "Plan ready. Approve to begin implementation?"
-  - Options: ["Approve", "Needs changes"]
-  - On "Approve" → Read `.claude/plans/<branch>/plan.md`, then run `/parallel-orchestration` to check for parallel work streams
-  - On "Needs changes" → User provides feedback via Other, re-delegate to planner with feedback
-
-- **Planning declined** → Proceed with user's original request without planning
-- **Cancelled** → No action needed
+<knowledge_bank name="feature_input_gate">
+**Generic (all types):**
+- Core mission/objective in one sentence
+- Success criteria (how do we know it's done?)
+- Explicit out-of-scope items
+- Acceptable level of jank/tech debt
+- Hard constraints (stack, APIs, security, existing patterns)
+- Primary users or systems affected
+- Key scenarios/user flows (1-3)
+- Happy path for each scenario
+- Must-do behaviors per scenario
+- Forbidden behaviors/invariants
+- Key edge cases
+- Anticipated follow-up work
+- Manual testing approach
+
+**UI/Frontend specific:**
+- UX quality bar (scrappy prototype | functional MVP | polished release)
+- Target devices/viewports
+- Accessibility requirements
+- Design references or screenshots available?
+- State management approach
+- Error/loading state handling
+
+**Backend/API specific:**
+- Input/output schemas (examples)
+- Performance targets (latency, throughput)
+- Data models/entities affected
+- Database migrations needed?
+- Authentication/authorization requirements
+- Rate limiting/quota considerations
+
+**Full-stack specific:**
+- All of the above
+- API contract between frontend and backend
+- Deployment coordination needs
+
+**Observability/Monitoring specific:**
+- What signals indicate success/failure?
+- Log levels and what to capture
+- Metrics to track
+- Alerting thresholds
+- Dashboard requirements
+
+**DX specific:**
+- Who is the developer audience?
+- Documentation requirements
+- Error message clarity
+- Local development impact
+- CI/CD pipeline changes
+
+**Infrastructure/DevOps specific:**
+- Environments affected (dev, staging, prod)
+- Rollback strategy
+- Security/compliance requirements
+- Scaling considerations
+- Cost implications
+
+**Informational context for LLM:**
+- Goal is confident delegation to specialists, not exhaustive documentation
+- Prioritize questions that would change architectural approach
+- Edge case questions can wait until findings gate
+- If user's description is detailed, fewer questions needed
+- Combine related bullets into single questions
+- Skip questions where answer is obvious from codebase
+- For --refine mode, only ask about NEW aspects
+</knowledge_bank>
 
-</process>
+<success_criteria>
+- Mode correctly determined from arguments and context
+- User input gathered via progressive disclosure
+- Specialists delegated with focused requirements
+- Findings gate reviewed with user
+- Plan created via planner delegation
+- Control passed to /continue
+</success_criteria>
 
 <constraints>
-- NEVER skip status check - always run `envoy plans frontmatter` first
-- NEVER create plan without user approval at Step 4
-- NEVER skip intake gate for vague prompts on new plans
-- Main agent delegates to planner - does not write plan directly
+- MUST use AskUserQuestion for all user interactions
+- MUST NOT proceed without user confirmation at gates
+- MUST append all user context to user_input.md via envoy
+- Quick mode MUST skip all questions
+- Specialist delegation MUST use discovery protocol
+- All delegations MUST follow INPUTS/OUTPUTS format
 </constraints>

package/.claude/commands/validate.md

@@ -0,0 +1,11 @@
+---
+description: Show detailed .claude/ validation errors
+---
+
+Run the validation script and display all errors:
+
+```bash
+python3 .claude/hooks/scripts/validate_artifacts.py
+```
+
+Parse the JSON output and list each error clearly for the user to address.

package/.claude/commands/whats-next.md

@@ -1,147 +1,119 @@
 ---
-description: Generate XML handoff document for session continuity
-argument-hint: [--save]
+description: Suggest next steps after plan completion based on implemented work
 ---
 
 <objective>
-Generate structured XML handoff document capturing session state for seamless context transfer to next session. Prevents knowledge loss and repeated work.
+Analyze completed plan and generate contextual next-step suggestions. Uses plan context (user_input.md, summary.md, plan.md) to suggest relevant follow-up work.
 </objective>
 
-<quick_start>
-1. Gather git status, branch, recent commits
-2. Extract completed/remaining work from plan
-3. Document failed approaches and critical context
-4. Output XML to chat (or save to file with --save)
-</quick_start>
-
-<success_criteria>
-- XML document captures all session work and state
-- Failed approaches documented with WHY they failed
-- Critical non-obvious context preserved
-- Next session can resume without rediscovery
-</success_criteria>
+<context>
+Plan status: !`.claude/envoy/envoy plan check`
+</context>
 
 <process>
+<step name="check_status">
+Parse plan check result:
+
+| Status | Action |
+|--------|--------|
+| in_progress | Tell user: "Plan has incomplete prompts. Run /continue or /plan --refine" and exit |
+| completed | Continue to get_context step |
+| no_plan | Generate generic suggestions (skip get_context) |
+</step>
+
+<step name="get_context">
+Call `.claude/envoy/envoy plan get-full-plan`
+
+Parse returned context:
+- user_input.md: original requirements, anticipated follow-ups, out-of-scope items
+- summary.md: what was implemented, key decisions
+- plan.md: prompts that were executed
+</step>
+
+<step name="generate_suggestions">
+Using the Suggestion Domains below and parsed context, generate **3-5 concrete suggestions**.
+
+**Priority order:**
+1. Explicitly mentioned follow-ups from user_input.md
+2. Natural extensions of what was built
+3. Quality/hardening improvements
+4. New capabilities enabled by implementation
+
+**Format each suggestion as actionable:**
+- Good: "Add unit tests for the auth service refresh token logic"
+- Bad: "Maybe add some tests"
+</step>
+
+<step name="present_suggestions">
+Output suggestions with routing guidance:
+
+"Based on the completed work, here are suggested next steps:
+
+1. [Suggestion 1]
+2. [Suggestion 2]
+3. [Suggestion 3]
+...
+
+**Ready to continue?**
+- `/plan [suggestion]` - Start planning one of these
+- `/plan [your own idea]` - Plan something else
+- `/plan --refine` - Add to current plan instead of starting fresh
+- `/debug [issue]` - If you found a bug to fix first"
+</step>
+</process>
 
-## Output Format
-
-```xml
-<handoff>
-  <work_completed>
-    <!-- Bullet list of completed tasks/changes this session -->
-  </work_completed>
-
-  <work_remaining>
-    <!-- Bullet list of outstanding tasks from plan -->
-  </work_remaining>
-
-  <attempted_approaches>
-    <!-- Any approaches tried that failed or were abandoned -->
-    <!-- Include WHY they failed to prevent repetition -->
-  </attempted_approaches>
-
-  <critical_context>
-    <!-- Non-obvious discoveries, constraints, or decisions -->
-    <!-- Things that would be lost without explicit capture -->
-  </critical_context>
-
-  <current_state>
-    <!-- Git status, branch, uncommitted changes -->
-    <!-- Any blockers or pending decisions -->
-  </current_state>
-</handoff>
-```
-
-## Execution
-
-### Step 1: Gather Session Context
-
-Analyze:
-1. Current git branch and status
-2. Recent commits (if on feature branch)
-3. Plan file contents (if exists at `.claude/plans/<branch>/plan.md`)
-4. Any uncommitted changes
-
-### Step 2: Extract Work Status
-
-From plan file (if exists):
-- `[x]` items → work_completed
-- `[ ]` items → work_remaining
-
-From session memory:
-- What was attempted this session
-- What succeeded vs failed
-- Why failures occurred
-
-### Step 3: Identify Critical Context
-
-Capture:
-- Design decisions made and rationale
-- Discovered constraints or gotchas
-- Dependencies or blockers identified
-- Any deviations from plan and why
-
-### Step 4: Document Current State
-
-```bash
-git status
-git branch --show-current
-git log --oneline -5  # if on feature branch
-```
-
-### Step 5: Generate Output
-
-If `--save` argument provided:
-- Save to `.claude/plans/<branch>/handoff.md`
-- Confirm: "Handoff saved to .claude/plans/<branch>/handoff.md"
-
-Otherwise:
-- Output XML directly to chat for copy/paste
+<knowledge_bank name="suggestion_domains">
+**Directly Mentioned:**
+- Anything in "Anticipated follow-ups" from user_input.md
+- Items explicitly marked "out of scope for this iteration"
+- Technical debt the user said was acceptable for now
+
+**Natural Extensions:**
+- Additional user flows that build on implemented features
+- Edge cases that weren't covered but now matter
+- Performance optimizations for implemented features
+- Mobile/responsive versions if only desktop was built
+- API extensions if backend was built
+- Admin/management UI if user-facing was built
+
+**Quality and Hardening:**
+- Test coverage for implemented features
+- Error handling improvements
+- Accessibility enhancements
+- Documentation (README, API docs, inline comments)
+- Logging/monitoring for new features
+- Security hardening (input validation, auth edge cases)
+
+**Developer Experience:**
+- Local development improvements
+- CI/CD enhancements
+- Developer documentation
+- Code cleanup/refactoring opportunities identified during implementation
+
+**New Capabilities:**
+- Features that are now possible because of what was built
+- Integrations with other systems
+- Analytics/reporting on new functionality
+- User feedback mechanisms
+
+**Observability and Operations:**
+- Dashboards for new features
+- Alerting for failure modes
+- Performance baselines
+- Usage tracking
+</knowledge_bank>
 
-</process>
+<success_criteria>
+- Plan status correctly determined
+- Context parsed from plan files
+- 3-5 contextual suggestions generated
+- Suggestions prioritized by relevance
+- Clear routing guidance provided
+</success_criteria>
 
 <constraints>
-- ALWAYS include WHY for failed approaches - prevents repetition
-- NEVER omit critical_context section - even if "none" is the value
-- Be specific in work_completed: include file paths, commit hashes
+- MUST check plan status first
+- MUST read plan context before generating suggestions
+- Suggestions MUST be specific to implemented work (not generic)
+- MUST provide routing guidance for each action type
 </constraints>
-
-## Usage Examples
-
-**End of session:**
-```
-/whats-next
-```
-Outputs XML to chat for next session.
-
-**Save for later:**
-```
-/whats-next --save
-```
-Persists to plan directory.
-
-## Section Guidelines
-
-### work_completed
-- Be specific: "Added intake gate to /plan command" not "made changes"
-- Include file paths modified
-- Note commits made
-
-### work_remaining
-- Pull directly from plan's unchecked items
-- Add any discovered tasks not in original plan
-
-### attempted_approaches
-- ONLY include if something failed or was abandoned
-- Always include WHY: "X failed because Y"
-- This prevents next session from repeating mistakes
-
-### critical_context
-- Non-obvious information that isn't in code comments
-- Verbal agreements or decisions
-- External constraints discovered
-- "If I forget this, I'll waste time rediscovering it"
-
-### current_state
-- Factual: branch, status, blockers
-- Any pending questions awaiting user input

package/.claude/envoy/envoy

@@ -1,9 +1,8 @@
 #!/bin/bash
-# claude-envoy: CLI for agent-scoped external tool access
+# claude-envoy: CLI for agent-scoped external tool access (TypeScript)
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
-VENV_DIR="$SCRIPT_DIR/.venv"
 
 # Load .env if exists
 if [ -f "$PROJECT_DIR/.env" ]; then
@@ -12,19 +11,17 @@ if [ -f "$PROJECT_DIR/.env" ]; then
     set +a
 fi
 
-# Auto-create venv if missing
-if [ ! -d "$VENV_DIR" ]; then
-    python3 -m venv "$VENV_DIR"
-    "$VENV_DIR/bin/pip" install -q -r "$SCRIPT_DIR/requirements.txt"
-    cp "$SCRIPT_DIR/requirements.txt" "$VENV_DIR/.requirements.txt"
+# Auto-install if node_modules missing
+if [ ! -d "$SCRIPT_DIR/node_modules" ]; then
+    npm install --prefix "$SCRIPT_DIR" --silent 2>/dev/null
+    cp "$SCRIPT_DIR/package.json" "$SCRIPT_DIR/node_modules/.package.json.cache" 2>/dev/null
 fi
 
-# Reinstall if requirements.txt changed
-if ! cmp -s "$SCRIPT_DIR/requirements.txt" "$VENV_DIR/.requirements.txt" 2>/dev/null; then
-    "$VENV_DIR/bin/pip" install -q -r "$SCRIPT_DIR/requirements.txt"
-    cp "$SCRIPT_DIR/requirements.txt" "$VENV_DIR/.requirements.txt"
+# Reinstall if package.json changed
+if ! cmp -s "$SCRIPT_DIR/package.json" "$SCRIPT_DIR/node_modules/.package.json.cache" 2>/dev/null; then
+    npm install --prefix "$SCRIPT_DIR" --silent 2>/dev/null
+    cp "$SCRIPT_DIR/package.json" "$SCRIPT_DIR/node_modules/.package.json.cache" 2>/dev/null
 fi
 
-# Suppress Python warnings (urllib3, deprecation, etc)
-export PYTHONWARNINGS="ignore"
-exec "$VENV_DIR/bin/python" "$SCRIPT_DIR/envoy.py" "$@"
+# Use tsx for direct TypeScript execution (no compile step needed)
+exec "$SCRIPT_DIR/node_modules/.bin/tsx" "$SCRIPT_DIR/src/cli.ts" "$@"