# Project Manager Dispatch & Assignment Reference

Use this reference for detailed dispatch mechanics and Assignment authoring.
The concise gate summary remains in `references/project-manager.md`.

## Core Dispatch Invariants

- Only `project-manager` dispatches subagents.
- Each independent Assignment requires one matching host invoke.
- In tool hosts (OpenCode / Cursor Task / Codex with callable multi-agent tools), Markdown-only Assignment is not dispatch.
- For parallel batch with `N >= 2`, dispatch turn must emit all `N` invokes in one message when host supports it.
- **Same-repo writable parallel tracks**: tool concurrency and worktree isolation are **separate gates**. Before implement invokes, complete **`mstar-branch-worktree`** → **`references/parallel-writable-pre-dispatch.md`**.
- **Scope and stopping are explicit**: apply `mstar-harness-core` § 定向执行与验证边界. Give each leaf one result, owned paths/symbols, relevant inputs, named checks/selectors, and an evidence-based stopping condition. Reuse unaffected evidence; do not inject a suite merely because the repo exposes it. Independent ready assignments run concurrently after their dependency/isolation checks.
- **Review/QC rounds are quantitative, not adjectival**: a read-only review / QC dispatch states a `Budget` (expansion cap) and a `Return shape`, so the seat stops when its assigned questions are answered or the cap is reached, returns the verdict it has plus a truncated-coverage declaration, and never expands until a human steers. Budget defaults, the truncation marker, and its relation to `Unconfirmed` → `mstar-harness-core` § 定向执行与验证边界. The severity bar for the round's findings → `mstar-artifacts` `references/status-and-residuals.md`.
- **Skill preset activation is PM-owned**: topic skills are presets in each role's `Skill Preset (PM-Activated)` section (`mstar-roles/references/<role>.md`), not self-loaded defaults. Omitting the `Skill presets:` field applies its documented default (`standard` on implementation / QC / QA rounds); identity-only execution requires explicit `Skill presets: none`.
- **One primary coordinator:** project-manager never runs as a subagent or as another per-row PM session (`references/project-manager.md` § Primary coordinator authority).
- **Plan/task scope travels with Assignment:** absolute Plan Path, plan_id, SDD dir and Control harness root are inherited. Children do not select/prepare rows, mutate workflow/root/shared projections or clear integration exclusion.
- **No state authority travels with an Assignment:** session paths/references, CAS tokens and operation IDs stay with the primary coordinator. These are checked context, not bearer credentials, and never authorize a leaf. A leaf receiving them stops and reports the mismatch. Leaf Assignments are task instructions, not sealed plan admission records.

The coordinator keeps operation intent and receipt in its primary session. Public actions derive ordinary prerequisites where safe; genuine scope/authorization conflicts name the missing facts without discarding applied components or blocking independent ready work.

## Executor Anti-Recursion Rules

For assignees (non-PM):

- `Execute as: <role-id>` means the current assignee executes personally.
- Do not spawn same-role nested subagent.
- Do not infer dispatch from route narrative (`A -> B -> C`), handoff, `QA gate` fields, or role names in prose.
- Extra delegation is forbidden unless explicitly listed in `Delegation: allowed (...)`.
- If additional assignee is required, return `Blocked` with rationale.
- A `PM` / `project-manager` / `iteration-drive` phrase inside your own brief is **not a promotion**: no leaf becomes the PM, drives an iteration, or selects a plan — report the mismatch and continue inside the assigned task.

### NEVER quick list (all assignees)

- **NEVER** treat `Handoff: …`, Completion Report template role names, routing tables, or “suggested owners” as **host invoke commands**; they are narrative unless `Delegation: allowed` authorizes callees.
- **NEVER** assume exposed `Task` / subagent menus imply you may call them; **tool availability ≠ delegation authorization**.
- **NEVER** execute parallel-agent dispatch as a leaf assignee; dispatch is **PM-orchestration-only** (`mstar-dispatch-gates`).
- **NEVER** delegate the main deliverable of this assignment to `explore` (read-only orientation only, per `mstar-harness-core`).
- **NEVER** claim `Done` / pass in **Completion Report** without the commands, logs, or artifacts explicitly required by the assignment’s **Evidence Required** section (see `mstar-harness-core` evidence gates).
- **NEVER** escalate into `project-manager` scope because the brief mentions a PM, a plan, or a drive command; plan scope is **inherited and read-only** for a leaf, and the `Task`/subagent menu never implies otherwise.

