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