taskchef 7.1.0 → 7.3.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.1.0",
+  "version": "7.3.0",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",
@@ -31,6 +31,7 @@
     "defaultPrompt": [
       "$taskchef-bootstrap Set up TaskChef in this folder.",
       "$taskchef-delegate Dispatch this request to the right project.",
+      "$taskchef-executor Execute this delegated TaskChef assignment.",
       "$taskchef-report Report on work in the TaskChef task history."
     ],
     "brandColor": "#D97706",

package/README.md

@@ -31,7 +31,7 @@ codex plugin add taskchef@favoyang-plugins
 npm install --global taskchef
 ```
 
-The plugin provides three skills and a local MCP server. The npm installation
+The plugin provides four skills and a local MCP server. The npm installation
 puts the `taskchef` CLI on `PATH`. TaskChef installs no hooks, schedules,
 daemons, or background identity search.
 
@@ -86,9 +86,21 @@ $taskchef-delegate In payments, add structured logs for failed retries and test
 ```
 
 TaskChef prepares a UUID and marker, persists the task before native creation,
-creates the executor, and returns its task link. The executor reads its own
-`CODEX_THREAD_ID` and self-links before substantive work. Independent
-outcomes may become separate executors; dependent work should stay together.
+creates the executor, and returns its task link. New executor instructions keep
+the assignment visible from the first line, then place the correlation marker
+immediately before an explicit `$taskchef-executor` invocation. That skill
+reads the executor's own `CODEX_THREAD_ID`, self-links, and reports lifecycle
+state. Independent outcomes may become separate executors; dependent work
+should stay together.
+
+For example, TaskChef generates this shape:
+
+```text
+Fix duplicate charges after a retry and add a regression test.
+
+<!-- taskchef_id=c0f010ff-84f2-4838-a69d-0ff1f5d721d7 -->
+Use $taskchef-executor to execute and report this delegated TaskChef assignment.
+```
 
 ## Work with and report executors
 
@@ -105,6 +117,11 @@ the last concise semantic result. A follow-up therefore appears as `working`
 immediately without erasing the previous outcome. TaskChef does not store the
 transcript or a lifecycle event log.
 
+Delegated tasks created by earlier TaskChef versions remain compatible: their
+inline executor protocol still parses, self-links, and may use the deprecated
+`report_result` alias. The v7 inline-paragraph named exports remain as deprecated
+historical snapshots, but new delegations use the executor skill and `report_state`.
+
 ## View and report tasks
 
 Ask the dispatcher for an on-demand report:

package/docs/firstmate-taskchef-comparison.md

@@ -70,7 +70,7 @@ responsibility until an outcome is landed, transferred, or safely preserved.
 | Dimension | TaskChef 7 | FirstMate at `038d0f7` |
 | --- | --- | --- |
 | Primary goal | Put multi-project work into the right visible Codex task and make it findable later. | Let one person direct a supervised crew across projects through one liaison. |
-| Product form | Codex plugin: three skills, local MCP server, data CLI, and loopback dashboard. | Cloneable agent distribution: instructions, internal skills, scripts, policies, and private on-disk state. |
+| Product form | Codex plugin: four skills, local MCP server, data CLI, and loopback dashboard. | Cloneable agent distribution: instructions, internal skills, scripts, policies, and private on-disk state. |
 | Runtime | Native Codex desktop tasks are the executors and live source of truth. | Harness-driven workers in tmux by default, with documented alternative session backends; Codex can be a harness, but Codex desktop is not a runtime backend. |
 | Coordinator lifetime | Dispatcher returns immediately and does not supervise. | First mate remains active and uses watcher/guard mechanisms to supervise meaningful events. |
 | Project isolation | Delegates to the configured Codex project; isolation follows native Codex/project behavior. | Ship and scout workers require separate Treehouse- or backend-managed worktrees. |
@@ -108,7 +108,7 @@ also insert an interpretation layer between user and worker.
 
 ### TaskChef
 
-**Fact:** `prepare_dispatch` allocates a TaskChef UUID and exact first-line
+**Fact:** `prepare_dispatch` allocates a TaskChef UUID and exact correlation
 marker. `record_task` persists the marked instruction before native task
 creation. The executor then reads its own `CODEX_THREAD_ID` and calls
 `link_task`; the dispatcher neither searches recent tasks nor repairs identity.