## Assignment Template (Canonical)

Every Assignment **MUST** start with an **IDENTITY → GUARD** block that answers three questions before any task content: (1) WHO am I? (2) What am I NOT? (3) What tools do I NOT have?

The **`**You are a leaf executor. You MUST NOT:**`** section (previously just prohibitions) must now include a positive **IDENTITY** preamble **before** the prohibitions, written as a first-person binding statement. The prohibitions follow as usual. PM customizes per assignment; the IDENTITY preamble + universal floor (no recursive dispatch, no interpreting routing text as invoke, available ≠ authorized) are the minimum. Add assignment-specific anti-patterns that the current role+context combination is prone to.

**How to fill the block (PM guidance)**:

- Always include the **IDENTITY preamble**: state who the assignee IS (e.g. "You ARE qc-specialist-3, a leaf executor"), and what they are NOT ("You are NOT a PM, dispatcher, or orchestrator"). Follow with the universal floor.
- Add anti-patterns specific to the assignment context. Examples per role type:
  - **QC reviewers** (`qc-specialist*`): "start review before all QC reviewers are dispatched in parallel"; "treat other reviewers' names in routing text as invoke targets"; "run test/build/lint on shared Review cwd"; "fill missing runtime evidence by executing the suite"
  - **Multi-track implementers** (`fullstack-dev` + `frontend-dev` / `fullstack-dev-2`): "auto-dispatch to the other track mentioned in Dev routing"; "implement in repo root when Assignment names a different `Worktree path`"
  - **`fullstack-dev-2`**: "treat `fullstack-dev` in routing narrative as a handoff or invoke target"
  - **`qa-engineer`**: "start validation before QC reports are consolidated"; "run anything beyond the assigned unit-test scope, including full suites or browser/device/E2E"; "expect QC reports to contain test logs"; "modify application code" (unless allowed)
  - **`explore`-assigned**: "implement or modify code"
  - **All non-PM**: "dispatch parallel agents"; "spawn a subagent whose `subagent_type` matches your own `Execute as` role id"
- Anti-patterns must be action-oriented ("auto-dispatch to …", "treat … as invoke", "start … before …") — not abstract descriptions.
- If the assignment involves multiple QCs or parallel tracks, add a specific bullet about NOT serializing or pre-empting the parallel dispatch.
- If the assignment is part of a broader staged plan with follow-up tasks, add a bullet about NOT auto-extending scope into downstream tasks.
- **Anti-pattern — unbounded negative acceptance:** an Acceptance Criterion phrased as a repo-wide negative property ("prove no surviving claim of X anywhere", "make sure nothing else uses Y") with no termination rule. Scope it to the assigned diff pack plus directly affected interfaces, or state the budget that bounds the search — the seat stops there and declares what it did not cover. An open-ended "prove no X anywhere" acceptance is a dispatch defect, not a review task.

