From 31b61718686a735593543d573e98ceda708c1ebf Mon Sep 17 00:00:00 2001 From: bastien Date: Mon, 13 Apr 2026 15:32:55 +0200 Subject: [PATCH] feat(skills): add /hotfix, /bugfix, and /feat lightweight skills Fill the gap between direct editing and the full /ship-feature orchestrator. Three new skills for common everyday tasks: - /hotfix: superficial bugs (typo, CSS, config), 1-2 files, no plan - /bugfix: deeper bugs with root cause investigation + fix plan - /feat: small features 1-5 files, light planning, no subagents Each skill documents its escalation path to the next level. Updated plugin-advisor with skill routing table and references. Co-Authored-By: Claude Opus 4.6 --- agents/plugin-advisor.md | 20 +++++- skills/bugfix/SKILL.md | 147 +++++++++++++++++++++++++++++++++++++++ skills/feat/SKILL.md | 136 ++++++++++++++++++++++++++++++++++++ skills/hotfix/SKILL.md | 86 +++++++++++++++++++++++ 4 files changed, 386 insertions(+), 3 deletions(-) create mode 100644 skills/bugfix/SKILL.md create mode 100644 skills/feat/SKILL.md create mode 100644 skills/hotfix/SKILL.md diff --git a/agents/plugin-advisor.md b/agents/plugin-advisor.md index 7282473..daab6a7 100644 --- a/agents/plugin-advisor.md +++ b/agents/plugin-advisor.md @@ -155,14 +155,28 @@ After presenting RECOMMENDATIONS, if any plugin has ⚡ ENABLE status: | `fast-libs` | context7 | — | Doc freshness critical | | `multi-agent` + `complex-arch` | gsd v2 CLI | ruflo (unless explicitly requested) | GSD v2 preferred; ruflo only on explicit user request | | `simple` / single-session | — | gsd, gstack, ruflo, ui-ux-pro-max | Saves ~3000-5000t | -| `embedded` / firmware | — | all toggles; superpowers optional | workflow: /analyze → edit or /ship-feature | +| `embedded` / firmware | — | all toggles; superpowers optional | workflow: /analyze → /hotfix or /bugfix or /ship-feature | | backend/lib/CLI only | — | frontend-design, ui-ux-pro-max, gstack | ~3100t saved | -| small project / hotfix | — | gstack, ruflo, gsd | Overhead exceeds value | +| small project / hotfix | — | gstack, ruflo, gsd | Use /hotfix, /bugfix, or /feat | **GSD v2 note:** `gsd-pi` is a standalone CLI (Pi SDK), not a Claude Code plugin. Zero passive token cost in CC sessions. Recommend when: feature > 1 day, multiple isolated context windows needed, crash recovery, cost tracking, or parallel workers. Usage: `gsd` in terminal → `/gsd auto`. **Ruflo note:** `ruflo` is a heavy CLI tool (310+ tools, ~500-1500t passive when hooks active). Only recommend when the project explicitly requires coordinating 5+ specialized agents simultaneously or swarm/parallel-orchestration architecture. For standard multi-session work, GSD v2 is sufficient and lighter. Install: `npm install -g ruflo@latest --omit=optional`. Init: `ruflo init --wizard`. +### Skill routing by task size + +When the plugin-advisor detects a `simple` or `hotfix` signal, suggest the appropriate lightweight skill instead of heavy orchestrators: + +| Task | Skill | When to use | Overhead | +|---|---|---|---| +| Typo, CSS fix, wrong value, missing import | `/hotfix` | Root cause obvious, 1-2 files max | ~30s | +| Bug with unclear root cause, multi-file | `/bugfix` | Needs investigation before fixing, up to ~5 files | ~3 min | +| Small feature, 1-5 files | `/feat` | Well-scoped addition, no design needed | ~2 min | +| Large feature, design decisions needed | `/ship-feature` | Multi-file, needs brainstorm + plan + review | ~10 min | +| New project from scratch | `/init-project` | Full project setup with scaffolding | ~15 min | + +**Escalation path:** `/hotfix` → `/bugfix` → `/ship-feature` (bugs), `/feat` → `/ship-feature` (features). Each skill documents when to escalate to the next level. + --- ## COMPATIBILITY MATRIX @@ -245,7 +259,7 @@ RULE: IF "embedded" signal (firmware, bare-metal, microcontroller, or Makefile+C → superpowers OPTIONAL: useful for initial design brainstorm on complex drivers, but unnecessary for single-function patches — user decides → GSD v2 CLI: not recommended (sessions are short, tasks are atomic) - → Recommend workflow: /analyze → Edit direct (hotfix) or /ship-feature (multi-file) + → Recommend workflow: /analyze → /hotfix (patch) or /bugfix (investigation) or /ship-feature (multi-file) → NOTE: print "embedded project detected — minimal plugin footprint recommended" RULE: IF gstack ON AND ruflo ON: diff --git a/skills/bugfix/SKILL.md b/skills/bugfix/SKILL.md new file mode 100644 index 0000000..a956ad6 --- /dev/null +++ b/skills/bugfix/SKILL.md @@ -0,0 +1,147 @@ +--- +name: bugfix +description: | + Structured bug fix with root cause investigation. For bugs where + the cause isn't immediately obvious, spans multiple files, or + requires careful analysis before fixing. Includes hypothesis-driven + investigation and a fix plan. + Trigger: "bugfix", "debug this", "fix this bug", "pourquoi ca marche pas", + "investigate and fix", "find and fix", "root cause + fix". + For obvious 1-2 file fixes → use /hotfix instead. + For bugs that need investigation only (no fix) → use /analyze. +argument-hint: +disable-model-invocation: false +allowed-tools: + - Read + - Edit + - Write + - Bash + - Grep + - Glob + - Agent +--- + +# BUGFIX — Structured Bug Fix + +Investigate, understand, plan, fix. No guessing. The iron law: +understand the root cause before writing a single fix. + +## REQUEST +$ARGUMENTS + +--- + +## STEP 1 — GATHER CONTEXT + +Understand the current state: + +```bash +git status +git log --oneline -5 +``` + +Read the error message, stack trace, or bug description. +Identify: +- **What** is broken (symptom) +- **Where** it manifests (file, line, endpoint, UI element) +- **When** it started (recent commit? always? after a deploy?) + +```bash +# If the user mentions "it was working before": +git log --oneline -20 --all -- +``` + +## STEP 2 — INVESTIGATE + +Trace the bug from symptom to root cause: + +1. Read the code path involved (follow the data flow). +2. Check recent changes to the affected files: + ```bash + git log --oneline -10 -- + git diff HEAD~5 -- # if recent regression suspected + ``` +3. Look for related tests — do they pass? Do they cover + the broken case? +4. Search for similar patterns elsewhere that might have + the same bug: + ```bash + # grep for the same pattern to assess blast radius + ``` + +## STEP 3 — HYPOTHESIZE + PLAN + +Present findings before fixing: + +``` +BUGFIX — DIAGNOSIS +BUG : +ROOT CAUSE: +EVIDENCE: +BLAST RADIUS: + +FIX PLAN: + 1. — + 2. — + [3. — add/update test for this case] + +RISK: +``` + +- If the root cause is still unclear after investigation, + say so explicitly. List remaining hypotheses ranked by + probability. Ask the user before proceeding. +- If the fix is trivial after investigation (1-2 lines): + proceed directly — no need to wait for approval on an + obvious fix. +- If the fix is significant (>10 lines, multiple files, + behavior change): wait for user approval. + +## STEP 4 — FIX + +Apply the fix following the plan: + +- Fix the root cause, not the symptom. +- Add or update tests to cover the bug case (regression test). +- If no test framework exists: document what you verified. +- Keep changes minimal — fix the bug, nothing else. + +## STEP 5 — VERIFY + COMMIT + +1. Run the full relevant test suite: + ```bash + # detect and run tests + ``` +2. If a build step exists, verify it passes. +3. Check for regressions in related functionality. +4. Commit using conventional format: + ``` + fix(): + + + + + Co-Authored-By: Claude + ``` +5. Print summary: + ``` + BUGFIX COMPLETE + BUG : + ROOT CAUSE : + FILE(S) : + TEST(S) : + REGRESSION : + ``` + +--- + +## RULES +- No fix without understanding the root cause first. +- No plugin check (lightweight skill, not an orchestrator). +- If investigation reveals a design flaw requiring significant + refactoring → stop, explain, suggest `/ship-feature` for the + proper fix. +- Always add a regression test when possible. +- Keep the fix scoped. No "while we're here" cleanups. +- If >5 files need changes → reconsider if `/ship-feature` + is more appropriate. diff --git a/skills/feat/SKILL.md b/skills/feat/SKILL.md new file mode 100644 index 0000000..5ead828 --- /dev/null +++ b/skills/feat/SKILL.md @@ -0,0 +1,136 @@ +--- +name: feat +description: | + Small feature implementation (1-5 files). Light planning, direct + implementation, no heavy orchestration. For features that don't + need the full /ship-feature pipeline (no design brainstorm, no + subagents, no plugin check gate). + Trigger: "feat", "small feature", "add this", "petite feature", + "quick feature", "ajoute ca", "implement this small thing". + For multi-file features needing design → use /ship-feature. + For bug fixes → use /hotfix or /bugfix. +argument-hint: +disable-model-invocation: false +allowed-tools: + - Read + - Edit + - Write + - Bash + - Grep + - Glob + - Agent +--- + +# FEAT — Small Feature, Fast Track + +Implement a small, well-scoped feature without the overhead of a +full orchestrator. Direct work, light planning, quick delivery. + +## REQUEST +$ARGUMENTS + +--- + +## STEP 0 — SCOPE CHECK + +Before starting, verify this is actually a small feature: + +```bash +git status +git log --oneline -3 +``` + +Read the relevant existing code to understand the context. + +**Escalate to `/ship-feature` if:** +- The feature needs >5 files of new/modified code +- It requires architectural decisions or design tradeoffs +- It involves new dependencies or infrastructure changes +- The user isn't sure what they want (needs brainstorming) + +**Downgrade to `/hotfix` if:** +- It's really just adding a missing field, config value, etc. + +Print a one-line scope confirmation: +``` +FEAT: — ~ files, +``` + +## STEP 1 — MINI-PLAN + +Quick mental model, not a formal plan document: + +1. List the files to create or modify (with line references). +2. Describe the approach in 2-5 bullet points. +3. Note any edge cases to handle. +4. If tests exist for the area, note which tests to add/update. + +Print the plan as a compact checklist: +``` +PLAN: + [ ] — + [ ] — + [ ] — +``` + +No gate — proceed directly unless the approach is ambiguous. +If ambiguous: ask the user one focused question, then proceed. + +## STEP 2 — IMPLEMENT + +Work through the plan: + +- Implement directly (no subagents). +- Write tests alongside the code (not after). +- Follow existing patterns in the codebase. +- Run tests incrementally as you go. + +## STEP 3 — VERIFY + +1. Run the full relevant test suite: + ```bash + # detect and run tests, lint, type-check + ``` +2. If a dev server is relevant, mention what the user should + check visually. +3. Quick self-review: scan your diff for obvious issues: + ```bash + git diff --stat + git diff + ``` + +## STEP 4 — COMMIT + +Commit using conventional format: +``` +feat(): + + + +Co-Authored-By: Claude +``` + +If the feature touched multiple concerns (e.g., feature + config + +test), consider splitting into 2-3 atomic commits using the same +logic as `/commit-change`. + +Print summary: +``` +FEAT COMPLETE +FEATURE : +FILE(S) : +TEST(S) : +VERIFIED : +``` + +--- + +## RULES +- Max 5 files. If more needed → `/ship-feature`. +- No plugin check (not an orchestrator). +- No brainstorm/design phase (if needed → `/ship-feature`). +- No subagents — direct implementation. +- Keep scope tight. If scope creep happens mid-work, stop + and suggest splitting into `/feat` + follow-up task. +- Follow existing code patterns. Don't introduce new patterns + for a small feature. diff --git a/skills/hotfix/SKILL.md b/skills/hotfix/SKILL.md new file mode 100644 index 0000000..6c00abc --- /dev/null +++ b/skills/hotfix/SKILL.md @@ -0,0 +1,86 @@ +--- +name: hotfix +description: | + Quick fix for superficial bugs: typos, CSS issues, config errors, + off-by-one, wrong variable name, missing import, broken link. + Use when the root cause is obvious and the fix is 1-2 files max. + Trigger: "hotfix", "quick fix", "typo", "fix this small thing", + "c'est juste un petit bug", "patch rapide". + Do NOT use for bugs requiring investigation — use /bugfix instead. +argument-hint: +disable-model-invocation: false +allowed-tools: + - Read + - Edit + - Write + - Bash + - Grep + - Glob +--- + +# HOTFIX — Quick Superficial Fix + +Fast-track fix for obvious bugs. No planning overhead, no plugin +check, no subagents. Get in, fix, verify, get out. + +## REQUEST +$ARGUMENTS + +--- + +## STEP 1 — LOCATE + +Find the bug. Use the description and any error message to go +straight to the source: + +```bash +git status +git log --oneline -3 +``` + +- Read the relevant file(s). Confirm the root cause is obvious + and superficial (typo, wrong value, missing import, etc.). +- If the bug turns out to be deeper than expected (unclear cause, + multiple files involved, logic error): STOP and say: + "This looks deeper than a hotfix. Run `/bugfix ` + for a structured investigation." + +## STEP 2 — FIX + +Apply the minimal change that fixes the bug: + +- Edit only what is necessary. No refactoring, no cleanup. +- If tests exist for the affected code, run them: + ```bash + # detect and run relevant tests + ``` +- If a build step exists, verify it still passes. + +## STEP 3 — VERIFY + COMMIT + +1. Verify the fix: + - Run the test suite or the specific test if available. + - If no tests: explain what you verified manually. +2. Commit using conventional format: + ``` + fix(): + + Co-Authored-By: Claude + ``` +3. Print summary: + ``` + HOTFIX APPLIED + FILE(S) : + FIX : + VERIFIED: + ``` + +--- + +## RULES +- Max 2 files changed. If more needed → `/bugfix`. +- No refactoring. No "while we're here" improvements. +- No plugin check (overhead > value for a hotfix). +- If root cause is unclear → escalate to `/bugfix`. +- If fix touches >5 lines of logic → reconsider if this is + truly a hotfix.