Move verbose checklist from hook reason into SKILL.md system context

SKILL.md

@@ -6,7 +6,7 @@ description: |
   parseable done signal in its final response. Provides deterministic machine
   detection for true completion.
 author: blader
-version: 2.1.0
+version: 2.2.0
 ---
 
 # Taskmaster
@@ -21,19 +21,76 @@ completion review cycle.
 1. **Agent tries to stop** — the stop hook fires every time.
 2. **Hook scans transcript** for a parseable token:
    `TASKMASTER_DONE::<session_id>`
-3. **Token missing** — hook blocks stop and injects a checklist plus the exact
-   token to emit when truly done.
+3. **Token missing** — hook blocks stop with a brief trigger message.
 4. **Token present** — hook allows stop and clears session counter state.
 
+## Completion Checklist
+
+When the stop hook blocks you, execute this checklist before emitting the
+done signal. Do NOT narrate or summarize — just DO the work.
+
+1. **RE-READ THE ORIGINAL USER MESSAGE(S).** List every discrete request or
+   acceptance criterion. For each one, confirm it is fully addressed — not
+   just started, FULLY done. If the user explicitly changed their mind,
+   withdrew a request, or told you to stop or skip something, treat that
+   item as resolved and do NOT continue working on it.
+
+2. **CHECK THE TASK LIST.** Review every task. Any task not marked completed?
+   Do it now — unless the user indicated it is no longer wanted.
+
+3. **CHECK THE PLAN.** Walk through each step — INCLUDING verification steps.
+   Any step skipped or partially done? Finish it — unless the user redirected
+   or deprioritized it. If the plan includes ANY verification steps (builds,
+   tests, lints, type-checks, manual validation, smoke tests, functional
+   tests, or any other form of verification), you MUST actually execute them
+   and see them pass — do not skip them or just claim they pass.
+
+4. **CHECK FOR ERRORS OR INCOMPLETE WORK.** Did anything fail or remain
+   unfinished? Fix it. This applies to ALL types of problems — logic errors,
+   missing functionality, incomplete refactors, broken scripts, configuration
+   issues, or anything else that prevents the work from being fully done.
+
+5. **CHECK FOR LOOSE ENDS.** Any TODO comments, placeholder code, missing
+   tests, untested changes, or follow-ups noted but not acted on?
+
+6. **CHECK FOR BLOCKERS.** If something is blocking you, do NOT give up. You
+   are a world-class engineer with access to a full development environment,
+   a terminal, every tool you need, and all the information on the internet.
+   If it does not violate the laws of physics, it is within your ability to
+   solve it. Try a different approach, read more code, search for examples,
+   re-examine your assumptions. Never declare something a blocker and stop.
+   Solve it.
+
+**User priority:** The user's latest instructions always take priority. If the
+user said to stop, move on, or skip something, respect that — do not force
+completion of work the user no longer wants.
+
+**DO NOT NARRATE — EXECUTE:** If any incomplete work remains, your ONLY job is
+to DO that work right now. Do NOT respond by explaining what the remaining
+tasks are, describing their complexity, listing their dependencies, or
+analyzing how difficult they will be. Do NOT ask the user for permission or
+direction to proceed. Do NOT write summaries of what is left. Just DO the
+work. The user asked you to do it — that IS your direction. Every sentence you
+spend describing remaining work instead of doing it is wasted. Open files,
+write code, run commands, fix bugs. Act.
+
+**HONESTY CHECK:** Before marking anything as "not possible" or "skipped", ask
+yourself: did you actually TRY, or are you rationalizing skipping it because
+it seems hard or inconvenient? "I can't do X" is almost never true — what you
+mean is "I haven't tried X yet." If you haven't attempted something, you don't
+get to claim it's impossible. Attempt it first.
+
 ## Parseable Done Signal
 
-When the work is genuinely complete, the agent must include this exact line
-in its final response (on its own line):
+When the work is genuinely complete, include this exact line in your final
+response (on its own line):
 
 ```text
 TASKMASTER_DONE::<session_id>
 ```
 
+Do NOT emit that done signal early. If any work remains, continue working.
+
 This gives external automation a deterministic completion marker to parse.
 
 ## Configuration

check-completion.sh

@@ -70,9 +70,9 @@ if [ "$MAX" -gt 0 ] && [ "$NEXT" -ge "$MAX" ]; then
 fi
 
 if [ "$HAS_RECENT_ERRORS" = true ]; then