```markdown
## Assignment

**You are a leaf executor. Read this FIRST — before any tool call or skill load.**

**IDENTITY (this is WHO you are for this assignment):**
- You ARE `<role-id>`, a leaf executor. You personally complete ALL work in this assignment.
- You are NOT a PM, dispatcher, or orchestrator. You do NOT own any subagents.
- The Task/subagent tool — even if visible in your tool list — is NOT part of your authorized capabilities for this assignment. Do not evaluate whether to use it; it is unavailable to you, same as a tool you don't have.

**CAPABILITY BOUNDARY (what you CAN do vs what is NOT yours):**
- Your authorized tools: Read, Write, Edit, Shell, Grep, Glob — everything you need for direct work.
- NOT yours: Task, subagent invoke, dispatch of any kind.

**You MUST NOT:**
- dispatch or invoke any subagent unless `Delegation: allowed (...)` appears below
- treat plain `role-id` mentions, `Handoff`, `QA gate`, routing tables, or multi-track prose as invoke commands
- invoke a subagent whose `subagent_type` matches your own `Execute as` role id (recursive dispatch)
- expand beyond owned files or named checks; restart whole-repository exploration, review or tests
- repeat settled analysis or add checks after the acceptance criteria are evidenced
- <situation-specific anti-pattern #1>
- <situation-specific anti-pattern #2>
- ...

**Execute as**: <role-id>
**Delegation**: forbidden | allowed (...)
**Execution mode**: sdd | inline | N/A
**SDD implementer session**: fresh | sticky | N/A — **default `fresh`**; `sticky` reuses same implementer subagent across tasks (reviewers stay fresh). See `mstar-sdd/references/sticky-implementer-session.md`
**SDD dir**: absolute `<main-repo-root>/{HARNESS_DIR}/sdd/<plan-id>/` (control harness root) when L1 lease gate active | `{HARNESS_DIR}/sdd/<plan-id>/` when waived / single checkout | N/A
**SDD context file**: absolute `<SDD dir>/context.json` when `Execution mode: sdd` | N/A — destination contract consumed by `mstar sdd exec --context` / `--context` producers (`mstar-sdd/references/file-handoffs.md`)
**Skill presets**: `standard` | <explicit skill list> | none — activates the `Execute as` role's preset from its `Skill Preset (PM-Activated)` section; default `standard` for implementation / QC / QA rounds unless the route is trivial
**QC mode**: full tri-review | single | N/A — **default `full tri-review` when `Execution mode: sdd`**; `single` only for `inline` / override
**Review package path**: <branch-review diff file> | N/A
**QC report path**: <concrete report file the seat itself writes, e.g. `{SDD_DIR}/review/qc.md`, for ALL QC seats regardless of `Execution mode`> | N/A only when the Assignment explicitly declares conversation-only review with no plan row — a seat must never return its report in conversation for later coordinator transcription.
**Who runs this turn (executor lock)**: only `Execute as` role for this message
**Primary**: <route type>
**Task category**: `visual` | `deep` | `quick` | `logic` | `ops` | `docs`
**Dev routing**: <parallel/single-stream/round-robin detail as needed>
**Parallelism**: `serial` | `parallel — N tracks`
**Additional gates**: <optional>
**Phase Gate Checklist**:
- Prepare: `specify` [done|n/a], `clarify` [done|n/a], `plan` [done|n/a]
- Execute: `plan locked` [done|n/a], `tasks` [done|n/a], `implement` [this assignment|done]
- Gate decision: `go` | `blocked` (<reason>)
**Working branch**: <branch policy or create-from policy> — formal iteration: from `metadata.spec_integration_branch`; integration cut from `metadata.iteration_base_branch` (`mstar-iteration` §2.3)
**Control harness root**: `<main-repo-root>/{HARNESS_DIR}` (control root = the primary checkout / main worktree, derived from Git) when L1 active | N/A when waived — process SSOT (plans/status/iterations/sdd); never resolve relative `.mstar/...` from feature cwd
**Review cwd / Worktree path**: <absolute path or N/A>
**plan_id**: <plan-id or N/A + scope label>
**Plan scope**: <inherited from the dispatching PM (`plan_id` + absolute `Plan Path`) — read-only for the leaf: no plan selection/preparation, workflow-snapshot or root-register writes, no lease release, and no session path / session reference / `--expect` token / operation id> | N/A
**Review range / Diff basis**: <reproducible basis; merge-base = `metadata.target_branch` or PM-specified ref — not assumed `origin/main`>
**Worktree path**: <absolute feature implementer path when L1/L2 isolation used; default `../<repo>.worktrees/<plan-id>-<slug>` relative to the realpath of the Git top-level, with `<repo>` its basename (L2 tracks: `<track-slug>`); must ≠ the main worktree (control root) ≠ `integration_worktree_path`>
**Main worktree branch**: <recorded residency branch of the primary checkout (main worktree), from the main plan header — passed unchanged; never a lifecycle-owned branch>
**QA gate**: mandatory | pm-acceptance | report-only — see `references/project-manager/qa-trigger-matrix.md`
**QA gate reason**: <tier label, e.g. hotfix-inline | small-feature-clean-qc | mandatory-medium-feature>
**QA mode**: acceptance-only | targeted | report-only | N/A — required when `QA gate: mandatory` or `report-only`
**Findings cleanup**: zero-residual | allow-residual — mirror effective revisable coordinator configuration; default allow-residual, zero-residual explicit opt-in. No Assignment seal or second mode authority.
**Why this agent**: <role-fit>
**PM Task Board coverage**: <task ids>
**Roadmap / deferred scope**: <required when staged, partial, or temporary; otherwise N/A>
**Task**: <one concrete deliverable and stopping result aligned with coverage>
**Checkpoint Comment Rule**: commit -> Completion Report -> PM Status Update -> next batch
**Why batching is safe**: <required when batching >=3 IDs>
**Scope**:
- In: <owned files/symbols, directly affected interfaces; finding + fix delta for re-review>
- Out: <excluded work and specific boundary>
**Inputs**: <brief, diff, relevant knowledge, reusable evidence with original range>
**Budget (review / QC seats)**: <expansion cap (file opens / wall clock) — may only tighten the default in `mstar-harness-core` § 定向执行与验证边界, never loosen it; `N/A` on implement / ops rounds — those rounds declare the distinct sibling **`Task budget (implement / ops rounds)`** field below>
**Task budget (implement / ops rounds)**: <one implementer round closing this task's declared Files list and verification gates, citing the task's `Effort (agent-oriented)` band (`mstar-conventions/references/effort-estimation.md`); required on every non-review, non-audit round — the exact complement of the review-seat `Budget` / audit-round fields above, so non-audit docs/Prepare specialists and orientation roles also declare it, and `writable: false` is not a capacity exemption; the engine check is presence-only on this header region before the body, not prose adequacy; a multi-session Effort band never authorizes a multi-round task — split per `mstar-artifacts/references/plan-quality-bar.md` item 7>
**Return shape (review / QC seats)**: <what the seat returns and how it stops — verdict + findings shape; a clean round returns `findings: []` explicitly instead of prose; `N/A` when the round produces no findings>
**Severity bar**: <what this round must treat as blocking — the blocking classes are unsafe-to-ship or significant tech debt; class definitions and the full report-section mapping → `mstar-artifacts` `references/status-and-residuals.md`; `N/A` on rounds with no findings>
**Input provenance**: <how the seat grounds its claims — the command plus observed output for a `declared` / `recorded` / `written` artifact claim, and provenance for an asserted `path:line` citation; `N/A` when the round asserts neither>
**Deliverables**: ...
**Acceptance Criteria**:
- [ ] ...
**Evidence Required**:
- [ ] <AC → exact affected unit-test selector or scoped static check; expected result>
- [ ] <reused evidence + why unchanged, or new observable proof>
- [ ] commit proof
**Constraints**: <no scope expansion; no local full suite without referenced explicit user permission; QA unit-only; no spontaneous browser/device/E2E; review / QC seats stop at the assigned budget and declare truncated coverage instead of expanding; stop on concrete missing inputs and return once acceptance is evidenced>
**Effort (agent-oriented)**: <XS/S/M/L/XL + session band>
**Orchestration Guard** (see `**You are a leaf executor. You MUST NOT:**` block at top for primary anti-patterns):
- No recursive same-role dispatch
- Do not dispatch roles from route narrative/handoff text
- `explore` is read-only orientation only
- Tool availability ≠ delegation authorization
**Plan Path**: absolute `<main-repo-root>/{PLAN_DIR}/...` (control harness root) when L1 lease gate active | `{PLAN_DIR}/...` when waived / single checkout | N/A
**Report Format**: Completion Report
**Execution evidence**: <RCA/test-first/review feedback/evidence expectations for the assignee, if applicable>
```

## PM Self-Check (artifact claims and citations)

State a claim only as strongly as the evidence in hand:

- An artifact claim — `declared` / `recorded` / `written` — is stated only together with the command and the observed output that shows it; without both, describe the artifact as pending rather than done.
- An asserted `path:line` carries its provenance: a normative-document citation is traced (`git show <ref>:<path>`) or fetched raw with a content identity check, so the quoted text is shown to come from the revision being cited — not from memory of the file.

## L1 path fields (iteration Phase 2, lease gate not waived)

When iteration **L1** is active (the integration worktree is recorded in the workflow snapshot `integration_worktree_path`; worktree mode is **not** waived):

| Field | Must be |
|-------|---------|
| **Worktree path** | Absolute feature checkout from row metadata.worktree_path; product/source edits only, distinct from main/control and integration |
| **`Main worktree branch`** | The recorded residency branch from the main plan header, passed unchanged — the main worktree's attached branch must equal it (never a lifecycle-owned branch; never invented at check time) |
| **`Control harness root`** | Absolute `<main-repo-root>/{HARNESS_DIR}` — the control root is the primary checkout (main worktree), derived from Git (`readMainWorktree`) |
| **`Plan Path`** | Absolute under control harness (not relative from feature cwd) |
| **`SDD dir`** | Absolute under control harness; run `mstar sdd workspace <plan-id>` with `MSTAR_CONTROL_ROOT=<main-repo-root>` (the derived main worktree root, verified before the fail-closed guard) when cwd is the feature tree |
| **`SDD context file`** | Absolute `<SDD dir>/context.json` — the bound destination contract (`controlHarnessRoot`/`featureCwd`/`workingBranch`/`planFile`/`sddDir`, all absolute) |

