@scriptgun/workerc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 workerc contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# workerc
+
+Claude Code session management — commands, hooks, 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.
+
+## Install
+
+```bash
+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`
+- **Progress directory** at `.claude/progress/`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/workerc:new` | Start a new work session with optional spec |
+| `/workerc:resume` | Resume an unclaimed session |
+| `/workerc:status` | Show current session progress |
+| `/workerc:list` | List all progress files with status |
+| `/workerc:scope` | Update spec scope mid-session |
+| `/workerc:commit` | Stage and commit with auto-generated message |
+| `/workerc:review` | Review work against spec |
+| `/workerc:handoff` | Pause session with handoff notes |
+| `/workerc:done` | Mark session complete |
+| `/workerc:abort` | Abandon session |
+
+## 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.
+
+### 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`).
+
+## 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
+
+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.
+
+## License
+
+MIT

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { init } from "./init.js";
+const args = process.argv.slice(2);
+const command = args[0];
+if (command === "init") {
+    const projectDir = resolve(args[1] ?? ".");
+    init(projectDir);
+}
+else {
+    console.log(`workerc — Claude Code session management
+
+Usage:
+  workerc init [dir]    Install commands, hooks, and settings
+
+Options:
+  dir                   Project directory (default: current)
+
+Examples:
+  npx workerc init
+  npx workerc init ./my-project`);
+    if (command && command !== "--help" && command !== "-h") {
+        process.exit(1);
+    }
+}

package/dist/detect.d.ts

@@ -0,0 +1,10 @@
+export interface DetectedTool {
+    name: string;
+    command: string;
+    extensions: string;
+}
+export interface DetectionResult {
+    linter: DetectedTool | undefined;
+    typeChecker: DetectedTool | undefined;
+}
+export declare function detect(projectDir: string): DetectionResult;

package/dist/detect.js

@@ -0,0 +1,59 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+const LINTER_CONFIGS = [
+    {
+        patterns: ["biome.json", "biome.jsonc"],
+        tool: {
+            name: "biome",
+            command: "npx biome check --write",
+            extensions: "ts|tsx|js|jsx|json|css",
+        },
+    },
+    {
+        patterns: [
+            "eslint.config.js",
+            "eslint.config.mjs",
+            "eslint.config.cjs",
+            "eslint.config.ts",
+            ".eslintrc",
+            ".eslintrc.js",
+            ".eslintrc.json",
+            ".eslintrc.yml",
+        ],
+        tool: {
+            name: "eslint",
+            command: "npx eslint --fix",
+            extensions: "ts|tsx|js|jsx",
+        },
+    },
+];
+const TYPE_CHECKER_CONFIGS = [
+    {
+        patterns: ["tsconfig.json"],
+        tool: {
+            name: "tsc",
+            command: "npx tsc --noEmit",
+            extensions: "ts|tsx",
+        },
+    },
+];
+function findConfig(projectDir, patterns) {
+    return patterns.some((p) => existsSync(join(projectDir, p)));
+}
+export function detect(projectDir) {
+    let linter;
+    for (const config of LINTER_CONFIGS) {
+        if (findConfig(projectDir, config.patterns)) {
+            linter = config.tool;
+            break;
+        }
+    }
+    let typeChecker;
+    for (const config of TYPE_CHECKER_CONFIGS) {
+        if (findConfig(projectDir, config.patterns)) {
+            typeChecker = config.tool;
+            break;
+        }
+    }
+    return { linter, typeChecker };
+}

package/dist/init.d.ts

@@ -0,0 +1 @@
+export declare function init(projectDir: string): Promise<void>;

package/dist/init.js

