@scriptgun/workerc 0.2.0 → 0.4.0

package/README.md

@@ -1,8 +1,8 @@
 # workerc
 
-Claude Code session management — commands, hooks, and progress tracking.
+Claude Code session management — commands, hooks, agents, and progress tracking.
 
-workerc adds structured session workflows to any project using [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It installs slash commands for managing work sessions, hooks that enforce progress tracking and code quality, and a progress file system that persists context across sessions.
+workerc adds structured session workflows to any project using [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It installs slash commands for managing work sessions, hooks that enforce progress tracking and code quality, agents for specialized tasks, and a progress file system that persists context across sessions.
 
 ## Install
 
@@ -12,16 +12,19 @@ npx @scriptgun/workerc init
 
 This interactively sets up:
 
-- **10 slash commands** in `.claude/commands/workerc/`
-- **Hooks** in `.claude/hooks/` (tracker + optional lint/type check)
-- **Settings** in `.claude/settings.local.json`
+- **14 slash commands** in `.claude/commands/workerc/`
+- **7 hooks** in `.claude/hooks/`
+- **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
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
 | `/workerc:new` | Start a new work session with optional spec |
+| `/workerc:plan` | Refine spec with codebase context — turns intent into blueprint |
 | `/workerc:resume` | Resume an unclaimed session |
 | `/workerc:status` | Show current session progress |
 | `/workerc:list` | List all progress files with status |
@@ -31,32 +34,53 @@ 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
 
 ### Always installed
 
-- **post-edit-tracker.sh** — Blocks edits if no progress file is active. Auto-claims pending sessions on first edit. Auto-tracks edited files. Enforces 15s freshness (agent must update progress regularly).
-- **session-start-compact.sh** — Re-injects session context after Claude compacts the conversation. Restores progress file, spec, and file list so the agent can continue seamlessly.
+- **post-edit-tracker.sh** — Blocks edits if no progress file is active. Auto-claims pending sessions on first edit. Auto-tracks edited files. Enforces 15s freshness.
+- **session-start-compact.sh** — Re-injects session context after conversation compaction. Restores progress file, spec, and file list.
+- **session-start-startup.sh** — Injects active progress context on every session start, not just compaction.
+- **workerc-check-update.cjs** — Checks npm registry for new workerc versions in background. Caches result for statusline.
+- **workerc-statusline.cjs** — Shows model, current task, directory, and context usage bar with color thresholds.
 
 ### Optional (auto-detected)
 
 - **post-edit-lint.sh** — Runs linter on every file edit. Detected tools: Biome, ESLint.
 - **post-edit-types.sh** — Runs type checker on every file edit. Detected tools: TypeScript (`tsc`).
 
+## Agents
+
+| Agent | Description |
+|-------|-------------|
+| **browser** | Web browsing and automation via Playwright MCP |
+| **commit** | Single-line git commits (`type(scope?): message`) |
+| **finder** | Fast codebase search using Haiku model |
+| **debugger** | Scientific method debugging with persistent debug sessions |
+
 ## How it works
 
-1. Run `/workerc:new` to start a session — creates a progress file in `.claude/progress/`
-2. The tracker hook auto-claims the session on your first file edit
-3. As you work, the tracker logs edited files and enforces regular progress updates
-4. Use `/workerc:commit` to commit, `/workerc:review` to check against spec
-5. Use `/workerc:handoff` to pause or `/workerc:done` to complete
+1. Run `/workerc:new` to start a session — creates a progress file and optional spec
+2. Run `/workerc:plan` to refine the spec with real codebase context
+3. The tracker hook auto-claims the session on your first file edit
+4. As you work, the tracker logs edited files and enforces regular progress updates
+5. The statusline shows your current task, model, and context usage
+6. Use `/workerc:commit` to commit, `/workerc:review` to check against spec
+7. Use `/workerc:handoff` to pause or `/workerc:done` to complete
 
 Progress files persist across sessions — use `/workerc:resume` to pick up where you left off.
 
 ## Re-running init
 
-`workerc init` is idempotent. Running it again updates all commands and hooks 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
+
+See [CHANGELOG.md](./CHANGELOG.md) for release history.
 
 ## License
 

package/dist/init.js

@@ -1,3 +1,5 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import * as p from "@clack/prompts";
 import { detect } from "./detect.js";
 import { mergeSettings } from "./merge-settings.js";
@@ -120,8 +122,25 @@ export async function init(projectDir) {
         hookDescriptions.push(`- ${typesHookFilename} (blocks on type errors)`);
     }
     hookDescriptions.push("- post-edit-tracker.sh (blocks if progress not updated within 15s)");
+    hookDescriptions.push("- workerc-check-update.cjs (checks for workerc updates on session start)");
+    hookDescriptions.push("- workerc-statusline.cjs (shows model, task, directory, context usage)");
+    hookDescriptions.push("- session-start-startup.sh (injects active progress on session start)");
     const activeHooksDescription = hookDescriptions.join("\n");
-    /* Step 6: Write files */
+    /* Step 6: CLAUDE.md */
+    let enableClaudeMd = false;
+    const claudeMdExists = existsSync(join(projectDir, ".claude", "CLAUDE.md"));
+    if (!claudeMdExists) {
+        const claudeMdAnswer = await p.confirm({
+            message: "Scaffold .claude/CLAUDE.md?",
+            initialValue: true,
+        });
+        if (p.isCancel(claudeMdAnswer)) {
+            p.cancel("Cancelled");
+            process.exit(0);
+        }
+        enableClaudeMd = claudeMdAnswer;
+    }
+    /* Step 7: Write files */
     spinner.start("Writing files");
     const result = writeFiles({
         projectDir,
@@ -134,9 +153,10 @@ export async function init(projectDir) {
         typeExtensions,
         typesHookFilename,
         activeHooksDescription,
+        enableClaudeMd,
     });
     spinner.stop("Files written");
-    /* Step 7: Merge settings */
+    /* Step 8: Merge settings */
     spinner.start("Updating settings");
     const settingsFile = mergeSettings({
         projectDir,
@@ -147,20 +167,26 @@ export async function init(projectDir) {
         typesHookFilename,
     });
     spinner.stop("Settings updated");
-    /* Step 8: Summary */
+    /* Step 9: Summary */
     p.log.success("workerc installed");
-    p.log.message([
+    const summary = [
         "",
-        "Commands (10):",
+        `Commands (${result.commands.length}):`,
         ...result.commands.map((f) => `  .claude/commands/workerc/${f}`),
         "",
         "Hooks:",
         ...result.hooks.map((f) => `  .claude/hooks/${f}`),
         "",
+        `Agents (${result.agents.length} built-in${result.customAgentCount > 0 ? `, ${result.customAgentCount} custom preserved` : ""}):`,
+        ...result.agents.map((f) => `  .claude/agents/${f}`),
+        "",
         `Settings: .claude/${settingsFile}`,
         "Progress: .claude/progress/",
-        "",
-        "Get started: run /workerc:new in Claude Code",
-    ].join("\n"));
+    ];
+    if (result.claudeMd) {
+        summary.push("CLAUDE.md: .claude/CLAUDE.md (customize it)");
+    }
+    summary.push("", "Get started: run /workerc:new in Claude Code");
+    p.log.message(summary.join("\n"));
     p.outro("done");
 }

package/dist/merge-settings.js

@@ -9,6 +9,9 @@ const WORKERC_HOOK_NAMES = [
     "post-edit-tracker.sh",
     "post-edit-lint.sh",
     "post-edit-types.sh",
+    "workerc-check-update.cjs",
+    "workerc-statusline.cjs",
+    "session-start-startup.sh",
 ];
 function isWorkercHook(hook) {
     return WORKERC_HOOK_NAMES.some((name) => hook.command.includes(name));
@@ -44,7 +47,30 @@ export function mergeSettings(options) {
             },
         ],
     };
-    settings.hooks.SessionStart = [...existingSessionStart, compactHook];
+    const checkUpdateHook = {
+        matcher: "",
+        hooks: [
+            {
+                type: "command",
+                command: 'node "$CLAUDE_PROJECT_DIR"/.claude/hooks/workerc-check-update.cjs',
+            },
+        ],
+    };
+    const startupHook = {
+        matcher: "",
+        hooks: [
+            {
+                type: "command",
+                command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/session-start-startup.sh',
+            },
+        ],
+    };
+    settings.hooks.SessionStart = [
+        ...existingSessionStart,
+        startupHook,
+        compactHook,
+        checkUpdateHook,
+    ];
     /* PostToolUse: keep non-workerc hooks, append workerc hooks */
     const existingPostToolUse = (settings.hooks.PostToolUse ?? []).filter((g) => !isWorkercGroup(g));
     const newPostToolUse = [];
@@ -81,6 +107,11 @@ export function mergeSettings(options) {
         ],
     });
     settings.hooks.PostToolUse = [...existingPostToolUse, ...newPostToolUse];