@@ -215,7 +215,7 @@ harness adapter.
 | --- | --- | --- |
 | Codex | Built around native Codex projects, tasks, thread reads, and desktop deep links. | Codex is one verified harness; desktop tasks are not its worker runtime. |
 | GitHub | Configured repository URLs aid routing; delivery remains the executor project's concern. | GitHub CLI, PR state, and configured delivery modes are part of supervised shipping workflows. |
-| Skills | Three plugin skills with narrow bootstrap, delegate, and report responsibilities. | Internal firstmate-only skills plus standalone public skills; AGENTS.md routes conditional procedures. |
+| Skills | Four plugin skills with narrow bootstrap, delegate, executor, and report responsibilities. | Internal firstmate-only skills plus standalone public skills; AGENTS.md routes conditional procedures. |
 | MCP | Four primary local TaskChef tools plus one deprecated compatibility alias own deterministic identity and state writes. | FirstMate describes itself as an agent distribution rather than an MCP product; deterministic behavior lives largely in scripts. |
 | Runtime extensions | Extend plugin skills/MCP/CLI/dashboard or compose native Codex capabilities. | Add or verify harness adapters, session backends, dispatch profiles, operational scripts, and optional integrations. |
 

package/docs/spec.md

@@ -18,7 +18,7 @@ is dated research, not contract.
 | **Delegated task** | One independently useful outcome represented by one TaskChef task UUID and snapshot. |
 | **Executor** | The native Codex task created to own and perform one delegated task. |
 | **Task record** | One complete JSON object in `tasks.jsonl`; it contains immutable intent/project fields and mutable identity/result fields. |
-| **Marker** | The exact first instruction line `<!-- taskchef_id=<lowercase full UUID> -->`, followed by a blank line. |
+| **Marker** | The exact correlation line `<!-- taskchef_id=<lowercase full UUID> -->`; new instructions place it after the complete assignment and immediately before the executor-skill invocation. |
 | **Record-before-create** | Persisting a link-pending task before asking Codex to create its executor. |
 | **Self-linking** | The executor's one-way registration of its own canonical Codex UUIDv7 from `CODEX_THREAD_ID`. |
 | **Link-pending** | A working task whose `threadId` is null and `updatedBy` is `dispatcher`. |
@@ -26,7 +26,7 @@ is dated research, not contract.
 | **Last semantic result** | The most recent `completed`, `needs_input`, or `failed` outcome, preserved separately while a newer turn is working. |
 | **Current turn ID** | The canonical Codex UUIDv7 returned by an exact native read of the linked executor for the turn being reported. |
 | **Dashboard** | The loopback, read-only UI derived from validated workspace snapshots and bounded native actions. |
-| **Skill** | One packaged agent procedure: `taskchef-bootstrap`, `taskchef-delegate`, or `taskchef-report`. |
+| **Skill** | One packaged agent procedure: `taskchef-bootstrap`, `taskchef-delegate`, `taskchef-executor`, or `taskchef-report`. |
 
 ## Components and ownership
 
@@ -34,6 +34,9 @@ is dated research, not contract.
   diagnostics. It MUST NOT dispatch or report unless separately requested.
 - `taskchef-delegate` MUST own routing and record-before-create delegation.
   It MUST return after creation and MUST NOT poll, supervise, or infer identity.
+- `taskchef-executor` MUST own executor assignment ownership, self-linking,
+  exact thread/turn identity, per-turn state reporting, failure behavior,
+  privacy, and idempotency. It MUST NOT dispatch the owned assignment again.
 - `taskchef-report` MUST own on-demand reporting. It MUST NOT poll or persist
   inferred state.
 - The MCP server MUST expose four primary lifecycle tools plus the deprecated
@@ -99,8 +102,11 @@ fields MUST NOT change after recording.
 
 1. The dispatcher MUST call `prepare_dispatch` once per outcome.
 2. It MUST choose exactly one configured project and exact native-project path.
-3. It MUST build the instruction from the returned marker, a blank line, the
-   packaged executor contract paragraphs, and the user's outcome.
+3. It MUST build the instruction with the user's outcome beginning on line 1
+   and remaining uninterrupted, followed by one blank line, the returned
+   marker, and exactly one concise explicit `$taskchef-executor` invocation on
+   the final line. It MUST NOT inline the executor protocol into a new
+   instruction.
 4. It MUST call `record_task` with `threadId: null` before native creation.
 5. It MUST create exactly one native Codex executor and return immediately.
 6. The executor MUST read its own `CODEX_THREAD_ID` and call `link_task`
