cc-discipline 2.5.1 → 2.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-discipline",
-  "version": "2.5.1",
+  "version": "2.6.1",
   "description": "Discipline framework for Claude Code — rules, hooks, and agents that keep AI on track",
   "bin": {
     "cc-discipline": "bin/cli.sh"

package/templates/.claude/hooks/action-counter.sh

@@ -27,9 +27,31 @@ JSONEOF
     exit 0
 fi
 
+# Progress.md staleness check: every 50 actions, check if progress.md was updated recently
+if [ $((COUNT % 50)) -eq 0 ]; then
+    CWD=$(echo "$INPUT" | jq -r '.cwd // ""' 2>/dev/null)
+    PROGRESS_FILE=""
+    [ -f "$CWD/docs/progress.md" ] && PROGRESS_FILE="$CWD/docs/progress.md"
+    [ -z "$PROGRESS_FILE" ] && [ -f "docs/progress.md" ] && PROGRESS_FILE="docs/progress.md"
+    if [ -n "$PROGRESS_FILE" ]; then
+        # Check if file was modified in the last 30 minutes
+        if command -v stat &>/dev/null; then
+            FILE_MOD=$(stat -f %m "$PROGRESS_FILE" 2>/dev/null || stat -c %Y "$PROGRESS_FILE" 2>/dev/null)
+            NOW=$(date +%s)
+            if [ -n "$FILE_MOD" ] && [ $((NOW - FILE_MOD)) -gt 1800 ]; then
+                STALE_MIN=$(( (NOW - FILE_MOD) / 60 ))
+                cat <<JSONEOF
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"PROGRESS STALE (${STALE_MIN}min since last update): docs/progress.md has not been updated in over 30 minutes. If compact happens now, everything you've done since the last update is LOST. Update the Working Context section NOW: key commands, current workflow, tools developed, environment state, gotchas. This takes 2 minutes and saves hours of re-discovery. Do it before your next task action."}}
+JSONEOF
+                exit 0
+            fi
+        fi
+    fi
+fi
+
 if [ $((COUNT % THRESHOLD)) -eq 0 ]; then
     cat <<JSONEOF
-{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"AUTO SELF-CHECK (#${COUNT} actions): Pause and verify: (1) Am I still serving the user's original request, or have I drifted? (2) Am I fixing the same thing repeatedly (mole-whacking)? (3) Have I claimed anything as 'verified' without actually running it? (4) Am I making changes the user didn't ask for? (5) Have I updated docs/progress.md with current status and completed milestones? If progress.md is stale, update it NOW before continuing. (6) Plan fidelity: if executing a plan, compare what the current step asked for vs what I actually delivered — am I cutting corners or simplifying the intent? Check the acceptance criteria. (7) Quality check: am I lowering quality to avoid difficulty? If I'm about to skip a verification, simplify an approach, or take a shortcut — STOP and ask the user instead of silently pushing forward. (8) Deferred work check: did I break a task into subtasks and skip some as 'low ROI' or 'can do later'? If yes, the analysis context is fresh NOW — finish them before moving on, or record enough detail in progress.md for a future session. (9) Friction check: did any hook/rule get in the way or miss something since last check? If so, note it in one line for /retro later. If ANY answer is concerning, STOP and report to the user before continuing."}}
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"AUTO SELF-CHECK (#${COUNT} actions): Pause and verify: (1) Am I still serving the user's original request, or have I drifted? (2) Am I fixing the same thing repeatedly (mole-whacking)? (3) Have I claimed anything as 'verified' without actually running it? (4) Am I making changes the user didn't ask for? (5) Is docs/progress.md up to date — especially the Working Context section (key commands, current workflow, tools developed, environment state, gotchas)? If a compact happened right now, could a fresh Claude resume from progress.md alone? If not, update it NOW. (6) Plan fidelity: if executing a plan, compare what the current step asked for vs what I actually delivered — am I cutting corners or simplifying the intent? Check the acceptance criteria. (7) Quality check: am I lowering quality to avoid difficulty? If I'm about to skip a verification, simplify an approach, or take a shortcut — STOP and ask the user instead of silently pushing forward. (8) Deferred work check: did I break a task into subtasks and skip some as 'low ROI' or 'can do later'? If yes, the analysis context is fresh NOW — finish them before moving on, or record enough detail in progress.md for a future session. (9) Friction check: did any hook/rule get in the way or miss something since last check? If so, note it in one line for /retro later. If ANY answer is concerning, STOP and report to the user before continuing."}}
 JSONEOF
 fi
 

