refactor(bugfix): migrate commands to skills-only architecture

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:**

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."
 }

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.

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

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.

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.

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.

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.

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.

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.

workflows/bugfix/.claude/commands/speedrun.md → 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:**
 

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.

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

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