@@ -117,6 +123,16 @@ If native creation fails after recording, the dispatcher MUST call
 A link failure MUST remain visible and retryable; the executor MUST report it
 visibly and MUST NOT continue substantive work.
 
+Previously recorded instructions with a first-line HTML marker, the older
+first-line `# taskchef_id=<full UUID>` heading, or the former blank line and
+inline executor protocol MUST remain marker-readable and executable. Their
+`report_result` calls MUST remain supported by the deprecated alias. New
+instructions MUST use the trailing marker and explicit executor skill contract
+above. A historical first-line instruction with an executor-skill invocation
+MUST contain exactly one invocation as its final line. A former inline-protocol
+instruction MUST retain non-whitespace task-specific content beyond its known
+lifecycle paragraphs.
+
 `needs_input` MUST mean a semantic user decision or missing fact. A native
 approval prompt MUST remain live Codex state and MUST NOT be stored as
 `needs_input`.
@@ -166,7 +182,7 @@ new preparation values, though it writes no state.
 | `id` | Non-empty string; MUST equal the instruction marker. |
 | `project` | Non-empty configured project path. |
 | `title` | Non-empty string. |
-| `instruction` | Non-empty string beginning with the exact marker and blank line. |
+| `instruction` | Non-empty string containing exactly one accepted marker and a non-empty assignment. New instructions use the required trailing marker and executor-invocation scaffold; historical first-line forms remain accepted. |
 | `threadId` | Literal null. |
 
 **Structured output:** `{ task: Task }`.

package/docs/workflows.md

@@ -11,10 +11,11 @@ research.
 | Surface | Responsibility |
 | --- | --- |
 | `skills/taskchef-delegate/SKILL.md` | Split, route, record-before-create, create, return. |
+| `skills/taskchef-executor/SKILL.md` | Own, self-link, execute, and report every executor turn. |
 | `skills/taskchef-bootstrap/SKILL.md` | Initialize current workspace and configure projects. |
 | `skills/taskchef-report/SKILL.md` | Select cached tasks and perform bounded live checks. |
 | `src/mcp.js` | Four primary lifecycle tools, one deprecated alias, and MCP annotations. |
-| `src/delegation.js` | UUID marker, executor contract paragraphs, and creation-failure handling. |
+| `src/delegation.js` | UUID marker, concise executor-skill invocation shape, and creation-failure handling. |
 | `src/workspace.js` | Current schemas, validation, locking, atomic JSONL writes, linking, and result freshness. |
 | `src/cli.js` | Administration, inspection, diagnostics, and dashboard startup. |
 | `src/dashboard.js` | Validated snapshots, SSE fan-out, and bounded open actions. |
@@ -55,7 +56,7 @@ sequenceDiagram
   D->>C: Create executor with marked instruction
   C-->>D: Created-task reference
   D-->>U: Return immediately
-  C->>E: Start executor
+  C->>E: Start executor and load $taskchef-executor
   E->>E: Read own CODEX_THREAD_ID
   E->>M: link_task(taskId, threadId)
   M->>W: linkTask()
@@ -67,6 +68,12 @@ Record-before-create makes native creation failure observable. Executor
 self-linking removes dispatcher-side polling, task search, title matching, and
 parent/child identity inference.
 
+The generated task begins with the complete assignment, then places its marker
+immediately before one explicit `$taskchef-executor` invocation. Older
+recorded tasks with first-line HTML or heading markers and former inline
+protocol remain readable; the deprecated `report_result` alias preserves their
+semantic callbacks.
+
 ## State reporting
 
 The executor obtains the turn identity from an exact native read of its own

package/index.js