package/templates/.claude/rules/03-context-mgmt.md

@@ -5,9 +5,13 @@
 - During debugging → update `docs/debug-log.md` (hypotheses, evidence, elimination results)
 - When making architectural decisions → record the decision and reasoning in progress.md
 
-### Research Isolation
-- When extensive code reading is needed → use subagents, don't read large volumes of files in the main conversation
-- After subagent returns a summary, make decisions in the main conversation based on the summary
+### Parallel Execution
+- **Don't do everything single-threaded.** When a task has independent parts, use subagents or tasks to work on them in parallel. Examples:
+  - Investigating 3 debug hypotheses → spawn 3 agents, each verifies one
+  - Researching multiple files/modules → one agent per area, summarize results
+  - Independent subtasks in a plan → parallel agents for non-dependent steps
+- **Keep the main conversation for decisions, not research.** Subagents do the reading and exploring; the main conversation synthesizes and decides.
+- **When to parallelize:** if two subtasks don't depend on each other's output, they should run concurrently, not sequentially.
 
 ### Compact Strategy
 - Do NOT proactively suggest compacting or warn about "context running low". The system will auto-compact when context hits 0% — there is no advance warning, and you cannot see the percentage. With 200K-1M context, most sessions never hit the limit. If you feel the urge to say "this session is getting long", that is anxiety, not a technical problem. Stop worrying about context and focus on the work.

package/templates/.claude/skills/commit/SKILL.md

@@ -15,7 +15,7 @@ Skip this step for projects with no configured test command.
 
 Check each in order (simple changes may skip):
 
-**docs/progress.md** — Does this change constitute a milestone or significant progress? If so, append a record.
+**docs/progress.md** — Does this change constitute a milestone or significant progress? If so, append a record. Also check the "Working Context" section: are Key Commands, Current Workflow, Tools & Scripts, Environment State, and Gotchas up to date? These are your lifeline after compact — if they're stale, a post-compact Claude starts from scratch.
 
 **docs/debug-log.md** — Are there debug sessions that need to be closed or updated?
 

package/templates/.claude/skills/self-check/SKILL.md

@@ -41,9 +41,23 @@ Pause and honestly answer every question below. Do NOT skip any. Do NOT rational
 ## 5. Is progress recorded?
 
 - When was `docs/progress.md` last updated?
-- Have I completed any milestones or made key decisions since the last update?
-- If yes: **update docs/progress.md NOW** with current status, completed items, and next steps.
-- This is critical for context survival across compacts and sessions.
+- If a compact happened RIGHT NOW, could a fresh Claude resume from progress.md alone?
+
+### 5a. Working Context (check each):
+- **Key Commands** — are all build/test/deploy commands listed? Not "run tests" but the exact command with flags and paths.
+- **Current Workflow** — is the step-by-step process documented? e.g., "1. edit schema → 2. run migrate → 3. run tests" with exact commands.
+- **Tools & Scripts** — any helpers or scripts developed this session? Include file path and what it does.
+- **Environment State** — what's running, what ports, what branch? e.g., "Docker on :5432, branch feature/auth"
+- **Gotchas** — any traps or workarounds discovered? e.g., "pytest must run from /src not root"
+
+### 5b. Milestones (check each completed milestone has):
+- **What** — what was accomplished (2-3 sentences, not one-liners)
+- **How** — approach taken, key files changed, commands used
+- **Why this approach** — why this way, what alternatives were rejected
+- **Gotchas** — what went wrong or was surprising
+- **Verification** — how it was confirmed working (test output, manual check)
+
+If ANY of the above are stale, empty, or one-liner lazy: **update docs/progress.md NOW before continuing.** This takes 2 minutes and saves hours of re-discovery after compact.
 
 ## 6. Status report
 

