refactor(bugfix): convert commands to skills, add CLAUDE.md, clean up#42
Draft
jwm4 wants to merge 11 commits intoambient-code:mainfrom
Draft
refactor(bugfix): convert commands to skills, add CLAUDE.md, clean up#42jwm4 wants to merge 11 commits intoambient-code:mainfrom
jwm4 wants to merge 11 commits intoambient-code:mainfrom
Conversation
- Convert all 5 commands (reproduce, diagnose, fix, test, document) into
detailed skills in .claude/skills/{name}/SKILL.md
- Rewrite commands as thin wrappers that delegate to skills, passing
arguments and session context
- Add CLAUDE.md with behavioral guidelines extracted from amber.md
(engineering discipline, safety guardrails, quality standards)
- Remove .claude/agents/amber.md (redundant with systemPrompt persona)
- Remove supplementary files (AMBER_RESEARCH.md, FIELD_REFERENCE.md,
TEMPLATE_FEEDBACK.md)
- Update systemPrompt to reference skills alongside commands
- Update README to reflect new structure
- Add .claude/skills/pr/SKILL.md with systematic fork-based PR workflow - Add .claude/commands/pr.md thin wrapper - Handles pre-flight checks, fork setup, branch/commit/push, and PR creation - Includes error recovery for common failures (no push access, sandbox restrictions, missing fork) - Update systemPrompt and startupPrompt to include /pr as phase 6 - Update README with PR phase documentation
Make CLAUDE.md self-contained by including workflow phases, commands, skill locations, and artifact path directly instead of referencing ambient.json (which is platform plumbing, not model-visible). Also fix markdown lint warnings (emphasis-as-heading, code block language).
- Add .claude/skills/review/SKILL.md — critically evaluates fix and tests, issues verdict (inadequate fix / incomplete tests / solid), recommends next steps - Add .claude/commands/review.md thin wrapper - Update /test skill to report verification.md path and summarize results inline to the user - Update systemPrompt, startupPrompt, CLAUDE.md, README with /review as optional phase 5 between test and document
- systemPrompt: add PHASE TRANSITIONS section requiring agent to stop and summarize at end of each phase instead of auto-advancing - CLAUDE.md: add Flow Control section reinforcing pause behavior, trim to ~70 lines per best practices - pr/SKILL.md: add placeholders table defining GH_USER, FORK_OWNER, UPSTREAM_OWNER/REPO, REPO, and BRANCH_NAME with sources - pr/SKILL.md: rewrite Step 2 to ask user before creating fork, wait for confirmation, never silently skip ahead - pr/SKILL.md: replace flat fallback with 4-rung fallback ladder, patch file is now absolute last resort - ambient.json: remove rubric (deferred to future PR), remove startupPrompt and results fields - Delete ambient.clean.json (no longer needed) - AGENTS.md: add sandbox restrictions table
- All command wrappers now say 'Read the file ... now and follow it step by step' instead of 'Using the X skill from ...' which the agent was interpreting as conceptual guidance rather than a file-read instruction - systemPrompt: add CRITICAL prefix to skill-reading instruction, explicitly say 'use the Read tool to open the referenced SKILL.md file' - pr/SKILL.md: add 'IMPORTANT: Follow This Skill Exactly' section at top with anti-improvisation rules - pr/SKILL.md: add pre-flight summary checkpoint between Steps 1 and 2 - pr/SKILL.md: upgrade 'no fork' path from 'STOP' to 'HARD STOP' with explicit instructions to wait for user twice (before fork attempt, after fork attempt fails) - pr/SKILL.md: add fork verification command before proceeding to Step 3 - Add critical rules: never attempt gh repo fork without asking user first, never fall back to patch files without exhausting all other options
- systemPrompt: add step to tell user which skill is being invoked before reading it, so user can correct if wrong phase was picked - CLAUDE.md: reinforce skill announcement policy
- Step 1a: don't dead-end on missing gh auth — continue pre-flight to gather info from git, then present options - Step 1b: add fallback git config when gh is unavailable - Step 1d: add git-remote-based fallback for upstream repo identification - Add decision point after pre-flight: present 3 clear options to user (set up auth, provide fork URL, or prepare for manual push) and WAIT for response instead of dumping all manual instructions at once
Every skill now ends with a 'When This Phase Is Done' section that: - Tells the agent to summarize findings to the user - Recommends the natural next step in the workflow - Explicitly says to stop and wait for the user This reinforces the phase-transition pause from the systemPrompt and CLAUDE.md at the skill level, so the agent gets the instruction to stop regardless of whether it's following the systemPrompt guidance or reading the skill directly. Next-step recommendations follow the natural flow: reproduce → diagnose → fix → test → review → document → pr
- New /assess phase (phase 1): reads the bug report, presents understanding, identifies gaps, proposes reproduction plan, and waits for user confirmation before taking any action. No code execution or cloning in this phase. - systemPrompt: updated to 8-phase flow starting with ASSESS, added explicit instruction to start with assess when user provides a bug report - CLAUDE.md: updated phase list to include assess - pr/SKILL.md: clarified that 'never push to upstream' applies even to org bots and GitHub Apps — no exceptions based on account type - pr/SKILL.md: added reminder at pre-flight summary not to skip Step 2
- systemPrompt: scope 'start with ASSESS' to initial bug report only - systemPrompt: add 'INTERPRETING USER RESPONSES' section so agent maps phase names and confirmations to the correct next phase - assess skill: allow cloning and reading code (but not executing) - assess skill: add Step 2 to check for repo and clone if missing, read referenced PRs/files to inform assessment - assess skill: update output to note repo is cloned for later phases
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The bugfix workflow had all process logic embedded directly in command files, a 600-line bundled agent persona (
amber.md) that duplicated the systemPrompt identity, and several supplementary files that were no longer needed.Changes
Commands → Skills Architecture
.claude/skills/{name}/SKILL.md— each contains the full process definition for a workflow phase (reproduce, diagnose, fix, test, document)$ARGUMENTSand existing session contextsystemPromptto reference skills alongside commandsAdded CLAUDE.md
amber.md: engineering discipline, safety guardrails, confidence levels, escalation criteria, PR template, quality standardsCleanup
.claude/agents/amber.md— redundant with the Amber persona defined insystemPrompt; useful content extracted toCLAUDE.mdAMBER_RESEARCH.md,FIELD_REFERENCE.md,TEMPLATE_FEEDBACK.mdNet Impact
851 insertions, 3,343 deletions— significant reduction in bloatTesting
ambient.jsonparses correctly)