@linimin/pi-letscook 0.1.61 → 0.1.62

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
 
-## Unreleased
+## 0.1.62
+
+### Changed
+
+- made ordinary chat implementation-first again so the primary agent may directly edit repo files without requiring `/cook` when workflow state is unnecessary
+- repositioned `/cook` as optional workflow mode for confirm-first startup, resumability, review/audit flow, and canonical `.agent/**` state rather than as a mandatory implementation boundary
+- updated ordinary-chat boundary docs, reminders, and release-parity checks so they no longer tell the agent to block repo edits pending explicit `/cook`
 
 ## 0.1.61
 

package/README.md

@@ -1,8 +1,8 @@
 # @linimin/pi-letscook
 
-`/cook` turns main-chat discussion about concrete repo changes into a resumable repo workflow stored in repo-local `.agent/**` state.
+`/cook` is optional workflow mode for turning main-chat discussion about concrete repo changes into a resumable repo workflow stored in repo-local `.agent/**` state.
 
-`/cook` is the explicit workflow boundary for starting, continuing, refocusing, or beginning the next round of long-running repo work.
+You can still implement directly in ordinary chat when you do not need workflow state. Use `/cook` when you want confirm-first startup, resumability, review/audit flow, or canonical `.agent/**` control.
 
 ## Use it when
 
@@ -10,10 +10,12 @@
 - you want one mission tracked in repo state instead of chat memory
 - you want clear continue / refocus / next-round behavior
 - you want review, audit, and verification tied to the repo
+- you want a confirm-first workflow boundary before canonical state is written
 
 ## Skip it when
 
 - you only need a one-off answer
+- you want the agent to implement directly in ordinary chat
 - you are brainstorming
 - you are writing planning docs but are not ready to start concrete repo changes
 
@@ -30,8 +32,8 @@ Then run `/reload` in Pi.
 1. Install the package:
    `pi install npm:@linimin/pi-letscook`
 2. Run `/reload` in Pi.
-3. In the main chat, describe and refine the concrete repo change you want.
-4. When you want to enter workflow, run `/cook`.
+3. In the main chat, either implement directly with the agent or refine the concrete repo change you want.
+4. When you want workflow mode, run `/cook`.
 5. Review the synthesized startup brief and choose **Start** or **Cancel**.
 6. Later, run `/cook` again to resume from canonical state or confirm a synthesized replacement or next-round startup brief.
 
@@ -43,7 +45,8 @@ Then run `/reload` in Pi.
 
 | If you want to... | Do this |
 |---|---|
-| Start a long-running task | Discuss the concrete repo change in the main chat, then run `/cook` when you want workflow to begin |
+| Implement directly without workflow | Ask in ordinary chat and let the agent modify the repo directly |
+| Start a tracked workflow | Discuss the concrete repo change in the main chat, then run `/cook` when you want workflow to begin |
 | Continue the current workflow | Run `/cook` |
 | Refocus or start the next round | Discuss the new concrete repo change in the main chat, then run `/cook` when you want a new startup brief synthesized |
 
@@ -64,20 +67,20 @@ If you pass inline arguments to `/cook`, it also fails closed and tells you to m
 
 ## Workflow entry
 
-Only explicit `/cook` enters the workflow. Ordinary prompts stay in the main chat and go straight to the primary agent.
+Only explicit `/cook` enters workflow mode. 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 still avoid starting long-running implementation directly in ordinary chat.
+Ordinary chat can still directly implement repo changes. `/cook` is for the cases where you want workflow control rather than just implementation help.
 
-Ordinary chat remains advisory until you explicitly run `/cook`. At that point `/cook` synthesizes a startup brief from recent discussion using primary-agent-style context, then asks you to **Start** or **Cancel** before rewriting canonical workflow state.
+When you explicitly run `/cook`, it synthesizes a startup brief from recent discussion using primary-agent-style context, then asks you to **Start** or **Cancel** before rewriting canonical workflow state.
 
-Optional explicit `/cook` capsules may still be used as compatibility startup intake, but they are no longer the default path and are not required for new-workflow or next-round entry.
+Optional explicit `/cook` capsules may still be used as compatibility startup intake, but they are not required for new-workflow or next-round entry.
 
 Important behavior:
-- `/cook` is the canonical workflow boundary and manual entry point
-- startup and next-round entry stay confirm-first, but they now derive startup from explicit user `/cook` entry plus recent discussion when needed
+- `/cook` is an optional workflow boundary and manual entry point
+- startup and next-round entry stay confirm-first, deriving startup from explicit user `/cook` entry plus recent discussion when needed
 - active workflows resume from canonical `.agent/**` state unless `/cook` synthesizes or receives a concrete replacement mission
 - 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 still must not start before explicit `/cook`