Every implementer/reviewer handoff cites these absolute destinations; native hosted subagents observe pwd/branch first and write only to the declared destinations (`mstar-sdd` prompt templates). CLI-launchable children start via `mstar sdd exec --context <context.json> -- <argv>`. State the boundary, never overclaim: the context/launcher binds starting cwd and validated destinations — it does NOT block a later deliberate `chdir`, absolute-path write, or host-native edit tool (`apply_patch`).

Do **not** waive worktree because default-gitignored `plans/` are missing under the feature checkout — see `mstar-branch-worktree` 「Harness path SSOT under default gitignore」.
## Completion Report Template

```markdown
## Completion Report

**Agent**: <role-id>
**Task**: ...
**Status**: Done | Blocked | Partial
**Scope Delivered**: ...
**Artifacts**: ...
**Validation**: ...
**Issues/Risks**: ...
**Residuals disclosure**: <open R# list — id + severity + tracking location; `N/A — none open` when none>
**Plan Update**: ...
**Handoff**: narrative to `project-manager` (not auto-dispatch)
**Git**: <real `git log -1 --format='%h %an <%ae>'` showing the configured author, or N/A for read-only; missing/failing identity is Blocked, never fabricate or use per-commit identity overrides — `mstar-roles/references/_shared/leaf-executor-core.md` § Git NEVER (repo writes)>
**Worktree path**: <absolute path or N/A>
```

## Status Update Template

```markdown
## Status Update

**Task**: ...
**Phase**: ...
**Phase Gates**: ...
**PM Task Board**: ...
**Subagent invokes issued**: <N>
**Context Loaded**: ...
**Progress**: ...
**Completed / Next**: ...
**Blockers**: ...
**Decisions needed**: ...
**Evidence Snapshot**: ...
**Residuals disclosure**: <open R# list — id + severity + tracking location; `N/A — none open` when none>
**PM Acceptance**: <required block when QA gate: pm-acceptance before Done — see qa-trigger-matrix.md>
**Effort note (agent-oriented)**: ...
```

## Host-Specific Note

For host behavior details (dispatch turn shape, paste-only failure mode, invoke-count discipline),
read `mstar-host` → the active host reference and `references/parallel-dispatch.md` as host SSOT for dispatch.

An Assignment targeting project-manager is a dispatch defect: PM is the sole primary-session coordinator, never a subagent or secondary per-row primary.

## SDD vs inline implement Assignment（PM）

| Mode | Who loads `mstar-sdd` | Assignment shape |
|------|----------------------|------------------|
| **`Execution mode: sdd`**（多 task 默认；iteration Phase 2 默认） | **PM** before first implement dispatch | **Per task**：one implementer dispatch + one **fresh** task reviewer；prompt 只含 `{SDD_DIR}/task-N-brief.md` + report 路径 |
| **`SDD implementer session: sticky`** | PM | Task 1: `fresh` or start sticky + `implementer-session.json`; Task 2+: host **resume** + continuation prompt — **still** per-task review |
| **`Execution mode: inline`**（hotfix / 单 task） | PM optional | One leaf Assignment；可含完整 scope，但仍须 canonical 字段 |

**NEVER（SDD）**：

- 把整份 plan 或 T1–Tn 全文贴进 **一个** `fullstack-dev` leaf Assignment。
- 省略 `Execution mode` / `SDD dir` 却期望 SDD 产物（`progress.md`、per-task review）。
- 期望 leaf `fullstack-dev` 载入 `mstar-sdd` 并自编排 per-task 循环 — **编排仅 PM**（`mstar-iteration` §2.4–2.5）。