+    /* Statusline: always overwrite with workerc's */
+    settings.statusLine = {
+        type: "command",
+        command: 'node "$CLAUDE_PROJECT_DIR"/.claude/hooks/workerc-statusline.cjs',
+    };
     writeFileSync(settingsPath, JSON.stringify(settings, null, "\t") + "\n");
     return filename;
 }

package/dist/templates/CLAUDE.md.tmpl

@@ -0,0 +1,17 @@
+## Behavior
+- concise responses
+- read relevant docs before work
+- root cause > quick fix
+
+## Code Style
+<!-- customize for your project -->
+
+## Repo
+<!-- describe your repo structure, package manager, build tools -->
+
+## Agents
+| agent | purpose |
+|-------|---------|
+| browser | web automation via Playwright MCP |
+| commit | git commits |
+| finder | fast codebase search |

package/dist/templates/agents/browser-agent.md

@@ -0,0 +1,7 @@
+---
+name: browser
+description: Web browsing and automation
+tools: Read, Bash
+---
+
+Use Playwright MCP for browser automation.

package/dist/templates/agents/commit-agent.md

@@ -0,0 +1,8 @@
+---
+name: commit
+description: Create git commits
+tools: Read, Bash, Grep, Glob
+---
+
+Single line commits: `type(scope?): message`
+No description body, no co-author.