+- ordinary main-chat discussion may clarify, propose, or directly implement repo changes without entering workflow mode
 
 ## Typical examples
 
@@ -91,7 +94,7 @@ I want to add login redirect handling and tests.
 
 ## What happens when you run `/cook`
 
-`/cook` first checks for a fresh explicit primary-agent handoff capsule as a compatibility intake path. If none is present, `/cook` synthesizes a startup brief from recent discussion using primary-agent-style context. New-workflow entry and done-workflow next-round entry still fail closed when that synthesis is too weak or planning-only. When a workflow is already active and no concrete replacement mission is available, `/cook` resumes from canonical `.agent/**` state.
+`/cook` first checks for a fresh explicit primary-agent handoff capsule as a compatibility intake path. If none is present, `/cook` synthesizes a startup brief from recent discussion using primary-agent-style context. New-workflow entry and done-workflow next-round entry still fail closed when that synthesis is too weak or planning-only. When a workflow is already active and no concrete replacement mission is available, `/cook` resumes from canonical `.agent/**` state. None of this prevents ordinary-chat implementation when you choose not to enter workflow mode.
 
 | Repo state | What you'll see |
 |---|---|

package/extensions/completion/index.ts

@@ -942,7 +942,7 @@ export default function completionExtension(pi: ExtensionAPI) {
 		structuredDiscussionFailureDetail: COOK_STRUCTURED_DISCUSSION_FAILURE_DETAIL,
 		mainChatRerunGuidance: COOK_MAIN_CHAT_RERUN_GUIDANCE,
 		cookCommandSpec: {
-			description: "/cook workflow: synthesize a startup brief when the user explicitly enters /cook, resume the current workflow from canonical state, or confirm a replacement mission from explicit /cook entry",
+			description: "/cook workflow: optionally enter tracked workflow mode, synthesize a startup brief from explicit /cook entry, resume the current workflow from canonical state, or confirm a replacement mission",
 		},
 		buildContextProposalContinuationReason,
 		completionKickoff,

package/extensions/completion/prompt-surfaces.ts

@@ -26,17 +26,16 @@ export type AdvisoryStartupBrief = {
 
 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, propose implementation approaches, and refine scope naturally.",
-		"/cook is the only explicit entrypoint into long-running completion workflow.",
+		"You are in ordinary main chat unless the user explicitly runs /cook.",
+		"Ordinary chat may clarify requirements, discuss tradeoffs, refine scope, and directly implement requested repo changes, including multi-file work, when that is the most helpful response.",
 		"Do not proactively tell the user to run /cook just because a task looks workflow-worthy, and do not emit a ```cook_handoff``` capsule by default in ordinary chat.",
-		"Even when the task has matured into workflow-level implementation work, ordinary chat remains ordinary chat until the user explicitly runs /cook.",
-		"Before that explicit /cook entry, 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.",
-		"If the user asks follow-up questions or wants to keep refining scope, continue helping in ordinary chat instead of steering them into workflow mode.",
-		"Once the user explicitly runs /cook, /cook will synthesize a startup brief from recent discussion using primary-agent-style context, then show Start/Cancel confirmation before canonical workflow state is rewritten.",
+		"/cook is optional workflow mode for resumability, review, audit, canonical .agent state, or deliberate multi-session control; it is not required just to edit repo files in ordinary chat.",
+		"If the user wants direct implementation now, stay in ordinary chat and help directly instead of blocking on /cook.",
+		"If the user asks follow-up questions or wants to keep refining scope, continue helping naturally in ordinary chat.",
+		"If the user explicitly runs /cook, /cook will synthesize a startup brief from recent discussion using primary-agent-style context, then show Start/Cancel confirmation before canonical workflow state is rewritten.",
 		"Only provide a preview startup brief or ```cook_handoff``` capsule in ordinary chat when the user explicitly asks for that preview behavior.",
 		"Any preview capsule is startup intake for /cook only: do not present it as canonical .agent state, an active slice, or a persistent repo contract.",
-		"If the task is still ordinary Q&A, lightweight brainstorming, or a tiny one-off fix, continue normally without forcing /cook.",
+		"When you continue in ordinary chat, do not pretend /cook already started and do not silently rewrite discussion into canonical workflow state.",
 	].join(" ");
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linimin/pi-letscook",
-  "version": "0.1.61",
+  "version": "0.1.62",
   "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

@@ -9,47 +9,46 @@ echo "[release-check] running control-plane validation, tracked .agent contract
 bash .agent/verify_completion_control_plane.sh
 git ls-files --error-unmatch .agent/README.md .agent/mission.md .agent/profile.json .agent/verify_completion_stop.sh .agent/verify_completion_control_plane.sh >/dev/null
 
-echo "[release-check] verifying public /cook parity and explicit-entry docs/help"
+echo "[release-check] verifying public /cook parity and optional-workflow docs/help"
 python3 - <<'PY'
 from pathlib import Path
 
 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.",
-        "Ordinary chat remains advisory until you explicitly run `/cook`. At that point `/cook` synthesizes a startup brief from recent discussion using primary-agent-style context, then asks you to **Start** or **Cancel** before rewriting canonical workflow state.",
-        "- startup and next-round entry stay confirm-first, but they now derive startup from explicit user `/cook` entry plus recent discussion when needed",
-        "- active workflows resume from canonical `.agent/**` state unless `/cook` synthesizes or receives a concrete replacement mission",
-        "`/cook` first checks for a fresh explicit primary-agent handoff capsule as a compatibility intake path. If none is present, `/cook` synthesizes a startup brief from recent discussion using primary-agent-style context.",
-        "when a concrete replacement mission suggests replacing an active workflow, `/cook` shows a chooser before any canonical state rewrite",
+        "You can still implement directly in ordinary chat when you do not need workflow state.",
+        "Only explicit `/cook` enters workflow mode. Ordinary prompts stay in the main chat and go straight to the primary agent.",
+        "Ordinary chat can still directly implement repo changes. `/cook` is for the cases where you want workflow control rather than just implementation help.",
+        "- `/cook` is an optional workflow boundary and manual entry point",
+        "- ordinary main-chat discussion may clarify, propose, or directly implement repo changes without entering workflow mode",
+        "None of this prevents ordinary-chat implementation when you choose not to enter workflow mode.",
     ],
     "CHANGELOG.md": [
-        "removed proactive primary-agent `/cook` prompting and default ordinary-chat `cook_handoff` emission so main chat stays advisory until the user explicitly runs `/cook`",
-        "changed bare `/cook` startup and done-workflow next-round entry to synthesize a deferred primary-agent startup brief from recent discussion instead of requiring a pre-authored explicit handoff capsule",
-        "updated public parity and shipped package contents so the tracked `.agent` contract files are included in package tarballs and packaged smoke/release verification can scaffold canonical state truthfully",
+        "made ordinary chat implementation-first again so the primary agent may directly edit repo files without requiring `/cook` when workflow state is unnecessary",
+        "repositioned `/cook` as optional workflow mode for confirm-first startup, resumability, review/audit flow, and canonical `.agent/**` state rather than as a mandatory implementation boundary",
+        "updated ordinary-chat boundary docs, reminders, and release-parity checks so they no longer tell the agent to block repo edits pending explicit `/cook`",
     ],
     "extensions/completion/prompt-surfaces.ts": [
-        '"/cook is the only explicit entrypoint into long-running completion workflow."',
-        '"Do not proactively tell the user to run /cook just because a task looks workflow-worthy, and do not emit a ```cook_handoff``` capsule by default in ordinary chat."',
-        '"Only provide a preview startup brief or ```cook_handoff``` capsule in ordinary chat when the user explicitly asks for that preview behavior."',
+        '"Ordinary chat may clarify requirements, discuss tradeoffs, refine scope, and directly implement requested repo changes, including multi-file work, when that is the most helpful response."',
+        '"/cook is optional workflow mode for resumability, review, audit, canonical .agent state, or deliberate multi-session control; it is not required just to edit repo files in ordinary chat."',
+        '"If the user wants direct implementation now, stay in ordinary chat and help directly instead of blocking on /cook."',
     ],
     "extensions/completion/index.ts": [
         '"/cook failed closed because it could not derive a concrete startup brief from recent discussion. Clarify the mission, first slice, or verification intent in the main chat, then rerun /cook."',
-        'description: "/cook workflow: synthesize a startup brief when the user explicitly enters /cook, resume the current workflow from canonical state, or confirm a replacement mission from explicit /cook entry"',
+        'description: "/cook workflow: optionally enter tracked workflow mode, synthesize a startup brief from explicit /cook entry, resume the current workflow from canonical state, or confirm a replacement mission"',
     ],
 }
 
 forbidden = {
     "README.md": [
-        "wait for a fresh primary-agent handoff",
-        "require a fresh valid explicit primary-agent handoff",
+        "mature long-running implementation still must not start before explicit `/cook`",
+        "Ordinary chat remains advisory until you explicitly run `/cook`.",
     ],
     "extensions/completion/prompt-surfaces.ts": [
-        '"When handing off, explain that /cook can start a new workflow or next round only from a fresh valid explicit primary-agent handoff capsule; otherwise it fails closed, while already-active workflows resume from canonical .agent state unless a fresh valid explicit handoff proposes replacement."',
+        '"Before that explicit /cook entry, 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."',
     ],
-    "extensions/completion/index.ts": [
-        'description: "/cook workflow: start a new workflow or next round only from a fresh explicit primary-agent handoff, resume the current workflow from canonical state, or confirm an explicit replacement from the explicit /cook command"',
-        '"/cook failed closed because new-workflow startup now requires a fresh valid explicit primary-agent handoff from the immediately preceding ordinary-chat turn; recent discussion alone no longer starts a workflow. Ask the primary agent to hand off explicitly in the main chat, then rerun /cook."',
+    "skills/cook-handoff-boundary/SKILL.md": [
+        "Before that explicit `/cook` entry, the primary agent must stop short of long-running implementation for workflow-level tasks.",
+        "not edit tracked product files for that workflow-level task in ordinary chat",
     ],
 }
 

package/scripts/smoke-test.sh

@@ -265,14 +265,14 @@ 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 'ordinary main chat unless the user explicitly runs /cook' in handoff_text, 'ordinary handoff reminder should preserve explicit /cook workflow entry'
+assert 'directly implement requested repo changes, including multi-file work' in handoff_text, 'ordinary handoff reminder should allow direct ordinary-chat implementation'
 assert 'Do not proactively tell the user to run /cook' in handoff_text, 'ordinary handoff reminder should keep ordinary chat neutral until explicit /cook entry'
-assert 'do not emit a ```cook_handoff``` capsule by default in ordinary chat' in handoff_text, 'ordinary handoff reminder should stop proactive capsule emission'
-assert 'ordinary chat remains ordinary chat until the user explicitly runs /cook' in handoff_text, 'ordinary handoff reminder should preserve the explicit /cook boundary'
-assert 'do not begin long-running product implementation in ordinary chat' in handoff_text, 'ordinary handoff reminder should still block workflow-level implementation before /cook'
+assert '/cook is optional workflow mode' in handoff_text, 'ordinary handoff reminder should position /cook as optional workflow mode'
+assert 'If the user wants direct implementation now, stay in ordinary chat and help directly instead of blocking on /cook.' in handoff_text, 'ordinary handoff reminder should avoid blocking implementation on /cook'
 assert 'Only provide a preview startup brief or ```cook_handoff``` capsule in ordinary chat when the user explicitly asks for that preview behavior.' in handoff_text, 'ordinary handoff reminder should restrict preview capsules to explicit preview requests'
 assert 'startup brief from recent discussion using primary-agent-style context' in handoff_text, 'ordinary handoff reminder should describe deferred startup synthesis'
-assert 'Start/Cancel confirmation before canonical workflow state is rewritten' in handoff_text, 'ordinary handoff reminder should preserve confirm-first startup'
+assert 'do not silently rewrite discussion into canonical workflow state' in handoff_text, 'ordinary handoff reminder should preserve non-canonical ordinary-chat behavior'
 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

@@ -1,23 +1,23 @@
 ---
 name: cook-handoff-boundary
-description: Ordinary-chat boundary contract for keeping main chat advisory until the user explicitly enters `/cook`, while preventing long-running implementation from starting before that explicit workflow entry.
+description: Ordinary-chat contract for treating `/cook` as an optional workflow mode while still allowing direct repo implementation in main chat when workflow state is unnecessary.
 ---
 
 # /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:
+This skill governs the relationship between:
 
-- ordinary main-chat discussion, clarification, and proposal work
-- explicit transition into long-running completion workflow through `/cook`
+- ordinary main-chat discussion and direct implementation
+- optional transition into long-running completion workflow through `/cook`
 
 ## Core Contract
 
-- Ordinary chat may be used to clarify requirements, discuss tradeoffs, propose implementation approaches, and refine scope.
-- `/cook` is the only explicit entrypoint into long-running completion workflow.
+- Ordinary chat may be used to clarify requirements, discuss tradeoffs, refine scope, and directly implement requested repo changes.
+- `/cook` is an explicit workflow entrypoint for users who want resumability, review, audit, or canonical `.agent/**` workflow state.
+- `/cook` is optional. It is not required just because the work spans multiple files or looks substantial.
 - Ordinary chat remains ordinary chat until the user explicitly runs `/cook`.
-- Before that explicit `/cook` entry, the primary agent must stop short of long-running implementation for workflow-level tasks.
 
 ## What Ordinary Chat May Do
 
@@ -27,47 +27,49 @@ The primary agent may:
 - discuss tradeoffs
 - refine scope and constraints
 - summarize likely mission, acceptance, or risks
-- help the user determine whether the work seems large enough for `/cook`
+- directly edit repo files when that is the most helpful response
+- complete multi-file implementation in ordinary chat when workflow state is unnecessary
 
 The primary agent should not:
 
-- proactively tell the user to run `/cook`
+- proactively tell the user to run `/cook` just because the task looks workflow-worthy
 - proactively emit a `cook_handoff` capsule by default
-- act as though workflow has already started
-- rewrite ordinary-chat discussion into canonical workflow state
+- act as though workflow has already started when it has not
+- silently rewrite ordinary-chat discussion into canonical workflow state
 
-## When Work Looks Workflow-Worthy
+## When `/cook` Is Helpful
 
-The primary agent should treat work as workflow-worthy when one or more of the following are true:
+The primary agent may mention `/cook` as an optional tool when it would genuinely help, for example when:
 
-- the task spans multiple files, steps, or verification surfaces
-- the next natural step would be bounded repo implementation rather than more explanation
-- the work 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
+- the work should be resumable across sessions
+- the user wants a tracked mission in canonical `.agent/**` state
+- the task benefits from explicit review / audit / stop-wave flow
+- the user wants a confirm-first workflow boundary before a long-running effort
 
-Even then, the boundary remains:
+But even in those cases:
 
-- ordinary chat can still keep refining the task
-- only explicit `/cook` starts workflow
+- do not force `/cook`
+- do not frame `/cook` as mandatory for direct repo edits
+- continue helping directly in ordinary chat unless the user explicitly chooses workflow mode
 
 ## Required Behavior Before Explicit `/cook`
 
-When a task has matured into workflow-level work, the primary agent must:
+Before the user explicitly runs `/cook`, the primary agent must:
 
-- stop before long-running implementation
-- not edit tracked product files for that workflow-level task in ordinary chat
-- continue ordinary discussion naturally if the user keeps asking questions or refining scope
-- wait for the user to explicitly run `/cook` before treating the conversation as workflow startup
+- keep the interaction in ordinary chat
+- directly implement requested repo changes when appropriate instead of blocking on workflow mode
+- continue ordinary discussion naturally if the user keeps refining the task
+- avoid claiming that canonical workflow state already exists unless `/cook` actually started it
 
 ## Deferred Handoff Model
 
 When the user explicitly runs `/cook`:
 
-- `/cook` will synthesize a startup brief from recent discussion using primary-agent-style context
-- `/cook` will show Start / Cancel confirmation before canonical workflow state is rewritten
-- that synthesized startup brief is advisory intake only, not canonical `.agent/**` state by itself
+- `/cook` synthesizes a startup brief from recent discussion using primary-agent-style context
+- `/cook` shows Start / Cancel confirmation before canonical workflow state is rewritten
+- that synthesized startup brief is advisory intake only until the user confirms startup
 
-This means the primary agent does **not** need to proactively attach startup capsules during ordinary chat just because the task looks ready.
+This means the primary agent does not need to proactively attach startup capsules during ordinary chat just because the task looks ready.
 
 ## Optional Preview Behavior
 
@@ -110,7 +112,7 @@ Notes:
 
 Suggested wording:
 
-> We are still in ordinary chat until you explicitly run `/cook`. If you want, we can keep refining the first slice here. When you do run `/cook`, it will synthesize a startup brief from our recent discussion and show Start / Cancel before workflow begins.
+> We can continue directly in ordinary chat if you want. If you prefer resumable workflow state, explicit review flow, or a confirm-first startup gate, you can run `/cook` and it will synthesize a startup brief from our recent discussion before workflow begins.
 
 A short recap may include mission, scope, or acceptance, but that recap must not be presented as canonical plan state.
 
@@ -118,15 +120,14 @@ A short recap may include mission, scope, or acceptance, but that recap must not
 
 Before the user explicitly runs `/cook`, 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
+- pretend `/cook` has already been invoked
 - silently rewrite ordinary-chat discussion into active workflow state
-- refuse ordinary-chat clarification only because `/cook` would now be appropriate
+- claim canonical `.agent/**` startup state exists when it does not
+- refuse ordinary-chat implementation solely because `/cook` would also be possible
 
 ## Relationship To `completion-protocol`
 
-This skill is only about pre-`/cook` ordinary-chat boundary behavior.
+This skill is only about pre-`/cook` ordinary-chat behavior.
 
 After the user explicitly enters `/cook`, the separate `completion-protocol` skill governs: