feat(ce-dispatch): single-unit sync MVP rewrite

.compound-engineering/config.local.example.yaml

@@ -12,14 +12,14 @@
 # work_delegate_effort: high     # minimal | low | medium | high | xhigh (omit to use ~/.codex/config.toml default)
 
 # --- Dispatch (external workspace delegation) ---
-# Settings for /ce-dispatch, which fans out plan implementation units to
-# external agent workspaces (e.g., Conductor) via GitHub issues.
+# Settings for /ce-dispatch, which hands one plan implementation unit at a time
+# off to an external agent workspace (e.g., Conductor) via a GitHub issue.
+# Single-unit sync MVP: orchestrator and agent coordinate via issue comments
+# and the resulting PR; the user pings each side manually.
 
-# dispatch_mode: conductor       # conductor | <other identifier> (default: conductor)
 # dispatch_branch_prefix: dispatch/   # branch prefix suggested in dispatch prompts (default: dispatch/)
 # dispatch_base_branch: main     # PR base branch (default: repo default branch)
 # dispatch_labels: ce-dispatch   # comma-separated labels applied to created issues (default: ce-dispatch)
-# dispatch_auto_review: true     # true | false (default: true) -- auto-run ce-code-review on each new PR
 
 # --- Product pulse ---
 # Settings written by /ce-product-pulse first-run interview. Re-run the skill with

plugins/compound-engineering/skills/ce-dispatch/references/conductor-notes.md

@@ -61,5 +61,5 @@ Source: [Workflow](https://www.conductor.build/docs/concepts/workflow), [From is
 
 - **Label** (default `ce-dispatch`): so humans can filter their issue list; not a Conductor requirement.
 - **Branch name suggestion** (`dispatch_branch_prefix` + U-ID + slug): so the orchestrator can correlate PRs back to U-IDs in Phase 4; the in-workspace agent is encouraged but not forced to honor it.
-- **HTML metadata comment in the issue body** (plan path, U-ID, dependencies, expected branch, base branch): structured data the orchestrator parses on subsequent runs to detect dependency state without rebuilding the graph from scratch. The HTML comment renders invisibly to humans on GitHub but stays parseable.
+- **HTML metadata comment in the issue body** (plan path, U-ID, agent name, worktree path, expected branch, base branch, labels, dispatched-at timestamp): structured data the orchestrator parses on subsequent runs so the Phase 4 respond loop can pick up where the user left off without re-asking for the worktree path or branch metadata. The HTML comment renders invisibly to humans on GitHub but stays parseable. Single-unit MVP: dependency-graph state is intentionally not part of the metadata; multi-unit dispatch (when it returns) can re-introduce that field.
 - **PR-based output contract** (a `## Dispatch Result` section in the PR description): replaces ce-work-beta's `--output-schema` JSON, since dispatched agents don't have a shared scratch directory with the orchestrator. The PR description is the durable handoff surface.

plugins/compound-engineering/skills/ce-dispatch/references/dispatch-prompt-template.md

@@ -1,47 +1,74 @@
 # Dispatch Prompt Template
 
-Build the dispatch prompt for each implementation unit (or coalesced batch of units with no inter-batch dependencies) using the XML-tagged sections below. The full rendered prompt becomes the **GitHub issue body** so the in-workspace agent (e.g., a Conductor workspace opened from the issue) sees the entire instruction set as its starting context.
+Build the dispatch prompt for a single implementation unit using the XML-tagged sections below. The full rendered prompt becomes the **GitHub issue body** so the in-workspace agent (e.g., a Conductor workspace opened in the user-supplied worktree) sees the entire instruction set as its starting context.
 
-The prompt is intentionally self-contained: do not assume the in-workspace agent has access to scratch directories, side-channel files, or shared state with the dispatching orchestrator. The plan file is referenced by repo-relative path so the agent can `Read` it for additional context.
+The prompt is intentionally self-contained: do not assume the in-workspace agent has access to scratch directories, side-channel files, or shared state with the dispatching orchestrator. The plan file and orientation files are referenced by repo-relative path so the agent can `Read` them for additional context (progressive context exposure -- list paths, do not inline content).
+
+This template is for **single-unit sync MVP dispatch**. Multi-unit fan-out, dependency-graph metadata, and parallel coordination hints are intentionally not part of this template.
 
 ## Required structure
 
 Render exactly these sections, in this order. Keep the XML tags so downstream tooling (and the contract test) can validate structure.
 
 ```xml
+<orientation>
+[A checklist of repo-relative paths the agent should `Read` first, before doing
+any work. Include only paths that exist in the target repo. Recommended set:
+- The plan file (this unit was extracted from it)
+- README.md
+- AGENTS.md (and CLAUDE.md if it diverges from AGENTS.md; root-level and any
+  plugin-scoped equivalents the unit touches)
+- docs/architecture.md, docs/architecture/, or any top-level architecture doc
+- The unit's `Patterns to follow` files (verbatim from the unit)
+- The unit's `Files:` paths so the agent reads existing code before editing
+
+Render as a Markdown bullet list with each path inline-quoted in backticks.
+The agent reads these to come in green and build context, rather than the
+orchestrator wasting prompt tokens inlining the content here.]
+</orientation>
+
+<agent-identity>
+[The agent's name and worktree absolute path, supplied by the user when
+ce-dispatch was invoked.
+
+Render as:
+- agent-name: `<worktree dirname, e.g. jackson>`
+- worktree-path: `<absolute path, e.g. /Users/you/conductor/workspaces/repo/jackson>`
+
+The agent uses `agent-name` to sign comments on this issue
+(`[<agent-name> -> orchestrator]`). The orchestrator addresses the agent the
+same way (`[orchestrator -> <agent-name>]`). It is purely a label -- no
+infrastructure depends on it.]
+</agent-identity>
+
 <context>
 [One paragraph orienting the in-workspace agent:
 - Plan file path (repo-relative) the unit was extracted from
 - One-sentence project context (read from plan frontmatter / repo README if available)
 - Note that this issue was created by ce-dispatch and corresponds to a single
-  implementation unit (or a small batch of independent units) from the plan.
-The agent should `Read` the plan file for the full picture before starting.]
+  implementation unit from the plan.
+The agent should `Read` the plan file (and the orientation files above) for
+the full picture before starting.]
 </context>
 
 <task>
-[For a single-unit dispatch: Goal from the implementation unit, verbatim.
-For a coalesced multi-unit dispatch: list each unit with its U-ID and Goal,
-stating the concrete job, repository context, and expected end state for each.
-Multi-unit dispatch is only valid when the units have no dependencies on each
-other and share enough context that batching is more efficient than separate
-issues -- otherwise prefer one issue per unit.]
+[The Goal from the implementation unit, verbatim. Single-unit dispatch only --
+no multi-unit coalescing in this template.]
 </task>
 
 <files>
-[Combined file list from the unit(s) -- files to create, modify, or read.
+[The unit's combined file list -- files to create, modify, or read.
 Use the plan's `Files:` section as the source of truth. Repo-relative paths only.]
 </files>
 
 <patterns>
-[File paths and conventions from the unit(s) "Patterns to follow" fields. If no
+[File paths and conventions from the unit's "Patterns to follow" field. If no
 patterns are specified: "No explicit patterns referenced -- follow existing
 conventions in the modified files."]
 </patterns>
 
 <approach>
-[For a single-unit dispatch: Approach from the unit, verbatim.
-For a multi-unit dispatch: list each unit's approach, noting any suggested
-ordering within the batch.]
+[The Approach from the unit, verbatim.]
 </approach>
 
 <constraints>
@@ -63,8 +90,9 @@ ordering within the batch.]
 - Resolve the task fully before opening the PR. Do not stop at the first
   plausible implementation if verification has not passed.
 - If you discover mid-execution that the unit's scope is wrong, the plan is
-  inconsistent, or required context is missing, surface that in the PR body's
-  `Issues` field rather than silently expanding scope.
+  inconsistent, or required context is missing, surface that in a new comment
+  on this issue using the `<comment-protocol>` below -- do not silently
+  expand scope.
 </constraints>
 
 <testing>
@@ -88,38 +116,101 @@ fix the issues and re-run until they pass. Do not open the PR until
 verification passes -- the orchestrator will not re-run verification before
 merging.
 
-[Test and lint commands from the project. Use the union of the unit(s)
-verification commands as a single combined invocation.]
+[Test and lint commands from the project. Use the unit's verification
+commands as a single combined invocation.]
 </verify>
 
 <ce-plugin>
-The Compound Engineering (CE) plugin may be installed in this workspace --
-check by running the platform's plugin/skill listing command, or by listing
-skills available to the harness. Two execution paths:
-
-- **Option A (preferred when CE plugin is installed):** Invoke `/ce-work` with
-  the plan path passed as the argument (use the platform's skill-invocation
-  primitive: `Skill` in Claude Code, `Skill` in Codex, the equivalent on
-  Gemini/Pi). `ce-work` reads the plan, builds a task list scoped to this
-  unit's U-ID, follows the project's patterns, and runs the standard
-  shipping workflow.
-- **Option B (CE plugin not installed):** Follow the `<task>`, `<files>`,
-  `<patterns>`, `<approach>`, `<constraints>`, `<testing>`, and `<verify>`
-  sections in this prompt directly without delegating to a CE skill.
-
-Once implementation passes verification, commit and push. If the CE plugin is
-installed, prefer `/ce-commit-push-pr` to author commits and open the PR with
-project-aware metadata. Otherwise commit with `git commit`, push with
-`git push`, and open the PR with the harness's PR action or `gh pr create`.
-
-The CE plugin is optional. The dispatch prompt is fully self-contained
-without it.
+The Compound Engineering (CE) plugin is the recommended path for this
+dispatch. Follow the **nine-step sequence** below. Each step is explicit so
+the agent runs the full compound-engineering loop end-to-end (work -> code
+review -> compound -> PR -> standby for feedback).
+
+1. **Read the orientation files** in `<orientation>` above. Build context
+   before doing any work. Do not skip this -- the orchestrator selected
+   these files specifically.
+2. **Run `/ce-work`** with the plan path passed as the argument (use the
+   platform's skill-invocation primitive: `Skill` in Claude Code, `Skill`
+   in Codex, the equivalent on Gemini/Pi). `ce-work` reads the plan, builds
+   a task list scoped to this unit's U-ID, and walks the implementation.
+   If `ce-work` produces a task list that needs the orchestrator's input
+   (ambiguity, missing context, scope question), STOP and use the
+   `<comment-protocol>` to ask -- do not proceed past the question.
+3. **Implement and verify** per `<task>`, `<files>`, `<patterns>`,
+   `<approach>`, `<constraints>`, `<testing>`, and `<verify>` above.
+4. **Run `/ce-code-review`** against your branch before opening the PR.
+   Use the platform's skill-invocation primitive. Address findings inline
+   if straightforward; defer to the orchestrator via the comment protocol
+   if the finding implies architectural change.
+5. **Run `/ce-compound`** if the unit produced learnings worth capturing
+   (a non-obvious bug fix, a pattern that should be documented, a
+   reproducible failure mode). Skip when there are no learnings.
+6. **Run `/ce-commit-push-pr`** to commit the work, push the branch, and
+   open the PR with an adaptive description. If `ce-commit-push-pr` is not
+   available in this workspace, fall back to `git commit && git push &&
+   gh pr create` and write the `## Dispatch Result` section by hand per
+   `<output-contract>`.
+7. **Append a comment** to this issue with the PR URL. Format:
+   `**[<agent-name> -> orchestrator] <ISO 8601 UTC>**\n\nPR opened: <pr-url>. Standing by for review.`
+8. **Stop. Wait for orchestrator ping.** Do not poll. Do not start the
+   next unit. Conductor (or the user) will surface the new orchestrator
+   comment to you when the orchestrator replies.
+9. **On orchestrator ping** with PR feedback: run `/ce-resolve-pr-feedback`
+   on the PR (use the platform's skill-invocation primitive). On
+   orchestrator ping with an issue-comment clarification: re-read the
+   issue thread, then continue the work. Loop until the orchestrator
+   approves the PR.
+
+If the CE plugin is **not** installed in this workspace, fall back to
+following `<task>`, `<files>`, `<patterns>`, `<approach>`, `<constraints>`,
+`<testing>`, and `<verify>` directly, and use `git` + `gh` for the
+commit/push/PR steps. The compound-engineering sequence still applies; only
+the skill invocations are replaced with manual equivalents.
 </ce-plugin>
 
+<comment-protocol>
+Use issue comments **only for clarifications** you cannot resolve from this
+issue body and the orientation files. Routine progress updates do not
+belong in comments -- the PR description is the durable progress surface.
+
+**When to comment:**
+- A decision you cannot make from this issue body alone changes a public
+  interface.
+- A decision introduces a new dependency or pattern not already in
+  `<patterns>` or the orientation files.
+- The unit's stated approach turns out to be wrong, inconsistent with the
+  plan, or missing required context.
+- Verification reveals the plan itself is wrong (e.g., the test scenarios
+  contradict the goal).
+
+**Format:**
+- Open a new comment on this issue.
+- First line: `**[<agent-name> -> orchestrator] <ISO 8601 UTC timestamp>**`
+- Then a blank line, then the body. The body must include:
+  1. **Question** -- one or two sentences naming the decision.
+  2. **What you considered** -- options you evaluated and why none was
+     obvious.
+  3. **What you need from the orchestrator** -- the specific input that
+     unblocks you.
+
+**After commenting:**
+- STOP. Do not proceed past the open question. Do not start the next
+  related task. Wait for an `**[orchestrator -> <agent-name>] <timestamp>**`
+  reply.
+- On reply, re-read the full comment thread before continuing.
+- If the reply does not fully unblock, ask a follow-up using the same
+  format and stop again.
+
+The orchestrator addresses you in the same shape:
+`**[orchestrator -> <agent-name>] <ISO 8601 UTC>**` followed by the reply
+body. You should be able to identify orchestrator replies unambiguously
+from the prefix.
+</comment-protocol>
+
 <output-contract>
 Report the result via the **PR description**, not via a JSON file or scratch
-artifact -- ce-dispatch reads the PR body to drive Phase 4 monitoring,
-review, and merge gating.
+artifact -- ce-dispatch reads the PR body in the Phase 4 respond loop to
+drive review and merge gating.
 
 Render this section verbatim under a top-level `## Dispatch Result` heading
 in the PR description (Markdown, not XML in the rendered PR):
@@ -144,7 +235,7 @@ in the PR description (Markdown, not XML in the rendered PR):
 (e.g., `bun test -- 14 passed, 0 failed` or `pytest -- exit code 0`).
 If verification was not possible, say why.
 
-**Unit ID:** the U-ID(s) this PR satisfies (e.g., `U3` or `U3, U5`).
+**Unit ID:** the U-ID this PR satisfies (e.g., `U3`).
 **Plan path:** the repo-relative plan file path.
 </output-contract>
 ```
@@ -156,21 +247,24 @@ Append the following HTML comment **outside** the `<output-contract>` block, at
 ```html
 <!-- ce-dispatch-metadata
 plan: <repo-relative plan path>
-unit_ids: <comma-separated U-IDs in this dispatch, e.g. U3 or U3,U5>
-dependencies: <comma-separated U-IDs this dispatch depends on, or "none">
+unit_id: <single U-ID for this dispatch, e.g. U3>
+agent_name: <worktree dirname, e.g. jackson>
+worktree_path: <absolute path the user supplied>
 expected_branch: <suggested branch name, e.g. dispatch/U3-add-rate-limiter>
 base_branch: <base branch the eventual PR targets, e.g. main>
 labels: <comma-separated labels applied to the issue>
 dispatched_at: <ISO 8601 UTC timestamp>
 -->
 ```
 
+Note: `dependencies:` is intentionally absent from the metadata in this single-unit MVP. Dependency-graph orchestration is out of scope for the MVP; the orchestrator does not gate merges on dependency state. A future iteration can re-introduce the field when multi-unit dispatch returns.
+
 ## What the orchestrator does NOT include in the prompt
 
 - **Scratch directory paths**: the in-workspace agent has its own filesystem; do not reference paths from the orchestrator's machine.
 - **Codex CLI invocation flags or `--output-schema` artifacts**: `ce-dispatch` does not delegate to `codex exec` directly; the in-workspace agent runs whatever harness Conductor (or another platform) provides.
-- **Orchestrator-private state**: dependency graphs, parallel-safety analysis, or the dispatch order. The in-workspace agent only needs its own unit context.
+- **Orchestrator-private state**: dependency graphs, parallel-safety analysis, dispatch order. The single-unit MVP does not produce any of those.
 
 ## Token budget guidance
 
-Keep the rendered prompt under ~8k tokens when possible. If a unit's plan section is large, link to the plan via repo-relative path inside `<context>` rather than inlining the full text — the agent can `Read` it.
+Keep the rendered prompt under ~8k tokens when possible. The `<orientation>` block is the main lever: list paths, do not inline content. If a unit's plan section is large, link to the plan via repo-relative path inside `<context>` rather than inlining the full text -- the agent can `Read` it.