@scriptgun/workerc 0.3.0 → 0.4.0

package/README.md

@@ -12,9 +12,9 @@ npx @scriptgun/workerc init
 
 This interactively sets up:
 
-- **12 slash commands** in `.claude/commands/workerc/`
+- **14 slash commands** in `.claude/commands/workerc/`
 - **7 hooks** in `.claude/hooks/`
-- **4 agents** in `.claude/agents/`
+- **4 agents** in `.claude/agents/` (custom agents preserved on re-init)
 - **Settings** in `.claude/settings.local.json` or `.claude/settings.json`
 - **Progress directory** at `.claude/progress/`
 - **Optional CLAUDE.md** scaffold
@@ -34,6 +34,8 @@ This interactively sets up:
 | `/workerc:handoff` | Pause session with handoff notes |
 | `/workerc:done` | Mark session complete |
 | `/workerc:abort` | Abandon session |
+| `/workerc:debug` | Investigate a bug with scientific method debugging |
+| `/workerc:checkpoint` | Create a save point for safe rollback |
 | `/workerc:update` | Update workerc to latest version |
 
 ## Hooks
@@ -74,7 +76,7 @@ Progress files persist across sessions — use `/workerc:resume` to pick up wher
 
 ## Re-running init
 
-`workerc init` is idempotent. Running it again updates all commands, hooks, and agents without duplicating settings entries.
+`workerc init` is idempotent. Running it again updates all commands, hooks, and agents without duplicating settings entries. Custom agents you've added to `.claude/agents/` are preserved.
 
 ## Changelog
 

package/dist/init.js

