@scriptgun/workerc 0.1.0

package/dist/templates/commands/handoff.md

@@ -0,0 +1,81 @@
+---
+name: workerc:handoff
+description: Pause work and write handoff notes for the next session
+allowed-tools:
+  - Read
+  - Edit
+  - Glob
+  - AskUserQuestion
+---
+
+<objective>
+Pause the current session with structured handoff notes so the next session can resume effectively.
+Different from /workerc:done — this is "paused", not "finished".
+</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: Suggest commit if uncommitted changes**
+
+If no `(commit)` log entry and tracked files have uncommitted changes:
+- Print: "Tip: run /workerc:commit first to commit your work-in-progress."
+- Continue anyway — this is a suggestion, not a block.
+
+**Step 3: Gather handoff info**
+
+Ask user:
+```
+AskUserQuestion(
+  header: "Handoff",
+  question: "Any notes for the next session? (blockers, gotchas, what's next)",
+  options: [
+    { label: "Auto-generate", description: "Summarize from progress log and files" },
+    { label: "I'll write notes", description: "I'll describe what to hand off" }
+  ],
+  multiSelect: false
+)
+```
+
+**If "Auto-generate":**
+- Read the progress file's ## Log and ## Files
+- Read the spec if one exists (line 3)
+- Summarize: what was done (from log), what's left (from spec scope minus done items), any blockers apparent from log
+
+**If "I'll write notes":**
+- Wait for user input, use that as the handoff content
+
+**Step 4: Write handoff to progress file**
+
+Append to the progress file (before ## Files):
+```
+## Handoff
+**Status:** Paused on {YYYY-MM-DD HH:MM}
+**Done so far:** {1-2 sentence summary of completed work}
+**Next steps:** {what to do next}
+**Blockers:** {any blockers, or "None"}
+**Notes:** {user notes or auto-generated context}
+```
+
+Add log entry: `- [ ] ({YYYY-MM-DD HH:MM}) (handoff) Session paused`
+
+**Step 5: Unclaim session**
+
+Update line 2: change session ID to empty `<!-- session:  -->`
+
+**Step 6: Confirm**
+
+Print:
+```
+Paused: {filename}
+Session unclaimed. Run /workerc:resume to pick this back up.
+```
+
+STOP.
+
+</process>

package/dist/templates/commands/list.md

@@ -0,0 +1,32 @@
+---
+name: workerc:list
+description: List all progress files with status
+allowed-tools:
+  - Read
+  - Glob
+---
+
+<objective>
+List all progress files with their status.
+</objective>
+
+<process>
+
+**Step 1: Read all progress files**
+
+Read all `.claude/progress/*.md` files.
+
+**Step 2: Display**
+
+For each file, print one line (check in this order):
+- `[DONE] {filename}: {line 1}` — if line 1 contains "[DONE]"
+- `[ABORTED] {filename}: {line 1}` — if line 1 contains "[ABORTED]"
+- `[ACTIVE] {filename}: {line 1}` — if line 2 has a non-empty session ID (not "pending")
+- `[PAUSED] {filename}: {line 1}` — if file has a `## Handoff` section
+- `[FREE] {filename}: {line 1}` — if line 2 has empty session, "pending", or no session tag
+
+Print summary: "X active, Y paused, Z free, W done, V aborted"
+
+STOP.
+
+</process>

package/dist/templates/commands/new.md

@@ -0,0 +1,108 @@
+---
+name: workerc:new
+description: Start a new work session with progress file and optional spec
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Start a NEW work session. Always creates a fresh progress file.
+The hook auto-claims "pending" progress files on first source file edit.
+</objective>
+
+<process>
+
+**Step 1: Spec question**
+
+Ask user:
+```
+AskUserQuestion(
+  header: "Spec",
+  question: "Do you have a written spec for this work?",
+  options: [
+    { label: "Yes, I'll give the path", description: "Link existing spec file" },
+    { label: "No, create one", description: "I'll describe what I'm building" },
+    { label: "No spec needed", description: "Skip straight to work" }
+  ],
+  multiSelect: false
+)
+```
+
+**If "Yes, I'll give the path":**
+- Ask for the path
+- Validate file exists
+- Store path as SPEC_PATH
+
+**If "No, create one":**
+- Ask: "What are you building?" and "What's in scope? What's out?" in a single AskUserQuestion with 2 questions
+- Write spec to `.claude/specs/{slug}.md`:
+  ```
+  # {Title}
+  ## Goal
+  {user's description}
+  ## Scope
+  - In: {in scope items}
+  - Out: {out of scope items}
+  ## Decisions
+  ## Discovered
+  ## Rejected
+  ```
+- Store path as SPEC_PATH
+
+**If "No spec needed":**
+- SPEC_PATH = "None"
+
+**Step 2: Create progress file**
+
+Ask user:
+```
+AskUserQuestion(
+  header: "Name",
+  question: "Short name for this work? (used for filename, e.g. 'auth-refactor')",
+  options: [
+    { label: "Suggest from spec", description: "Auto-generate from spec/description" }
+  ],
+  multiSelect: false
+)
+```
+
+Generate slug from name (lowercase, hyphens, max 40 chars).
+
+If `.claude/progress/{slug}.md` already exists, append `-2` (or `-3`, etc.) to make it unique.
+
+Write `.claude/progress/{slug}.md`:
+```
+Progress for {name} created on {YYYY-MM-DD}
+<!-- session: pending -->
+<!-- spec: {SPEC_PATH or None} -->
+
+## Log
+
+## Files
+```
+
+The hook will auto-claim this with the real session ID on the first source file edit.
+
+**Step 3: Confirm and start**
+
+Print:
+```
+Session started: {name}
+Progress: .claude/progress/{slug}.md
+Spec: {SPEC_PATH or None}
+```
+
+**If a spec exists (SPEC_PATH is not "None"):**
+- Read the spec file
+- Start implementing immediately — the spec IS the instructions
+- Do NOT ask "what do you want to do?"
+
+**If no spec:**
+- STOP and wait for user's next message with instructions
+
+</process>

package/dist/templates/commands/resume.md

@@ -0,0 +1,64 @@
+---
+name: workerc:resume
+description: Resume an existing work session by claiming an unclaimed progress file
+allowed-tools:
+  - Read
+  - Edit
+  - Glob
+  - AskUserQuestion
+---
+
+<objective>
+Resume an existing work session. Finds unclaimed/pending progress files and lets the user pick one.
+If none found, tells user to run /workerc:new instead.
+</objective>
+
+<process>
+
+**Step 1: Find resumable progress files**
+
+Read all `.claude/progress/*.md` files. Collect ones where:
+- Line 1 does NOT contain "[DONE]" or "[ABORTED]"
+- Line 2 has `<!-- session: pending -->` or `<!-- session:  -->` or no session tag
+
+If none found:
+- Print: "No unclaimed progress files found. Run /workerc:new to start fresh."
+- STOP
+
+**Step 2: Let user pick**
+
+If only 1 unclaimed: skip the question, pick it automatically.
+
+If multiple:
+```
+AskUserQuestion(
+  header: "Resume",
+  question: "Which one do you want to resume?",
+  options: [list names from line 1],
+  multiSelect: false
+)
+```
+
+**Step 3: Claim and resume**
+
+Set line 2 of chosen file to `<!-- session: pending -->` (hook auto-claims on first edit).
+
+Print:
+```
+Resuming: {line 1}
+Progress: .claude/progress/{filename}
+```
+
+Print the last 5 log entries.
+
+If the file has a `## Handoff` section, print it in full — this is the previous session's context.
+
+If it has a spec (line 3, not "None"):
+- Read the spec file
+- Re-read files listed in ## Files section
+- Resume implementing — do NOT ask what to do
+
+If no spec:
+- STOP and wait for user's next message with instructions
+
+</process>

package/dist/templates/commands/review.md

@@ -0,0 +1,86 @@
+---
+name: workerc:review
+description: Review work against spec before marking done
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+---
+
+<objective>
+Self-check: compare what was built against the spec. Reports coverage, does NOT auto-fix.
+Run this before /workerc:done to catch gaps.
+</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 for spec**
+
+Read line 3 for spec path.
+
+If spec is "None" or missing:
+- Print: "No spec linked. Showing work summary instead."
+- Read all files listed in ## Files section
+- Print a summary of what was built (1 line per file: filename + what changed)
+- STOP
+
+**Step 3: Read spec and progress**
+
+Read the spec file fully.
+Read the progress file fully.
+
+**Step 4: Extract scope items**
+
+From the spec's `## Scope` section (or `## Goal` if no Scope), extract each item.
+Items with ~~strikethrough~~ = done in spec.
+
+**Step 5: Verify each scope item**
+
+For each scope item:
+- Check if it appears done in the spec (strikethrough)
+- Check if related work appears in the progress ## Log
+- Read relevant files from ## Files to verify implementation exists
+
+**Step 6: Print checklist**
+
+Print:
+```
+## Review: {progress filename}
+Spec: {spec path}
+
+| Status | Scope Item |
+|--------|-----------|
+| done | {item that's verified} |
+| missing | {item with no evidence of implementation} |
+| partial | {item with some but incomplete evidence} |
+
+Summary: X/Y scope items done, Z missing, W partial
+```
+
+If any items are "missing" or "partial":
+- Print: "Run /workerc:done only after addressing gaps — or update spec to descope."
+
+If all done:
+- Print: "All scope items covered. Safe to run /workerc:done."
+
+**Step 7: Check spec completeness**
+
+Check if the spec has content in these sections:
+- `## Decisions` — empty?
+- `## Discovered` — empty?
+- `## Rejected` — empty?
+
+If ALL three are empty:
+- Print: "Spec hygiene: Decisions, Discovered, and Rejected are all empty. Consider documenting any choices made or things learned during this work."
+
+If only some are empty, skip — not every session has rejections or discoveries.
+
+STOP.
+
+</process>

package/dist/templates/commands/scope.md

@@ -0,0 +1,74 @@
+---
+name: workerc:scope
+description: Update spec scope — add, remove, or mark items done
+allowed-tools:
+  - Read
+  - Edit
+  - Glob
+  - AskUserQuestion
+---
+
+<objective>
+Structured way to update the spec's scope mid-session. Keeps scope changes logged in progress.
+</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 for spec**
+
+Read line 3 for spec path.
+
+If spec is "None" or missing:
+- Print: "No spec linked to this session. Nothing to update."
+- STOP
+
+**Step 3: Read and show current scope**
+
+Read the spec file. Print the current `## Scope` section.
+
+**Step 4: Ask what to do**
+
+```
+AskUserQuestion(
+  header: "Scope",
+  question: "What do you want to change?",
+  options: [
+    { label: "Add item", description: "Add something new to scope" },
+    { label: "Remove item", description: "Descope something" },
+    { label: "Mark done", description: "Strikethrough a completed item" }
+  ],
+  multiSelect: false
+)
+```
+
+**If "Add item":**
+- Ask: "What should be added to scope?"
+- Wait for user input
+- Append `- In: {user input}` to the `## Scope` section in the spec
+- Log: `- [x] ({YYYY-MM-DD HH:MM}) (scope) Added to scope: {item}`
+
+**If "Remove item":**
+- Collect current "In:" items from spec
+- Use AskUserQuestion with those items as options (label = item text, description = "Remove this from scope")
+- Remove the chosen line from spec
+- Log: `- [x] ({YYYY-MM-DD HH:MM}) (scope) Descoped: {item}`
+
+**If "Mark done":**
+- Collect current "In:" items that aren't struck through
+- Use AskUserQuestion with those items as options (label = item text, description = "Mark as completed")
+- Wrap chosen item text in ~~strikethrough~~
+- Log: `- [x] ({YYYY-MM-DD HH:MM}) (scope) Completed: {item}`
+
+**Step 5: Confirm**
+
+Print updated `## Scope` section.
+
+STOP.
+
+</process>

package/dist/templates/commands/status.md

@@ -0,0 +1,30 @@
+---
+name: workerc:status
+description: Show current session progress
+allowed-tools:
+  - Read
+  - Glob
+---
+
+<objective>
+Show the current session's progress file. No analysis, no suggestions.
+</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. Run /workerc:new to start." and STOP.
+
+**Step 2: Display**
+
+Print the full progress file contents.
+
+If there's a spec link (line 3, not "None"):
+- Print "Spec: {path}"
+
+STOP.
+
+</process>

package/dist/templates/hooks/post-edit-lint.sh.tmpl

@@ -0,0 +1,27 @@
+#!/bin/bash
+# Post-edit hook: Lint check
+# Always exit 0, use JSON {"decision":"block","reason":"..."} to report errors
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+[ -z "$FILE" ] && exit 0
+[ ! -f "$FILE" ] && exit 0
+
+# Only check files the linter cares about
+echo "$FILE" | grep -qE '\.({{{EXTENSIONS}}})$' || exit 0
+
+# Skip .claude directory entirely
+echo "$FILE" | grep -qE '/\.claude/' && exit 0
+
+LINT_OUTPUT=$({{{LINT_COMMAND}}} "$FILE" 2>&1)
+if [ $? -ne 0 ]; then
+	jq -n --arg reason "Lint issues in $FILE:
+$LINT_OUTPUT
+
+FIX THESE BEFORE RESPONDING." '{"decision":"block","reason":$reason}'
+	exit 0
+fi
+
+echo '{}'
+exit 0

package/dist/templates/hooks/post-edit-tracker.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+# Post-edit hook: Tracker enforcement (session-scoped)
+# Always exit 0, use JSON {"decision":"block","reason":"..."} to report errors
+#
+# Logic:
+# 1. Find tracker claimed by this session → check 15s freshness
+# 2. Find "pending" tracker (from /workerc:new) → auto-claim it with real session ID
+# 3. No tracker found → block, tell agent to create/claim one
+#
+# Subagents share parent session_id — parent's tracker covers them
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
+
+[ -z "$FILE" ] && exit 0
+[ ! -f "$FILE" ] && exit 0
+[ -z "$SESSION_ID" ] && exit 0
+
+# Skip entire .claude directory
+echo "$FILE" | grep -qE '/\.claude/' && exit 0
+
+TRACKER_DIR="$(cd "$(dirname "$0")/../progress" 2>/dev/null && pwd)"
+
+# No progress dir = block
+if [ -z "$TRACKER_DIR" ] || [ ! -d "$TRACKER_DIR" ]; then
+	jq -n --arg reason "No .claude/progress/ directory found. Run /workerc:new to create one." '{"decision":"block","reason":$reason}'
+	exit 0
+fi
+
+# Scan all trackers
+NOW=$(date +%s)
+MY_TRACKER=""
+MY_TRACKER_AGE=""
+PENDING_TRACKER=""
+UNCLAIMED=""
+
+for t in "$TRACKER_DIR"/*.md; do
+	[ -f "$t" ] || continue
+	LINE1=$(head -1 "$t")
+
+	# Skip done/aborted trackers
+	echo "$LINE1" | grep -q "\[DONE\]" && continue
+	echo "$LINE1" | grep -q "\[ABORTED\]" && continue
+
+	LINE2=$(sed -n '2p' "$t")
+
+	# Already claimed by this session
+	if echo "$LINE2" | grep -q "<!-- session: $SESSION_ID -->"; then
+		MY_TRACKER="$t"
+		MOD=$(stat -f %m "$t" 2>/dev/null || stat -c %Y "$t" 2>/dev/null)
+		MY_TRACKER_AGE=$((NOW - MOD))
+		break
+	fi
+
+	# Pending tracker (from /workerc:new)
+	if echo "$LINE2" | grep -q "<!-- session: pending -->"; then
+		if [ -z "$PENDING_TRACKER" ]; then
+			PENDING_TRACKER="$t"
+		else
+			# Multiple pending — can't auto-claim safely
+			PENDING_TRACKER="AMBIGUOUS"
+		fi
+		continue
+	fi
+
+	# Unclaimed (empty session or no session tag)
+	if echo "$LINE2" | grep -q "<!-- session:  -->" || ! echo "$LINE2" | grep -q "<!-- session:"; then
+		UNCLAIMED="$UNCLAIMED
+  $(basename "$t"): $LINE1"
+	fi
+done
+
+# Case 1: Already claimed by this session — check freshness + auto-track files
+if [ -n "$MY_TRACKER" ]; then
+	# Auto-append edited file to ## Files if not already listed
+	PROJECT_DIR="$(cd "$(dirname "$0")/../.." 2>/dev/null && pwd)"
+	REL_FILE="${FILE#$PROJECT_DIR/}"
+	if ! grep -qF "$REL_FILE" "$MY_TRACKER" 2>/dev/null; then
+		echo "- $REL_FILE" >> "$MY_TRACKER"
+	fi
+
+	if [ "$MY_TRACKER_AGE" -le 15 ]; then
+		echo '{}'
+		exit 0
+	fi
+	jq -n --arg reason "Tracker $(basename "$MY_TRACKER") not updated in ${MY_TRACKER_AGE}s. UPDATE your tracker before continuing." '{"decision":"block","reason":$reason}'
+	exit 0
+fi
+
+# Case 2: Pending tracker exists — auto-claim it + track first file
+if [ "$PENDING_TRACKER" = "AMBIGUOUS" ]; then
+	jq -n --arg reason "Multiple pending progress files found. Claim one manually: set line 2 to <!-- session: $SESSION_ID -->" '{"decision":"block","reason":$reason}'
+	exit 0
+fi
+if [ -n "$PENDING_TRACKER" ]; then
+	# Replace "pending" with real session ID using sed
+	sed -i '' "s/<!-- session: pending -->/<!-- session: $SESSION_ID -->/" "$PENDING_TRACKER" 2>/dev/null || \
+	sed -i "s/<!-- session: pending -->/<!-- session: $SESSION_ID -->/" "$PENDING_TRACKER" 2>/dev/null
+	# Track the first edited file
+	PROJECT_DIR="$(cd "$(dirname "$0")/../.." 2>/dev/null && pwd)"
+	REL_FILE="${FILE#$PROJECT_DIR/}"
+	if ! grep -qF "$REL_FILE" "$PENDING_TRACKER" 2>/dev/null; then
+		echo "- $REL_FILE" >> "$PENDING_TRACKER"
+	fi
+	# Touch it so freshness check passes
+	touch "$PENDING_TRACKER"
+	echo '{}'
+	exit 0
+fi
+
+# Case 3: No tracker — block
+REASON="No progress file for this session. Run /workerc:new to set up."
+if [ -n "$UNCLAIMED" ]; then
+	REASON="$REASON
+Unclaimed trackers you could claim:$UNCLAIMED
+
+To claim: set line 2 to <!-- session: $SESSION_ID -->"
+fi
+jq -n --arg reason "$REASON" '{"decision":"block","reason":$reason}'
+exit 0

package/dist/templates/hooks/post-edit-types.sh.tmpl

@@ -0,0 +1,25 @@
+#!/bin/bash
+# Post-edit hook: Type check
+# Always exit 0, use JSON {"decision":"block","reason":"..."} to report errors
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+[ -z "$FILE" ] && exit 0
+[ ! -f "$FILE" ] && exit 0
+echo "$FILE" | grep -qE '\.({{{EXTENSIONS}}})$' || exit 0
+
+# Skip .claude directory entirely
+echo "$FILE" | grep -qE '/\.claude/' && exit 0
+
+TSC_OUTPUT=$({{{TYPE_COMMAND}}} 2>&1 | head -20)
+if [ -n "$TSC_OUTPUT" ]; then
+	jq -n --arg reason "TypeScript errors:
+$TSC_OUTPUT
+
+FIX THESE BEFORE RESPONDING." '{"decision":"block","reason":$reason}'
+	exit 0
+fi
+
+echo '{}'
+exit 0