@linimin/pi-letscook 0.1.55 → 0.1.56

package/CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - made `/cook` derive a confirmable startup brief from recent discussion before any canonical workflow rewrite, then preserve the confirmed brief in canonical state as advisory intake for later re-grounding
 - removed inline `/cook` arguments from the shipped entry path again so explicit bare `/cook` is the only public command, and fail closed when recent discussion is insufficient or unreliable
+- added a pre-`/cook` ordinary-chat handoff boundary so the primary agent is instructed to stop at `/cook` once a task has matured into completion-workflow scope instead of starting long-running implementation directly in ordinary chat
 
 ## 0.1.54
 

package/README.md

@@ -62,10 +62,13 @@ If you pass inline arguments to `/cook`, it also fails closed and tells you to m
 
 Only explicit `/cook` enters the workflow. Ordinary prompts stay in the main chat and go straight to the primary agent.
 
+If a task has clearly matured into completion-workflow scope, the primary agent should hand you off to `/cook` instead of starting long-running implementation directly in ordinary chat.
+
 Important behavior:
 - `/cook` is the canonical workflow boundary and manual entry point
 - startup, refocus, and next-round routing stay confirm-first; nothing silently starts a workflow
 - explicit slash commands other than `/cook` continue normally in the main chat
+- ordinary main-chat discussion may clarify or propose, but mature long-running implementation should be handed off to `/cook`
 
 ## Typical examples
 

package/extensions/completion/index.ts

