refactor(bugfix): convert commands to skills, add CLAUDE.md, clean up

[jwm4]

Bugfix workflow: skill-based architecture with workflow controller

Problem

The bugfix workflow had all process logic inline in command files. This meant users only got the workflow's carefully designed process if they typed the exact slash command — saying "fix this bug" in natural language would bypass all of it. Phase transitions were unreliable, the agent would auto-advance without pausing, and the PR creation process failed in predictable ways that weren't handled.

Changes

Architecture: commands → skills → controller

Refactored from a command-heavy design to a three-layer architecture:

• Controller skill (.claude/skills/controller/SKILL.md) — owns all phase transitions, recommendations, and flow logic. The single source of truth for "what happens next."
• Phase skills (.claude/skills/{name}/SKILL.md) — contain the full multi-step process for each phase. Report findings only; never recommend next steps.
• Command wrappers (.claude/commands/*.md) — thin pointers (~5 lines each) that route to the controller.

This means users get the workflow's benefit whether they type /fix or "fix this bug."

New phases:

• /assess — initial phase that reads the bug report, summarizes understanding, identifies gaps, and proposes a plan before jumping into reproduction
• /review — optional phase after /test that critically evaluates the fix and tests, looking for gaps and missed edge cases
• /pr — systematic, failure-resistant pull request creation with fork workflows, bot identity handling, and a 4-rung fallback ladder

New files:

• workflows/bugfix/CLAUDE.md — behavioral guidelines (principles, hard limits, safety, quality, escalation)
• docs/adr/2026-02-12-bugfix-lessons-learned.md — 16 lessons learned about prompt engineering for multi-phase AI workflows

Deleted files:

• .claude/agents/amber.md — redundant with systemPrompt; useful content moved to CLAUDE.md
• AMBER_RESEARCH.md, FIELD_REFERENCE.md, TEMPLATE_FEEDBACK.md — supplementary docs not used by the workflow
• .ambient/ambient.clean.json — unused duplicate

Simplified systemPrompt:

Reduced from ~100 lines to ~10 lines. The systemPrompt now just identifies the agent, points at the controller, and lists the workspace layout. All behavioral rules live in CLAUDE.md; all process logic lives in skills.

Key design decisions

• Skills trigger controller re-reads. Each skill ends with "Then re-read the controller for next-step guidance." This is the mechanism that prevents the agent from getting stuck in the previous skill's context after a phase completes.
• Controller owns all recommendations. Skills report findings; the controller decides what to suggest next. This prevents skills from recommending skipping phases (e.g., fix → PR, skipping test and review).
• Flexible recommendations over rigid routing. The controller has guidance for skipping forward, going back, and ending early — not a fixed phase-to-phase table.
• PR skill handles bot identity. When running as a GitHub App, the skill resolves the real user via /installation/repositories, uses the correct jq fields for fork detection, and treats gh pr create 403 as an expected outcome (provides a GitHub compare URL) rather than an error to debug.

Testing

Iteratively tested on the Ambient Code Platform across multiple sessions. The ADR documents all issues encountered and how they were resolved.

[jeremyeder]

This is solid, I'll load it as a custom workflow and see how we do. Thanks!

[jwm4]

Oh, I forgot to mention this in the PR description. Here are three things that I think should be in this workflow but are not in this PR because I wanted to break up the work a little:

1. YOLO mode, i.e., some way to tell the model to just run the entire workflow and without stopping and asking questions. I don't think this is hard to do, but I do think it will take some iterating to get it to work well because the current workflow has pretty strong guidance to not YOLO, getting it to YOLO only when it's supposed to (and making sure it doesn't forget whether it's in YOLO mode or not) might be a little tricky. I have some thoughts on how to do it, but I want to take the time to get it right.
2. Context7 and/or DeepWiki MCP servers: Since these are free hosted servers that don't require any credentials or set up, it would be super easy to include them in the workflow I think. I haven't tried that out, but I think it would work. I would be inclined to start with just Context7 to start because I've gotten a lot of good results from that one and furthermore it's usually better to limit how many different options you give a model. The workflow is fairly complex already so if we're going to add an extra tools I would want to do so sparingly.
3. The Ambient-specific rubric mechanism: Right now the workflow has a skill for assessing the quality of a fix. That skill could probably be complimented by having a formal rubric schema in ambient.json and a corresponding rubric.md, but I don't really have good intuition as to what guidance would go in the skill versus what guidance would go in the rubric.md versus what would be implicit in the schema. I also don't really understand what's being done with either the schema or the rubric.md. So I think a lot more work would be needed to figure out how to make this skill and the Ambient-specific rubric mechanism work well together. I'm also a little concerned that if we do this and we wind up limiting the scope of the skill because it's covered well through the Ambient-specific rubric mechanism then the workflow becomes less portable, i.e., you can't easily just drop it into Claude Code because the skill is specifically designed to complement the Ambient-specific rubric mechanism and thus not to work well as a standalone skill. So I'm a little on the fence about whether this is even a good idea.