@@ -177,7 +177,7 @@ export async function init(projectDir) {
         "Hooks:",
         ...result.hooks.map((f) => `  .claude/hooks/${f}`),
         "",
-        "Agents:",
+        `Agents (${result.agents.length} built-in${result.customAgentCount > 0 ? `, ${result.customAgentCount} custom preserved` : ""}):`,
         ...result.agents.map((f) => `  .claude/agents/${f}`),
         "",
         `Settings: .claude/${settingsFile}`,

package/dist/templates/commands/checkpoint.md

@@ -0,0 +1,74 @@
+---
+name: workerc:checkpoint
+description: Create a save point — snapshot current state for safe rollback
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - AskUserQuestion
+---
+
+<objective>
+Create a named checkpoint of the current working state. Uses git to snapshot changes so you can rollback if the next steps go wrong. Logs checkpoint in progress file.
+</objective>
+
+<process>
+
+**Step 1: Find session progress file**
+
+Read all `.claude/progress/*.md`. Find the one with `<!-- session: CURRENT_SESSION_ID -->` on line 2.
+
+If none found: print "No active progress file for this session." and STOP.
+
+**Step 2: Check git state**
+
+Run `git status --short` and `git diff --stat`.
+
+If no changes (clean working tree):
+- Print: "Nothing to checkpoint — working tree is clean."
+- STOP
+
+**Step 3: Name the checkpoint**
+
+Ask:
+```
+AskUserQuestion(
+  header: "Checkpoint",
+  question: "Name this checkpoint? (describes what's safe so far)",
+  options: [
+    { label: "Auto-name", description: "Generate from progress file context" },
+    { label: "I'll name it", description: "I'll provide a name" }
+  ],
+  multiSelect: false
+)
+```
+
+**If "Auto-name":** Generate from latest progress log entries (e.g. "auth-middleware-working").
+**If "I'll name it":** Wait for user input.
+
+Generate tag name: `checkpoint/{slug}/{YYYYMMDD-HHMM}` (e.g. `checkpoint/auth-middleware-working/20260210-1530`).
+
+**Step 4: Create checkpoint**
+
+Stage all current changes and create a temporary commit + tag:
+
+```bash
+git stash push -m "workerc-checkpoint: {name}"
+git stash apply
+```
+
+This creates a stash entry that acts as a named snapshot. The working tree stays exactly as it was.
+
+Log in progress file:
+`- [x] ({YYYY-MM-DD HH:MM}) (checkpoint) {name}`
+
+Print:
+```
+Checkpoint created: {name}
+Stash: git stash list | grep "workerc-checkpoint: {name}"
+Rollback: git stash pop (applies last stash) or git checkout -- . (discard changes)
+```
+
+STOP.
+
+</process>

package/dist/templates/commands/debug.md

@@ -0,0 +1,183 @@
+---
+name: workerc:debug
+description: Investigate a bug using scientific method with persistent debug session
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - AskUserQuestion
+  - WebSearch
+---
+
+<objective>
+Start or resume a debug session. Uses scientific method: gather symptoms, form hypotheses, test one at a time, find root cause, fix, verify. Maintains a persistent debug file that survives context resets.
+</objective>
+
+<process>
+
+**Step 1: Check for active debug sessions**
+
+Look for files matching `.claude/progress/debug-*.md` that are NOT marked `[DONE]` or `[ABORTED]`.
+
+If active sessions exist AND user didn't describe a new issue:
+- List them with current hypothesis and next action
+- Ask:
+```
+AskUserQuestion(
+  header: "Debug",
+  question: "Resume existing session or start new?",
+  options: [
+    { label: "Resume", description: "Continue the active debug session" },
+    { label: "New", description: "Start investigating a new bug" }
+  ],
+  multiSelect: false
+)
+```
+
+If no active sessions or user chose "New": continue to Step 2.
+If "Resume": read the debug file, announce status and current hypothesis, continue from where Current Focus left off.
+
+**Step 2: Gather symptoms**
+
+Ask the user:
+```
+AskUserQuestion(
+  header: "Bug",
+  question: "What's happening?",
+  options: [
+    { label: "Describe it", description: "I'll explain the symptoms" },
+    { label: "Error message", description: "I have a specific error" }
+  ],
+  multiSelect: false
+)
+```
+
+Wait for user input. Then ask follow-ups as needed:
+- What did you expect to happen?
+- When did it start? Did it ever work?
+- Can you reproduce it consistently?
+
+**Step 3: Create debug file**
+
+Generate slug from the bug description (lowercase, hyphens, max 30 chars).
+
+Write `.claude/progress/debug-{slug}.md`:
+```markdown
+# Debug: {title}
+<!-- session: pending -->
+<!-- spec: None -->
+
+## Current Focus
+hypothesis: gathering symptoms
+test: n/a
+next: investigate codebase around error
+
+## Symptoms
+expected: {what should happen}
+actual: {what actually happens}
+errors: {error messages or "none"}
+reproduction: {how to trigger}
+
+## Eliminated
+
+## Evidence
+
+## Log
+- [ ] ({YYYY-MM-DD HH:MM}) (debug) Session started: {title}
+
+## Files
+```
+
+**Step 4: Investigate**
+
+Follow the debugger methodology:
+
+**4a. Gather initial evidence**
+- Search codebase for error text, relevant files, related code
+- Read the most relevant files COMPLETELY
+- Run the app/tests to observe behavior
+- APPEND each finding to `## Evidence`
+
+**4b. Form hypothesis**
+- Based on evidence, form a SPECIFIC, FALSIFIABLE hypothesis
+- Update `## Current Focus` with hypothesis, test, and next action
+- Log: `- [ ] ({timestamp}) (debug) Hypothesis: {hypothesis}`
+
+**4c. Test hypothesis**
+- Execute ONE test at a time
+- Change ONE variable at a time
+- Append result to `## Evidence`
+
+**4d. Evaluate**
+- **Confirmed:** Root cause found — proceed to Step 5
+- **Eliminated:** Append to `## Eliminated` with evidence, form new hypothesis, repeat 4b
+
+Key principles:
+- One hypothesis at a time
+- Falsifiable predictions: "If H is true, I will observe X"
+- Strong evidence: directly observable, repeatable, unambiguous
+- Don't act on "I think it might be X" — wait for proof
+
+**Step 5: Present root cause and fix plan**
+
+```
+## Root Cause Found
+
+**Cause:** {specific root cause with evidence}
+
+**Evidence:**
+- {key finding 1}
+- {key finding 2}
+
+**Proposed fix:** {minimal change to address root cause}
+
+**Files to change:**
+- {file}: {what to change}
+```
+
+Ask:
+```
+AskUserQuestion(
+  header: "Fix",
+  question: "How should we proceed?",
+  options: [
+    { label: "Fix it", description: "Apply the minimal fix" },
+    { label: "Different fix", description: "I want a different approach" },
+    { label: "Just diagnose", description: "Don't fix, I'll handle it" }
+  ],
+  multiSelect: false
+)
+```
+
+**If "Fix it":** Apply the smallest change that addresses root cause. Proceed to Step 6.
+**If "Different fix":** Wait for user's approach, apply that instead. Proceed to Step 6.
+**If "Just diagnose":** Log root cause, mark session done, STOP.
+
+**Step 6: Verify**
+
+- Test against original Symptoms
+- Run related tests if they exist
+- Verify the fix doesn't break adjacent functionality
+
+**If verification fails:** Log failure, go back to Step 4 with new evidence.
+
+**If verification passes:**
+
+Update debug file:
+- Log: `- [x] ({timestamp}) (debug) Root cause: {cause}`
+- Log: `- [x] ({timestamp}) (debug) Fix verified: {what was fixed}`
+
+Print:
+```
+Bug fixed and verified.
+Root cause: {cause}
+Fix: {what changed}
+Files: {list}
+```
+
+STOP.
+
+</process>

package/dist/write-files.d.ts

@@ -15,5 +15,6 @@ export declare function writeFiles(options: WriteOptions): {
     commands: string[];
     hooks: string[];
     agents: string[];
+    customAgentCount: number;
     claudeMd: boolean;
 };

package/dist/write-files.js

@@ -40,12 +40,18 @@ export function writeFiles(options) {
     for (const file of commandFiles) {
         cpSync(join(commandsSrc, file), join(commandsTarget, file));
     }
-    /* Copy agent templates verbatim */
+    /* Copy agent templates — only overwrite workerc's own agents */
     const agentsSrc = join(templateDir, "agents");
     const agentFiles = readdirSync(agentsSrc).filter((f) => f.endsWith(".md"));
+    const workercAgentNames = new Set(agentFiles);
     for (const file of agentFiles) {
         cpSync(join(agentsSrc, file), join(agentsTarget, file));
     }
+    /* Count custom agents preserved (exist in target but not in workerc templates) */
+    const existingAgents = existsSync(agentsTarget)
+        ? readdirSync(agentsTarget).filter((f) => f.endsWith(".md"))
+        : [];
+    const customAgentCount = existingAgents.filter((f) => !workercAgentNames.has(f)).length;
     /* Copy/template hook files */
     const writtenHooks = [];
     /* Tracker — verbatim copy */
@@ -103,5 +109,11 @@ export function writeFiles(options) {
             claudeMd = true;
         }
     }
-    return { commands: commandFiles, hooks: writtenHooks, agents: agentFiles, claudeMd };
+    return {
+        commands: commandFiles,
+        hooks: writtenHooks,
+        agents: agentFiles,
+        customAgentCount,
+        claudeMd,
+    };
 }

package/package.json

@@ -34,5 +34,5 @@
   },
   "type": "module",
   "types": "./dist/init.d.ts",
-  "version": "0.3.0"
+  "version": "0.4.0"
 }