@@ -38,6 +38,7 @@ import {
 	buildContextProposalConfirmationLayout as buildExtractedContextProposalConfirmationLayout,
 	buildContextProposalConfirmationSelectItems,
 	buildContextProposalContinuationReason as buildExtractedContextProposalContinuationReason,
+	buildCookHandoffBoundaryReminder as buildExtractedCookHandoffBoundaryReminder,
 	buildEvaluationRoleContextLines as buildExtractedEvaluationRoleContextLines,
 	buildEvaluationRoleReminderText as buildExtractedEvaluationRoleReminderText,
 	buildResumeCapsule as buildExtractedResumeCapsule,
@@ -181,6 +182,10 @@ function completionTestSystemReminderPath(): string | undefined {
 	return asString(process.env.PI_COMPLETION_TEST_SYSTEM_REMINDER_PATH);
 }
 
+function completionTestCookHandoffReminderPath(): string | undefined {
+	return asString(process.env.PI_COMPLETION_TEST_COOK_HANDOFF_REMINDER_PATH);
+}
+
 function maybeWriteTestSnapshot(targetPath: string | undefined, content: string): void {
 	if (!targetPath) return;
 	try {
@@ -225,6 +230,19 @@ function shouldInjectCompletionWorkflowContext(snapshot: CompletionStateSnapshot
 	return hasCompletionRoutingActivation(snapshot) && isCompletionDriverPromptTurn(ctx);
 }
 
+function shouldInjectCookHandoffBoundary(event: { prompt?: string }, ctx: { sessionManager?: any }): boolean {
+	if (roleFromEnv()) return false;
+	if (isCompletionDriverPromptTurn(ctx)) return false;
+	const prompt = typeof event.prompt === "string" ? event.prompt.trim() : "";
+	if (!prompt) return false;
+	if (prompt.startsWith("/")) return false;
+	return true;
+}
+
+function buildCookHandoffBoundaryReminder(): string {
+	return buildExtractedCookHandoffBoundaryReminder();
+}
+
 function buildDoneWorkflowBoundaryReminder(snapshot: CompletionStateSnapshot): string {
 	const missionAnchor = asString(snapshot.state?.mission_anchor) ?? asString(snapshot.plan?.mission_anchor) ?? "(unknown)";
 	const continuationReason = asString(snapshot.state?.continuation_reason) ?? "(unknown)";
@@ -926,7 +944,7 @@ export default function completionExtension(pi: ExtensionAPI) {
 		}
 	});
 
-	pi.on("before_agent_start", async (_event, ctx) => {
+	pi.on("before_agent_start", async (event, ctx) => {
 		const loaded = await loadCompletionDataForReminder(getCtxCwd(ctx));
 		const driverPromptTurn = isCompletionDriverPromptTurn(ctx);
 		if (loaded && driverPromptTurn) {
@@ -934,28 +952,35 @@ export default function completionExtension(pi: ExtensionAPI) {
 			const fingerprint = completionContinuationFingerprint(loaded.snapshot);
 			if (fingerprint) markQueuedDriverPromptInFlight(rootKey, fingerprint);
 		}
-		if (!loaded || !shouldInjectCompletionWorkflowContext(loaded.snapshot, ctx)) return;
-		const additions = isWorkflowDone(loaded.snapshot)
-			? [buildDoneWorkflowBoundaryReminder(loaded.snapshot)]
-			: [composeSystemReminder(loaded.snapshot, loaded.sliceHistory, loaded.stopHistory)];
-		if (!isWorkflowDone(loaded.snapshot)) {
-			const markerText = await readText(loaded.snapshot.files.compactionMarkerPath);
-			let marker: JsonRecord | undefined;
-			if (markerText) {
-				try {
-					const parsed = JSON.parse(markerText);
-					marker = isRecord(parsed) ? parsed : undefined;
-				} catch {
-					marker = undefined;
+		const systemPrompt = getSystemPromptSafe(ctx);
+		if (!systemPrompt) return;
+		if (loaded && shouldInjectCompletionWorkflowContext(loaded.snapshot, ctx)) {
+			const additions = isWorkflowDone(loaded.snapshot)
+				? [buildDoneWorkflowBoundaryReminder(loaded.snapshot)]
+				: [composeSystemReminder(loaded.snapshot, loaded.sliceHistory, loaded.stopHistory)];
+			if (!isWorkflowDone(loaded.snapshot)) {
+				const markerText = await readText(loaded.snapshot.files.compactionMarkerPath);
+				let marker: JsonRecord | undefined;
+				if (markerText) {
+					try {
+						const parsed = JSON.parse(markerText);
+						marker = isRecord(parsed) ? parsed : undefined;
+					} catch {
+						marker = undefined;
+					}
 				}
+				if (marker) additions.push(buildPostCompactionDriverInstructions(loaded.snapshot, marker));
 			}
-			if (marker) additions.push(buildPostCompactionDriverInstructions(loaded.snapshot, marker));
+			maybeWriteTestSnapshot(completionTestSystemReminderPath(), additions.join("\n\n"));
+			return {
+				systemPrompt: `${systemPrompt}\n\n${additions.join("\n\n")}`,
+			};
 		}
-		maybeWriteTestSnapshot(completionTestSystemReminderPath(), additions.join("\n\n"));
-		const systemPrompt = getSystemPromptSafe(ctx);
-		if (!systemPrompt) return;
+		if (!shouldInjectCookHandoffBoundary(event, ctx)) return;
+		const handoffReminder = buildCookHandoffBoundaryReminder();
+		maybeWriteTestSnapshot(completionTestCookHandoffReminderPath(), handoffReminder);
 		return {
-			systemPrompt: `${systemPrompt}\n\n${additions.join("\n\n")}`,
+			systemPrompt: `${systemPrompt}\n\n${handoffReminder}`,
 		};
 	});
 

package/extensions/completion/prompt-surfaces.ts

@@ -24,6 +24,18 @@ export type AdvisoryStartupBrief = {
 	evaluation_profile?: string;
 };
 
+export function buildCookHandoffBoundaryReminder(): string {
+	return [
+		"You are still in ordinary main chat before any explicit /cook workflow entry.",
+		"Use ordinary chat to clarify requirements, discuss tradeoffs, and propose implementation approaches.",
+		"/cook is the only explicit entrypoint into long-running completion workflow.",
+		"When you judge that the task has matured into completion-workflow scope — for example the user has clearly shifted from exploration into implementation intent, you have just produced a concrete plan or proposal whose next step would naturally be implementation, or the task spans multiple files, steps, or verification surfaces — stop short of long-running implementation and tell the user to run /cook.",
+		"At that handoff point, do not begin long-running product implementation in ordinary chat, do not edit tracked product files for that workflow-level task, and do not act as though /cook had already been invoked.",
+		"When handing off, explain that /cook will derive a startup brief from recent discussion and ask for confirmation before workflow start.",
+		"If the task is still ordinary Q&A, lightweight brainstorming, or a tiny one-off fix, continue normally without forcing /cook.",
+	].join(" ");
+}
+
 export function buildContextProposalGoalText(proposal: {
 	mission: string;
 	scope: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linimin/pi-letscook",
-  "version": "0.1.55",
+  "version": "0.1.56",
   "description": "Pi package for long-running completion workflows with canonical .agent state, role-based subagents, continuity, and verification helpers.",
   "license": "MIT",
   "private": false,

package/scripts/release-check.sh

@@ -17,6 +17,7 @@ checks = {
     "README.md": [
         "`/cook` is the explicit workflow boundary for starting, continuing, refocusing, or beginning the next round of long-running repo work.",
         "Only explicit `/cook` enters the workflow. Ordinary prompts stay in the main chat and go straight to the primary agent.",
+        "If a task has clearly matured into completion-workflow scope, the primary agent should hand you off to `/cook` instead of starting long-running implementation directly in ordinary chat.",
         "`/cook` is the canonical workflow boundary and manual entry point",
         "Discuss the concrete repo change in the main chat, then run `/cook`",
         "The confirmed startup brief is also preserved there as advisory intake for later re-grounding.",
@@ -24,10 +25,12 @@ checks = {
     "CHANGELOG.md": [
         "made `/cook` derive a confirmable startup brief from recent discussion before any canonical workflow rewrite, then preserve the confirmed brief in canonical state as advisory intake for later re-grounding",
         "removed inline `/cook` arguments from the shipped entry path again so explicit bare `/cook` is the only public command, and fail closed when recent discussion is insufficient or unreliable",
+        "added a pre-`/cook` ordinary-chat handoff boundary so the primary agent is instructed to stop at `/cook` once a task has matured into completion-workflow scope instead of starting long-running implementation directly in ordinary chat",
     ],
-    "extensions/completion/index.ts": [
-        'description: "/cook workflow: derive a startup brief from recent discussion, then start, continue, refocus, or start the next round from the explicit /cook command"',
-        '"/cook failed closed because recent discussion did not produce a clear execution-ready startup brief with Mission/Scope/Constraints/Acceptance for concrete repo changes. Clarify the concrete repo changes in the main chat and rerun /cook."',
+    "extensions/completion/prompt-surfaces.ts": [
+        '"/cook is the only explicit entrypoint into long-running completion workflow."',
+        '"When you judge that the task has matured into completion-workflow scope',
+        '"If the task is still ordinary Q&A, lightweight brainstorming, or a tiny one-off fix, continue normally without forcing /cook."',
     ],
 }
 

package/scripts/smoke-test.sh

@@ -51,6 +51,7 @@ ROOT="$TMPDIR/repo"
 KICKOFF_PROMPT="$TMPDIR/kickoff-prompt.txt"
 RESUME_PROMPT="$TMPDIR/resume-prompt.txt"
 ORDINARY_SYSTEM_REMINDER="$TMPDIR/ordinary-system-reminder.txt"
+ORDINARY_HANDOFF_REMINDER="$TMPDIR/ordinary-handoff-reminder.txt"
 UNCLEAR_ROUTING_SNAPSHOT="$TMPDIR/active-unclear-routing.json"
 UNCLEAR_CHOOSER_SNAPSHOT="$TMPDIR/unexpected-existing-workflow-chooser.json"
 ORDINARY_AUTO_RESUME_PROMPT="$TMPDIR/ordinary-auto-resume-prompt.txt"
@@ -146,23 +147,29 @@ assert f'- task_type: {expected_task_type}' in kickoff, 'kickoff prompt missing
 assert f'- evaluation_profile: {expected_eval_profile}' in kickoff, 'kickoff prompt missing canonical evaluation_profile'
 PY
 
-rm -f "$ORDINARY_SYSTEM_REMINDER" "$ORDINARY_AUTO_RESUME_PROMPT"
+rm -f "$ORDINARY_SYSTEM_REMINDER" "$ORDINARY_HANDOFF_REMINDER" "$ORDINARY_AUTO_RESUME_PROMPT"
 PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
 PI_COMPLETION_TEST_SYSTEM_REMINDER_PATH="$ORDINARY_SYSTEM_REMINDER" \
+PI_COMPLETION_TEST_COOK_HANDOFF_REMINDER_PATH="$ORDINARY_HANDOFF_REMINDER" \
 PI_COMPLETION_TEST_AUTO_CONTINUE_ON_SESSION_START=1 \
 PI_COMPLETION_TEST_AUTO_CONTINUE_PROMPT_PATH="$ORDINARY_AUTO_RESUME_PROMPT" \
 pi -e "$PKG_ROOT" -p "Summarize the repo briefly." \
   >"$TMPDIR/pi-completion-smoke-ordinary.out" 2>"$TMPDIR/pi-completion-smoke-ordinary.err"
 
-python3 - "$TMPDIR/pi-completion-smoke-ordinary.out" "$TMPDIR/pi-completion-smoke-ordinary.err" "$ORDINARY_SYSTEM_REMINDER" "$ORDINARY_AUTO_RESUME_PROMPT" <<'PY'
+python3 - "$TMPDIR/pi-completion-smoke-ordinary.out" "$TMPDIR/pi-completion-smoke-ordinary.err" "$ORDINARY_SYSTEM_REMINDER" "$ORDINARY_HANDOFF_REMINDER" "$ORDINARY_AUTO_RESUME_PROMPT" <<'PY'
 import sys
 from pathlib import Path
 
 output = Path(sys.argv[1]).read_text() + Path(sys.argv[2]).read_text()
 reminder = Path(sys.argv[3])
-auto_resume = Path(sys.argv[4])
+handoff = Path(sys.argv[4])
+auto_resume = Path(sys.argv[5])
 
 assert not reminder.exists(), 'ordinary non-/cook turn should not inject completion reminder solely from canonical state'
+assert handoff.exists(), 'ordinary non-/cook turn should inject the /cook handoff boundary reminder'
+handoff_text = handoff.read_text()
+assert '/cook is the only explicit entrypoint into long-running completion workflow.' in handoff_text, 'ordinary handoff reminder should preserve the explicit /cook workflow boundary'
+assert 'stop short of long-running implementation and tell the user to run /cook.' in handoff_text, 'ordinary handoff reminder should require primary-agent handoff before implementation'
 assert not auto_resume.exists(), 'ordinary non-/cook turn should not queue auto-resume before /cook activation'
 assert 'Skipped completion workflow auto-resume prompt (test mode)' not in output, 'ordinary non-/cook turn should not attempt auto-resume'
 PY

package/skills/cook-handoff-boundary/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: cook-handoff-boundary
+description: Ordinary-chat boundary contract for deciding when a task has matured enough that the primary agent must stop short of long-running implementation and hand the user off to `/cook`.
+---
+
+# /cook Handoff Boundary
+
+Load or summarize this contract when the primary agent is operating in ordinary main chat before the user has explicitly entered `/cook`.
+
+This skill governs the boundary between:
+
+- ordinary main-chat discussion, clarification, and proposal work
+- explicit transition into long-running completion workflow through `/cook`
+
+## Core Contract
+
+- Ordinary chat may be used to clarify requirements, discuss tradeoffs, and propose implementation approaches.
+- `/cook` is the only explicit entrypoint into long-running completion workflow.
+- When the primary agent judges that a task has matured into completion-workflow scope, it must stop short of implementation and direct the user to `/cook`.
+
+## When To Hand Off To `/cook`
+
+The primary agent should consider `/cook` handoff appropriate when one or more of the following are true:
+
+- the user has clearly shifted from exploration into implementation intent
+- the agent has just produced a concrete plan or proposal whose natural next step would be implementation
+- the task spans multiple files, steps, or verification surfaces
+- the task needs resumability, review, audit, or canonical workflow state
+- the task is better treated as a long-running repo mission than a one-off answer or tiny fix
+
+## Required Handoff Behavior
+
+When the task is judged ready for completion workflow, the primary agent must:
+
+- stop before long-running implementation
+- not edit tracked product files in ordinary chat for that workflow-level task
+- tell the user to run `/cook`
+- explain that `/cook` will derive a startup brief from recent discussion and ask for confirmation before workflow start
+
+Suggested wording:
+
+> This task is now mature enough for the `/cook` workflow. If you want me to start implementation, run `/cook`. I’ll use our recent discussion to generate a startup brief for confirmation before the workflow begins.
+
+A short recap may include mission, scope, or acceptance, but that recap must not be presented as canonical plan state.
+
+## Forbidden Behaviors
+
+Once the task is judged ready for completion workflow, the primary agent must not:
+
+- directly begin long-running implementation in ordinary chat
+- modify tracked product files as part of that workflow-level task
+- act as though `/cook` had already been invoked
+- silently rewrite ordinary-chat discussion into active workflow state
+
+## Relationship To `completion-protocol`
+
+This skill is only about pre-`/cook` ordinary-chat handoff behavior.
+
+After the user explicitly enters `/cook`, the separate `completion-protocol` skill governs:
+
+- canonical `.agent/**` workflow state
+- workflow-driver behavior
+- mandatory completion-role dispatch
+- review, audit, and stop-wave rules