@@ -0,0 +1,144 @@
+import * as p from "@clack/prompts";
+import { detect } from "./detect.js";
+import { mergeSettings } from "./merge-settings.js";
+import { writeFiles } from "./write-files.js";
+export async function init(projectDir) {
+    p.intro("workerc init");
+    /* Step 1: Detect tools */
+    const spinner = p.spinner();
+    spinner.start("Detecting project tools");
+    const detected = detect(projectDir);
+    spinner.stop("Detection complete");
+    if (detected.linter) {
+        p.log.info(`Found linter: ${detected.linter.name}`);
+    }
+    if (detected.typeChecker) {
+        p.log.info(`Found type checker: ${detected.typeChecker.name}`);
+    }
+    if (!detected.linter && !detected.typeChecker) {
+        p.log.info("No linter or type checker detected");
+    }
+    /* Step 2: Lint hook */
+    let enableLint = false;
+    let lintCommand = "";
+    let lintExtensions = "";
+    const lintHookFilename = "post-edit-lint.sh";
+    if (detected.linter) {
+        const lintAnswer = await p.confirm({
+            message: `Enable lint hook? (${detected.linter.name}: ${detected.linter.command})`,
+            initialValue: true,
+        });
+        if (p.isCancel(lintAnswer)) {
+            p.cancel("Cancelled");
+            process.exit(0);
+        }
+        enableLint = lintAnswer;
+        if (enableLint) {
+            const cmdAnswer = await p.text({
+                message: "Lint command (file path appended automatically):",
+                initialValue: detected.linter.command,
+            });
+            if (p.isCancel(cmdAnswer)) {
+                p.cancel("Cancelled");
+                process.exit(0);
+            }
+            lintCommand = cmdAnswer;
+            const extAnswer = await p.text({
+                message: "File extensions to check (pipe-separated):",
+                initialValue: detected.linter.extensions,
+            });
+            if (p.isCancel(extAnswer)) {
+                p.cancel("Cancelled");
+                process.exit(0);
+            }
+            lintExtensions = extAnswer;
+        }
+    }
+    /* Step 3: Type check hook */
+    let enableTypes = false;
+    let typeCommand = "";
+    let typeExtensions = "";
+    const typesHookFilename = "post-edit-types.sh";
+    if (detected.typeChecker) {
+        const typesAnswer = await p.confirm({
+            message: `Enable type check hook? (${detected.typeChecker.name}: ${detected.typeChecker.command})`,
+            initialValue: true,
+        });
+        if (p.isCancel(typesAnswer)) {
+            p.cancel("Cancelled");
+            process.exit(0);
+        }
+        enableTypes = typesAnswer;
+        if (enableTypes) {
+            const cmdAnswer = await p.text({
+                message: "Type check command:",
+                initialValue: detected.typeChecker.command,
+            });
+            if (p.isCancel(cmdAnswer)) {
+                p.cancel("Cancelled");
+                process.exit(0);
+            }
+            typeCommand = cmdAnswer;
+            const extAnswer = await p.text({
+                message: "File extensions to check (pipe-separated):",
+                initialValue: detected.typeChecker.extensions,
+            });
+            if (p.isCancel(extAnswer)) {
+                p.cancel("Cancelled");
+                process.exit(0);
+            }
+            typeExtensions = extAnswer;
+        }
+    }
+    /* Step 4: Build active hooks description for compact hook */
+    const hookDescriptions = [];
+    if (enableLint) {
+        hookDescriptions.push(`- ${lintHookFilename} (blocks on lint/format errors)`);
+    }
+    if (enableTypes) {
+        hookDescriptions.push(`- ${typesHookFilename} (blocks on type errors)`);
+    }
+    hookDescriptions.push("- post-edit-tracker.sh (blocks if progress not updated within 15s)");
+    const activeHooksDescription = hookDescriptions.join("\n");
+    /* Step 5: Write files */
+    spinner.start("Writing files");
+    const result = writeFiles({
+        projectDir,
+        enableLint,
+        lintCommand,
+        lintExtensions,
+        lintHookFilename,
+        enableTypes,
+        typeCommand,
+        typeExtensions,
+        typesHookFilename,
+        activeHooksDescription,
+    });
+    spinner.stop("Files written");
+    /* Step 6: Merge settings */
+    spinner.start("Updating settings");
+    mergeSettings({
+        projectDir,
+        enableLint,
+        lintHookFilename,
+        enableTypes,
+        typesHookFilename,
+    });
+    spinner.stop("Settings updated");
+    /* Step 7: Summary */
+    p.log.success("workerc installed");
+    p.log.message([
+        "",
+        "Commands (10):",
+        ...result.commands.map((f) => `  .claude/commands/workerc/${f}`),
+        "",
+        "Hooks:",
+        ...result.hooks.map((f) => `  .claude/hooks/${f}`),
+        "",
+        "Settings: .claude/settings.local.json",
+        "Progress: .claude/progress/",
+        "",
+        "Get started: run /workerc:new in Claude Code",
+    ].join("\n"));
+    p.outro("done");
+}

package/dist/merge-settings.d.ts

@@ -0,0 +1,8 @@
+export interface MergeOptions {
+    projectDir: string;
+    enableLint: boolean;
+    lintHookFilename: string;
+    enableTypes: boolean;
+    typesHookFilename: string;
+}
+export declare function mergeSettings(options: MergeOptions): void;

package/dist/merge-settings.js