package/dist/templates/agents/debugger-agent.md

@@ -0,0 +1,256 @@
+---
+name: debugger
+description: Investigates bugs using scientific method with persistent debug sessions
+tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch
+---
+
+<role>
+You investigate bugs using systematic scientific method. You maintain a persistent debug file that survives context resets.
+
+User = Reporter (knows symptoms), You = Investigator (find the cause).
+
+Never ask the user what's causing the bug or which file has the problem. Ask about their experience. Investigate the cause yourself.
+</role>
+
+<philosophy>
+
+## Meta-Debugging: Your Own Code
+
+When debugging code you wrote, you're fighting your own mental model.
+
+- **Treat your code as foreign** — read it as if someone else wrote it
+- **Question your design decisions** — they're hypotheses, not facts
+- **Admit your mental model might be wrong** — code behavior is truth, your model is a guess
+- **Prioritize code you touched** — if you modified 100 lines and something breaks, those are prime suspects
+
+The hardest admission: "I implemented this wrong."
+
+## Foundation Principles
+
+- **What do you know for certain?** Observable facts, not assumptions
+- **What are you assuming?** Have you verified it?
+- **Strip away everything you think you know.** Build from observable facts.
+
+## Cognitive Biases
+
+| Bias | Trap | Antidote |
+|------|------|----------|
+| Confirmation | Only seek supporting evidence | "What would prove me wrong?" |
+| Anchoring | First explanation becomes your anchor | Generate 3+ hypotheses before investigating any |
+| Sunk Cost | 2 hours on one path, keep going | Every 30 min: "If I started fresh, would I take this path?" |
+
+## Core Disciplines
+
+- **Change one variable** at a time. Multiple changes = no idea what mattered.
+- **Complete reading.** Read entire functions, not just "relevant" lines.
+- **Embrace not knowing.** "I don't know" = good. "It must be X" = dangerous.
+
+</philosophy>
+
+<hypothesis_testing>
+
+## Falsifiability
+
+A good hypothesis can be proven wrong. If you can't design an experiment to disprove it, it's not useful.
+
+**Bad:** "Something is wrong with the state"
+**Good:** "User state resets because component remounts on route change"
+
+The difference: specificity.
+
+## Process
+
+For each hypothesis:
+1. **Prediction:** If H is true, I will observe X
+2. **Test:** Execute one specific test
+3. **Observe:** Record what actually happened
+4. **Conclude:** Support or refute?
+
+**One hypothesis at a time.** If you change three things and it works, you don't know which fixed it.
+
+## Evidence Quality
+
+**Strong:** Directly observable, repeatable, unambiguous, independent
+**Weak:** Hearsay, non-repeatable, ambiguous, confounded
+
+Act when you can answer YES to all:
+1. Understand the mechanism? (not just "what" but "why")
+2. Reproduce reliably?
+3. Have evidence, not just theory?
+4. Ruled out alternatives?
+
+## When Disproven
+
+1. Acknowledge explicitly with evidence
+2. Extract the learning — what did this rule out?
+3. Form new hypotheses based on what you now know
+4. Don't get attached — being wrong quickly beats being wrong slowly
+
+</hypothesis_testing>
+
+<investigation_techniques>
+
+## Binary Search
+
+**When:** Large codebase, many possible failure points.
+
+Cut problem space in half repeatedly:
+1. Identify boundaries (where works, where fails)
+2. Test midpoint
+3. Determine which half contains the bug
+4. Repeat until exact line
+
+## Minimal Reproduction
+
+**When:** Complex system, many moving parts.
+
+1. Copy failing code to new file
+2. Remove one piece at a time
+3. Still reproduces? Keep it removed. Doesn't? Put it back.
+4. Repeat until bare minimum
+5. Bug is now obvious
+
+## Working Backwards
+
+**When:** You know correct output, don't know why you're not getting it.
+
+1. Define desired output precisely
+2. What function produces this? Test with expected input.
+3. Correct output? Bug is earlier. Wrong output? Bug is here.
+4. Repeat backwards through call stack
+
+## Differential Debugging
+
+**When:** Used to work, now doesn't. Works in one env but not another.
+
+List differences (code, env, config, data), test each in isolation.
+
+## Git Bisect
+
+**When:** Feature worked in past, broke at unknown commit.
+
+```bash
+git bisect start
+git bisect bad
+git bisect good abc123
+```
+
+100 commits → ~7 tests to find breaking commit.
+
+## Technique Selection
+
+| Situation | Technique |
+|-----------|-----------|
+| Large codebase | Binary search |
+| Confused | Rubber duck, add logging first |
+| Complex system | Minimal reproduction |
+| Know desired output | Working backwards |
+| Used to work | Differential debugging, git bisect |
+| Many possible causes | Comment out everything |
+
+</investigation_techniques>
+
+<debug_file>
+
+## Location
+
+Debug files live in `.claude/progress/debug-{slug}.md`
+
+## Structure
+
+```markdown
+# Debug: {title}
+<!-- session: {SESSION_ID} -->
+<!-- spec: None -->
+
+## Current Focus
+hypothesis: {current theory}
+test: {how testing it}
+next: {immediate next step}
+
+## Symptoms
+expected: {what should happen}
+actual: {what actually happens}
+errors: {error messages}
+reproduction: {how to trigger}
+
+## Eliminated
+- {theory}: {evidence that disproved it}
+
+## Evidence
+- {what examined}: {what observed} → {implication}
+
+## Log
+- [ ] ({timestamp}) (debug) {action taken}
+
+## Files
+```
+
+## Rules
+
+| Section | Rule |
+|---------|------|
+| Current Focus | OVERWRITE before every action |
+| Symptoms | IMMUTABLE after gathering |
+| Eliminated | APPEND only |
+| Evidence | APPEND only |
+| Log | APPEND only |
+
+Update the file BEFORE taking action, not after. If context resets, the file shows what was about to happen.
+
+</debug_file>
+
+<execution_flow>
+
+**Step 1: Start or resume**
+
+Check `.claude/progress/debug-*.md` for active sessions matching this session ID.
+
+If resuming: read file, announce status, continue from Current Focus.
+If new: create debug file immediately.
+
+**Step 2: Gather symptoms**
+
+Ask about: expected behavior, actual behavior, error messages, when it started.
+Update file after EACH answer.
+
+**Step 3: Investigate**
+
+1. Gather initial evidence (search codebase, read files, run tests)
+2. Form SPECIFIC, FALSIFIABLE hypothesis
+3. Test ONE hypothesis at a time
+4. Append to Evidence and Eliminated as you go
+5. Repeat until root cause confirmed
+
+**Step 4: Fix**
+
+- Make SMALLEST change that addresses root cause
+- Update debug file with fix details
+
+**Step 5: Verify**
+
+- Test against original Symptoms
+- If fails: back to Step 3
+- If passes: log resolution
+
+**Step 6: Done**
+
+Log completion in debug file. Print root cause and fix summary.
+
+</execution_flow>
+
+<when_to_restart>
+
+Consider starting over when:
+1. 2+ hours with no progress — you're tunnel-visioned
+2. 3+ "fixes" that didn't work — your mental model is wrong
+3. You can't explain the current behavior — don't add changes on top of confusion
+4. The fix works but you don't know why — this isn't fixed, this is luck
+
+Restart protocol:
+1. Write down what you know for certain
+2. Write down what you've ruled out
+3. List new hypotheses (different from before)
+4. Begin again from evidence gathering
+
+</when_to_restart>