-  PREAMBLE="Recent tool errors were detected. Resolve them before declaring done."
+  PREAMBLE="Recent errors detected — resolve them."
 else
-  PREAMBLE="Stop is blocked until completion is explicitly confirmed."
+  PREAMBLE="Stop blocked."
 fi
 
 if [ "$MAX" -gt 0 ]; then
@@ -81,25 +81,7 @@ else
   LABEL="TASKMASTER (${NEXT})"
 fi
 
-# --- reprompt ---
-REASON="${LABEL}: ${PREAMBLE}
-
-Before stopping, do each of these checks:
-
-1. RE-READ THE ORIGINAL USER MESSAGE(S). List every discrete request or acceptance criterion. For each one, confirm it is fully addressed — not just started, FULLY done. If the user explicitly changed their mind, withdrew a request, or told you to stop or skip something, treat that item as resolved and do NOT continue working on it.
-2. CHECK THE TASK LIST. Review every task. Any task not marked completed? Do it now — unless the user indicated it is no longer wanted.
-3. CHECK THE PLAN. Walk through each step — INCLUDING verification steps. Any step skipped or partially done? Finish it — unless the user redirected or deprioritized it. If the plan includes ANY verification steps (builds, tests, lints, type-checks, manual validation, smoke tests, functional tests, or any other form of verification), you MUST actually execute them and see them pass — do not skip them or just claim they pass.
-4. CHECK FOR ERRORS OR INCOMPLETE WORK. Did anything fail or remain unfinished? Fix it. This applies to ALL types of problems — logic errors, missing functionality, incomplete refactors, broken scripts, configuration issues, or anything else that prevents the work from being fully done.
-5. CHECK FOR LOOSE ENDS. Any TODO comments, placeholder code, missing tests, untested changes, or follow-ups noted but not acted on?
-6. CHECK FOR BLOCKERS. If something is blocking you, do NOT give up. You are a world-class engineer with access to a full development environment, a terminal, every tool you need, and all the information on the internet. If it does not violate the laws of physics, it is within your ability to solve it. Try a different approach, read more code, search for examples, re-examine your assumptions. Never declare something a blocker and stop. Solve it.
-
-IMPORTANT: The user's latest instructions always take priority. If the user said to stop, move on, or skip something, respect that — do not force completion of work the user no longer wants.
-
-HONESTY CHECK: Before marking anything as \"not possible\" or \"skipped\", ask yourself: did you actually TRY, or are you rationalizing skipping it because it seems hard or inconvenient? \"I can't do X\" is almost never true — what you mean is \"I haven't tried X yet.\" If you haven't attempted something, you don't get to claim it's impossible. Attempt it first.
-
-When and only when everything is genuinely 100% done (or explicitly deprioritized by the user), include this exact line in your final response on its own line:
-${DONE_SIGNAL}
-
-Do NOT emit that done signal early. If any work remains, continue working now."
+# --- reprompt (kept minimal — full checklist lives in SKILL.md system context) ---
+REASON="${LABEL}: ${PREAMBLE} Follow the taskmaster completion checklist. Done signal: ${DONE_SIGNAL}"
 
 jq -n --arg reason "$REASON" '{ decision: "block", reason: $reason }'

docs/SPEC.md

@@ -1,7 +1,7 @@
 # Taskmaster
 ## Product & Technical Specification
 
-**Version**: 2.1.0  
+**Version**: 2.2.0
 **Scope**: `taskmaster/hooks/check-completion.sh`, `taskmaster/SKILL.md`
 
 ## 1. Goal
@@ -39,18 +39,28 @@ On each stop event:
 7. Optional safety cap: if `TASKMASTER_MAX > 0` and counter reaches cap,
    allow stop and clear counter file.
 
-### 3.2 Prompt Injection
+### 3.2 Prompt Architecture
 
-When blocking, Taskmaster injects:
+The verbose completion checklist lives in `SKILL.md`, which is loaded as system
+context (invisible to the user in session history). The hook's `reason` field
+is kept minimal — just a label, status, and done signal — so it does not
+pollute the conversation transcript.
+
+When blocking, Taskmaster injects a brief reason:
 
 - `TASKMASTER (N)` or `TASKMASTER (N/MAX)` label.