@@ -0,0 +1,82 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/**
+ * Identifies workerc-managed hooks by checking if the command path
+ * contains ".claude/hooks/" and one of our known script names.
+ */
+const WORKERC_HOOK_NAMES = [
+    "session-start-compact.sh",
+    "post-edit-tracker.sh",
+    "post-edit-lint.sh",
+    "post-edit-types.sh",
+];
+function isWorkercHook(hook) {
+    return WORKERC_HOOK_NAMES.some((name) => hook.command.includes(name));
+}
+function isWorkercGroup(group) {
+    return group.hooks.every(isWorkercHook);
+}
+export function mergeSettings(options) {
+    const settingsPath = join(options.projectDir, ".claude", "settings.local.json");
+    const settingsDir = dirname(settingsPath);
+    if (!existsSync(settingsDir)) {
+        mkdirSync(settingsDir, { recursive: true });
+    }
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        const raw = readFileSync(settingsPath, "utf-8");
+        settings = JSON.parse(raw);
+    }
+    if (!settings.hooks) {
+        settings.hooks = {};
+    }
+    /* SessionStart: remove old workerc hooks, add compact */
+    const existingSessionStart = (settings.hooks.SessionStart ?? []).filter((g) => !isWorkercGroup(g));
+    const compactHook = {
+        matcher: "compact",
+        hooks: [
+            {
+                type: "command",
+                command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/session-start-compact.sh',
+            },
+        ],
+    };
+    settings.hooks.SessionStart = [...existingSessionStart, compactHook];
+    /* PostToolUse: remove old workerc hooks, add new ones */
+    const existingPostToolUse = (settings.hooks.PostToolUse ?? []).filter((g) => !isWorkercGroup(g));
+    const newPostToolUse = [];
+    if (options.enableLint) {
+        newPostToolUse.push({
+            matcher: "Write|Edit",
+            hooks: [
+                {
+                    type: "command",
+                    command: `"$CLAUDE_PROJECT_DIR"/.claude/hooks/${options.lintHookFilename}`,
+                },
+            ],
+        });
+    }
+    if (options.enableTypes) {
+        newPostToolUse.push({
+            matcher: "Write|Edit",
+            hooks: [
+                {
+                    type: "command",
+                    command: `"$CLAUDE_PROJECT_DIR"/.claude/hooks/${options.typesHookFilename}`,
+                },
+            ],
+        });
+    }
+    /* Tracker always goes last */
+    newPostToolUse.push({
+        matcher: "Write|Edit",
+        hooks: [
+            {
+                type: "command",
+                command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/post-edit-tracker.sh',
+            },
+        ],
+    });
+    settings.hooks.PostToolUse = [...existingPostToolUse, ...newPostToolUse];
+    writeFileSync(settingsPath, JSON.stringify(settings, null, "\t") + "\n");
+}

package/dist/templates/commands/abort.md

@@ -0,0 +1,63 @@
+---
+name: workerc:abort
+description: Abandon current work and mark progress as aborted
+allowed-tools:
+  - Read
+  - Edit
+  - Glob
+  - AskUserQuestion
+---
+
+<objective>
+Mark the current session's work as abandoned. Different from done (finished) and handoff (paused).
+Use when: wrong approach, spec changed, work no longer needed.
+</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: Get reason**
+
+Ask user:
+```
+AskUserQuestion(
+  header: "Reason",
+  question: "Why is this work being abandoned?",
+  options: [
+    { label: "Wrong approach", description: "The approach didn't work out" },
+    { label: "No longer needed", description: "Requirements changed or feature dropped" },
+    { label: "Blocked", description: "Can't proceed due to external dependency" }
+  ],
+  multiSelect: false
+)
+```
+
+**Step 3: Update progress file**
+
+- Update line 1: append " [ABORTED]"
+- Update line 2: change session ID to empty `<!-- session:  -->`
+- Add log entry: `- [ ] ({YYYY-MM-DD HH:MM}) (abort) Abandoned: {reason}`
+
+**Step 4: Update spec if exists**
+
+Read line 3 for spec path. If spec exists (not "None"):
+- Read the spec file
+- Append to `## Rejected` section: `- {YYYY-MM-DD}: Aborted — {reason}`
+
+**Step 5: Confirm**
+
+Print:
+```
+Aborted: {filename}
+Reason: {reason}
+Session unclaimed. Progress kept as historical record.
+```
+
+STOP.
+
+</process>

package/dist/templates/commands/commit.md