package/dist/templates/agents/finder-agent.md

@@ -0,0 +1,8 @@
+---
+name: finder
+description: Fast codebase search
+tools: Read, Grep, Glob
+model: haiku
+---
+
+Returns file paths with line numbers.

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/templates/commands/plan.md

@@ -0,0 +1,167 @@
+---
+name: workerc:plan
+description: Refine spec with codebase context — turns intent into implementation blueprint
+allowed-tools:
+  - Read
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Read the current spec + progress, explore the codebase around relevant areas, present recommendations with options to the user, then rewrite the spec with concrete implementation details.
+Turns vague intent into a precise blueprint with real file paths, patterns, types, and edge cases.
+</objective>
+
+<process>
+
+**Step 1: Find session and spec**
+
+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.
+
+Read line 3 for spec path.
+
+If spec is "None" or missing:
+- Print: "No spec linked to this session. Create one with /workerc:new or /workerc:scope first."
+- STOP
+
+Read the full spec file. Read the full progress file.
+
+**Step 2: Understand the goal**
+
+From the spec's `## Goal` and `## Scope` sections, identify:
+- What the user wants to build/change
+- What's explicitly in/out of scope
+- Any decisions already made (in `## Decisions`)
+
+Print a one-line summary of the goal to confirm understanding.
+
+**Step 3: Explore the codebase**
+
+Based on the goal and scope, explore the codebase to gather real context:
+
+- **Find relevant files:** Use Glob and Grep to find files related to the goal. Look for existing patterns, types, utilities, middleware, routes, tests — anything the implementation should follow or integrate with.
+- **Read key files:** Read the most relevant 3-5 files to understand existing patterns, naming conventions, directory structure, and coding style.
+- **Map dependencies:** Identify what the new code needs to import, extend, or integrate with.
+- **Check for prior art:** Look for similar features already implemented that can serve as a template.
+
+**Step 4: Present recommendations**
+
+Based on what you discovered, present a structured recommendation:
+
+```
+## Recommendation
+
+### Approach
+{1-3 sentences describing the recommended approach}
+
+### Key files
+- `path/to/file.ts` — {why this file matters}
+- `path/to/pattern.ts` — {pattern to follow}
+
+### Implementation steps
+1. {step 1}
+2. {step 2}
+...
+
+### Patterns to follow
+- {existing pattern from codebase}
+
+### Edge cases
+- {edge case 1}
+- {edge case 2}
+
+### Open questions
+- {anything unclear that needs user input}
+```
+
+Then ask the user:
+
+```
+AskUserQuestion(
+  header: "Plan",
+  question: "How should we proceed with this plan?",
+  options: [
+    { label: "Looks good", description: "Write this into the spec" },
+    { label: "Adjust", description: "I want to change some things" },
+    { label: "Different approach", description: "I have a different idea" }
+  ],
+  multiSelect: false
+)
+```
+
+**If "Adjust":**
+- Wait for user's adjustments
+- Incorporate their feedback
+- Re-present the updated recommendation
+- Ask again
+
+**If "Different approach":**
+- Wait for user's alternative
+- Re-explore codebase with new direction
+- Go back to Step 4
+
+**If "Looks good":**
+- Proceed to Step 5
+
+**Step 5: Rewrite the spec**
+
+Update the spec file with concrete implementation details. Preserve existing sections and add/expand:
+
+```markdown
+# {Title}
+
+## Goal
+{original goal, unchanged}
+
+## Scope
+{original scope, unchanged}
+
+## Implementation Plan
+
+### Approach
+{the approved approach}
+
+### Steps
+- [ ] {step 1} — `path/to/file.ts`
+- [ ] {step 2} — `path/to/file.ts`
+...
+
+### Patterns
+{existing patterns to follow, with file:line references}
+
+### Types / Interfaces
+{key types the implementation needs, with references to where they're defined}
+
+### Edge Cases
+{edge cases to handle}
+
+## Decisions
+{any new decisions from the planning process, appended to existing}
+
+## Discovered
+{anything discovered during exploration — gotchas, constraints, existing bugs}
+
+## Rejected
+{approaches considered but rejected, with reasons}
+```
+
+**Step 6: Log and confirm**
+
+Add to progress log:
+`- [x] ({YYYY-MM-DD HH:MM}) (plan) Refined spec with implementation details`
+
+Print:
+```
+Spec updated: {spec path}
+{N} implementation steps planned
+Ready to build — the spec is now your blueprint.
+```
+
+STOP.
+
+</process>

package/dist/templates/commands/update.md

@@ -0,0 +1,29 @@
+---
+name: workerc:update
+description: Update workerc to the latest version
+allowed-tools:
+  - Bash
+---
+
+<objective>
+Update workerc to the latest version and re-run init.
+</objective>
+
+<process>
+
+**Step 1: Run update**
+
+```bash
+npx @scriptgun/workerc@latest init
+```
+
+This will re-detect tools, re-write hooks, and update settings.
+The init wizard is interactive — follow the prompts.
+
+**Step 2: Confirm**
+
+Print: "workerc updated. Restart Claude Code to pick up new hooks."
+
+STOP.
+
+</process>

package/dist/templates/hooks/session-start-startup.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# SessionStart hook: Inject active progress context on fresh session start
+# Fires on: every session start (matcher "" in settings)
+# Complements session-start-compact.sh which only fires on compaction
+
+INPUT=$(cat)
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
+
+[ -z "$SESSION_ID" ] && exit 0
+
+TRACKER_DIR="$(cd "$(dirname "$0")/../progress" 2>/dev/null && pwd)"
+[ -z "$TRACKER_DIR" ] || [ ! -d "$TRACKER_DIR" ] && exit 0
+
+PROJECT_DIR="$(cd "$(dirname "$0")/../.." 2>/dev/null && pwd)"
+
+# Find this session's active tracker
+MY_TRACKER=""
+for t in "$TRACKER_DIR"/*.md; do
+	[ -f "$t" ] || continue
+	LINE1=$(head -1 "$t")
+	echo "$LINE1" | grep -q "\[DONE\]" && continue
+	echo "$LINE1" | grep -q "\[ABORTED\]" && continue
+	LINE2=$(sed -n '2p' "$t")
+	if echo "$LINE2" | grep -q "<!-- session: $SESSION_ID -->"; then
+		MY_TRACKER="$t"
+		break
+	fi
+done
+
+[ -z "$MY_TRACKER" ] && exit 0
+
+# Read tracker
+TRACKER_CONTENT=$(cat "$MY_TRACKER")
+TRACKER_NAME=$(basename "$MY_TRACKER")
+TRACKER_REL=".claude/progress/$TRACKER_NAME"
+
+# Extract spec path (line 3: <!-- spec: path -->)
+SPEC_PATH=""
+SPEC_CONTENT=""
+SPEC_LINE=$(sed -n '3p' "$MY_TRACKER")
+if echo "$SPEC_LINE" | grep -q "<!-- spec:"; then
+	SPEC_PATH=$(echo "$SPEC_LINE" | sed -n 's/<!-- spec: \(.*\) -->/\1/p')
+fi
+
+if [ -n "$SPEC_PATH" ] && [ "$SPEC_PATH" != "None" ]; then
+	FULL_SPEC="$PROJECT_DIR/$SPEC_PATH"
+	if [ -f "$FULL_SPEC" ]; then
+		SPEC_CONTENT=$(cat "$FULL_SPEC")
+	fi
+fi
+
+DONE_COUNT=$(grep -c '^\- \[x\]' "$MY_TRACKER" 2>/dev/null || echo "0")
+
+CONTEXT="# ACTIVE SESSION CONTEXT
+
+You have an active work session. Session ID: $SESSION_ID
+
+## Progress: $TRACKER_REL ($DONE_COUNT entries completed)
+$TRACKER_CONTENT
+
+## REQUIRED: Read your context files before working:
+1. Read file $PROJECT_DIR/$TRACKER_REL"
+
+if [ -n "$SPEC_PATH" ] && [ "$SPEC_PATH" != "None" ]; then
+	CONTEXT="$CONTEXT
+2. Read file $PROJECT_DIR/$SPEC_PATH"
+fi
+
+CONTEXT="$CONTEXT
+3. Review ## Files to rebuild code context
+4. Continue working from where you left off"
+
+if [ -n "$SPEC_CONTENT" ]; then
+	CONTEXT="$CONTEXT
+
+## Spec: $SPEC_PATH
+$SPEC_CONTENT"
+fi
+
+jq -n --arg ctx "$CONTEXT" '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":$ctx}}'
+exit 0

package/dist/templates/hooks/workerc-check-update.cjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/* SessionStart hook: check for workerc updates in background */
+/* Spawns a detached child so the hook exits immediately */
+
+const fs = require("fs")
+const path = require("path")
+const os = require("os")
+const { spawn } = require("child_process")
+
+const homeDir = os.homedir()
+const cacheDir = path.join(homeDir, ".claude", "cache")
+const cacheFile = path.join(cacheDir, "workerc-update-check.json")
+
+if (!fs.existsSync(cacheDir)) {
+  fs.mkdirSync(cacheDir, { recursive: true })
+}
+
+const child = spawn(
+  process.execPath,
+  [
+    "-e",
+    `
+const fs = require("fs")
+const { execSync } = require("child_process")
+
+const cacheFile = ${JSON.stringify(cacheFile)}
+
+let installed = "0.0.0"
+try {
+  const out = execSync("npm ls @scriptgun/workerc --json 2>/dev/null || npx workerc --version 2>/dev/null", {
+    encoding: "utf8",
+    timeout: 10000,
+    windowsHide: true,
+  }).trim()
+  /* Try JSON parse (npm ls), fall back to raw version string */
+  try {
+    const json = JSON.parse(out)
+    installed = json.dependencies?.["@scriptgun/workerc"]?.version || "0.0.0"
+  } catch (_) {
+    if (/^\\d+\\.\\d+/.test(out)) installed = out
+  }
+} catch (_) {}
+
+let latest = null
+try {
+  latest = execSync("npm view @scriptgun/workerc version", {
+    encoding: "utf8",
+    timeout: 10000,
+    windowsHide: true,
+  }).trim()
+} catch (_) {}
+
+const result = {
+  update_available: latest && installed !== latest,
+  installed,
+  latest: latest || "unknown",
+  checked: Math.floor(Date.now() / 1000),
+}
+
+fs.writeFileSync(cacheFile, JSON.stringify(result))
+`,
+  ],
+  { stdio: "ignore", windowsHide: true }
+)
+
+child.unref()

package/dist/templates/hooks/workerc-statusline.cjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/* Statusline hook: model | task | directory | context usage */
+/* Reads current task from workerc progress files */
+
+const fs = require("fs")
+const path = require("path")
+const os = require("os")
+
+let input = ""
+process.stdin.setEncoding("utf8")
+process.stdin.on("data", (chunk) => (input += chunk))
+process.stdin.on("end", () => {
+  try {
+    const data = JSON.parse(input)
+    const model = data.model?.display_name || "Claude"
+    const dir = data.workspace?.current_dir || process.cwd()
+    const session = data.session_id || ""
+    const remaining = data.context_window?.remaining_percentage
+
+    /* Context window bar (scaled to 80% real limit) */
+    let ctx = ""
+    if (remaining != null) {
+      const rem = Math.round(remaining)
+      const rawUsed = Math.max(0, Math.min(100, 100 - rem))
+      const used = Math.min(100, Math.round((rawUsed / 80) * 100))
+      const filled = Math.floor(used / 10)
+      const bar = "\u2588".repeat(filled) + "\u2591".repeat(10 - filled)
+
+      if (used < 63) {
+        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`
+      } else if (used < 81) {
+        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`
+      } else if (used < 95) {
+        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`
+      } else {
+        ctx = ` \x1b[5;31m\uD83D\uDC80 ${bar} ${used}%\x1b[0m`
+      }
+    }
+
+    /* Current task from workerc progress files */
+    let task = ""
+    const projectDir = data.workspace?.current_dir || process.cwd()
+    const progressDir = path.join(projectDir, ".claude", "progress")
+
+    if (session && fs.existsSync(progressDir)) {
+      const files = fs.readdirSync(progressDir).filter((f) => f.endsWith(".md"))
+
+      for (const file of files) {
+        const filePath = path.join(progressDir, file)
+        try {
+          const content = fs.readFileSync(filePath, "utf8")
+          const lines = content.split("\n")
+
+          /* Line 1: title, skip if DONE/ABORTED */
+          if (/\[DONE\]|\[ABORTED\]/.test(lines[0] || "")) continue
+          /* Line 2: <!-- session: ID --> */
+          if (!(lines[1] || "").includes(`<!-- session: ${session} -->`)) continue
+
+          /* Extract title from "# Title" */
+          const titleMatch = (lines[0] || "").match(/^#\s+(.+)/)
+          if (titleMatch) task = titleMatch[1].replace(/\s*\[.*?\]\s*/g, "").trim()
+          break
+        } catch (_) {}
+      }
+    }
+
+    /* workerc update available? */
+    let updateNotice = ""
+    const cacheFile = path.join(os.homedir(), ".claude", "cache", "workerc-update-check.json")
+    if (fs.existsSync(cacheFile)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(cacheFile, "utf8"))
+        if (cache.update_available) {
+          updateNotice = "\x1b[33m\u2B06 workerc update\x1b[0m \u2502 "
+        }
+      } catch (_) {}
+    }
+
+    /* Output */
+    const dirname = path.basename(dir)
+    if (task) {
+      process.stdout.write(
+        `${updateNotice}\x1b[2m${model}\x1b[0m \u2502 \x1b[1m${task}\x1b[0m \u2502 \x1b[2m${dirname}\x1b[0m${ctx}`
+      )
+    } else {
+      process.stdout.write(
+        `${updateNotice}\x1b[2m${model}\x1b[0m \u2502 \x1b[2m${dirname}\x1b[0m${ctx}`
+      )
+    }
+  } catch (_) {
+    /* Silent fail */
+  }
+})

package/dist/write-files.d.ts

@@ -9,8 +9,12 @@ export interface WriteOptions {
     typeExtensions: string;
     typesHookFilename: string;
     activeHooksDescription: string;
+    enableClaudeMd: boolean;
 }
 export declare function writeFiles(options: WriteOptions): {
     commands: string[];
     hooks: string[];
+    agents: string[];
+    customAgentCount: number;
+    claudeMd: boolean;
 };

package/dist/write-files.js

@@ -28,9 +28,11 @@ export function writeFiles(options) {
     const claudeDir = join(options.projectDir, ".claude");
     const commandsTarget = join(claudeDir, "commands", "workerc");
     const hooksTarget = join(claudeDir, "hooks");
+    const agentsTarget = join(claudeDir, "agents");
     const progressDir = join(claudeDir, "progress");
     ensureDir(commandsTarget);
     ensureDir(hooksTarget);
+    ensureDir(agentsTarget);
     ensureDir(progressDir);
     /* Copy command templates verbatim */
     const commandsSrc = join(templateDir, "commands");
@@ -38,12 +40,36 @@ export function writeFiles(options) {
     for (const file of commandFiles) {
         cpSync(join(commandsSrc, file), join(commandsTarget, file));
     }
+    /* 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 */
     cpSync(join(templateDir, "hooks", "post-edit-tracker.sh"), join(hooksTarget, "post-edit-tracker.sh"));
     chmodSync(join(hooksTarget, "post-edit-tracker.sh"), 0o755);
     writtenHooks.push("post-edit-tracker.sh");
+    /* Check-update — verbatim copy */
+    cpSync(join(templateDir, "hooks", "workerc-check-update.cjs"), join(hooksTarget, "workerc-check-update.cjs"));
+    chmodSync(join(hooksTarget, "workerc-check-update.cjs"), 0o755);
+    writtenHooks.push("workerc-check-update.cjs");
+    /* Statusline — verbatim copy */
+    cpSync(join(templateDir, "hooks", "workerc-statusline.cjs"), join(hooksTarget, "workerc-statusline.cjs"));
+    chmodSync(join(hooksTarget, "workerc-statusline.cjs"), 0o755);
+    writtenHooks.push("workerc-statusline.cjs");
+    /* Startup — verbatim copy */
+    cpSync(join(templateDir, "hooks", "session-start-startup.sh"), join(hooksTarget, "session-start-startup.sh"));
+    chmodSync(join(hooksTarget, "session-start-startup.sh"), 0o755);
+    writtenHooks.push("session-start-startup.sh");
     /* Session start compact — template {{ACTIVE_HOOKS}} */
     const compactSrc = readFileSync(join(templateDir, "hooks", "session-start-compact.sh"), "utf-8");
     const compactRendered = renderTemplate(compactSrc, {
@@ -74,5 +100,20 @@ export function writeFiles(options) {
         chmodSync(join(hooksTarget, options.typesHookFilename), 0o755);
         writtenHooks.push(options.typesHookFilename);
     }
-    return { commands: commandFiles, hooks: writtenHooks };
+    /* CLAUDE.md — optional scaffold */
+    let claudeMd = false;
+    if (options.enableClaudeMd) {
+        const claudeMdPath = join(options.projectDir, ".claude", "CLAUDE.md");
+        if (!existsSync(claudeMdPath)) {
+            cpSync(join(templateDir, "CLAUDE.md.tmpl"), claudeMdPath);
+            claudeMd = true;
+        }
+    }
+    return {
+        commands: commandFiles,
+        hooks: writtenHooks,
+        agents: agentFiles,
+        customAgentCount,
+        claudeMd,
+    };
 }

package/package.json

@@ -1,21 +1,18 @@
 {
-  "name": "@scriptgun/workerc",
-  "version": "0.2.0",
-  "description": "Claude Code session management CLI — commands, hooks, and progress tracking",
-  "type": "module",
   "bin": {
     "workerc": "dist/bin.js"
   },
-  "main": "./dist/init.js",
-  "types": "./dist/init.d.ts",
+  "dependencies": {
+    "@clack/prompts": "1.0.0"
+  },
+  "description": "Claude Code session management CLI — commands, hooks, and progress tracking",
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
   "files": [
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsc && cp -r src/templates dist/templates && chmod +x dist/bin.js",
-    "type:check": "tsc --noEmit"
-  },
   "keywords": [
     "claude",
     "claude-code",
@@ -25,14 +22,17 @@
     "workerc"
   ],
   "license": "MIT",
+  "main": "./dist/init.js",
+  "name": "@scriptgun/workerc",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lovrozagar/workerc.git"
   },
-  "dependencies": {
-    "@clack/prompts": "1.0.0"
+  "scripts": {
+    "build": "tsc && cp -r src/templates dist/templates && chmod +x dist/bin.js",
+    "type:check": "tsc --noEmit"
   },
-  "devDependencies": {
-    "typescript": "^5.9.3"
-  }
+  "type": "module",
+  "types": "./dist/init.d.ts",
+  "version": "0.4.0"
 }