package/templates/.claude/skills/think/SKILL.md

@@ -50,7 +50,8 @@ After the user answers (or if you skipped Step 2), propose **2-3 approaches**:
 - Cons: ...
 - Steps:
   1. [step] — done when: [acceptance criteria]
-  2. [step] — done when: [acceptance criteria]
+  2. [step] — done when: [acceptance criteria] (parallel with 1)
+  3. [step] — done when: [acceptance criteria] (depends on 1+2)
 
 **Approach B: [name]**
 - How: [1-2 sentences]
@@ -58,7 +59,8 @@ After the user answers (or if you skipped Step 2), propose **2-3 approaches**:
 - Cons: ...
 - Steps:
   1. [step] — done when: [acceptance criteria]
-  2. [step] — done when: [acceptance criteria]
+  2. [step] — done when: [acceptance criteria] (parallel with 1)
+  3. [step] — done when: [acceptance criteria] (depends on 1+2)
 
 **Recommendation: [A/B/C] because [reason]**
 ```
@@ -71,6 +73,7 @@ Rules:
 - Flag risks or unknowns you've spotted
 - **Every step must have acceptance criteria** — "done when" must be observable and verifiable, not vague. Bad: "done when refactored". Good: "done when 3 methods extracted, each ≤20 lines, all tests pass"
 - **Simplicity bias** — If a simple approach meets all requirements, list it first and recommend it. Do NOT lead with complex/elegant solutions unless the user signals they want that. "Simple but sufficient" beats "powerful but overkill".
+- **Mark parallel opportunities** — In the steps, annotate which can run concurrently (via subagents/tasks) and which have dependencies. Don't default to sequential when parallel is possible.
 
 ## Step 4: Self-review
 

package/templates/docs/progress.md

@@ -14,9 +14,52 @@
 
 ---
 
+## Working Context
+
+<!-- Claude: THIS SECTION IS CRITICAL. After compact, this is all you have.
+     Update this continuously, not as a last-minute save.
+     Everything here should let a post-compact Claude resume at full speed. -->
+
+### Key Commands
+<!-- Build, test, deploy, env setup — anything you'd need to re-run -->
+
+### Current Workflow
+<!-- Step-by-step: what process are you following right now?
+     e.g., "1. Edit schema → 2. Run migrate → 3. Run tests → 4. Check API"
+     Include the exact commands, flags, paths. -->
+
+### Tools & Scripts Developed
+<!-- Any helper scripts, one-liners, or tools created this session.
+     Include the file path and what it does. These are easy to forget. -->
+
+### Environment State
+<!-- What's running? What's configured? What ports? What branches?
+     e.g., "Docker compose up on port 5432, feature/auth branch checked out" -->
+
+### Gotchas Discovered
+<!-- Things that bit you this session. Workarounds found. Traps to avoid.
+     e.g., "pytest must be run from /src not root", "API returns 200 on error" -->
+
+---
+
 ## Milestones
 
-<!-- Claude: append a record below after completing each milestone -->
+<!-- Claude: append a record below after completing each milestone.
+     DON'T just write one sentence. Each milestone should capture enough
+     detail that a future session can learn from it, not just know it happened.
+     Use the template below. -->
+
+<!-- TEMPLATE (copy and fill for each milestone):
+
+### [date] — [milestone title]
+
+**What**: [what was accomplished, 2-3 sentences]
+**How**: [approach taken, key files changed, commands used]
+**Why this approach**: [why this way and not another — rejected alternatives]
+**Gotchas**: [what went wrong, what was surprising, workarounds]
+**Verification**: [how we confirmed it works — test output, manual check]
+
+-->
 
 ---