@@ -33,6 +33,7 @@ export {
   EXECUTOR_LINK_PARAGRAPH,
   EXECUTOR_RESULT_PARAGRAPH,
   EXECUTOR_WORKING_PARAGRAPH,
+  EXECUTOR_SKILL_INVOCATION,
   createAndRecordDelegation,
   isProvisionalThreadId,
   normalizeCodexThreadId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.1.0",
+  "version": "7.3.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -33,6 +33,7 @@
     "src",
     "skills/taskchef-bootstrap",
     "skills/taskchef-delegate",
+    "skills/taskchef-executor",
     "skills/taskchef-report"
   ],
   "engines": {

package/skills/taskchef-bootstrap/SKILL.md

@@ -38,7 +38,7 @@ all deterministic workspace operations.
    `codex add` or hard-code an application bundle path.
 3. `workspace init` takes no stdin, creates an empty
    configuration when missing, creates the one-entry-per-task JSONL log, and
-   refreshes managed instructions. The installed plugin provides all three
+   refreshes managed instructions. The installed plugin provides all four
    TaskChef skills outside the dispatcher workspace.
 4. Run `doctor --json` after setup or when the user asks to diagnose the
    workspace. Doctor is read-only. Rerun `workspace init --json` to repair the

package/skills/taskchef-delegate/SKILL.md

@@ -10,17 +10,22 @@ and return immediately.
 
 ## Invocation boundary
 
-A task whose initial structured `codexDelegation.input` starts with an exact
-`<!-- taskchef_id=<full UUID> -->` marker already owns that delegated
-assignment. Execute it in the current task. Do not re-dispatch it merely
-because it concerns TaskChef or a configured project. Explicit requests to
-delegate separate work remain valid.
-
-Use the bundled `prepare_dispatch`, `record_task`, `link_task`, and
-`report_state` MCP tools directly. `report_result` is a deprecated compatibility
-alias and must not be emitted into new executor instructions. Never fall back to shell writes. If a
-required tool is unavailable, stop and report that the TaskChef plugin must be
-reloaded or installed.
+A task whose initial structured `codexDelegation.input` contains either the
+exact new trailing TaskChef marker plus final `$taskchef-executor` invocation,
+an exact first-line HTML marker, or the historical first-line
+`# taskchef_id=<full UUID>` heading already owns that delegated assignment.
+This includes former inline-protocol tasks that lack the skill invocation.
+An owned instruction must have exactly one accepted marker and a non-whitespace
+task-specific assignment. If it contains an executor-skill invocation, require
+exactly one as the final line. Marker-only, duplicate-marker, scaffold-only, or
+misplaced-invocation inputs are not valid delegated tasks. Execute a valid one
+in the current task. Do not re-dispatch it merely because it concerns TaskChef
+or a configured project. Explicit requests to delegate separate work remain
+valid.
+
+Use the bundled `prepare_dispatch`, `record_task`, and `report_state` MCP tools
+directly. Never fall back to shell writes. If a required tool is unavailable,
+stop and report that the TaskChef plugin must be reloaded or installed.
 
 ## Boundaries
 
@@ -43,16 +48,17 @@ reloaded or installed.
 3. Route against configured project `name`, `description`, and canonical
    `githubRepos`; use `path` only as checkout identity. Require exactly one
    match and an exact native-project path. Ask instead of guessing.
-4. Prefix each executor instruction with the preparation's exact marker as the
-   first line, a blank line, and these required paragraphs before the body:
-
-   > This task owns the delegated assignment. Execute it in this task; do not re-dispatch it merely because it concerns TaskChef or a configured project. Explicit requests to delegate separate work remain valid.
-
-   > Before any other work, read this executor's own durable Codex thread ID from the current task's CODEX_THREAD_ID environment value and call the TaskChef link_task MCP tool with that thread ID and the marked TaskChef task ID. Never use CODEX_SESSION_ID or the parent or delegator thread ID. If linking fails, CODEX_THREAD_ID is unavailable, or the tool is unavailable, report the failure visibly and retry on a later turn; do not guess an identity or continue substantive work while the task is link-pending.
-
-   > After a successful initial link, and at the start of every follow-up turn before substantive work, read this exact Codex thread natively to obtain the current turn ID and call TaskChef report_state with the marked task ID, the self-linked thread ID, that current turn ID, status working, and summary omitted or null. link_task remains the first TaskChef action on the initial turn; do not report working before identity is linked. Never reuse a prior turn ID after a follow-up.
-
-   > Before ending, read this exact Codex thread again and call TaskChef report_state for the same current working turn with status completed, needs_input, or failed and a concise summary. Use needs_input only for a semantic decision or information the user must provide; a native approval prompt is live Codex state, not a TaskChef result. Do not include secrets, transcripts, or raw command output.
+4. Build each executor instruction in this exact shape:
+
+   - Begin with the actual assignment on the first line and keep its complete
+     body uninterrupted.
+   - After the assignment, add one blank line and the preparation's exact
+     marker on its own line.
+   - Immediately after the marker, end the instruction with exactly:
+     `Use $taskchef-executor to execute and report this delegated TaskChef assignment.`
+   - Include exactly one marker and exactly one executor-skill invocation.
+   - Do not inline executor ownership, identity, linking, or result-reporting
+     protocol. The explicitly invoked executor skill owns those mechanics.
 
 5. Before creating each executor, call `record_task` exactly once with `id`,
    `project`, `title`, the exact marked `instruction`, and `threadId: null`.
@@ -63,23 +69,3 @@ reloaded or installed.
    when creation returns a durable ID; the child must self-link.
 8. If creation fails after recording, call `report_state` with `failed`, null
    thread/turn IDs, and a bounded summary before returning the failure.
-
-## Executor contract
-
-The executor must make `link_task(taskId, threadId)` its first TaskChef action.
-It obtains its own durable ID from the current task's `CODEX_THREAD_ID`, never
-from the delegation's `sourceThreadId`, `CODEX_SESSION_ID`, inherited session
-metadata, title matching, or a parent task.
-Identical retries are safe. A rejected link, unavailable tool, or interrupted
-initial turn leaves the record visibly link-pending and retryable; the executor
-must not guess or do substantive work first.
-
-After linking on the initial turn, and before substantive work on every later
-turn, the executor reads the exact thread and calls `report_state` with
-`working`, the current turn ID, and no summary. Before ending that same turn it
-reports a semantic state with the same turn ID and a summary. A follow-up must
-use the new turn ID. `needs_input` is only for a real user decision, not live
-approval UI.
-
-The filesystem watcher surfaces `link_task` and `report_state` writes to the
-dashboard. The linked child ID drives the exact Codex deep link.

package/skills/taskchef-executor/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: taskchef-executor
+description: "Execute an assignment carrying either the new exact TaskChef marker-plus-invocation scaffold or an accepted historical first-line TaskChef marker or inline protocol. Includes executor ownership, self-linking, per-turn lifecycle reporting, identity safety, and final semantic state. Use when explicitly invoked by a new delegated instruction or when resuming the same new or historical executor task. Do not use to dispatch work or report on other TaskChef tasks."
+---
+
+# TaskChef Executor
+
+Own and execute the delegated assignment in the current Codex task. Do not
+re-dispatch it merely because it concerns TaskChef or a configured project.
+Explicit requests to delegate separate work remain valid.
+
+New instructions present the complete assignment first, followed by one blank
+line, the exact `<!-- taskchef_id=<full UUID> -->` marker, and the final
+explicit skill invocation. Treat that UUID as the TaskChef task ID. The
+assignment is everything before the blank line that precedes the marker; the
+marker and invocation are lifecycle scaffolding, not part of the deliverable.
+Require exactly one marker and do not infer an ID from similar prose.
+
+## Start every execution turn
+
+Complete this lifecycle setup before substantive assignment work:
+
+1. Read this task's own durable Codex thread ID from `CODEX_THREAD_ID`. Never
+   use `CODEX_SESSION_ID`, `sourceThreadId`, a parent or delegator ID,
+   inherited metadata, title matching, recent-task search, transcripts, or a
+   provisional client ID.
+2. On the initial turn, call TaskChef `link_task` with the marked task ID and
+   that exact thread ID as the first TaskChef action. An identical retry is
+   idempotent. On a follow-up, retry the same link only when the prior link
+   cannot be established from the task context.
+3. Read this exact Codex thread natively and obtain the current turn ID. Do not
+   infer it or reuse an earlier turn ID.
+4. Call TaskChef `report_state` with the marked task ID, self-linked thread ID,
+   current turn ID, `status: working`, and an omitted or null summary.
+
+If `CODEX_THREAD_ID`, exact native thread reading, or a required TaskChef tool
+is unavailable, or if linking or the working-state report fails, report the
+failure visibly and stop before substantive work. Retry on a later turn. Never
+guess identity or bypass a link-pending state.
+
+## Finish every execution turn
+
+Before ending, read this exact Codex thread again and call `report_state` for
+the current turn with one semantic status and a concise summary:
+
+- `completed` only when the assignment is genuinely complete.
+- `needs_input` only when a semantic decision or missing information must come
+  from the user.
+- `failed` when the requested outcome cannot be completed or safely resumed.
+
+A live native approval prompt is Codex state, not semantic `needs_input`; leave
+the approval live instead of storing it as a TaskChef result. Never invent or
+reuse a turn ID after a follow-up. If a final-report response is lost, an
+identical retry is safe only while the same turn remains current. On a later
+turn, run the start lifecycle with its new current turn ID and report that
+turn's actual outcome. Say reporting failures visibly instead of claiming a
+tracked outcome.
+
+Summaries must omit secrets, transcripts, raw command output, hidden reasoning,
+and unnecessary personal data. Identical lifecycle retries are safe; never
+replace a same-turn report with different content or let an older turn
+overwrite newer state.
+
+## Compatibility
+
+Existing delegated tasks may include the former inline ownership, linking, and
+`report_result` paragraphs. Continue executing those tasks here without
+re-dispatching. Prefer `report_state` when available. If an older installed
+TaskChef exposes only `report_result`, follow its inline protocol; after an
+upgrade, the deprecated `report_result` alias remains available for exact
+legacy retries. Also accept historical instructions whose exact HTML marker is
+the first line, with or without the former blank line, and the older exact
+first-line `# taskchef_id=<full UUID>` heading. These compatibility forms do
+not change the identity or lifecycle rules above. For either first-line form,
+the assignment follows the marker. Ignore the final executor invocation and
+any recognizable former inline ownership, linking, working-state, or
+result-reporting paragraphs as lifecycle scaffolding; execute the remaining
+task-specific body. Require non-whitespace task-specific content and never
+treat an invocation by itself as an assignment.

package/skills/taskchef-executor/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TaskChef Executor"
+  short_description: "Run and report a delegated TaskChef assignment."
+  default_prompt: "Use $taskchef-executor to execute and report this delegated TaskChef assignment."

package/src/delegation.js

@@ -1,14 +1,42 @@
 import { randomUUID } from "node:crypto";
 
+/** @deprecated Historical v7 inline-prompt snapshot. New delegations use taskchef-executor. */
 export const EXECUTOR_OWNERSHIP_PARAGRAPH = "This task owns the delegated assignment. Execute it in this task; do not re-dispatch it merely because it concerns TaskChef or a configured project. Explicit requests to delegate separate work remain valid.";
+/** @deprecated Historical v7 inline-prompt snapshot. New delegations use taskchef-executor. */
 export const EXECUTOR_LINK_PARAGRAPH = "Before any other work, read this executor's own durable Codex thread ID from the current task's CODEX_THREAD_ID environment value and call the TaskChef link_task MCP tool with that thread ID and the marked TaskChef task ID. Never use CODEX_SESSION_ID or the parent or delegator thread ID. If linking fails, CODEX_THREAD_ID is unavailable, or the tool is unavailable, report the failure visibly and retry on a later turn; do not guess an identity or continue substantive work while the task is link-pending.";
+/** @deprecated Historical v7 inline-prompt snapshot. New delegations use taskchef-executor. */
 export const EXECUTOR_WORKING_PARAGRAPH = "After a successful initial link, and at the start of every follow-up turn before substantive work, read this exact Codex thread natively to obtain the current turn ID and call TaskChef report_state with the marked task ID, the self-linked thread ID, that current turn ID, status working, and summary omitted or null. link_task remains the first TaskChef action on the initial turn; do not report working before identity is linked. Never reuse a prior turn ID after a follow-up.";
+/** @deprecated Historical v7 inline-prompt snapshot. New delegations use taskchef-executor. */
 export const EXECUTOR_RESULT_PARAGRAPH = "Before ending, read this exact Codex thread again and call TaskChef report_state for the same current working turn with status completed, needs_input, or failed and a concise summary. Use needs_input only for a semantic decision or information the user must provide; a native approval prompt is live Codex state, not a TaskChef result. Do not include secrets, transcripts, or raw command output.";
+export const EXECUTOR_SKILL_INVOCATION = "Use $taskchef-executor to execute and report this delegated TaskChef assignment.";
+const HISTORICAL_RESULT_WITH_TURN_PARAGRAPH = "Before ending, call the TaskChef report_result MCP tool with the marked task ID, this executor's self-linked thread ID, the current turn ID from an exact native read of that same thread, completed, needs_input, or failed, and a concise summary. Never reuse a prior turn ID after a follow-up. Use needs_input only for a semantic decision or information the user must provide; a native approval prompt is live Codex state, not a TaskChef result. Do not include secrets, transcripts, or raw command output.";
+const HISTORICAL_RESULT_PARAGRAPH = "Before ending, call the TaskChef report_result MCP tool with completed, needs_input, or failed and a concise summary. Use needs_input only for a semantic decision or information the user must provide; a native approval prompt is live Codex state, not a TaskChef result. Do not include secrets, transcripts, or raw command output.";
+const HISTORICAL_EXECUTOR_SCAFFOLD_LINES = new Set([
+  EXECUTOR_OWNERSHIP_PARAGRAPH,
+  EXECUTOR_LINK_PARAGRAPH,
+  EXECUTOR_WORKING_PARAGRAPH,
+  EXECUTOR_RESULT_PARAGRAPH,
+  HISTORICAL_RESULT_WITH_TURN_PARAGRAPH,
+  HISTORICAL_RESULT_PARAGRAPH,
+]);
+const HISTORICAL_INLINE_PROTOCOLS = [
+  [EXECUTOR_OWNERSHIP_PARAGRAPH, EXECUTOR_LINK_PARAGRAPH, EXECUTOR_WORKING_PARAGRAPH, EXECUTOR_RESULT_PARAGRAPH],
+  [EXECUTOR_OWNERSHIP_PARAGRAPH, EXECUTOR_LINK_PARAGRAPH, HISTORICAL_RESULT_WITH_TURN_PARAGRAPH],
+  [EXECUTOR_OWNERSHIP_PARAGRAPH, HISTORICAL_RESULT_PARAGRAPH],
+  [EXECUTOR_OWNERSHIP_PARAGRAPH],
+];
+
+function hasTaskSpecificContent(lines) {
+  return lines.some((line) => (
+    line.trim().length > 0 && !HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line)
+  ));
+}
 
 const UUID_SOURCE = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
 const UUID_PATTERN = new RegExp(`^${UUID_SOURCE}$`);
 const CODEX_UUID_V7_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 const TASKCHEF_MARKER_PATTERN = new RegExp(`^<!-- taskchef_id=(${UUID_SOURCE}) -->$`);
