From cfe6a85e33a5f684bea62557c8214e53a58fefed Mon Sep 17 00:00:00 2001 From: Bill Murdock Date: Thu, 19 Mar 2026 18:13:17 -0400 Subject: [PATCH] refactor(bugfix): migrate commands to skills-only architecture Commands in Claude Code are now unified with skills. The eight thin stub commands that just dispatched to the controller were pure boilerplate, and speedrun was the only command with real logic. - Delete .claude/commands/ directory (9 files) - Convert speedrun command to .claude/skills/speedrun/SKILL.md - Add Dispatch section to each phase skill so it reads the controller when invoked directly (not via controller or speedrun) - Update return-path references from commands/speedrun to skills/speedrun - Trim ambient.json: remove unused greeting field, simplify systemPrompt - Update README, CLAUDE.md, and WORKFLOW_DEVELOPMENT_GUIDE examples Made-with: Cursor --- WORKFLOW_DEVELOPMENT_GUIDE.md | 9 +++----- workflows/bugfix/.ambient/ambient.json | 5 ++--- workflows/bugfix/.claude/commands/assess.md | 7 ------- workflows/bugfix/.claude/commands/diagnose.md | 7 ------- workflows/bugfix/.claude/commands/document.md | 7 ------- workflows/bugfix/.claude/commands/fix.md | 7 ------- workflows/bugfix/.claude/commands/pr.md | 7 ------- .../bugfix/.claude/commands/reproduce.md | 7 ------- workflows/bugfix/.claude/commands/review.md | 7 ------- workflows/bugfix/.claude/commands/test.md | 7 ------- .../bugfix/.claude/skills/assess/SKILL.md | 10 ++++++++- .../bugfix/.claude/skills/controller/SKILL.md | 2 +- .../bugfix/.claude/skills/diagnose/SKILL.md | 10 ++++++++- .../bugfix/.claude/skills/document/SKILL.md | 10 ++++++++- workflows/bugfix/.claude/skills/fix/SKILL.md | 10 ++++++++- workflows/bugfix/.claude/skills/pr/SKILL.md | 10 ++++++++- .../bugfix/.claude/skills/reproduce/SKILL.md | 10 ++++++++- .../bugfix/.claude/skills/review/SKILL.md | 10 ++++++++- .../speedrun.md => skills/speedrun/SKILL.md} | 15 +++++++------ workflows/bugfix/.claude/skills/test/SKILL.md | 10 ++++++++- workflows/bugfix/CLAUDE.md | 7 ++++--- workflows/bugfix/README.md | 21 +++++++------------ 22 files changed, 97 insertions(+), 98 deletions(-) delete mode 100644 workflows/bugfix/.claude/commands/assess.md delete mode 100644 workflows/bugfix/.claude/commands/diagnose.md delete mode 100644 workflows/bugfix/.claude/commands/document.md delete mode 100644 workflows/bugfix/.claude/commands/fix.md delete mode 100644 workflows/bugfix/.claude/commands/pr.md delete mode 100644 workflows/bugfix/.claude/commands/reproduce.md delete mode 100644 workflows/bugfix/.claude/commands/review.md delete mode 100644 workflows/bugfix/.claude/commands/test.md rename workflows/bugfix/.claude/{commands/speedrun.md => skills/speedrun/SKILL.md} (91%) diff --git a/WORKFLOW_DEVELOPMENT_GUIDE.md b/WORKFLOW_DEVELOPMENT_GUIDE.md index d08f876..7378d9c 100644 --- a/WORKFLOW_DEVELOPMENT_GUIDE.md +++ b/WORKFLOW_DEVELOPMENT_GUIDE.md @@ -339,11 +339,8 @@ git checkout -b feature/bugfix-improvements # Edit the workflow configuration vim workflows/bugfix/.ambient/ambient.json -# Add or modify a command -vim workflows/bugfix/.claude/commands/diagnose.md - # Add or modify a skill -vim workflows/bugfix/.claude/skills/root-cause-analysis/SKILL.md +vim workflows/bugfix/.claude/skills/diagnose/SKILL.md # Edit persistent context vim workflows/bugfix/CLAUDE.md @@ -492,8 +489,8 @@ Claude can sometimes mix these up, especially when: **1. Use explicit paths:** ```text -❌ "Create a new command for the diagnose phase" -✅ "Create a new command at workflows/bugfix/.claude/commands/diagnose.md" +❌ "Create a new skill for the diagnose phase" +✅ "Create a new skill at workflows/bugfix/.claude/skills/diagnose/SKILL.md" ``` **2. Be explicit about context:** diff --git a/workflows/bugfix/.ambient/ambient.json b/workflows/bugfix/.ambient/ambient.json index dec1076..975beef 100644 --- a/workflows/bugfix/.ambient/ambient.json +++ b/workflows/bugfix/.ambient/ambient.json @@ -1,7 +1,6 @@ { "name": "Fix a bug", "description": "Systematic workflow for analyzing, fixing, and verifying software bugs with comprehensive testing and documentation. Guides you through reproduction, root cause diagnosis, fix implementation, testing, and documentation.", - "systemPrompt": "You are Amber, the Ambient Code Platform's expert colleague for systematic bug resolution.\n\nYou are controlled by a workflow controller at:\n .claude/skills/controller/SKILL.md\n\nRead it at the start of the session. It defines how to execute phases, recommend next steps, and handle transitions.\n\nWorkspace layout:\n- Controller: .claude/skills/controller/SKILL.md\n- Phase skills: .claude/skills/{name}/SKILL.md\n- Commands: .claude/commands/*.md\n- Artifacts: artifacts/bugfix/", - "startupPrompt": "Greet the user as Amber, their bug fix assistant. Explain that you'll guide them through systematic bug resolution: assess the report, reproduce the bug, diagnose root cause, implement the fix, test it, and document everything. Ask them to describe the bug or paste a bug report or issue URL to get started.", - "greeting": "Welcome to the Bug Fix workflow! I'm Amber, and I'll guide you through systematic bug resolution.\n\nPhases:\n1. Assess — Understand the bug report and propose a plan\n2. Reproduce — Confirm the bug is reproducible\n3. Diagnose — Identify the root cause\n4. Fix — Implement the solution\n5. Test — Verify the fix and add regression tests\n6. Document — Create documentation and optionally a PR\n\nTo get started, describe the bug or paste a bug report or issue URL." + "systemPrompt": "You are Amber, an expert colleague for systematic bug resolution.\n\nAt the start of the session, read .claude/skills/controller/SKILL.md — it defines the workflow phases, how to execute them, and how to recommend next steps.", + "startupPrompt": "Greet the user as Amber, their bug fix assistant. Explain that you'll guide them through systematic bug resolution: assess the report, reproduce the bug, diagnose root cause, implement the fix, test it, and document everything. Ask them to describe the bug or paste a bug report or issue URL to get started." } diff --git a/workflows/bugfix/.claude/commands/assess.md b/workflows/bugfix/.claude/commands/assess.md deleted file mode 100644 index 8a4b409..0000000 --- a/workflows/bugfix/.claude/commands/assess.md +++ /dev/null @@ -1,7 +0,0 @@ -# /assess - -Read `.claude/skills/controller/SKILL.md` and follow it. - -Dispatch the **assess** phase. Context: - -$ARGUMENTS diff --git a/workflows/bugfix/.claude/commands/diagnose.md b/workflows/bugfix/.claude/commands/diagnose.md deleted file mode 100644 index e8c652d..0000000 --- a/workflows/bugfix/.claude/commands/diagnose.md +++ /dev/null @@ -1,7 +0,0 @@ -# /diagnose - -Read `.claude/skills/controller/SKILL.md` and follow it. - -Dispatch the **diagnose** phase. Context: - -$ARGUMENTS diff --git a/workflows/bugfix/.claude/commands/document.md b/workflows/bugfix/.claude/commands/document.md deleted file mode 100644 index 0746379..0000000 --- a/workflows/bugfix/.claude/commands/document.md +++ /dev/null @@ -1,7 +0,0 @@ -# /document - -Read `.claude/skills/controller/SKILL.md` and follow it. - -Dispatch the **document** phase. Context: - -$ARGUMENTS diff --git a/workflows/bugfix/.claude/commands/fix.md b/workflows/bugfix/.claude/commands/fix.md deleted file mode 100644 index dbf3ade..0000000 --- a/workflows/bugfix/.claude/commands/fix.md +++ /dev/null @@ -1,7 +0,0 @@ -# /fix - -Read `.claude/skills/controller/SKILL.md` and follow it. - -Dispatch the **fix** phase. Context: - -$ARGUMENTS diff --git a/workflows/bugfix/.claude/commands/pr.md b/workflows/bugfix/.claude/commands/pr.md deleted file mode 100644 index d4a309a..0000000 --- a/workflows/bugfix/.claude/commands/pr.md +++ /dev/null @@ -1,7 +0,0 @@ -# /pr - -Read `.claude/skills/controller/SKILL.md` and follow it. - -Dispatch the **pr** phase. Context: - -$ARGUMENTS diff --git a/workflows/bugfix/.claude/commands/reproduce.md b/workflows/bugfix/.claude/commands/reproduce.md deleted file mode 100644 index 55f7cda..0000000 --- a/workflows/bugfix/.claude/commands/reproduce.md +++ /dev/null @@ -1,7 +0,0 @@ -# /reproduce - -Read `.claude/skills/controller/SKILL.md` and follow it. - -Dispatch the **reproduce** phase. Context: - -$ARGUMENTS diff --git a/workflows/bugfix/.claude/commands/review.md b/workflows/bugfix/.claude/commands/review.md deleted file mode 100644 index b74b31c..0000000 --- a/workflows/bugfix/.claude/commands/review.md +++ /dev/null @@ -1,7 +0,0 @@ -# /review - -Read `.claude/skills/controller/SKILL.md` and follow it. - -Dispatch the **review** phase. Context: - -$ARGUMENTS diff --git a/workflows/bugfix/.claude/commands/test.md b/workflows/bugfix/.claude/commands/test.md deleted file mode 100644 index 198c2f3..0000000 --- a/workflows/bugfix/.claude/commands/test.md +++ /dev/null @@ -1,7 +0,0 @@ -# /test - -Read `.claude/skills/controller/SKILL.md` and follow it. - -Dispatch the **test** phase. Context: - -$ARGUMENTS diff --git a/workflows/bugfix/.claude/skills/assess/SKILL.md b/workflows/bugfix/.claude/skills/assess/SKILL.md index 91b85f9..8b161ff 100644 --- a/workflows/bugfix/.claude/skills/assess/SKILL.md +++ b/workflows/bugfix/.claude/skills/assess/SKILL.md @@ -5,6 +5,14 @@ description: Understand the bug report and propose a plan before taking action. # Assess Bug Report Skill +## Dispatch + +If you were dispatched by the controller or by speedrun, continue below. +Otherwise, read `.claude/skills/controller/SKILL.md` first — it will send +you back here with the proper workflow context. + +--- + You are reviewing a bug report to build a shared understanding with the user before any work begins. This is the first phase of the bugfix workflow. Your job is to read, think, and explain — not to start fixing anything. @@ -153,4 +161,4 @@ Report your assessment: - Key gaps or risks identified - Your proposed plan -Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/commands/speedrun.md` for next phase.") and **re-read that file** for next-step guidance. +Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/skills/speedrun/SKILL.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/.claude/skills/controller/SKILL.md b/workflows/bugfix/.claude/skills/controller/SKILL.md index 80794fa..70697f5 100644 --- a/workflows/bugfix/.claude/skills/controller/SKILL.md +++ b/workflows/bugfix/.claude/skills/controller/SKILL.md @@ -42,7 +42,7 @@ Phases can be skipped or reordered at the user's discretion. file as the dispatcher so skills know where to return, e.g., "Starting the /fix phase (dispatched by `.claude/skills/controller/SKILL.md`)." This is very important so the user knows the workflow is working, learns - about the commands, and so skills can find their way back here. + about the available phases, and so skills can find their way back here. 2. **Read** the skill file from the list above 3. **Execute** the skill's steps directly — the user should see your progress 4. When the skill is done, it will report its findings and re-read this diff --git a/workflows/bugfix/.claude/skills/diagnose/SKILL.md b/workflows/bugfix/.claude/skills/diagnose/SKILL.md index c22149e..02003d1 100755 --- a/workflows/bugfix/.claude/skills/diagnose/SKILL.md +++ b/workflows/bugfix/.claude/skills/diagnose/SKILL.md @@ -5,6 +5,14 @@ description: Perform systematic root cause analysis to identify the underlying i # Diagnose Root Cause Skill +## Dispatch + +If you were dispatched by the controller or by speedrun, continue below. +Otherwise, read `.claude/skills/controller/SKILL.md` first — it will send +you back here with the proper workflow context. + +--- + You are a systematic root cause analysis specialist. Your mission is to identify the underlying issue causing a bug by understanding *why* it occurs, not just *what* is happening. ## Your Role @@ -118,4 +126,4 @@ Report your findings: - Confidence level in the diagnosis - Where the root cause analysis was written -Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/commands/speedrun.md` for next phase.") and **re-read that file** for next-step guidance. +Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/skills/speedrun/SKILL.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/.claude/skills/document/SKILL.md b/workflows/bugfix/.claude/skills/document/SKILL.md index b29d933..09cb3e4 100644 --- a/workflows/bugfix/.claude/skills/document/SKILL.md +++ b/workflows/bugfix/.claude/skills/document/SKILL.md @@ -5,6 +5,14 @@ description: Create comprehensive documentation for a bug fix including issue up # Document Fix Skill +## Dispatch + +If you were dispatched by the controller or by speedrun, continue below. +Otherwise, read `.claude/skills/controller/SKILL.md` first — it will send +you back here with the proper workflow context. + +--- + You are a thorough documentation specialist for bug fixes. Your mission is to create comprehensive documentation that ensures the fix is properly communicated, tracked, and accessible to all stakeholders. ## Your Role @@ -165,4 +173,4 @@ Report your results: - What documents were created and where - Any gaps flagged for later -Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/commands/speedrun.md` for next phase.") and **re-read that file** for next-step guidance. +Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/skills/speedrun/SKILL.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/.claude/skills/fix/SKILL.md b/workflows/bugfix/.claude/skills/fix/SKILL.md index 3b6d091..f0113a3 100755 --- a/workflows/bugfix/.claude/skills/fix/SKILL.md +++ b/workflows/bugfix/.claude/skills/fix/SKILL.md @@ -5,6 +5,14 @@ description: Implement a bug fix based on root cause analysis, following project # Implement Bug Fix Skill +## Dispatch + +If you were dispatched by the controller or by speedrun, continue below. +Otherwise, read `.claude/skills/controller/SKILL.md` first — it will send +you back here with the proper workflow context. + +--- + You are a disciplined bug fix implementation specialist. Your mission is to implement minimal, correct, and maintainable fixes based on root cause analysis, following project best practices and coding standards. ## Your Role @@ -135,4 +143,4 @@ Report your results: - What quality checks passed - Where the implementation notes were written -Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/commands/speedrun.md` for next phase.") and **re-read that file** for next-step guidance. +Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/skills/speedrun/SKILL.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/.claude/skills/pr/SKILL.md b/workflows/bugfix/.claude/skills/pr/SKILL.md index 7d80f9f..fb42a74 100644 --- a/workflows/bugfix/.claude/skills/pr/SKILL.md +++ b/workflows/bugfix/.claude/skills/pr/SKILL.md @@ -5,6 +5,14 @@ description: Create a pull request for a bug fix, handling fork workflows, authe # Create Pull Request Skill +## Dispatch + +If you were dispatched by the controller or by speedrun, continue below. +Otherwise, read `.claude/skills/controller/SKILL.md` first — it will send +you back here with the proper workflow context. + +--- + You are preparing to submit a bug fix as a pull request. This skill provides a systematic, failure-resistant process for getting code from the working directory into a PR. It handles the common obstacles: authentication, fork workflows, @@ -598,4 +606,4 @@ Report your results: - What was included - Any follow-up actions needed (mark ready for review, add reviewers, etc.) -Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/commands/speedrun.md` for next phase.") and **re-read that file** for next-step guidance. +Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/skills/speedrun/SKILL.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/.claude/skills/reproduce/SKILL.md b/workflows/bugfix/.claude/skills/reproduce/SKILL.md index 512dc27..af1ea35 100644 --- a/workflows/bugfix/.claude/skills/reproduce/SKILL.md +++ b/workflows/bugfix/.claude/skills/reproduce/SKILL.md @@ -5,6 +5,14 @@ description: Systematically reproduce a reported bug and document its observable # Reproduce Bug Skill +## Dispatch + +If you were dispatched by the controller or by speedrun, continue below. +Otherwise, read `.claude/skills/controller/SKILL.md` first — it will send +you back here with the proper workflow context. + +--- + You are a systematic bug reproduction specialist. Your mission is to confirm and document reported bugs, creating a solid foundation for diagnosis by establishing clear, reproducible test cases. ## Your Role @@ -90,4 +98,4 @@ Report your findings: - Key observations and environment details - Where the reproduction report was written -Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/commands/speedrun.md` for next phase.") and **re-read that file** for next-step guidance. +Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/skills/speedrun/SKILL.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/.claude/skills/review/SKILL.md b/workflows/bugfix/.claude/skills/review/SKILL.md index 2b4772c..8fd7257 100644 --- a/workflows/bugfix/.claude/skills/review/SKILL.md +++ b/workflows/bugfix/.claude/skills/review/SKILL.md @@ -5,6 +5,14 @@ description: Critically evaluate a bug fix and its tests, then recommend next st # Review Fix & Tests Skill +## Dispatch + +If you were dispatched by the controller or by speedrun, continue below. +Otherwise, read `.claude/skills/controller/SKILL.md` first — it will send +you back here with the proper workflow context. + +--- + You are a skeptical reviewer whose job is to poke holes in the fix and its tests. Your goal is not to validate — it's to find what's wrong, what's missing, and what could fail in production. Be constructive but honest. @@ -199,4 +207,4 @@ in Step 5. Your verdict and recommendation (from Step 5) serve as the phase summary. -Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/commands/speedrun.md` for next phase.") and **re-read that file** for next-step guidance. +Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/skills/speedrun/SKILL.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/.claude/commands/speedrun.md b/workflows/bugfix/.claude/skills/speedrun/SKILL.md similarity index 91% rename from workflows/bugfix/.claude/commands/speedrun.md rename to workflows/bugfix/.claude/skills/speedrun/SKILL.md index ca254a7..86a57d7 100644 --- a/workflows/bugfix/.claude/commands/speedrun.md +++ b/workflows/bugfix/.claude/skills/speedrun/SKILL.md @@ -1,7 +1,6 @@ --- +name: speedrun description: Speed-run the remaining bugfix phases without stopping between them. -displayName: speedrun -icon: ⚡ --- # /speedrun — Run the Remaining Workflow @@ -27,7 +26,7 @@ Each time you read this file, you will: 2. If all phases are done, print the completion report and stop 3. Otherwise, execute that one phase (see "Execute a Phase" below) 4. The phase skill will tell you to return to the file that dispatched it — - that's this file (`.claude/commands/speedrun.md`). Re-read it and repeat. + that's this file (`.claude/skills/speedrun/SKILL.md`). Re-read it and repeat. This loop continues until all phases are complete or an escalation stops you. @@ -60,19 +59,19 @@ context, then pick the first phase that is NOT done. ## Execute a Phase 1. **Announce** the phase and include this file as the dispatcher: - "Starting the /[phase] phase (dispatched by `.claude/commands/speedrun.md` — speedrun mode)." + "Starting the /[phase] phase (dispatched by `.claude/skills/speedrun/SKILL.md` — speedrun mode)." 2. **Read** the phase skill from the table above 3. **Execute** the skill's steps 4. The skill will tell you to announce which file you are returning to and - re-read it. Return to **this file** (`.claude/commands/speedrun.md`). + re-read it. Return to **this file** (`.claude/skills/speedrun/SKILL.md`). ## Speedrun Rules - **Do not stop and wait between phases.** After each phase, return here and continue to the next one. -- **Do not read the controller.** This command replaces the controller for this +- **Do not read the controller.** This skill replaces the controller for this run. If you are tempted to read `.claude/skills/controller/SKILL.md`, read - `.claude/commands/speedrun.md` instead. + `.claude/skills/speedrun/SKILL.md` instead. - **DO still follow CLAUDE.md escalation rules.** If a phase hits an escalation condition (confidence below 80%, unclear root cause after investigation, multiple valid solutions with unclear trade-offs, security or @@ -163,7 +162,7 @@ When all phases are done (or if you stop early due to escalation), present: /speedrun ``` -The command detects existing artifacts and picks up from the next incomplete phase. +The skill detects existing artifacts and picks up from the next incomplete phase. **With an explicit starting point:** diff --git a/workflows/bugfix/.claude/skills/test/SKILL.md b/workflows/bugfix/.claude/skills/test/SKILL.md index 8b218aa..235093e 100755 --- a/workflows/bugfix/.claude/skills/test/SKILL.md +++ b/workflows/bugfix/.claude/skills/test/SKILL.md @@ -5,6 +5,14 @@ description: Verify a bug fix with comprehensive testing and create regression t # Test & Verify Fix Skill +## Dispatch + +If you were dispatched by the controller or by speedrun, continue below. +Otherwise, read `.claude/skills/controller/SKILL.md` first — it will send +you back here with the proper workflow context. + +--- + You are a thorough testing and verification specialist. Your mission is to verify that a bug fix works correctly and create comprehensive tests to prevent regression, ensuring the fix resolves the issue without introducing new problems. ## Your Role @@ -157,4 +165,4 @@ Report your results: - Whether the full test suite passes - Where the verification report was written -Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/commands/speedrun.md` for next phase.") and **re-read that file** for next-step guidance. +Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/skills/speedrun/SKILL.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/CLAUDE.md b/workflows/bugfix/CLAUDE.md index 8ea6335..88f8262 100755 --- a/workflows/bugfix/CLAUDE.md +++ b/workflows/bugfix/CLAUDE.md @@ -11,9 +11,10 @@ Systematic bug resolution through these phases: 7. **Document** (`/document`) — Release notes and documentation 8. **PR** (`/pr`) — Submit a pull request -The workflow controller lives at `.claude/skills/controller/SKILL.md`. -It defines how to execute phases, recommend next steps, and handle transitions. -Phase skills are at `.claude/skills/{name}/SKILL.md`. +All phases are implemented as skills at `.claude/skills/{name}/SKILL.md`. +The workflow controller at `.claude/skills/controller/SKILL.md` manages phase +transitions and recommendations. The `/speedrun` skill at +`.claude/skills/speedrun/SKILL.md` runs all remaining phases without stopping. Artifacts go in `artifacts/bugfix/`. ## Principles diff --git a/workflows/bugfix/README.md b/workflows/bugfix/README.md index 7cf1fde..57d25cb 100644 --- a/workflows/bugfix/README.md +++ b/workflows/bugfix/README.md @@ -19,31 +19,26 @@ bugfix/ ├── .ambient/ │ └── ambient.json # Workflow configuration ├── .claude/ -│ ├── commands/ # Slash commands (thin wrappers → skills) -│ │ ├── reproduce.md -│ │ ├── diagnose.md -│ │ ├── fix.md -│ │ ├── test.md -│ │ ├── review.md -│ │ ├── document.md -│ │ └── pr.md -│ └── skills/ # Detailed process definitions +│ └── skills/ # All workflow logic lives here +│ ├── controller/SKILL.md # Phase transitions and recommendations +│ ├── assess/SKILL.md │ ├── reproduce/SKILL.md │ ├── diagnose/SKILL.md │ ├── fix/SKILL.md │ ├── test/SKILL.md │ ├── review/SKILL.md │ ├── document/SKILL.md -│ └── pr/SKILL.md +│ ├── pr/SKILL.md +│ └── speedrun/SKILL.md # Runs all remaining phases in sequence ├── CLAUDE.md # Behavioral guidelines └── README.md # This file ``` -### How Commands and Skills Work Together +### How Skills Work -Each **command** is a thin wrapper that invokes a corresponding **skill**. When you run `/diagnose`, the command file tells the agent to read the Diagnose skill from `.claude/skills/diagnose/SKILL.md` and apply it — passing along any arguments you provided plus existing session context. +Each phase is implemented as a **skill** in `.claude/skills/{name}/SKILL.md`. When you run `/assess`, `/fix`, etc., the corresponding skill is invoked directly. Each phase skill checks whether it was dispatched by the controller or speedrun; if invoked standalone, it reads the controller first to ensure proper workflow context. -This separation keeps commands simple and consistent while the skills contain the full process details. +The **controller** skill manages phase transitions and recommends next steps. The **speedrun** skill bypasses the controller and runs all remaining phases in sequence without stopping. ## Workflow Phases