Add dispatch-start skill and update docs/tests

Introduce a new bundled skill 'dispatch-start' (skills/dispatch-start/SKILL.md and agents/openai.yaml) that serves as the entrypoint for Dispatch planning/runtime decisions. Update README to mention the new skill and its usage. Adjust tests (tests/skills.test.js) to include the new skill in the bundled list, update expected counts, assert output includes dispatch-start, and run the build step before packing in the pack/test to ensure the skill is included.

Author: PatrickJS

README.md

@@ -339,6 +339,8 @@ Checklist for a new Codex thread:
    ```
 
 5. In a fresh Codex session, use the installed skills when their triggers match:
+   - `$dispatch-start` as the first skill for broad goals, async requests,
+     multi-repo work, or "spawn chats" requests.
    - `$dispatch-root-runtime` for broad root-chat coordination.
    - `$dispatch-code-routing` before code edits that might split into lanes,
      worktrees, child chats, or domain-owner chats.
@@ -393,6 +395,8 @@ The `skills/` directory is part of the package. These skills ship with
 `@async/dispatch` and are installed into Codex with
 `async-dispatch skills install`.
 
+- `dispatch-start`: entrypoint routing for raw goals; starts planning when
+  broad async work has no approved board yet.
 - `dispatch-root-runtime`: goal, draft, board, runtime, worker, receipt, idle,
   and wake coordination.
 - `dispatch-code-routing`: quick code-routing decisions before edits, including

skills/dispatch-start/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: dispatch-start
+description: Start async-dispatch as the entrypoint for broad Codex root-chat work. Use when a user asks to run async, spawn chats, coordinate multi-repo or multi-slice work, start a Dispatch-managed goal, resume an existing Dispatch board or runtime, or decide whether a raw request should enter planning before implementation.
+---
+
+# Dispatch Start
+
+## Overview
+
+Use this as the first Dispatch skill for a raw user goal. It decides whether the
+root can work directly, must resume existing Dispatch state, or must enter the
+goal -> draft -> board -> runtime planning path before any worker or child-chat
+launch.
+
+The important default is: no approved board means start the board phase, not
+root-only implementation.
+
+## Start Decision
+
+First inspect local state and the request:
+
+```bash
+async-dispatch snapshot
+```
+
+Then choose one mode:
+
+- `resume-runtime`: a matching active runtime ledger already exists. Continue
+  with `dispatch-root-runtime`.
+- `resume-board`: a matching board exists but is not approved or started.
+  Present the board/draft for review before `board approve` or `runtime start`.
+- `planning-required`: the request is broad, async, multi-repo, multi-slice, or
+  asks to spawn chats, but no approved board exists.
+- `root-only`: the request is small enough for the root chat, or the user
+  explicitly asked for root-only execution.
+
+For `planning-required`, do not edit repos, create worker chats, or commit code.
+Start the Dispatch planning phase.
+
+## Missing State Recovery
+
+When Dispatch state is missing, report the recovery path instead of stopping at
+"no plan found."
+
+- No matching plan exists: keep using `dispatch-start`; create/refine the goal,
+  draft a plan, and give the human the draft path plus approval choices.
+- Plan exists but no board exists: keep using `dispatch-start`; ask the human to
+  approve or correct the draft, then run `plan ready` and `plan compile`.
+- Board exists but no runtime exists: keep using `dispatch-start`; ask the human
+  to approve or correct the board, then run `board approve` and `runtime start`.
+- Runtime exists: hand off to `dispatch-root-runtime` for nodes, workers,
+  receipts, idle/wake, and closeout.
+- Code work is ready inside an active runtime: use `dispatch-code-routing`
+  before root edits or worker launches.
+
+For a missing plan, the human action must be concrete:
+
+```text
+Reply "approve draft" to compile the board, or reply with corrections such as
+"split core graph and runtime into separate phases" or "keep this root-only."
+```
+
+## Planning Phase
+
+Create a durable goal and gather enough context to draft a real plan:
+
+```bash
+async-dispatch goal init --seed "..."
+async-dispatch context add <goalId> --note "..."
+async-dispatch goal refine <goalId> --statement "..." --purpose "..." --success-proof "..." --constraint "..." --why "..."
+```
+
+Draft a human-readable plan before runtime work:
+
+```bash
+async-dispatch plan template human-draft --seed "..."
+async-dispatch plan draft <goalId> --from <draft.md>
+```
+
+Present the draft or board shape to the user for review. Ask for approval or
+corrections, not whether planning should happen. Record corrections with:
+
+```bash
+async-dispatch plan decision <planId> --note "..."
+async-dispatch plan enrich <planId> --note "..."
+async-dispatch plan resolve <planId> --decision-id D001 --resolution "..."
+```
+
+Only after the human-reviewed draft is ready:
+
+```bash
+async-dispatch plan ready <planId> --note "Human reviewed the draft."
+async-dispatch plan compile <planId>
+```
+
+Do not approve the board on behalf of the user unless their latest message
+clearly approved the specific draft/board. After approval:
+
+```bash
+async-dispatch board approve <boardId> --note "Human reviewed the board."
+async-dispatch runtime start <boardId>
+```
+
+## Runtime Handoff
+
+After `runtime start`, switch to `dispatch-root-runtime` for nodes, domain
+owners, workers, receipts, idle/wake, and closeout. Use `dispatch-code-routing`
+before code edits that might become root work, child chats, domain-owner chats,
+or worktree lanes.
+
+Launch workers only from approved runtime state with ownership, verification,
+stop conditions, and a root integration point recorded.
+
+## Output Contract
+
+For the first response after this skill triggers, report:
+
+```markdown
+## Dispatch Start
+Mode: planning-required | resume-runtime | resume-board | root-only
+Source state: [matching goal/plan/board/runtime or none]
+Goal: [short restatement]
+Next phase: [planning, board review, runtime, or root-only]
+Root action: [exact command or review step being performed now]
+Human review needed: [what the user must approve or correct before workers]
+Missing state action: [skill to continue with, exact command family, and concrete human reply]
+```
+
+If the mode is `planning-required`, include a concise draft plan or the command
+sequence used to create one. If the mode is `root-only`, say why the request is
+small enough or quote the explicit root-only instruction.
+
+Never end a missing-plan response with only "review needed." Include the next
+agent action, the next human action, and the skill that owns the next phase.

skills/dispatch-start/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Dispatch Start"
+  short_description: "Start Dispatch planning and runtime"
+  default_prompt: "Use $dispatch-start to start this goal through Dispatch planning and runtime."

tests/skills.test.js

@@ -16,20 +16,22 @@ import {
 const execFile = promisify(execFileCallback);
 const repoRoot = fileURLToPath(new URL("..", import.meta.url));
 const cliPath = path.join(repoRoot, "src", "cli.js");
+const bundledSkillNames = [
+  "dispatch-code-routing",
+  "dispatch-root-runtime",
+  "dispatch-skill-evolution",
+  "dispatch-start"
+];
 
 test("bundled skills are listed and validated for CLI installation", async () => {
   const skills = await listBundledSkills();
   const names = skills.map((skill) => skill.name);
   const validation = await validateBundledSkills();
 
-  assert.deepEqual(names, [
-    "dispatch-code-routing",
-    "dispatch-root-runtime",
-    "dispatch-skill-evolution"
-  ]);
+  assert.deepEqual(names, bundledSkillNames);
   assert.ok(skills.every((skill) => skill.description.includes("Dispatch") || skill.description.includes("async-dispatch")));
   assert.equal(validation.ok, true);
-  assert.equal(validation.skills.length, 3);
+  assert.equal(validation.skills.length, 4);
 });
 
 test("bundled skill names must match safe folder basenames", async () => {
@@ -49,7 +51,7 @@ test("skill installer records metadata, status, and preserves unmanaged folders"
   const targetDir = await fs.mkdtemp(path.join(os.tmpdir(), "dispatch-skills-"));
   try {
     const initial = await installBundledSkills({ targetDir });
-    assert.equal(initial.results.length, 3);
+    assert.equal(initial.results.length, 4);
     assert.ok(initial.results.every((result) => result.action === "installed"));
 
     const current = await getSkillInstallStatus({ targetDir, skills: "dispatch-root-runtime" });
@@ -109,11 +111,7 @@ test("skills CLI supports JSON list, status, install, and unknown skill errors",
   const targetDir = await fs.mkdtemp(path.join(os.tmpdir(), "dispatch-skills-cli-"));
   try {
     const listed = JSON.parse((await execCli(["skills", "list", "--json"])).stdout);
-    assert.deepEqual(listed.skills.map((skill) => skill.name), [
-      "dispatch-code-routing",
-      "dispatch-root-runtime",
-      "dispatch-skill-evolution"
-    ]);
+    assert.deepEqual(listed.skills.map((skill) => skill.name), bundledSkillNames);
 
     const install = JSON.parse((await execCli([
       "skills",
@@ -135,7 +133,7 @@ test("skills CLI supports JSON list, status, install, and unknown skill errors",
       targetDir,
       "--json"
     ])).stdout);
-    assert.deepEqual(status.results.map((result) => result.status), ["current", "current", "missing"]);
+    assert.deepEqual(status.results.map((result) => result.status), ["current", "current", "missing", "missing"]);
 
     await assert.rejects(
       () => execCli(["skills", "install", "--target", targetDir, "--skill", "../escape"]),
@@ -149,6 +147,9 @@ test("skills CLI supports JSON list, status, install, and unknown skill errors",
 test("packed package exposes the async-dispatch CLI and bundled skills", async () => {
   const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "dispatch-pack-"));
   try {
+    await execFile(process.execPath, [path.join(repoRoot, "scripts", "build-dist.js")], {
+      cwd: repoRoot
+    });
     const pack = JSON.parse((await execFile("pnpm", ["pack", "--json", "--pack-destination", tmp], {
       cwd: repoRoot
     })).stdout);
@@ -158,6 +159,7 @@ test("packed package exposes the async-dispatch CLI and bundled skills", async (
     const bin = path.join(installDir, "node_modules", ".bin", "async-dispatch");
     const listed = await execFile(bin, ["skills", "list"]);
     assert.match(listed.stdout, /dispatch-root-runtime/);
+    assert.match(listed.stdout, /dispatch-start/);
 
     const targetDir = path.join(tmp, "codex-skills");
     const installed = await execFile(bin, ["skills", "install", "--target", targetDir, "--skill", "dispatch-root-runtime"]);