@@ -0,0 +1,145 @@
+---
+name: workerc:commit
+description: Commit tracked files with auto-generated conventional commit message
+allowed-tools:
+  - Read
+  - Glob
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Stage and commit files from the current session's progress file.
+Auto-generates conventional commit message from progress context.
+NEVER add Co-Authored-By, AI attribution, or any footer to the commit message.
+</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: Read progress and spec**
+
+Read the full progress file.
+Read spec if one exists (line 3, not "None").
+
+**Step 3: Check git status**
+
+Run `git status --short` and `git diff --stat`.
+
+Get the list of files from `## Files` section.
+
+For each file in ## Files, check if it has uncommitted changes (modified, untracked, or staged).
+Collect only files that actually have changes — skip files already committed or unchanged.
+
+If no files have changes:
+- Print: "No uncommitted changes in tracked files."
+- STOP
+
+**Step 4: Ask what to stage**
+
+```
+AskUserQuestion(
+  header: "Stage",
+  question: "Which files to commit?",
+  options: [
+    { label: "Tracked files", description: "Only files listed in ## Files that have changes" },
+    { label: "Let me pick", description: "I'll tell you which files" }
+  ],
+  multiSelect: false
+)
+```
+
+**If "Tracked files":** stage all changed files from ## Files.
+**If "Let me pick":** wait for user input, stage only those files.
+
+Run `git add` for the selected files. Do NOT use `git add -A` or `git add .`.
+
+**Step 5: Generate commit message**
+
+**Prefix** — infer from log entries and file types:
+- `fix` if log contains: fix, bug, broken, patch, repair, resolve
+- `feat` if log contains: add, create, implement, new, feature
+- `refactor` if log contains: refactor, move, rename, extract, reorganize
+- `test` if log contains: test
+- `docs` if only .md files changed
+- `chore` if only config/tooling files changed
+- `style` if log contains: style, css, theme, layout
+- fallback: `feat`
+
+**Scope** — infer from file paths:
+- If spec exists: use spec filename slug (e.g. `auth-refactor` from `auth-refactor.md`)
+- Else if all files share a common parent dir: use that dir name
+- Else: use first meaningful directory from ## Files
+- Keep scope short (1-2 words, no path separators)
+
+**Message** — from progress file line 1:
+- Take the work name, lowercase it
+- Remove "Progress for" prefix and date suffix
+- Keep it under 50 chars total (with prefix and scope)
+
+**Body** — from last 5 log entries:
+- Extract the description part (after the timestamp and scope)
+- Format as bullet points with `-`
+- NEVER add Co-Authored-By lines
+- NEVER add AI attribution or generated-by footers
+- NEVER add any trailer lines
+- Body is ONLY the bullet points from the log
+
+Full format:
+```
+{prefix}({scope}): {message}
+
+{body bullet points}
+```
+
+**Step 6: Preview and confirm**
+
+Print the full draft commit message in a code block.
+Print the list of files that will be committed.
+
+```
+AskUserQuestion(
+  header: "Commit",
+  question: "How does this look?",
+  options: [
+    { label: "Commit as-is", description: "Use this exact message" },
+    { label: "Edit", description: "I'll adjust the message" }
+  ],
+  multiSelect: false
+)
+```
+
+**If "Edit":** wait for user to provide corrected message, use that instead.
+**If "Commit as-is":** proceed with the generated message.
+
+**Step 7: Commit**
+
+Run `git commit` with the final message. Use HEREDOC format:
+```bash
+git commit -m "$(cat <<'EOF'
+{final message here — NO Co-Authored-By, NO trailers}
+EOF
+)"
+```
+
+IMPORTANT: The commit message must contain ONLY the prefix/scope/message and body bullets. Nothing else. No signatures, no attribution, no footers.
+
+**Step 8: Log the commit**
+
+Get the short hash with `git rev-parse --short HEAD`.
+Add to progress log: `- [x] ({YYYY-MM-DD HH:MM}) (commit) {short_hash}: {prefix}({scope}): {message}`
+
+Print:
+```
+Committed: {short_hash}
+{prefix}({scope}): {message}
+```
+
+STOP.
+
+</process>

package/dist/templates/commands/done.md

@@ -0,0 +1,46 @@
+---
+name: workerc:done
+description: Mark current session progress as complete and unclaim
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+---
+
+<objective>
+Mark the current session's progress file as complete. Unclaim it so it becomes a historical record.
+</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: Pre-done suggestions**
+
+Check progress log and git status:
+- If spec exists (line 3, not "None") and no `(review)` log entry: print "Tip: run /workerc:review first to verify spec coverage."
+- If no `(commit)` log entry and tracked files have uncommitted changes: print "Tip: run /workerc:commit first to commit your changes."
+- Continue anyway — these are suggestions, not blocks.
+
+**Step 3: Mark complete**
+
+- Update line 1: append " [DONE]" to the description
+- Update line 2: change session ID to empty `<!-- session:  -->`
+- Add final log entry: `- [x] ({YYYY-MM-DD HH:MM}) (done) Session complete`
+
+**Step 4: Confirm**
+
+Print:
+```
+Complete: {filename}
+Session unclaimed. This is now a historical record.
+```
+
+STOP.
+
+</process>