+const LEGACY_TASKCHEF_MARKER_PATTERN = new RegExp(`^# taskchef_id=(${UUID_SOURCE})$`);
 
 function requireObject(value, name) {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${name} must be an object`);
@@ -84,20 +112,93 @@ export function taskChefMarker(taskId) {
 
 export function parseTaskChefMarker(instruction) {
   if (typeof instruction !== "string") return null;
-  const firstLine = instruction.split(/\r?\n/, 1)[0];
-  const currentMatch = firstLine.match(TASKCHEF_MARKER_PATTERN);
-  if (currentMatch === null) return null;
-  const prefix = instruction.match(/^([^\r\n]*)(\r?\n)\2/);
-  return prefix === null ? null : currentMatch[1];
+  const lines = instruction.split(/\r\n|\r|\n/);
+  const hasHistoricalAssignment = () => {
+    const rest = lines.slice(1);
+    const executorSkillInvocationIndices = rest.flatMap((line, index) => (
+      line === EXECUTOR_SKILL_INVOCATION ? [index] : []
+    ));
+    if (executorSkillInvocationIndices.length > 0) {
+      const bodyLines = rest.slice(0, -2);
+      return executorSkillInvocationIndices.length === 1
+        && executorSkillInvocationIndices[0] === rest.length - 1
+        && lines.at(-1) === EXECUTOR_SKILL_INVOCATION
+        && lines.at(-2) === ""
+        && bodyLines.length > 0
+        && bodyLines[0].trim().length > 0
+        && bodyLines.at(-1).trim().length > 0
+        && hasTaskSpecificContent(bodyLines)
+        && !bodyLines.some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line));
+    }
+
+    const containsInlineScaffold = rest.some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line));
+    if (!containsInlineScaffold) return rest.join("\n").trim().length > 0;
+    return HISTORICAL_INLINE_PROTOCOLS.some((protocol) => {
+      const prefix = ["", ...protocol.flatMap((line) => [line, ""])];
+      if (!prefix.every((line, index) => rest[index] === line)) return false;
+      const bodyLines = rest.slice(prefix.length);
+      return hasTaskSpecificContent(bodyLines)
+        && !bodyLines.some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line));
+    });
+  };
+  const currentMatches = lines.flatMap((line, index) => {
+    const match = line.match(TASKCHEF_MARKER_PATTERN);
+    return match === null ? [] : [{ id: match[1], index }];
+  });
+  const legacyMatches = lines.flatMap((line, index) => {
+    const match = line.match(LEGACY_TASKCHEF_MARKER_PATTERN);
+    return match === null ? [] : [{ id: match[1], index }];
+  });
+  if (currentMatches.length + legacyMatches.length !== 1) return null;
+
+  if (legacyMatches.length === 1) {
+    const [{ id, index }] = legacyMatches;
+    if (index !== 0) return null;
+    return hasHistoricalAssignment() ? id : null;
+  }
+
+  const [{ id, index }] = currentMatches;
+  if (index === 0) {
+    return hasHistoricalAssignment() ? id : null;
+  }
+  const executorSkillReferences = instruction.match(/\$taskchef-executor\b/gi) ?? [];
+  const isTrailingScaffold = index === lines.length - 2
+    && index >= 2
+    && lines[0].trim().length > 0
+    && lines.at(-3) === ""
+    && lines.at(-4).trim().length > 0
+    && lines.at(-1) === EXECUTOR_SKILL_INVOCATION
+    && hasTaskSpecificContent(lines.slice(0, index - 1))
+    && !lines.slice(0, index - 1).some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line))
+    && executorSkillReferences.length === 1;
+  return isTrailingScaffold ? id : null;
 }
 
 export function prepareDelegation(instruction, { taskId = randomUUID() } = {}) {
-  requireString(instruction, "instruction");
-  if (parseTaskChefMarker(instruction) !== null) throw new Error("instruction already contains a TaskChef marker");
+  const rawBody = requireString(instruction, "instruction");
+  if (/^[^\S\r\n]*(?:\r\n|\r|\n)/.test(rawBody)) {
+    throw new Error("instruction must begin with useful task content on its first line");
+  }
+  const body = rawBody.replace(/(?:(?:\r\n|\r|\n)[^\S\r\n]*)+$/, "");
+  if (body.split(/\r\n|\r|\n/).some((line) => (
+    TASKCHEF_MARKER_PATTERN.test(line) || LEGACY_TASKCHEF_MARKER_PATTERN.test(line)
+  ))) {
+    throw new Error("instruction already contains a TaskChef marker");
+  }
+  if (/\$taskchef-executor\b/i.test(body)) {
+    throw new Error("instruction contains a reserved TaskChef executor skill reference");
+  }
+  const bodyLines = body.split(/\r\n|\r|\n/);
+  if (!hasTaskSpecificContent(bodyLines)) {
+    throw new Error("instruction must contain task-specific content, not only TaskChef lifecycle scaffolding");
+  }
+  if (bodyLines.some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line))) {
+    throw new Error("instruction contains reserved historical TaskChef lifecycle scaffolding");
+  }
   const id = requireUuid(taskId);
   return {
     id,
-    instruction: `${taskChefMarker(id)}\n\n${EXECUTOR_OWNERSHIP_PARAGRAPH}\n\n${EXECUTOR_LINK_PARAGRAPH}\n\n${EXECUTOR_WORKING_PARAGRAPH}\n\n${EXECUTOR_RESULT_PARAGRAPH}\n\n${instruction}`,
+    instruction: `${body}\n\n${taskChefMarker(id)}\n${EXECUTOR_SKILL_INVOCATION}`,
   };
 }
 

package/src/mcp.js

@@ -68,7 +68,7 @@ export function createTaskChefMcpServer({
     { name: "taskchef", version: "1.0.0" },
     {
       instructions:
-        "Prepare with prepare_dispatch, call record_task before creating the Codex task, then create it natively and return immediately. The executor must call link_task first, report_state working at the start of each execution turn, and report_state with a semantic outcome before ending.",
+        "Prepare with prepare_dispatch, call record_task before creating the Codex task, then create it natively and return immediately. Follow the active TaskChef skill for role-specific sequencing of the identity and state tools.",
     },
   );
 
@@ -114,7 +114,7 @@ export function createTaskChefMcpServer({
     },
     async (input) => {
       if (parseTaskChefMarker(input.instruction) !== input.id) {
-        throw new Error("record_task instruction must start with its exact TaskChef marker");
+        throw new Error("record_task instruction must contain its exact TaskChef marker in an accepted scaffold");
       }
       const task = await record(workspace, input);
       return toolResult("task", task, `Recorded TaskChef task ${task.id}.`);

package/src/workspace.js

@@ -737,7 +737,7 @@ async function validateDispatchShape(dispatch, name = "task") {
     id,
     project,
     title: requireString(dispatch.title, `${name}.title`).trim(),
-    instruction: requireString(dispatch.instruction, `${name}.instruction`).trim(),
+    instruction: requireString(dispatch.instruction, `${name}.instruction`),
     threadId: dispatch.threadId === null
       ? null
       : normalizeDurableThreadId(dispatch.threadId, `${name}.threadId`),