configs-all 1.0.0

package/docs/plans/2026-02-28-autonomous-command-suite.md

@@ -0,0 +1,682 @@
+# Autonomous Command Suite Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Create five new slash commands (`/context`, `/plans`, `/prep`, `/go`, `/partyon`) and update global CLAUDE.md to support maximum autonomous work with persistent documentation artifacts.
+
+**Architecture:** Five `.md` command files in `claude/commands/` plus two new sections in `claude/CLAUDE.md`. Commands compose into a pipeline: `/research` → `/context` → `/plans` → execution. `/prep` orchestrates the first three, `/go` handles execution, `/partyon` chains both.
+
+**Tech Stack:** Markdown command files, zsh syntax validation, Claude Code slash command conventions.
+
+**Design doc:** `docs/plans/2026-02-28-autonomous-command-suite-design.md`
+
+---
+
+### Task 1: Create `/context` command
+
+**Files:**
+- Create: `claude/commands/context.md`
+
+**Step 1: Write the command file**
+
+```markdown
+## Repo & Machine Context Snapshot
+
+Build a comprehensive, persistent context document for the current repository. This is a knowledge snapshot that future Claude sessions read first to avoid redundant exploration and reduce token costs.
+
+### Input
+$ARGUMENTS - optional focus area (e.g., "frontend", "deployment pipeline"). If omitted, builds full repo context.
+
+### Instructions
+
+1. **Read existing documentation first:**
+   - Read the project CLAUDE.md if it exists
+   - Read ALL files in `docs/research/` if the directory exists
+   - Read ALL files in `docs/context/` if the directory exists — if a context doc already exists for this repo, you will UPDATE it rather than creating a duplicate
+   - Read MEMORY.md if accessible
+
+2. **Gather comprehensive context** using parallel Explore subagents for independent areas:
+
+   **Project identity:**
+   - Tech stack (detect from package.json, requirements.txt, Makefile, Cargo.toml, go.mod, etc.)
+   - Project structure — key directories and their roles (not just a file listing)
+   - Entry points (main files, index files, CLI entry points)
+
+   **Architecture:**
+   - How the codebase is organized (monorepo? modular? layered?)
+   - Key abstractions and patterns used
+   - Data flow for the primary use case
+
+   **Development workflow:**
+   - How to build, test, lint, format (exact commands)
+   - CI/CD pipeline if present
+   - Deploy process if present
+   - Environment variables and configuration
+
+   **Testing infrastructure:**
+   - Test framework and how to run tests
+   - Test coverage and quality assessment
+   - Key test files and what they cover
+
+   **Dependencies:**
+   - Critical internal dependencies (what depends on what)
+   - External dependencies and their roles
+   - Version constraints that matter
+
+   **Environment:**
+   - Current machine/hostname and platform
+   - Available tools (node, python, docker, kubectl, etc.)
+   - Machine-specific quirks if known from MEMORY.md
+
+   **Recent trajectory:**
+   - Last 20-30 git commits to understand current direction
+   - Any in-progress branches or uncommitted work
+   - Recent patterns in what's being changed
+
+   **Gotchas:**
+   - Non-obvious behavior, implicit assumptions
+   - Tech debt or fragile areas
+   - Things that have broken before (from git history or docs)
+
+3. **Verify findings against actual code.** Do not trust documentation blindly — read key files to confirm claims. If an existing context doc says "tests use Jest" but you find Vitest in package.json, update accordingly.
+
+4. **Write or update** `docs/context/YYYY-MM-DD-<repo-name>.md`:
+
+   ```markdown
+   # Context: <Repo Name>
+   _Last updated: YYYY-MM-DD_
+   _Machine: <hostname>_
+   _Platform: <macOS/Linux/WSL>_
+
+   ## Overview
+   What this project does in 2-3 sentences.
+
+   ## Tech Stack
+   Languages, frameworks, key libraries with versions.
+
+   ## Project Structure
+   Key directories and their roles. Not a full file listing — focus on what matters.
+
+   ## Architecture
+   How the pieces fit together. Key patterns and conventions.
+
+   ## Development Workflow
+   Exact commands to build, test, lint, format, deploy.
+
+   ## Testing
+   Framework, how to run, coverage, key test files.
+
+   ## Dependencies
+   Critical internal and external dependencies.
+
+   ## Environment
+   Machine-specific context, available tools, quirks.
+
+   ## Recent Trajectory
+   What's been changing recently, current direction.
+
+   ## Gotchas
+   Non-obvious behavior, fragile areas, things that break.
+   ```
+
+   Omit sections that don't apply. Add sections if the repo warrants it.
+
+5. **If updating an existing context doc:** Preserve the original date in the filename but update the `_Last updated_` field. Only change sections where reality has diverged from what's documented.
+
+6. Report the file path and a brief summary of what was captured (or what changed if updating).
+```
+
+**Step 2: Validate syntax**
+
+Run: `cat claude/commands/context.md | head -1`
+Expected: `## Repo & Machine Context Snapshot`
+
+**Step 3: Commit**
+
+```bash
+git add claude/commands/context.md
+git commit -m "feat(claude): add /context command for repo knowledge snapshots"
+```
+
+---
+
+### Task 2: Create `/plans` command
+
+**Files:**
+- Create: `claude/commands/plans.md`
+
+**Step 1: Write the command file**
+
+```markdown
+## Implementation Plan Generator
+
+Generate a detailed, step-by-step implementation plan based on existing research, context, and codebase understanding. All architectural and implementation decisions are made autonomously with documented rationale.
+
+### Input
+$ARGUMENTS - task description (e.g., "add webhook support to billing", "refactor sync for 5th machine")
+
+### Instructions
+
+1. **Read existing documentation first:**
+   - Read the project CLAUDE.md if it exists
+   - Read ALL files in `docs/context/` — this is your primary knowledge source
+   - Read ALL files in `docs/research/` — supplementary understanding
+   - Read ALL files in `docs/plans/` — check for existing or related plans
+
+2. **Targeted code exploration** for the specific area the task touches:
+   - Read function bodies, not just signatures
+   - Follow imports to understand real dependencies
+   - Check existing tests for the area being changed
+   - Look at recent git history on key files for "why" context
+   - Use parallel Explore subagents for independent areas
+
+3. **Make all decisions autonomously.** Choose libraries, patterns, file structure, naming, error handling — and document WHY for each non-obvious choice. Use current best practices and standards. Do not ask — decide and document.
+
+4. **Write the plan** to `docs/plans/YYYY-MM-DD-<task-slug>.md`:
+
+   ```markdown
+   # Plan: <Task>
+   _Date: YYYY-MM-DD_
+   _Context: docs/context/<file>.md_
+   _Research: docs/research/<file>.md (if applicable)_
+
+   ## Goal
+   What this plan accomplishes in 1-2 sentences.
+
+   ## Decisions & Rationale
+   Every non-obvious choice made, with reasoning. (Libraries, patterns, file structure, naming, error handling, approach.)
+
+   ## Steps
+
+   ### Step 1: [Title]
+   - **File:** `exact/path/to/file`
+   - **What:** Specific change description with enough detail for an agent with zero context
+   - **Why:** Reasoning if non-obvious
+   - **Code:** Complete code to write (not "add validation" — show the actual code)
+   - **Verify:** Exact command to confirm this step worked and expected output
+
+   ### Step 2: ...
+
+   ## Verification Plan
+   - [ ] Tests to run (unit, e2e, integration — exact commands)
+   - [ ] Lint/build commands (exact commands)
+   - [ ] Manual checks (browser, API, CLI — exact steps)
+   - [ ] Edge cases to validate
+
+   ## Risks
+   Known risks and mitigation for each.
+   ```
+
+5. **Plan granularity:** Each step should be 2-5 minutes of work. One action per step. If a step has substeps, break it into multiple steps.
+
+6. **Do NOT execute anything.** This command produces plans only.
+
+7. Report the file path and a brief summary of the plan (goal, number of steps, key decisions made).
+```
+
+**Step 2: Validate syntax**
+
+Run: `cat claude/commands/plans.md | head -1`
+Expected: `## Implementation Plan Generator`
+
+**Step 3: Commit**
+
+```bash
+git add claude/commands/plans.md
+git commit -m "feat(claude): add /plans command for autonomous implementation planning"
+```
+
+---
+
+### Task 3: Create `/prep` command
+
+**Files:**
+- Create: `claude/commands/prep.md`
+
+**Step 1: Write the command file**
+
+```markdown
+## Full Preparation Pipeline
+
+Orchestrate deep research, context validation, and implementation planning in a single session. This replaces built-in plan mode with unrestricted tool access and persistent documentation artifacts.
+
+The goal is to set Claude up for maximum autonomous execution — thorough understanding, verified context, and a concrete plan with all decisions made and documented.
+
+### Input
+$ARGUMENTS - task description (e.g., "add webhook support to billing", "refactor the sync system")
+
+### Instructions
+
+Execute these three phases in order, carrying all context forward between phases.
+
+#### Phase 1: Research
+
+1. **Read ALL existing documentation first:**
+   - Project CLAUDE.md
+   - ALL files in `docs/research/`
+   - ALL files in `docs/context/`
+   - ALL files in `docs/plans/` (for awareness of past/in-progress work)
+   - MEMORY.md if accessible
+
+2. **Deep codebase exploration** scoped to the task, using parallel Explore subagents:
+   - Trace data flow end-to-end for the area being changed
+   - Read function bodies, not just signatures
+   - Follow imports to understand real dependencies
+   - Check tests to understand intended behavior and edge cases
+   - Look at recent git history on key files for "why" context
+
+3. **Verify all findings against actual code.** Never trust documentation blindly. If a research doc says X but the code shows Y, the code is truth.
+
+4. **Write or update** `docs/research/YYYY-MM-DD-<topic>.md` with findings. If an existing research doc covers this area, update it rather than creating a duplicate. Use the same format as `/research`:
+
+   ```markdown
+   # Research: <Topic>
+   _Date: YYYY-MM-DD_
+
+   ## Overview
+   ## Architecture
+   ## Data Flow
+   ## Patterns & Conventions
+   ## Dependencies
+   ## Gotchas
+   ## Open Questions
+   ```
+
+#### Phase 2: Context
+
+5. **Validate and update the repo context snapshot.** If `docs/context/` has an existing context doc:
+   - Read it fully
+   - Verify key claims against current repo state
+   - Update any stale sections
+   - Add task-specific context from Phase 1 that future agents will need
+
+   If no context doc exists, create one following the `/context` format:
+
+   ```markdown
+   # Context: <Repo Name>
+   _Last updated: YYYY-MM-DD_
+   _Machine: <hostname>_
+   _Platform: <macOS/Linux/WSL>_
+
+   ## Overview
+   ## Tech Stack
+   ## Project Structure
+   ## Architecture
+   ## Development Workflow
+   ## Testing
+   ## Dependencies
+   ## Environment
+   ## Recent Trajectory
+   ## Gotchas
+   ```
+
+#### Phase 3: Plan
+
+6. **Generate the implementation plan** with the full benefit of freshly verified research and context. Make all architectural and implementation decisions autonomously. Document rationale for every non-obvious choice.
+
+7. **Write** `docs/plans/YYYY-MM-DD-<task-slug>.md`:
+
+   ```markdown
+   # Plan: <Task>
+   _Date: YYYY-MM-DD_
+   _Context: docs/context/<file>.md_
+   _Research: docs/research/<file>.md_
+
+   ## Goal
+   What this plan accomplishes in 1-2 sentences.
+
+   ## Decisions & Rationale
+   Every non-obvious choice, with reasoning.
+
+   ## Steps
+   ### Step 1: [Title]
+   - **File:** `exact/path/to/file`
+   - **What:** Specific change description
+   - **Why:** Reasoning if non-obvious
+   - **Code:** Complete code to write
+   - **Verify:** Exact command and expected output
+
+   ## Verification Plan
+   - [ ] Tests, lint, build, manual checks — exact commands
+
+   ## Risks
+   Known risks and mitigation.
+   ```
+
+   Each step: 2-5 minutes, one action, concrete enough for a zero-context subagent.
+
+#### Report
+
+8. **Output all three file paths** and a summary:
+   - Research: what was learned or updated
+   - Context: what was captured or changed
+   - Plan: goal, number of steps, key decisions
+
+   The plan is now ready for `/go` to execute.
+```
+
+**Step 2: Validate syntax**
+
+Run: `cat claude/commands/prep.md | head -1`
+Expected: `## Full Preparation Pipeline`
+
+**Step 3: Commit**
+
+```bash
+git add claude/commands/prep.md
+git commit -m "feat(claude): add /prep command — orchestrates research, context, and planning"
+```
+
+---
+
+### Task 4: Create `/go` command
+
+**Files:**
+- Create: `claude/commands/go.md`
+
+**Step 1: Write the command file**
+
+```markdown
+## Execute Plan to Completion
+
+Read the latest implementation plan (or a specified one) and execute it autonomously to 100% completion. Every step is verified. Every claim is backed by evidence. Does not stop until the task is fully done and proven.
+
+### Input
+$ARGUMENTS - optional path to a specific plan file. If omitted, finds the most recent file in `docs/plans/`.
+
+### Instructions
+
+1. **Load the plan:**
+   - If `$ARGUMENTS` specifies a file, read it
+   - Otherwise, find the most recent `.md` file in `docs/plans/` and read it
+   - If no plans exist, stop and tell the user to run `/prep` or `/plans` first
+
+2. **Load supporting context:**
+   - Read the `_Context:_` and `_Research:_` files referenced in the plan header
+   - Read the project CLAUDE.md if it exists
+   - This gives the executing agents full situational awareness
+
+3. **Review the plan critically** before starting:
+   - Are there any steps that seem wrong or outdated given current code?
+   - Are there missing dependencies between steps?
+   - If issues are found, fix the plan first, then execute the corrected version
+
+4. **Execute each step using subagent-driven development:**
+
+   For each step in the plan:
+
+   a. **Dispatch implementer subagent** (Agent tool, `subagent_type: "general-purpose"`):
+      - Provide the step details (file, what, why, code, verify)
+      - Provide relevant context from the loaded docs
+      - Implementer implements the change, runs the step's verify command, and commits
+
+   b. **Dispatch spec compliance reviewer** (Agent tool, `subagent_type: "general-purpose"`):
+      - Does the implementation match exactly what the plan specified?
+      - Are there deviations, missing pieces, or incorrect implementations?
+      - If issues: implementer fixes them before proceeding
+
+   c. **Dispatch code quality reviewer** (Agent tool, `subagent_type: "general-purpose"`):
+      - Does the code follow project conventions and patterns?
+      - Architecture, naming, error handling all sound?
+      - If issues: implementer fixes them before proceeding
+
+   d. **Verify the step** — run the step's verify command independently (don't trust the subagent's claim)
+
+   e. **Move to next step** only after current step is fully verified
+
+5. **Full verification after all steps complete:**
+
+   Run EVERY applicable verification from the plan's Verification Plan section:
+
+   - **Tests:** Run the full test suite (unit, integration, e2e — whatever exists). All must pass.
+   - **Lint/Format:** Run linter and formatter. Zero errors.
+   - **Build:** Run the build command. Must succeed.
+   - **Browser testing:** If frontend changes, use playwright or chrome MCP tools to verify rendering and behavior.
+   - **API testing:** If backend changes, test endpoints with curl/httpx against a running server.
+   - **Infrastructure:** If K8s/Terraform changes, run dry-run/plan commands.
+   - **Edge cases:** Test any edge cases listed in the Verification Plan.
+   - **Manual checks:** Execute any manual verification steps listed.
+
+   If ANY verification fails: diagnose, fix, re-verify. Do not skip failures.
+
+6. **Update artifacts after completion:**
+   - Update `docs/context/` if the implementation changed the architecture or introduced new patterns
+   - Mark the plan file as completed by adding to the top:
+     ```markdown
+     > **Status: COMPLETED** — _YYYY-MM-DD_
+     > **Summary:** [1-2 sentence summary of what was done]
+     ```
+   - Commit all remaining changes with conventional commit messages
+
+7. **Final step:** Invoke `superpowers:verification-before-completion` to confirm all claims. Then invoke `superpowers:finishing-a-development-branch` to handle branch completion (merge, PR, or cleanup).
+
+8. **Report:** Summary of what was implemented, all verification results, and any issues encountered and resolved.
+
+### Critical Rules
+
+- **Never claim done without fresh verification output as evidence.**
+- **Never skip a failing test.** Diagnose and fix it.
+- **Never move to the next step with open issues.**
+- **If blocked on a step,** try alternative approaches before asking for help.
+- **One commit per logical change,** conventional commit format.
+```
+
+**Step 2: Validate syntax**
+
+Run: `cat claude/commands/go.md | head -1`
+Expected: `## Execute Plan to Completion`
+
+**Step 3: Commit**
+
+```bash
+git add claude/commands/go.md
+git commit -m "feat(claude): add /go command — executes plans to 100% verified completion"
+```
+
+---
+
+### Task 5: Create `/partyon` command
+
+**Files:**
+- Create: `claude/commands/partyon.md`
+
+**Step 1: Write the command file**
+
+```markdown
+## Full Autopilot — Prep and Execute
+
+The complete autonomous pipeline. Researches the codebase, builds context, creates an implementation plan, gets one approval, then executes to 100% verified completion.
+
+Give it a task and walk away. Come back to done.
+
+### Input
+$ARGUMENTS - task description (e.g., "add dark mode support", "refactor authentication to use JWT")
+
+### Instructions
+
+#### Phase 1: Preparation
+
+1. **Run the full `/prep` pipeline:**
+
+   a. **Research** — deep codebase exploration scoped to the task:
+      - Read ALL existing `docs/research/`, `docs/context/`, `docs/plans/`, and project CLAUDE.md
+      - Verify findings against actual code (never trust docs blindly)
+      - Write/update `docs/research/YYYY-MM-DD-<topic>.md`
+
+   b. **Context** — validate and update the repo knowledge snapshot:
+      - Read existing context docs, verify against current state
+      - Update stale sections, add task-specific context
+      - Write/update `docs/context/YYYY-MM-DD-<repo-name>.md`
+
+   c. **Plan** — generate implementation plan with all decisions documented:
+      - Full benefit of freshly verified research + context
+      - All decisions autonomous with documented rationale
+      - Write `docs/plans/YYYY-MM-DD-<task-slug>.md`
+      - Each step: 2-5 minutes, exact file paths, complete code, verify commands
+
+#### Phase 2: Checkpoint
+
+2. **Present the plan for approval.** This is the ONE moment of human input in the entire flow.
+
+   Output:
+   - The three artifact file paths (research, context, plan)
+   - A brief summary: goal, key decisions, number of steps, identified risks
+   - Ask: "Plan ready. Say 'go' to execute, or edit the plan file and tell me what changed."
+
+   **Skip checkpoint:** If `$ARGUMENTS` contains "no approval", "don't wait", "just do it", or "skip review" — skip this checkpoint and proceed directly to execution.
+
+3. **Wait for approval.** On any affirmative response ("go", "looks good", "yes", "ship it", etc.), proceed to Phase 3.
+
+#### Phase 3: Execution
+
+4. **Execute the plan using the `/go` process:**
+
+   For each step:
+   a. Dispatch implementer subagent with step details + full context
+   b. Dispatch spec compliance reviewer — does implementation match plan?
+   c. Dispatch code quality reviewer — patterns, architecture, conventions
+   d. Fix any issues before moving to next step
+   e. Verify independently — run the step's verify command
+
+5. **Full verification after all steps:**
+   - Complete test suite (all must pass)
+   - Linter/formatter (zero errors)
+   - Build (must succeed)
+   - Browser testing if frontend (playwright/chrome MCP)
+   - API testing if backend
+   - Infrastructure dry-run if DevOps
+   - All edge cases and manual checks from the Verification Plan
+
+   If ANY verification fails: diagnose, fix, re-verify. Never skip.
+
+6. **Update artifacts:**
+   - Update `docs/context/` if architecture changed
+   - Mark plan as COMPLETED
+   - Commit all changes with conventional commit messages
+
+7. **Finish:** Invoke `superpowers:verification-before-completion`, then `superpowers:finishing-a-development-branch`.
+
+8. **Report:** Full summary of what was researched, decided, planned, implemented, and verified. Include all verification evidence.
+```
+
+**Step 2: Validate syntax**
+
+Run: `cat claude/commands/partyon.md | head -1`
+Expected: `## Full Autopilot — Prep and Execute`
+
+**Step 3: Commit**
+
+```bash
+git add claude/commands/partyon.md
+git commit -m "feat(claude): add /partyon command — full autopilot from task to verified completion"
+```
+
+---
+
+### Task 6: Update global CLAUDE.md with documentation leverage and autonomous execution sections
+
+**Files:**
+- Modify: `claude/CLAUDE.md` (the global `~/CLAUDE.md`)
+
+**Step 1: Add "Leveraging Existing Documentation" section after "Core Principles" (after line 14)**
+
+Insert after the Core Principles section:
+
+```markdown
+## Leveraging Existing Documentation
+
+Before exploring any codebase, check for existing documentation artifacts:
+1. **`docs/context/`** — read the most recent context snapshot. This is your primary knowledge source.
+2. **`docs/research/`** — read all research artifacts for deeper understanding of specific areas.
+3. **`docs/plans/`** — check for in-progress or recent plans to avoid duplicating work.
+4. **Read the project CLAUDE.md** — conventions, commands, architecture specific to this repo.
+
+These are trusted starting points. Verify against actual code for the specific area you're changing, but don't re-explore what's already documented. When you produce new understanding through your work, update the relevant doc so future sessions benefit.
+```
+
+**Step 2: Strengthen "Core Principles" — update the "Plan first" bullet (line 10)**
+
+Change:
+```markdown
+- **Plan first, then one-shot.** Start complex tasks in plan mode. Iterate on the plan, then implement in one pass.
+```
+
+To:
+```markdown
+- **Plan first, then one-shot.** For complex tasks, use `/prep` to research, build context, and plan — then execute in one pass. Use `/partyon` for full autopilot. Avoid built-in plan mode (restricted tool access).
+```
+
+**Step 3: Add "Autonomous Execution" section after "Leveraging Existing Documentation"**
+
+```markdown
+## Autonomous Execution
+
+When given a task, the goal is maximum autonomous progress with minimum human input:
+- Make best-practice decisions using current standards and document your rationale
+- Don't ask about implementation details you can reasonably decide
+- Use `docs/context/` and `docs/research/` to stay informed without re-exploring
+- Verify your own work with actual command output, not assumptions
+- When blocked, try alternative approaches before asking for help
+- When a task is done, prove it's done with evidence — never claim success without verification output
+```
+
+**Step 4: Verify the file is valid markdown**
+
+Run: `head -20 claude/CLAUDE.md`
+Expected: File starts with `# Global Claude Code Instructions` and has the new sections in place.
+
+**Step 5: Commit**
+
+```bash
+git add claude/CLAUDE.md
+git commit -m "feat(claude): add documentation leverage and autonomous execution to global CLAUDE.md"
+```
+
+---
+
+### Task 7: Create `docs/context/` and `docs/research/` directories
+
+**Files:**
+- Create: `docs/context/.gitkeep`
+- Create: `docs/research/.gitkeep`
+
+**Step 1: Create directories with .gitkeep files**
+
+```bash
+mkdir -p docs/context docs/research
+touch docs/context/.gitkeep docs/research/.gitkeep
+```
+
+**Step 2: Commit**
+
+```bash
+git add docs/context/.gitkeep docs/research/.gitkeep
+git commit -m "chore: add docs/context and docs/research directories for persistent artifacts"
+```
+
+---
+
+### Task 8: Sync commands to system
+
+**Step 1: Verify all command files exist**
+
+Run: `ls -la claude/commands/{context,plans,prep,go,partyon}.md`
+Expected: All five files listed.
+
+**Step 2: Run push-configs to deploy**
+
+Run: `./scripts/sync/push-configs.zsh`
+Expected: Script completes without errors. Claude commands are synced to `~/.claude/commands/`.
+
+**Step 3: Verify commands are available**
+
+Run: `ls -la ~/.claude/commands/{context,plans,prep,go,partyon}.md`
+Expected: All five files present in the deployed location.
+
+**Step 4: Commit any remaining changes**
+
+If push-configs modified anything, commit it:
+```bash
+git add -A
+git commit -m "chore: sync autonomous command suite to system"
+```