-- A completion checklist (requests, plan, errors, loose ends, blockers).
-- The exact done line to emit when truly complete.
+- Short status (stop blocked / errors detected).
+- Reference to follow the taskmaster completion checklist.
+- The exact done signal to emit when truly complete.
+
+The full checklist (re-read user messages, check task list, check plan, check
+for errors, check for loose ends, check for blockers, honesty check) is in the
+"Completion Checklist" section of `SKILL.md`.
 
 ### 3.3 Error Signal Hinting
 
 Taskmaster inspects recent transcript lines for `"is_error": true` and adjusts
-preamble text to explicitly call out unresolved errors.
+the brief preamble text to call out unresolved errors.
 
 ## 4. Runtime Interfaces
 

hooks/check-completion.sh

@@ -77,9 +77,9 @@ if [ "$MAX" -gt 0 ] && [ "$NEXT" -ge "$MAX" ]; then
 fi
 
 if [ "$HAS_RECENT_ERRORS" = true ]; then
-  PREAMBLE="Recent tool errors were detected. Resolve them before declaring done."
+  PREAMBLE="Recent errors detected — resolve them."
 else
-  PREAMBLE="Stop is blocked until completion is explicitly confirmed."
+  PREAMBLE="Stop blocked."
 fi
 
 if [ "$MAX" -gt 0 ]; then
@@ -88,27 +88,7 @@ else
   LABEL="TASKMASTER (${NEXT})"
 fi
 
-# --- reprompt ---
-REASON="${LABEL}: ${PREAMBLE}
-
-Before stopping, do each of these checks:
-
-1. RE-READ THE ORIGINAL USER MESSAGE(S). List every discrete request or acceptance criterion. For each one, confirm it is fully addressed — not just started, FULLY done. If the user explicitly changed their mind, withdrew a request, or told you to stop or skip something, treat that item as resolved and do NOT continue working on it.
-2. CHECK THE TASK LIST. Review every task. Any task not marked completed? Do it now — unless the user indicated it is no longer wanted.
-3. CHECK THE PLAN. Walk through each step — INCLUDING verification steps. Any step skipped or partially done? Finish it — unless the user redirected or deprioritized it. If the plan includes ANY verification steps (builds, tests, lints, type-checks, manual validation, smoke tests, functional tests, or any other form of verification), you MUST actually execute them and see them pass — do not skip them or just claim they pass.
-4. CHECK FOR ERRORS OR INCOMPLETE WORK. Did anything fail or remain unfinished? Fix it. This applies to ALL types of problems — logic errors, missing functionality, incomplete refactors, broken scripts, configuration issues, or anything else that prevents the work from being fully done.
-5. CHECK FOR LOOSE ENDS. Any TODO comments, placeholder code, missing tests, untested changes, or follow-ups noted but not acted on?
-6. CHECK FOR BLOCKERS. If something is blocking you, do NOT give up. You are a world-class engineer with access to a full development environment, a terminal, every tool you need, and all the information on the internet. If it does not violate the laws of physics, it is within your ability to solve it. Try a different approach, read more code, search for examples, re-examine your assumptions. Never declare something a blocker and stop. Solve it.
-
-IMPORTANT: The user's latest instructions always take priority. If the user said to stop, move on, or skip something, respect that — do not force completion of work the user no longer wants.
-
-DO NOT NARRATE — EXECUTE: If any incomplete work remains, your ONLY job is to DO that work right now. Do NOT respond by explaining what the remaining tasks are, describing their complexity, listing their dependencies, or analyzing how difficult they will be. Do NOT ask the user for permission or direction to proceed. Do NOT write summaries of what is left. Just DO the work. The user asked you to do it — that IS your direction. Every sentence you spend describing remaining work instead of doing it is wasted. Open files, write code, run commands, fix bugs. Act.
-
-HONESTY CHECK: Before marking anything as \"not possible\" or \"skipped\", ask yourself: did you actually TRY, or are you rationalizing skipping it because it seems hard or inconvenient? \"I can't do X\" is almost never true — what you mean is \"I haven't tried X yet.\" If you haven't attempted something, you don't get to claim it's impossible. Attempt it first.
-
-When and only when everything is genuinely 100% done (or explicitly deprioritized by the user), include this exact line in your final response on its own line:
-${DONE_SIGNAL}
-
-Do NOT emit that done signal early. If any work remains, continue working now."
+# --- reprompt (kept minimal — full checklist lives in SKILL.md system context) ---
+REASON="${LABEL}: ${PREAMBLE} Follow the taskmaster completion checklist. Done signal: ${DONE_SIGNAL}"
 
 jq -n --arg reason "$REASON" '{ decision: "block", reason: $reason }'