orbitmap 0.4.2 → 0.4.4

package/dist/agent-instructions.js

@@ -1,26 +1,50 @@
 // Single source of truth for all OrbitMap agent-facing instruction text.
 //
+// THIS FILE IS THE CANONICAL HOME of the skills. `orbitmap init` installs them; the
+// copies under `~/.claude/skills/` (or a project's `.claude/skills/`) are INSTALLS,
+// not sources. Edit here, then re-install — never the other way around.
+//
 // Two layers, mirroring how the OrbitMap MCP server works:
 //   1. THIN_HOOK      — always-on, injected into CLAUDE.md / AGENTS.md (~10 lines).
 //                       Equivalent of the MCP "system instructions" that are always
 //                       in the system prompt. Guarantees the agent always knows the
 //                       project uses OrbitMap and knows the workflow skeleton.
-//   2. The four skills — the deep, on-demand layer. Equivalent of the MCP tool
-//                       catalogue (INSTRUCTIONS_FULL), split by topic:
-//                         orbitmap          — object model, context, command map
-//                         orbitmap-working  — task lifecycle, logging, git/delivery
-//                         orbitmap-planning — missions, intents, ideas, issues
-//                         orbitmap-docs     — documents
+//   2. The skills — the deep, on-demand layer: the four gates of the
+//                       product-building flow plus the entry point and docs:
+//                         orbitmap            — entry point: object model, context,
+//                                               command map
+//                         orbitmap-brainstorm — gate 1: idea → agreed outcome
+//                         orbitmap-design     — gate 2: outcome → design doc
+//                         orbitmap-plan       — gate 3: design → executable tasks
+//                                               (+ general planning entities)
+//                         orbitmap-execute    — gate 4: execution, two flows. Flow A
+//                                               ("execute IN-x") orchestrates a whole
+//                                               intent: parallel workers in dependency
+//                                               waves, baseline + impact test gates, a
+//                                               goal-based fix loop, ending in_review on
+//                                               an intent branch. Flow B ("work on
+//                                               TS-x") runs one task inline. Ships a
+//                                               reference file, references/
+//                                               worker-contract.md, that dispatched
+//                                               workers read INSTEAD of the skill
+//                                               (see SkillDef.references).
+//                         orbitmap-docs       — documents
 //                       Shipped two ways:
 //                         - Claude:     one `.claude/skills/<name>/SKILL.md` per skill,
-//                                       loaded on demand (zero per-turn context cost).
-//                         - non-Claude: all four bodies concatenated into the agent
+//                                       plus any `references/*` files, loaded on demand
+//                                       (zero per-turn context cost).
+//                         - non-Claude: all skill BODIES concatenated into the agent
 //                                       config file (no skill ecosystem to lean on).
+//                                       Reference files are not inlined: without
+//                                       subagent dispatch, Flow A runs serially and the
+//                                       worker contract folds into the executor's own
+//                                       rules.
 //
-// The content below is normative: it is transcribed from §8 of
-// `docs/local-mode-poc-spec.md`, which is itself the MCP oracle
-// (`orbitmap-mcp/src/orbitmap_mcp/instructions.py`, INSTRUCTIONS_FULL) translated into
-// CLI-command vocabulary. Do not paraphrase it; change the spec first.
+// History: the original four skills (orbitmap, orbitmap-execute, orbitmap-plan,
+// orbitmap-docs) were transcribed from §8 of `docs/local-mode-poc-spec.md`, itself a
+// CLI translation of the MCP oracle (`orbitmap-mcp/.../instructions.py`). The skills
+// have since evolved past that spec — worklog wiring, the keep/drop test, and the v2
+// whole-intent execute flow — so THIS FILE is now normative, not the spec.
 export const MARKER_START = '<!-- ORBITMAP_START -->';
 export const MARKER_END = '<!-- ORBITMAP_END -->';
 /** The core skill name (entry point). Kept for backwards compatibility. */
@@ -40,6 +64,15 @@ through the \`orbitmap\` CLI (run with \`npx orbitmap …\` if not on PATH). The
 identically in cloud mode and local-files mode — never assume which one is active, and
 never read or write the workspace's data files directly. The CLI is the only interface.
 
+## Goal
+Operate OrbitMap correctly: always start from \`orbitmap context\`, act on the active mission
+and open intents, write every item to the area the work belongs to, and go through the CLI
+only — never the data files.
+
+**Interface:** every action below is an OrbitMap operation — run the \`orbitmap\` CLI command
+shown, or its equivalent MCP tool when this session uses MCP; \`orbitmap <cmd> --help\` and the
+MCP tool schemas are the authority. Never edit the workspace data files directly.
+
 ## General behaviour
 - Always prioritise the user's direct request. If the user asks you to do something
   (read a file, write code, answer a question), handle that first.
@@ -57,11 +90,35 @@ never read or write the workspace's data files directly. The CLI is the only int
 - Entity numbers (TS-xxxxxx etc.) are accepted by every command that takes an id.
 
 ## Context
-- Area resolves automatically (config/env). Override per call with \`--area <slug>\`.
-- If a command fails asking for area context, run \`orbitmap areas\` to list areas, then
-  retry with \`--area\`.
-- \`orbitmap context\` shows who you are, the workspace, and the active area. Run it when
-  unsure.
+- START HERE, always: \`orbitmap context\`. \`orbitmap context\` is authoritative and returns
+  in ONE call everything a session needs — the agent, the workspace, the areas you work in,
+  the active mission, open intents, your tasks and the documents. Never list areas and never
+  ask the user "which area?" before you have read it.
+- You work in a WORKSPACE, not inside a single area. Missions, intents
+  and documents are workspace-level and take no area — a document is exactly ONE copy,
+  global to the workspace, never per-area. Tasks, vibes, issues and ideas are
+  AREA-scoped.
+- Missions and intents outrank individual tasks. Asked to work on "what matters", take the
+  active mission and open intents from context and pick work that serves them.
+- The area follows from the directory, never from a question to the user:
+  \`.orbitmap/config.json\` maps directories → area slugs at the workspace root, and each
+  area directory carries its own \`.orbitmap/config.json\` marker naming its area. That
+  config is the only source of truth — never hard-code area names anywhere.
+  So: do area-scoped work from the directory it belongs to and let the CLI resolve it.
+- \`--area <slug>\` is an OVERRIDE for a single call, not part of normal usage — reach for it
+  only to read or write outside the area the current directory resolves to.
+- If a command fails with \`AREA_CONTEXT_REQUIRED\`, its details list the mapped
+  directories: cd into the right one, or retry with \`--area <slug>\`.
+- WRITES: the resolved area is a default for *reading*, never a statement of where the
+  work belongs. Before creating anything area-scoped (task, subtask, issue, vibe),
+  derive the target area from the work itself (which repo/package it lives in) and pass
+  \`--area <slug>\` if that differs from the area the CLI echoes. If the work itself is
+  genuinely ambiguous, ASK THE USER; do not guess. There is no
+  \`move\` command: a write in the wrong area has to be recreated.
+- Every write echoes its scope on stderr: \`creates in area <slug> (source: …)\` when it
+  creates an object, \`scoped to area <slug> (source: …)\` when it changes one by id. A
+  \`source\` of \`global ~/.orbitmap/config.json\` is a machine-wide leftover that nothing
+  here chose — treat it as unconfirmed and pass \`--area\` explicitly.
 
 ## Task statuses
 backlog, todo, in_progress, in_review, review_changes, done, blocked.
@@ -69,7 +126,8 @@ backlog, todo, in_progress, in_review, review_changes, done, blocked.
 \`orbitmap tasks --status backlog\` when the user asks about the backlog.
 
 ## Command reference (all commands accept --json)
-- Context: \`orbitmap context\`, \`orbitmap areas\`, \`orbitmap overview\`
+- Context: \`orbitmap context\` (start here), \`orbitmap overview\`, \`orbitmap areas\`
+  (rarely needed — context already lists the areas you work in)
 - Tasks: \`orbitmap tasks [--status s1,s2]\`, \`orbitmap task TS-x\`, \`orbitmap get <ID>\`,
   \`orbitmap start [TS-x]\`, \`orbitmap status TS-x <status> [--delivery <d>]\`,
   \`orbitmap create "title" [--intent IN-x|--mission MS-x] [--priority p]\`,
@@ -87,155 +145,1016 @@ backlog, todo, in_progress, in_review, review_changes, done, blocked.
 - If OrbitMap is unreachable (network down / workspace directory unavailable), inform
   the user and continue the primary work without logging. Do NOT retry failed orbitmap
   calls in a loop — report the issue and proceed with the task.`;
-// ── Skill: orbitmap-working — §8.4 ─────────────────────────────────────────────
-export const SKILL_WORKING_FRONTMATTER = `---
-name: orbitmap-working
+// ── Skill: orbitmap-execute (v2 — whole-intent orchestration + single-task flow) ──
+export const SKILL_EXECUTE_FRONTMATTER = `---
+name: orbitmap-execute
 description: >
-  Working on OrbitMap tasks: starting/resuming, logging work, decisions and blockers,
-  finishing with the correct status, git branches and delivery status. Use whenever
-  implementing, resuming, or finishing a tracked task.
+  Executing OrbitMap work — the fourth gate of the product-building flow. Two flows:
+  "execute IN-x" delivers a whole planned intent in the background (parallel worker
+  waves, per-task tests, the intent test, an impact pass against a baseline, a
+  goal-based fix loop, everything ending in_review on an intent branch — merging stays
+  the user's), and "work on TS-x" runs a single tracked task (starting/resuming,
+  logging, finishing with the correct status, git branches and delivery status). Use
+  whenever executing a planned intent or implementing, resuming, or finishing a
+  tracked task.
 ---`;
-export const SKILL_WORKING_BODY = `# Working on OrbitMap tasks
+export const SKILL_EXECUTE_BODY = `# Executing OrbitMap work
 
-## Task workflow (on user request)
-When the user asks you to work on tasks:
-1. \`orbitmap tasks --status in_progress\` — check for unfinished work.
-2. If found → \`orbitmap task TS-x\` → read the work log → resume from the resume point.
-3. If not → \`orbitmap start\` — auto-picks the first todo task, sets it in_progress and
-   prints full context (description, agent_instructions, logs).
-4. If no tasks → inform the user.
-Use \`orbitmap start TS-x\` to begin a specific task; \`orbitmap task TS-x\` only inspects.
+## Goal
+Deliver work and leave Orb an accurate record. Flow A takes a PLANNED intent to delivered:
+every task built and tested, the intent test and an impact pass green against a pre-run
+baseline, all tasks \`in_review\` on an intent branch — merging and closing stay the user's.
+Flow B takes ONE tracked task from start to a correct finish. Both end with the right
+statuses, delivery and worklog so the next agent can resume.
 
-## Rules
-- Work on ONE task at a time.
-- Always read agent_instructions from the task before implementing. Task-level
-  agent_instructions take precedence over area-level instructions.
-- Only work on subtasks assigned to you; do not pick up other agents' subtasks.
-- Do NOT mark a parent task done while it has unfinished subtasks, unless the user
-  explicitly asks.
-
-## Logging
+**Interface:** every action below is an OrbitMap operation — run the \`orbitmap\` CLI command
+shown, or its equivalent MCP tool when this session uses MCP; \`orbitmap <cmd> --help\` and the
+MCP tool schemas are the authority. Never edit the workspace data files directly.
+
+## Choosing a flow
+- "execute IN-x", "deliver this intent", "run the plan" → **Flow A** (orchestration).
+- "work on TS-x", "start a task", a vague "work on what's important" → **Flow B**.
+- Flow A dispatches workers that follow \`references/worker-contract.md\` (shipped next to
+  this file) — a worker reads that contract, not this skill.
+
+## Key principles
+- **The contract is the outcome, not a checklist.** The run works as long as needed to
+  deliver the intent with all gates green — never "tried N times, giving up".
+- **Autonomy: decide and log.** A judgment call within the design → decide, keep going,
+  log it if it passes the keep/drop test. A stuck task → \`blocked\` with a logged blocker
+  while the REST of the intent continues. Interrupt the user ONLY for intent-level risk: a
+  design contradiction, an unfixable intent test. Never a silent skip; never the whole run
+  dying for one task.
+- **No new bugs, checkably.** Capture a test BASELINE before touching anything. A
+  regression is a failure NOT in the baseline — pre-existing failures/flakes are neither
+  blamed on the run nor silently counted green. What the run broke, the run fixes.
+- **Merging is human.** The run holds commit authority only — never merge, never push to
+  the default branch, never close tasks or the intent as \`done\`. The branch is the user's
+  review boundary.
+- **Distrust and verify.** Instructions age; the tree is the truth. Re-grep any claim a
+  task's instructions make about the code ("X lives in Y", "verified list of call sites")
+  before relying on it.
+- **The orchestrator owns shared state.** Workers never run git, never write OrbitMap,
+  never use the shared test DB, never format, never change dependencies — commits, logs,
+  statuses, formatting and test gates all happen at fold time, in the orchestrator.
+- **Never end the run to wait.** Shared gates QUEUE safely: run them in the foreground
+  and wait on the command (generous timeout); an overrun that gets backgrounded resumes
+  you on completion. Ending your turn is only for: run COMPLETE, or hard-blocked and
+  logged — a background run that yields to "wait for a signal" is a dead run.
+
+## Flow A — execute IN-x (whole intent)
+1. **Premise check.** \`orbitmap intent show IN-x\`: it must exist, be at status \`build\`,
+   and have tasks with agent_instructions. Anything missing → refuse politely and point at
+   the missing gate (\`orbitmap-brainstorm\` for no outcome, \`orbitmap-design\` for no
+   design, \`orbitmap-plan\` for no tasks). Read the outcome, design, plan field and work
+   log in full — they are the run's spec.
+2. **Repos & baseline.** The touched repos follow from the tasks' areas — an intent may
+   span several. Resolve each area to a directory in this order: the workspace's mapped
+   directories (\`orbitmap context\` / \`.orbitmap/config.json\`), the workspace or repo
+   CLAUDE.md (repo tables), the area's own description (\`orbitmap areas\` — descriptions
+   often name the repo). NEVER guess a directory: an unmappable area blocks its tasks and
+   their dependents, logged, while the rest of the run continues. Each repo's BASE branch
+   is where its work lands per the workspace docs (e.g. develop); undocumented → the
+   repo's current default branch, decide-and-log. Then run each touched repo's full gate
+   once; record suite counts and every pre-existing failure/flake. Reuse a baseline when
+   the repo's HEAD already has a green result recorded this session. A gate that cannot
+   COMPLETE (a pre-existing hang) is itself a finding: register it as an issue, then
+   baseline by subsets so every suite is still covered, and compare like with like.
+3. **Branch.** In each touched repo, create \`intent/<IN-number>-<name-slug>\` (e.g.
+   \`intent/7bcc4y-execute-skill-v2\`) from its base branch (step 2). Honor a task's own
+   \`branch_name\` only when that task genuinely needs isolation.
+4. **Wave loop** — repeat while runnable tasks remain:
+   - Ready-set: unstarted tasks whose dependencies are all folded; \`blocked\` tasks and
+     tasks depending on them drop out (log a blocker on those left unrunnable).
+   - Size the wave by GATE CONTENTION, not a constant: tasks needing the shared test DB
+     ≤4 concurrent (the gate serialises anyway); light, file-disjoint tasks (docs,
+     separate repos) as wide as the ready-set — 10+ is fine.
+   - Dispatch one worker (subagent) per task. Prompt = the task number, its
+     agent_instructions PASTED VERBATIM (workers get no CLI credentials — never make one
+     fetch its own spec), the repo path, the exact files it owns, and one line: "Follow
+     references/worker-contract.md of the orbitmap-execute skill." Worktree isolation
+     ONLY when same-repo tasks in the wave overlap on files; otherwise slice the wave
+     file-disjoint in one tree; cross-repo needs nothing.
+   - FOLD the workers' results sequentially in dependency order, a gate between folds:
+     integrate one task → scoped tests → formatter → commit \`[TS-x] …\` (one commit may
+     carry several tasks that verify as one unit) → log per the keep/drop test →
+     \`orbitmap status TS-x in_review --delivery on_branch\`.
+   - A task neither the worker nor the fold can save → \`orbitmap log TS-x "Blocked: …"
+     --type blocker\` + \`orbitmap status TS-x blocked\` — the run CONTINUES without it.
+     Its dependents leave the ready-set with their own logged blocker but KEEP their
+     status (backlog): they are waiting, not failed.
+   - Recompute the ready-set; next wave.
+5. **Intent test.** The plan gate guarantees an intent-level test task; run it LAST —
+   and run it AS THE ORCHESTRATOR, never a worker: it needs the shared gates and the
+   live app, exactly what the worker contract forbids workers.
+6. **Impact pass.** Full gate per touched repo, diffed against the baseline — a regression
+   is a failure not in the baseline. When an API response shape moved, also run the
+   contract-coupling steps (regenerate the committed spec, refresh the consumer's vendored
+   fixtures) before judging the gates.
+7. **Fix loop.** Every regression or intent-test failure → a fix, gated by scoped tests;
+   after the LAST fix the full pass runs again. NO round cap — loop until every task is
+   delivered or honestly blocked and the gates are green vs baseline. An unfixable intent
+   test or a design contradiction → STOP and ask the user: that is intent-level risk, the
+   one thing that interrupts.
+8. **Report + resume note.** Leave every repo checked out on its BASE branch — the
+   intent branch is named in the report, not left underfoot. Report in chat: what
+   shipped, what was decided, what is blocked and why, deviations from the plan, gate
+   results vs baseline. Write ONE resume
+   point: \`orbitmap log IN-x "Resume point: …" --type note\`. The intent STAYS \`build\`;
+   merging and closing are the USER'S. The merge EVENT — whoever performs it — is what
+   later flips the tasks to \`--delivery merged\`.
+
+**No subagent runtime?** Same flow, serial: do steps 4–7 yourself, task by task, with the
+worker contract as your own build rules. The contract is the outcome, not the parallelism.
+
+## Process flow (Flow A)
+\`\`\`dot
+digraph orbitmap_execute {
+    "Premise: intent at build, tasks with instructions?" [shape=diamond];
+    "Refuse politely; point at the missing gate" [shape=box];
+    "Baseline: full gate per touched repo, results recorded" [shape=box];
+    "Branch intent/<number>-<slug> per touched repo" [shape=box];
+    "Compute ready-set from dependency edges" [shape=box];
+    "Size wave by gate contention; dispatch workers (worktrees only on file overlap)" [shape=box];
+    "Fold sequentially, gate between folds: scoped tests, format, commit [TS-x], log, in_review on_branch" [shape=box];
+    "Stuck task: blocked + logged blocker; run continues" [shape=box];
+    "Runnable tasks remain?" [shape=diamond];
+    "Run the intent test task (last)" [shape=box];
+    "Impact pass: full gate per repo, diff vs baseline (+contract steps)" [shape=box];
+    "Regressions or intent-test failures?" [shape=diamond];
+    "Fix findings, scoped tests per fix" [shape=box];
+    "Intent-level risk: stop and ask the user" [shape=box];
+    "Report + resume note; intent stays build; user merges" [shape=doublecircle];
+
+    "Premise: intent at build, tasks with instructions?" -> "Refuse politely; point at the missing gate" [label="no"];
+    "Premise: intent at build, tasks with instructions?" -> "Baseline: full gate per touched repo, results recorded" [label="yes"];
+    "Baseline: full gate per touched repo, results recorded" -> "Branch intent/<number>-<slug> per touched repo";
+    "Branch intent/<number>-<slug> per touched repo" -> "Compute ready-set from dependency edges";
+    "Compute ready-set from dependency edges" -> "Size wave by gate contention; dispatch workers (worktrees only on file overlap)";
+    "Size wave by gate contention; dispatch workers (worktrees only on file overlap)" -> "Fold sequentially, gate between folds: scoped tests, format, commit [TS-x], log, in_review on_branch";
+    "Size wave by gate contention; dispatch workers (worktrees only on file overlap)" -> "Stuck task: blocked + logged blocker; run continues" [label="worker stuck"];
+    "Stuck task: blocked + logged blocker; run continues" -> "Runnable tasks remain?";
+    "Fold sequentially, gate between folds: scoped tests, format, commit [TS-x], log, in_review on_branch" -> "Runnable tasks remain?";
+    "Runnable tasks remain?" -> "Compute ready-set from dependency edges" [label="yes"];
+    "Runnable tasks remain?" -> "Run the intent test task (last)" [label="no"];
+    "Run the intent test task (last)" -> "Impact pass: full gate per repo, diff vs baseline (+contract steps)";
+    "Impact pass: full gate per repo, diff vs baseline (+contract steps)" -> "Regressions or intent-test failures?";
+    "Regressions or intent-test failures?" -> "Fix findings, scoped tests per fix" [label="yes"];
+    "Fix findings, scoped tests per fix" -> "Impact pass: full gate per repo, diff vs baseline (+contract steps)" [label="re-run"];
+    "Fix findings, scoped tests per fix" -> "Intent-level risk: stop and ask the user" [label="unfixable / contradiction"];
+    "Regressions or intent-test failures?" -> "Report + resume note; intent stays build; user merges" [label="no"];
+}
+\`\`\`
+
+## Flow B — work on TS-x (single task)
+1. \`orbitmap context\` — workspace, areas, active mission, open intents and your tasks in
+   one call. Never ask which area; never list areas first.
+2. Unfinished work in context (or \`orbitmap tasks --status in_progress\`) →
+   \`orbitmap task TS-x\` → read the work log → resume from the resume point.
+3. Otherwise pick work serving the active mission / open intents, or \`orbitmap start\` —
+   auto-picks the first todo task, sets it in_progress and prints full context.
+   \`orbitmap start TS-x\` begins a specific task; \`orbitmap task TS-x\` only inspects.
+   Nothing to pick up → inform the user.
+4. Read agent_instructions before implementing — task-level overrides area-level — then
+   distrust-and-verify their claims against the tree.
+5. Work on ONE task at a time. Implement, run the task's tests, commit \`[TS-x] …\`.
+6. Log as you work (below); finish per "End of session or task".
+
+## Logging (both flows)
 - \`orbitmap log TS-x "…" --type note|code_change|decision|blocker\` — work WITHIN a task.
 - \`orbitmap vibe log "…" --type discovery|exploration|fix\` — ad-hoc work outside a task.
-- Use \`--type decision\` when you pick between approaches, reject an alternative, or lock
-  in a non-obvious assumption — record the choice AND the why, not just the outcome.
 - \`orbitmap idea add\` — future possibilities, NOT problems (problems →
   \`orbitmap issue register\`).
-- Keep log content concrete, concise, and useful for someone resuming work later.
+- \`note\` is the CATCH-ALL: anything useful that is not a \`code_change\`, \`decision\` or
+  \`blocker\` goes in as \`note\`, with \`--meta\` carrying any unusual structure. There is
+  deliberately NO \`other\` type. NEVER write \`status_change\` — the server authors it on
+  every transition and the API rejects it from clients.
+- KEEP/DROP TEST — log a \`decision\` when ANY of these is true: an alternative was
+  considered and REJECTED (record which, and why it lost); a non-obvious assumption or
+  constraint was LOCKED IN; a choice was made that a later reader would otherwise
+  re-litigate. Do NOT log: restating the outcome, design or plan (they are already
+  fields on the intent); confirming something already written down elsewhere; mechanical
+  facts recoverable from git, CI or the tracker (test counts, file lists, commit hashes);
+  progress narration ("started X", "working on Y").
+  KEEP → "Parallelised the build across four subagents; the Laravel slices were split by
+  file ownership to avoid collisions in one working tree." — records the rejected
+  alternative (one agent per repo) and why it lost.
+  DROP → "make verify green at 2415 passed after merging all four agents." — a mechanical
+  fact already in the commit message and the CI output.
+- Promote to the parent intent — TWO filters, BOTH must pass: the entry is a \`decision\` or
+  \`blocker\` (never \`note\`/\`code_change\`), AND it passes the keep/drop test. Then ALSO
+  write a SECOND, separately-worded entry for a reader who never saw the task:
+  \`orbitmap log IN-x "<the decision and why>" --type decision --meta
+  '{"source":{"type":"task","id":"<task-uuid>"}}'\` (fall back to the TS- number if you
+  lack the UUID). Two distinct entries, never one shared row.
 
 ## End of session or task — MANDATORY
 - Task finished → default to **in_review** so a human verifies before closing:
   \`orbitmap log TS-x "Ready for review: …" --type note\` then
-  \`orbitmap status TS-x in_review\`.
+  \`orbitmap status TS-x in_review\` (add \`--delivery on_branch\` when code was committed).
 - Task finished AND the user's prompt or the task's agent_instructions explicitly say to
-  close without review → \`orbitmap log TS-x "Summary: …" --type note\` then
-  \`orbitmap status TS-x done\`.
-- Blocked by an external dependency you cannot resolve (waiting on another task, missing
-  access/credentials, unclear requirements, failing external service) →
-  \`orbitmap log TS-x "Blocked: <reason>" --type blocker\` then
-  \`orbitmap status TS-x blocked\`.
-- Session ending, task not done but NOT blocked → \`orbitmap log TS-x "Resume point: …"
+  close without review → log a summary \`note\`, then \`orbitmap status TS-x done\`.
+- Blocked by something outside your control → \`orbitmap log TS-x "Blocked: <reason>"
+  --type blocker\` then \`orbitmap status TS-x blocked\`.
+- Session ending, task unfinished but NOT blocked → \`orbitmap log TS-x "Resume point: …"
   --type note\` — leave status in_progress.
 - NEVER leave a task without a final log entry.
+- Closing the intent (ONLY when the user explicitly asks — Flow A never does) → the
+  transition must carry the build phase's entries (\`--log <type>:<content>\` is
+  repeatable): \`orbitmap intent update IN-x --status done --log code_change:"<what was
+  built>" --log note:"<what remains>"\`. A transition carrying no \`--log\` is REFUSED (422)
+  and writes nothing at all.
 
 ### Status decision guide
-- **in_review**: work is finished. THE DEFAULT for completed work. The requester should
-  verify before closing.
-- **done**: only when the prompt or task agent_instructions explicitly allow closing
-  without review ("auto-close", "mark as done", "no review needed"). A user saying "do
-  this task" is NOT permission to auto-close.
-- **blocked**: an external factor outside your control stops you. Always log the
-  specific blocker.
+- **in_review**: work finished. THE DEFAULT — the requester verifies before closing.
+- **done**: only when the prompt or agent_instructions explicitly allow closing without
+  review. "Do this task" is NOT permission to auto-close.
+- **blocked**: an external factor stops you. Always log the specific blocker.
 - **in_progress** (keep): session ends but you can resume autonomously next time.
 
-## Git workflow
-- When the task context contains a branch_name, create or switch to it:
-  \`git checkout -b <branch_name>\` (or \`git checkout <branch_name>\` if it exists).
-- If the task has NO branch_name, work on the current branch — do not create one.
-- Do NOT work directly on main/master/develop unless the task has no branch_name and you
-  are already on a feature branch.
-
-## Delivery flow
+## Git & delivery
+- Flow B: when the task context carries a \`branch_name\`, create or switch to it; without
+  one, stay on the current branch — and never work directly on main/master/develop.
 - Commit messages: prefix the entity number with its type tag —
   \`[TS-r5d8zf] Add delivery status field\` (also \`[IS-…]\`, \`[ID-…]\`, \`[VB-…]\`).
-- When you committed/pushed code during the task, finish with
-  \`orbitmap status TS-x <status> --delivery on_branch\`.
-- When the user asks what's in a branch/PR: \`git log target..source --oneline\`, parse
-  \`[TS-…]\`/\`[IS-…]\` tags, report the matched entities.
-- When the user reports a merge or release: update the relevant tasks with
-  \`--delivery merged\` or \`--delivery released\`.
-
-## Planning mode (agents with a plan mode)
-When you create an implementation plan for a tracked task, you MUST include OrbitMap
-lifecycle steps as explicit plan items:
-- First step: reference the OrbitMap task number and title.
-- Last steps, always: (1) \`orbitmap log\` with a summary of all changes; (2)
-  \`orbitmap status\` set per the status decision guide (or a resume-point log if
-  incomplete).
-
-## Example: completing a task (default → in_review)
-1. \`orbitmap tasks --status in_progress\` → empty
-2. \`orbitmap start\` → task context
-3. read agent_instructions; implement; run tests; commit with \`[TS-x]\` prefix
-4. \`orbitmap log TS-x "Implemented X by doing Y" --type code_change\`
-5. \`orbitmap log TS-x "Ready for review: all tests pass." --type note\`
-6. \`orbitmap status TS-x in_review --delivery on_branch\``;
-// ── Skill: orbitmap-planning — §8.5 ────────────────────────────────────────────
-export const SKILL_PLANNING_FRONTMATTER = `---
-name: orbitmap-planning
+- Committed/pushed code during a task → finish with \`--delivery on_branch\`.
+- Asked what's in a branch/PR: \`git log target..source --oneline\`, parse the \`[TS-…]\`
+  tags, report the matched entities.
+- The delivery status follows the merge/release EVENT, whoever performs it: on a merge
+  update the affected tasks with \`--delivery merged\`; on a release, \`--delivery released\`.
+
+## Rules
+- Flow A never merges, never pushes to the default branch, never closes tasks or the
+  intent as \`done\` — the run ends at \`in_review\` on the intent branch, intent at \`build\`.
+- Baseline before any change; "no new bugs" = no failure absent from the baseline.
+- The fix loop is goal-based — no round cap; termination is delivered-or-blocked plus
+  green gates, never a retry budget.
+- Decide-and-log within the design; \`blocked\` + continue for a stuck task; interrupt the
+  user only for intent-level risk. Never a silent skip.
+- Workers follow \`references/worker-contract.md\`: no git, no OrbitMap writes, no shared
+  test DB, no formatter, no dependency changes — the orchestrator owns all of those.
+- Flow B works on ONE task at a time.
+- Always read agent_instructions before implementing, then re-verify their claims against
+  the tree (distrust-and-verify).
+- Agents with a plan mode: an implementation plan for a tracked task MUST include the
+  lifecycle as explicit steps — first the task number/title, last the final \`orbitmap log\`
+  + \`orbitmap status\` per the status decision guide.
+- NEVER leave a task without a final log entry; never author \`status_change\`; an intent
+  transition without \`--log\` entries is refused (422).`;
+// Reference files shipped WITH the orbitmap-execute skill (the worker contract that
+// dispatched subagents read instead of the whole skill). See SkillDef.references for
+// the shape the installer consumes.
+export const SKILL_EXECUTE_REFERENCES = {
+    'references/worker-contract.md': `# Worker contract — building one task for the orchestrator
+
+You are a WORKER: a subagent dispatched by an orchestrator running the \`orbitmap-execute\`
+skill. You build exactly ONE task. The orchestrator owns everything shared — git, OrbitMap
+state, formatting, the test gates. Your job is the code and an honest report.
+
+## Read, then verify
+- Read your task verbatim: \`orbitmap task TS-x\` (read-only). Its agent_instructions are
+  your spec; task-level instructions override area-level ones.
+- DISTRUST AND VERIFY: re-grep every claim the instructions make about the tree ("X lives
+  in Y", "the verified list of call sites") before relying on it. Instructions age; the
+  tree is the truth. A claim that does not hold is a DEVIATION to report — adapt to the
+  real tree and say so; do not build on the false claim.
+
+## Boundaries — hard
+- Own ONLY the files named in your dispatch prompt. A change needed elsewhere is a
+  finding to report, never an edit to make.
+- NEVER run git — no commit, branch, stash, checkout. The orchestrator commits.
+- NEVER write OrbitMap state — no \`orbitmap log\` / \`status\` / \`create\` / \`update\`.
+  Reading (\`orbitmap task\`, \`orbitmap doc\`) is fine.
+- NEVER use the shared test DB or its Docker gate — parallel workers would collide on it.
+  The orchestrator runs those tests at fold time.
+- NEVER run the repo formatter (it rewrites files you do not own) and NEVER change
+  dependencies or lockfiles. Report the need instead.
+
+## Build
+- Implement within your file boundary, following the instructions and the repo's
+  conventions.
+- Write the task's TESTS as instructed — they gate your task at fold time.
+- Syntax-check everything you touch with cheap, isolated checks (\`php -l\`, \`tsc --noEmit\`,
+  \`python -m py_compile\`, a scoped non-shared test run) — never the shared gates.
+
+## Report — your final text goes to the orchestrator, not to a user
+Structure it as:
+- **Files changed** — every file, one line each on what changed and why.
+- **Deviations** — every departure from the instructions (including claims that did not
+  survive verification), and why.
+- **Out-of-scope findings** — bugs or risks outside your boundary: REPORT, never fix.
+- **Uncertainties** — anything you are not sure holds. Flagged beats hidden: the
+  orchestrator can check in seconds what a silent guess costs in hours.
+Plain and factual — the orchestrator folds, tests and commits from this report.`,
+};
+// ── Skill: orbitmap-plan — §8.5 ────────────────────────────────────────────
+export const SKILL_PLAN_FRONTMATTER = `---
+name: orbitmap-plan
 description: >
-  Planning with OrbitMap: missions (time-boxed focus), intents (goals grouping work),
-  promoting ideas to tasks, triaging issues, decomposing work into tasks and subtasks.
-  Use for "plan", "roadmap", "mission", "intent", "break this down", idea or issue
-  triage requests.
+  Planning an intent's design into executable tasks in OrbitMap — the third gate of the
+  product-building flow (after design). Decomposes the agreed design into Orb-hierarchy
+  tasks that provably cover the intent: tests per task + an intent-level test, a coverage
+  hard-gate, correct-area placement, self-contained context/doc-grounded agent_instructions,
+  cross-task notes in the intent plan field, and a doc-update-after-green step; then creates
+  the tasks and hands off to orbitmap-execute. Use for "plan this intent", "break this down
+  into tasks", an intent entering \`plan\` status — and for general planning (missions,
+  intents, promoting ideas, triaging issues).
 ---`;
-export const SKILL_PLANNING_BODY = `# Planning in OrbitMap
+export const SKILL_PLAN_BODY = `# Planning a design into executable tasks
+
+## Goal
+Produce the intent's PLAN — a validated set of executable Orb tasks (with tests and
+dependencies) that fully covers the design — and create those tasks. The task set plus the
+plan-field notes are this gate's one deliverable.
+
+**Interface:** every action below is an OrbitMap operation — run the \`orbitmap\` CLI command
+shown, or its equivalent MCP tool when this session uses MCP; \`orbitmap <cmd> --help\` and the
+MCP tool schemas are the authority. Never edit the workspace data files directly.
+
+## The outcome is the north star; the design is its communication form
+The tasks you plan exist to REALISE the intent's OUTCOME — the outcome is the north star,
+the direction everything heads toward. The design is NOT the end; it is the agreed
+communication form that expresses HOW the outcome gets built. So plan against the design,
+but keep the outcome as the test: every task, and the plan as a whole, must move the
+outcome closer — and if the design and the outcome ever disagree, the OUTCOME wins; surface
+the gap rather than planning to a design that misses it. Read the outcome AND the design
+first; every task traces back to both. If the design is missing or too thin to plan against
+(the intent has not been through the design gate), STOP and step aside to \`orbitmap-design\`
+— do not decompose an unsettled design.
+
+## The plan field may hold seed notes
+The intent's \`plan\` field may already carry seed notes — build-order, task ideas and
+execution risks that the \`orbitmap-brainstorm\` gate (or the user) filed there earlier. If
+it does, read them FIRST and treat them as your HIGHEST-PRIORITY input: the USER-marked
+notes outrank your own ideas and any agent notes. Absorb them into the plan you build, then
+let your finished plan-field write REPLACE them (absorb, then replace). If the field already
+holds a real plan (notes + summary) instead of seed notes, treat it as an existing plan to
+refine.
+
+## Key principles
+- **Cover the whole design.** The plan is complete only when every part of the design maps
+  to at least one task and the task set, executed, delivers the outcome. Under-coverage is
+  the main failure mode — the coverage check is a HARD GATE, not a nicety.
+- **Every task is testable, and the intent is tested.** Each task carries its own tests;
+  the intent gets ONE test that proves the whole outcome.
+- **Every task is self-contained.** A fresh execute-agent with ZERO prior context must
+  succeed from the task alone — so its \`agent_instructions\` carry the task's own summary,
+  the Orb context and doc pointers it needs, and its acceptance/tests.
+- **Flat tasks, no subtasks.** Decompose into a flat list of tasks; this gate does NOT use
+  subtasks. Express structure through dependencies, not nesting.
+- **Dependencies live in two places.** Wire the Orb dependency EDGE (\`orbitmap dep add\`) so
+  \`orbitmap-execute\` can compute the ready-set and order/parallelise work — AND name the
+  blocker and WHY inside the dependent task's own instructions ("depends on TS-x: needs the
+  schema it produces"), so a zero-context agent sees it without querying the graph.
+- **Right area.** Derive each task's area from the work itself (which repo/package), not
+  from where you happen to be; pass \`--area <slug>\` when it differs.
+- **Ground in verified reality.** Read the design, the relevant doc bodies and the repo
+  before decomposing — never plan against a stale or assumed state.
+- **Know the neighbourhood.** Reuse or extend the intent's EXISTING tasks — never silently
+  re-decompose work that already exists.
+- **One question at a time; ask sparingly; prefer multiple choice.** When you must ask,
+  offer enumerable options with a recommended default; open questions are a last resort.
 
 ## Hierarchy
 Mission (MS-) → Intent (IN-) → Task (TS-) / Issue (IS-). Missions and intents are
-workspace-level; tasks live in areas. An intent groups the tasks/issues that realise one
-goal; a mission time-boxes a set of intents (and directly-attached items) toward an
-outcome. At most ONE mission is active at a time.
-
-## Missions
-- \`orbitmap mission list\` / \`orbitmap mission show MS-x\`
-- \`orbitmap mission create "name" [--outcome "…"] [--start d] [--end d]\`
-- \`orbitmap mission status MS-x active|completed|cancelled\` — activating fails while
-  another mission is active; complete or cancel it first.
-- \`orbitmap mission link MS-x IN-y|TS-y|IS-y|ID-y\` / \`mission unlink\` — attach items.
-
-## Intents
-- \`orbitmap intent create "name" [--mission MS-x]\`, statuses:
-  new → design → plan → build → done (or cancelled); update with
-  \`orbitmap intent update IN-x --status build\`.
-- \`orbitmap intent link IN-x TS-y|IS-y\` attaches work items to the intent.
-- RULE (intent-exclusive): an item linked to an intent gets its mission THROUGH the
-  intent — never set a direct mission on a task/issue that has an intent. The CLI
-  enforces this; do not fight it.
-
-## Planning workflow (recommended when the user asks to plan a body of work)
-1. Clarify the outcome → \`orbitmap mission create\` (or pick the active mission).
-2. Split into goals → \`orbitmap intent create\` per goal, \`mission link\` them.
-3. Decompose each intent into concrete tasks →
-   \`orbitmap create "title" --intent IN-x [--priority p]\`, subtasks via
-   \`orbitmap subtask\`.
-4. Wire ordering constraints → \`orbitmap dep add TS-a TS-b\` (a depends on b).
-5. Review: \`orbitmap mission show MS-x\` and \`orbitmap overview\`.
-
-## Ideas (opportunities, not problems)
-- Capture: \`orbitmap idea add "…" [--priority p]\`.
-- Review: \`orbitmap idea list\` (default pending).
-- Promote to work: analyse the codebase first, then \`orbitmap create "task title"
-  --intent …\` referencing the idea in the description, then
-  \`orbitmap idea status ID-x used\`. Reject with \`… rejected\`.
-
-## Issues (problems)
-- Report: \`orbitmap issue register "title" --severity critical|high|medium|low
-  [--description "…"]\`.
-- Start investigating: \`orbitmap issue status IS-x investigating\`.
-- Convert to work: \`orbitmap create\` a fix task, link it, and resolve with
-  \`orbitmap issue resolve IS-x --task TS-y --resolution "…"\` (or status wont_fix /
-  duplicate with a reason).`;
+workspace-level and take no area; tasks and issues are area-scoped. An intent groups the
+tasks/issues that realise one goal; a mission time-boxes a set of intents toward an
+outcome. At most ONE mission is active at a time. RULE (intent-exclusive): an item linked
+to an intent gets its mission THROUGH the intent — never set a direct mission on a
+task/issue that has an intent; the CLI enforces this.
+
+## Dependencies
+- **Two layers, always.** The Orb dependency EDGE (\`orbitmap dep add TS-a TS-b\` — a
+  depends on b) is machine-readable, so \`orbitmap-execute\` computes the ready-set, orders
+  work, and runs independent tasks in parallel. The one-line "depends on TS-x: <why>" in
+  the dependent task's \`agent_instructions\` is what a zero-context agent reads without
+  querying the graph. Do both for every dependency.
+- **Only REAL blockers.** Add an edge only when a task genuinely cannot start until another
+  is done — it needs that task's output (a schema, an interface, a bumped contract). Never
+  encode mere preference or "feels tidier" ordering: false dependencies serialise work that
+  could have run in parallel.
+- **Depend on the smallest thing.** If a task needs just one artifact from its predecessor,
+  say exactly that in the note; do not over-couple whole tasks when one output suffices.
+- **Keep the DAG shallow and wide.** Prefer many independent tasks over a long chain — a
+  deep chain forces serial execution and slows the whole intent. Split or re-cut to widen
+  where the design allows.
+- **At least one ready task.** Some task must have NO dependencies — that is where execution
+  starts. A plan where everything depends on something else cannot begin; re-cut it.
+- **No cycles.** If A depends on B and B on A, the task boundaries are wrong — re-cut them.
+- **Cross-area dependencies are first-class.** Provider-before-consumer across repos (e.g. a
+  contract/schema change in one area before the tasks that re-vendor it in others) is a real
+  edge — wire it even though the tasks live in different areas.
+
+## Flow
+1. Gather context. Read the intent's \`outcome\` + \`design\` + \`plan\` field
+   (\`orbitmap intent show IN-x\`) — if the plan field holds seed notes, absorb them as
+   highest-priority input (see above); \`orbitmap context\`; the relevant doc BODIES (\`orbitmap doc <slug>\` — the design flagged
+   which); the neighbourhood (mission, sibling intents, and the intent's EXISTING tasks —
+   do not re-decompose them). Verify against the repo before decomposing.
+2. Decompose the design into a FLAT list of concrete tasks, each placed in the CORRECT
+   area — \`orbitmap create "title" --intent IN-x --area <slug> [--priority p]\`. No
+   subtasks.
+   - KEEP/DROP TEST — log a \`decision\` when ANY of these is true: an alternative was
+     considered and REJECTED (record which, and why it lost); a non-obvious assumption or
+     constraint was LOCKED IN; a choice was made that a later reader would otherwise
+     re-litigate. Do NOT log: restating the outcome, design or plan (they are already
+     fields on the intent); confirming something already written down elsewhere; mechanical
+     facts recoverable from git, CI or the tracker (test counts, file lists, commit hashes);
+     progress narration ("started X", "working on Y").
+     KEEP → "Parallelised the build across four subagents; the Laravel slices were split by
+     file ownership to avoid collisions in one working tree." — records the rejected
+     alternative (one agent per repo) and why it lost.
+     DROP → "make verify green at 2415 passed after merging all four agents." — a mechanical
+     fact already in the commit message and the CI output.
+   - LOG IT THE MOMENT IT IS AGREED, not batched at the end:
+     \`orbitmap log IN-x "<the decision and why — task shape, sequencing, area>" --type decision\`.
+     An abandoned session must still leave its decisions recorded.
+   - Progress stops (a design gap you cannot close, a missing prerequisite) →
+     \`orbitmap log IN-x "Blocked: <what stopped and why>" --type blocker\`.
+   - \`note\` is the CATCH-ALL — anything useful that is not \`code_change\` / \`decision\` /
+     \`blocker\` goes in as \`note\`, with \`--meta\` for unusual structure. There is deliberately
+     NO \`other\` type. NEVER write \`status_change\`: the server authors it on every transition.
+3. For EACH task, write \`agent_instructions\` a zero-context execute-agent can run from
+   alone: a one-line SUMMARY / outcome of the task; the Orb context + the specific doc
+   slugs + the files/acceptance it needs; its TESTS (what to add and how to run them); and,
+   if it is blocked, a one-line "depends on TS-x: <why>".
+4. Add ONE intent-level test that proves the whole outcome is delivered.
+5. Wire ordering — \`orbitmap dep add TS-a TS-b\` (a depends on b) — for every dependency,
+   matching the "depends on" line you put in the task's instructions.
+6. COVERAGE GATE (hard): walk the design element by element and confirm each maps to a
+   task, and that the task set as a whole delivers the outcome. If anything is uncovered,
+   add or fix tasks and re-check. Do NOT proceed while a gap remains.
+7. Write cross-task PLANNING NOTES + a short SUMMARY to the intent \`plan\` field —
+   \`orbitmap intent update IN-x --plan "<notes>"\`: decisions valid for all tasks,
+   sequencing rationale, and the coverage argument. This REPLACES any seed notes that were
+   in the field — you have already absorbed them.
+8. Ensure a final DOC-UPDATE task exists: after the implementation is done and all tests
+   are green, update the OrbitMap documentation (see the \`orbitmap-docs\` skill).
+9. SELF-REVIEW the plan with fresh eyes (see the Self-review section) and fix issues inline.
+10. Present the plan (tasks + areas + tests + the coverage argument) and get the user's
+    approval before creating anything.
+11. On approval: create the tasks + dependency edges, then SHOW the created tasks in the
+    terminal (display number · title · area · its dependencies) so the user sees exactly
+    what landed; write the plan field; advance the intent \`plan → build\` carrying this
+    gate's entries — \`--log <type>:<content>\` is REPEATABLE, and \`plan → build\` takes
+    \`decision\` (task shape) + \`note\` (resume point):
+    \`orbitmap intent update IN-x --status build --log decision:"<task-shape decision + why>" --log note:"<resume point>"\`
+    (a transition carrying no \`--log\` is REFUSED with 422 and writes nothing); and offer
+    the \`orbitmap-execute\` skill by name so the user can approve and start execution right
+    away — do NOT auto-chain into it yourself.
+
+## Self-review
+Before presenting, read the plan with fresh eyes — this is where a weak plan is caught:
+- **Placeholders?** Every task's instructions must be concrete: real files, real
+  acceptance, named tests. No "TBD", "add tests", "handle edge cases", or "similar to
+  above" without the specifics. Fix inline.
+- **Coverage holds?** Re-walk the design — every element still maps to a task, and the set
+  still delivers the outcome.
+- **Consistent?** What a task produces (names, interfaces, files) matches what its
+  dependents consume; the dependency edges form a sane DAG with no cycles.
+- **Right-sized?** Each task is independently testable — not a multi-day monolith, not a
+  trivial sliver a reviewer couldn't meaningfully gate.
+Fix any issue inline; no need to re-review — just fix and move on.
+
+## Process flow
+\`\`\`dot
+digraph orbitmap_plan {
+    "Gather context: design + outcome + docs + neighbourhood" [shape=box];
+    "Design solid enough to plan?" [shape=diamond];
+    "Step aside to orbitmap-design" [shape=box];
+    "Decompose into a flat list of tasks, each in the correct area" [shape=box];
+    "Log decisions passing the keep/drop test, as they land" [shape=box];
+    "Per task: summary + context/doc-grounded instructions + tests + depends-on line" [shape=box];
+    "Add one intent-level test" [shape=box];
+    "Wire dependency edges" [shape=box];
+    "Coverage complete? (every design element to a task)" [shape=diamond];
+    "Write plan-field notes + summary" [shape=box];
+    "Add doc-update-after-green task" [shape=box];
+    "Self-review the plan (placeholders / coverage / consistency / size)" [shape=box];
+    "User approves the plan?" [shape=diamond];
+    "Create tasks + dependency edges in Orb" [shape=box];
+    "Show the created tasks in the terminal" [shape=box];
+    "Advance status plan to build, with --log entries (refused if none)" [shape=box];
+    "Offer orbitmap-execute (approve to start execution)" [shape=doublecircle];
+
+    "Gather context: design + outcome + docs + neighbourhood" -> "Design solid enough to plan?";
+    "Design solid enough to plan?" -> "Step aside to orbitmap-design" [label="no"];
+    "Design solid enough to plan?" -> "Decompose into a flat list of tasks, each in the correct area" [label="yes"];
+    "Decompose into a flat list of tasks, each in the correct area" -> "Log decisions passing the keep/drop test, as they land";
+    "Log decisions passing the keep/drop test, as they land" -> "Per task: summary + context/doc-grounded instructions + tests + depends-on line";
+    "Per task: summary + context/doc-grounded instructions + tests + depends-on line" -> "Add one intent-level test";
+    "Add one intent-level test" -> "Wire dependency edges";
+    "Wire dependency edges" -> "Coverage complete? (every design element to a task)";
+    "Coverage complete? (every design element to a task)" -> "Decompose into a flat list of tasks, each in the correct area" [label="no, add tasks"];
+    "Coverage complete? (every design element to a task)" -> "Write plan-field notes + summary" [label="yes"];
+    "Write plan-field notes + summary" -> "Add doc-update-after-green task";
+    "Add doc-update-after-green task" -> "Self-review the plan (placeholders / coverage / consistency / size)";
+    "Self-review the plan (placeholders / coverage / consistency / size)" -> "User approves the plan?";
+    "User approves the plan?" -> "Decompose into a flat list of tasks, each in the correct area" [label="no, revise"];
+    "User approves the plan?" -> "Create tasks + dependency edges in Orb" [label="yes"];
+    "Create tasks + dependency edges in Orb" -> "Show the created tasks in the terminal";
+    "Show the created tasks in the terminal" -> "Advance status plan to build, with --log entries (refused if none)";
+    "Advance status plan to build, with --log entries (refused if none)" -> "Offer orbitmap-execute (approve to start execution)";
+}
+\`\`\`
+
+## Before you hand off
+- **Coverage?** Every design element maps to a task, and the set delivers the outcome.
+- **Tests?** Every task has tests; one intent-level test proves the outcome.
+- **Self-contained?** Every task's instructions carry summary + Orb context + doc pointers
+  + acceptance + any depends-on line — runnable by a zero-context agent.
+- **No placeholders?** Self-review done; no vague/TBD instructions remain.
+- **Areas?** Each task in the right area.
+- **Dependencies?** Orb dep edges wired AND named in the dependent tasks' instructions.
+- **Plan field?** Cross-task notes + a summary written to the intent \`plan\` field.
+- **Doc-update?** A doc-update-after-green task is in the plan.
+Then create the tasks + edges, SHOW them in the terminal, advance \`plan → build\`, and offer
+\`orbitmap-execute\` — never auto-chain.
+
+## Planning entities (reference)
+For general planning outside a single design (setting up missions, capturing ideas,
+triaging issues):
+- **Missions:** \`orbitmap mission list|show MS-x\`; \`orbitmap mission create "name"
+  [--outcome "…"] [--start d] [--end d]\`; \`orbitmap mission status MS-x
+  active|completed|cancelled\` (activating fails while another is active — complete/cancel
+  it first); \`orbitmap mission link|unlink MS-x IN-y|TS-y|IS-y|ID-y\`. A mission status
+  change takes the same repeatable \`--log <type>:<content>\` and is refused (422) without
+  at least one entry — \`cancelled\` above all needs its \`decision:"<why abandoned>"\`.
+  \`orbitmap log MS-x "…" --type …\` logs against a mission outside a transition.
+- **Intents:** \`orbitmap intent create "name" [--outcome "…"] [--design "…"] [--plan "…"]
+  [--mission MS-x]\`, statuses new → design → plan → build → done (or cancelled). The
+  \`outcome\` is the north star, \`design\` the agreed solution, \`plan\` the agreed build
+  plan — produced by the \`orbitmap-brainstorm\` / \`orbitmap-design\` / \`orbitmap-plan\`
+  gates respectively.
+- **Ideas (opportunities, not problems):** \`orbitmap idea add "…" [--priority p]\`;
+  \`orbitmap idea list\`; promote by analysing the codebase, then \`orbitmap create "title"
+  --intent …\` referencing the idea, then \`orbitmap idea status ID-x used\` (or \`rejected\`).
+- **Issues (problems):** \`orbitmap issue register "title" --severity
+  critical|high|medium|low [--description "…"]\`; \`orbitmap issue status IS-x
+  investigating\`; resolve with a fix task via \`orbitmap issue resolve IS-x --task TS-y
+  --resolution "…"\` (or \`wont_fix\` / \`duplicate\` with a reason).
+
+## Rules
+- Cover the whole design — the coverage check is a HARD GATE; never hand off with a gap.
+- Flat tasks only — no subtasks; express structure through dependencies.
+- Every task carries its tests; the intent carries one outcome-proving test.
+- Every task's \`agent_instructions\` are self-contained for a zero-context agent (summary +
+  Orb context + doc pointers + acceptance + any depends-on line). No placeholders.
+- Wire dependencies as Orb edges AND name them in the dependent tasks' instructions.
+- Place each task in the correct area; derive it from the work, not the current directory.
+- Self-review the plan before presenting; fix placeholders/coverage/consistency inline.
+- Write cross-task notes + a summary to the intent \`plan\` field.
+- Log \`decision\` entries that pass the keep/drop test (Flow step 2) as they are agreed, never
+  batched; \`blocker\` whenever progress stops — an abandoned session must still leave a record.
+- The \`plan → build\` transition must carry the gate's entries as repeatable
+  \`--log <type>:<content>\` — \`decision\` (task shape) + \`note\` (resume point); without at
+  least one it is refused (422) and nothing is written. Never author \`status_change\` — the
+  server writes it.
+- Include a doc-update-after-green task in every plan.
+- After approval, create the tasks + edges and SHOW them in the terminal.
+- Advance \`plan → build\` only after the user has approved the plan.
+- Never auto-chain into execution — offer \`orbitmap-execute\` and stop.`;
+// ── Skill: orbitmap-brainstorm — no MCP oracle counterpart (Orb works without superpowers) ──
+export const SKILL_BRAINSTORM_FRONTMATTER = `---
+name: orbitmap-brainstorm
+description: >
+  Brainstorming an idea into an agreed outcome in OrbitMap — the first gate of the
+  product-building flow, run as a natural thinking-partner conversation. You MUST use this
+  before any creative work — creating features, building components, adding functionality,
+  or modifying behavior. It explores intent, requirements and constraints one question at a
+  time until the outcome is AGREED, writes that outcome to the intent's outcome field, and
+  files useful asides to the design (and, when relevant, plan) fields for the later gates.
+  Use for "I have an idea", "brainstorm this", "let's think through X", "what should we
+  build/do about X", shaping an intent's outcome, or an intent at \`new\` status.
+---`;
+export const SKILL_BRAINSTORM_BODY = `# Framing an idea into an outcome
+
+## Goal
+Produce the intent's OUTCOME — a short statement of WHAT should change and WHY, that the
+user actually agrees to. That agreed outcome is this gate's deliverable; the design and
+plan are later gates' jobs.
+
+**Interface:** every action below is an OrbitMap operation — run the \`orbitmap\` CLI command
+shown, or its equivalent MCP tool when this session uses MCP; \`orbitmap <cmd> --help\` and the
+MCP tool schemas are the authority. Never edit the workspace data files directly.
+
+## From idea to agreed outcome
+This is the FIRST gate of OrbitMap's product-building flow, and it is a natural
+conversation — you are a thinking partner, not a form. Turn a raw idea into an outcome the
+user actually AGREES to; that agreement is the ONE thing you must reach before moving on.
+You are deciding WHAT should change and WHY — not designing the solution, not starting to
+build. As the conversation flows it will wander into HOW and into build-order; do not block
+on those — capture them as notes filed to the right downstream field (design or plan) and
+steer gently back to the outcome. The agreed outcome plus those routed notes are the baton
+you hand to \`orbitmap-design\` (and, through the plan field, to \`orbitmap-plan\`).
+
+## Key principles
+- **Thinking partner, not a form.** Follow the conversation and reflect back to converge —
+  do not interrogate. The ONE thing you must reach is an AGREED OUTCOME; everything else
+  useful gets captured for later, never blocked on.
+- **Gate before build.** No feature, component, or behavior change starts before the
+  outcome is agreed and written to OrbitMap. "Too simple to frame" is exactly where
+  unexamined assumptions cost the most — every idea gets an outcome, even a one-sentence
+  one.
+- **The outcome is an agreement, not your guess.** It is the user's, in the user's words.
+  Never advance on an assumed or half-agreed outcome.
+- **One question at a time.** Refine by dialogue, never a questionnaire dump.
+- **Prefer multiple choice — open questions are a LAST RESORT.** When a question's options
+  can be enumerated, ALWAYS offer them as a multiple choice with a recommended default; ask
+  an open-ended question only when the option space genuinely cannot be enumerated. Always
+  include a free-text "or something else — tell me" escape.
+- **Ask sparingly — earn every question.** Before asking: (1) answer it yourself from the
+  idea, the context and the repo — never ask what you can already determine; (2) drop it if
+  the answer would not change the outcome; (3) batch tightly-related micro-decisions into
+  ONE question. Prefer proposing a sensible default for the user to correct over an open
+  interrogation. Aim for the few highest-leverage questions — "one question at a time" sets
+  the pace, not the total count.
+- **Lead with a recommendation.** Present options and the outcome conversationally, leading
+  with the option you recommend and WHY — never a flat, neutral menu with no steer.
+- **YAGNI.** Cut every want that does not serve the outcome; a smaller outcome ships.
+- **Capture the user's opinions faithfully — and mark them as the user's.** Label the
+  user's notes as user notes in whichever field they land (design or plan); the design and
+  plan gates treat user-marked notes as their highest-priority input, so do not paraphrase
+  away their intent. You may add your own notes too — keep them clearly separate.
+- **Route notes by type (light-touch).** As the conversation surfaces useful asides, file
+  them to the field that will use them: HOW / tech / UX → the **design** notes; build-order
+  / task ideas / execution risks → the **plan** notes; WHAT / WHY stays in the outcome.
+  Capture the obvious and steer back — do not over-police a flowing conversation. Feeding
+  the plan field is OPTIONAL: only when the chat actually produced build-order material.
+- **Ground in verified reality — never frame on assumptions.** Before framing, verify the
+  idea against the actual repo and tracker, not the plan doc's or the user's claim: is this
+  already built or partially shipped, is a prerequisite phase actually done, do the named
+  entities exist? A wrong premise wastes the whole design and build that follow.
+- **Framing precedes design precedes build.** You decide WHAT and WHY here; HOW is the
+  design gate's job. For every point, ask "would a different answer change WHAT ships, or
+  only HOW it is built?" — route HOW answers (assets, routes, component structure, exact
+  validation) into the design notes, never into the agreed outcome. Do not slip into
+  solutioning.
+
+## Flow
+1. Gather context.
+   - \`orbitmap context\` and \`orbitmap intent show IN-x\` already carry the workspace,
+     mission, recently-used and open intents, and the target intent; read any referenced
+     idea (ID-) too.
+   - Check the repo itself — relevant files, docs, recent commits — when the outcome
+     touches existing code and to get all the context.
+   - Skim the available knowledge — the doc lists (\`available_docs\` across areas,
+     \`workspace_knowledge\`, \`orbit_docs\`), from the intent context if present, else
+     \`orbitmap docs\`. METADATA only (title / context / sections_count) — do not read bodies
+     here. Note which docs are relevant and record their slugs in the design notes.
+   - Know the neighbourhood (status matters): the MISSION's outcome + status (does this
+     intent serve a still-active mission?) and the SIBLING intents under that mission/orbit
+     with their outcomes + statuses — from the intent context if present, else
+     \`orbitmap mission show MS-x\` / \`orbitmap intents\`. Reconcile or link rather than frame
+     a duplicate/conflicting outcome; ignore siblings that are \`done\`/\`cancelled\`.
+   - Verify the premise before framing: is this already built or partially shipped, is any
+     prerequisite phase actually complete, do the named entities exist? Grep migrations /
+     commits / the tracker — frame on what is true NOW, not on the plan doc's claim.
+2. Clarify the idea into an outcome, ONE question at a time — the real goal, what changes
+   and for whom, what success looks like, the constraints. As you go, capture the user's
+   opinions, preferences and context as notes; these outrank your own ideas in the design
+   stage, so record them faithfully.
+   - KEEP/DROP TEST — log a \`decision\` when ANY of these is true: an alternative was
+     considered and REJECTED (record which, and why it lost); a non-obvious assumption or
+     constraint was LOCKED IN; a choice was made that a later reader would otherwise
+     re-litigate. Do NOT log: restating the outcome, design or plan (they are already
+     fields on the intent); confirming something already written down elsewhere; mechanical
+     facts recoverable from git, CI or the tracker (test counts, file lists, commit hashes);
+     progress narration ("started X", "working on Y").
+     KEEP → "Parallelised the build across four subagents; the Laravel slices were split by
+     file ownership to avoid collisions in one working tree." — records the rejected
+     alternative (one agent per repo) and why it lost.
+     DROP → "make verify green at 2415 passed after merging all four agents." — a mechanical
+     fact already in the commit message and the CI output.
+   - LOG IT THE MOMENT IT PASSES, not batched at the end: \`orbitmap log IN-x "<what was
+     decided and why>" --type decision\`. An abandoned session must still leave its decisions
+     recorded. If the intent does not exist yet, create it (step 4) at the first passing
+     answer and log from then on.
+   - Progress stops (missing access, an unanswerable question, a conflicting intent) →
+     \`orbitmap log IN-x "Blocked: <what stopped and why>" --type blocker\`.
+   - \`note\` is the CATCH-ALL — anything useful that is not \`code_change\` / \`decision\` /
+     \`blocker\` goes in as \`note\`, with \`--meta\` for unusual structure. There is deliberately
+     NO \`other\` type. NEVER write \`status_change\`: the server authors it on every transition.
+3. Present the outcome as a short, concrete statement that also names what is explicitly
+   OUT of scope and how success will be measured or checked. Refine it with the user until
+   they AGREE — never proceed on a vague or assumed outcome.
+4. Persist (create or refine). Update an existing unprocessed intent, or create one:
+   \`orbitmap intent update IN-x --outcome "<agreed outcome>" [--design "<design notes>"] [--plan "<plan notes>"]\`
+   / \`orbitmap intent create "<name>" --outcome "<agreed outcome>" [--design "…"] [--plan "…"]\`.
+   The agreed **outcome** goes in the outcome field. Route the captured notes by type —
+   HOW / tech / UX → the **design** field; build-order / task ideas / execution risks → the
+   **plan** field (OPTIONAL — only if the conversation produced any). Mark the user's notes
+   as the user's in both fields; you may add your own, kept separate. The design gate reads
+   the design notes and the plan gate reads the plan notes, each as its highest-priority
+   input.
+   - If you promoted an OrbitMap idea, mark it used: \`orbitmap idea status ID-x used\`.
+5. Advance the lifecycle, carrying this gate's entries — \`--log <type>:<content>\` is
+   REPEATABLE and \`new → design\` is decision-heavy (why this outcome, what is out of scope):
+   \`orbitmap intent update IN-x --status design --log decision:"<why this outcome>" --log decision:"<what is out of scope>"\`.
+   A transition carrying no \`--log\` is REFUSED (422) and writes nothing — not the status,
+   not an entry — so this is not optional.
+6. Ask the user whether to review the outcome further or start designing — offer the
+   \`orbitmap-design\` skill by name. Do NOT auto-chain into it yourself.
+
+## Process flow
+\`\`\`dot
+digraph orbitmap_brainstorm {
+    "Gather context: Orb (intents / idea) + repo (files, docs, commits)" [shape=box];
+    "Clarify idea into an outcome, one question at a time" [shape=box];
+    "Log decisions passing the keep/drop test, as they land" [shape=box];
+    "Capture user opinions / context as notes" [shape=box];
+    "Present the outcome" [shape=box];
+    "User agrees the outcome?" [shape=diamond];
+    "Create or refine intent: agreed outcome" [shape=box];
+    "Route notes to design/plan fields by type (marked as the user's)" [shape=box];
+    "Promote referenced idea to used" [shape=box];
+    "Advance status new to design, with --log entries (refused if none)" [shape=box];
+    "Offer orbitmap-design (review or design?)" [shape=doublecircle];
+
+    "Gather context: Orb (intents / idea) + repo (files, docs, commits)" -> "Clarify idea into an outcome, one question at a time";
+    "Clarify idea into an outcome, one question at a time" -> "Log decisions passing the keep/drop test, as they land";
+    "Log decisions passing the keep/drop test, as they land" -> "Capture user opinions / context as notes";
+    "Capture user opinions / context as notes" -> "Present the outcome";
+    "Present the outcome" -> "User agrees the outcome?";
+    "User agrees the outcome?" -> "Clarify idea into an outcome, one question at a time" [label="no, refine"];
+    "User agrees the outcome?" -> "Create or refine intent: agreed outcome" [label="yes"];
+    "Create or refine intent: agreed outcome" -> "Route notes to design/plan fields by type (marked as the user's)";
+    "Route notes to design/plan fields by type (marked as the user's)" -> "Promote referenced idea to used";
+    "Promote referenced idea to used" -> "Advance status new to design, with --log entries (refused if none)";
+    "Advance status new to design, with --log entries (refused if none)" -> "Offer orbitmap-design (review or design?)";
+}
+\`\`\`
+
+## After the outcome
+Before handing off, review the agreed outcome with fresh eyes:
+- **Vague or assumed?** Is it concrete and in the user's words, or did you fill gaps? Fix.
+- **Unmeasurable?** Can you tell when it is met? If not, sharpen the success criteria.
+- **Too big?** If it needs several independent designs, decompose into sibling intents and
+  frame the first — do not hand design an outcome that is really three outcomes.
+Then write it (Flow step 4), advance \`new → design\`, and hand the baton to
+\`orbitmap-design\` — never auto-chain.
+
+## Rules
+- One question at a time — never dump a checklist of questions on the user in one turn.
+- The outcome is an AGREEMENT, not your guess: never advance to \`design\` status until the
+  user has agreed the outcome in words.
+- Mark the user's notes as the user's in whichever field they land (design or plan): the
+  design and plan gates treat user-marked notes as highest-priority input. Add your own
+  notes too, kept clearly separate.
+- Route notes by type (light-touch): HOW/tech/UX → design field; build-order/task/risk →
+  plan field (optional); WHAT/WHY stays in the outcome. Capture and steer back; do not
+  over-police the conversation.
+- Log \`decision\` entries that pass the keep/drop test (Flow step 2) as they land, never
+  batched; \`blocker\` whenever progress stops — an abandoned session must still leave a record.
+- The \`new → design\` transition must carry the gate's entries as repeatable
+  \`--log <type>:<content>\`; without at least one it is refused (422) and nothing is written.
+  Never author \`status_change\` — the server writes it.
+- Create-or-refine: reuse an existing unprocessed intent instead of creating a duplicate.
+- Ground the outcome in verified repo/tracker reality, not the plan doc or a stated claim —
+  check it is still needed and still undone before framing.
+- Keep the outcome WHAT/WHY: name what is OUT of scope and how success is measured; push
+  HOW answers into the design notes.
+- If the intent already has an agreed outcome (status \`design\` or later), step aside and
+  point at \`orbitmap-design\` — do not re-frame a settled outcome.
+- Never auto-chain into designing after framing — always ask first.`;
+// ── Skill: orbitmap-design — no MCP oracle counterpart (Orb works without superpowers) ──
+export const SKILL_DESIGN_FRONTMATTER = `---
+name: orbitmap-design
+description: >
+  Designing an intent's solution in OrbitMap: turns an agreed outcome into an approach,
+  technical spec, and UX (when there's UI), one question at a time, then writes the
+  result to the intent's design field. Use for "design this intent", "let's design X", or
+  an intent entering \`design\` status. Use it once the outcome is agreed; if the outcome is
+  still missing or vague, step aside to \`orbitmap-brainstorm\` first.
+---`;
+export const SKILL_DESIGN_BODY = `# Designing an intent's solution
+
+## Goal
+Produce the intent's DESIGN — a buildable, code-grounded markdown doc (approach, technical
+spec, UX where there's UI) that a plan can be built from. That design doc is this gate's
+one deliverable.
+
+**Interface:** every action below is an OrbitMap operation — run the \`orbitmap\` CLI command
+shown, or its equivalent MCP tool when this session uses MCP; \`orbitmap <cmd> --help\` and the
+MCP tool schemas are the authority. Never edit the workspace data files directly.
+
+## The outcome is the north star
+An intent's \`outcome\` is why the design exists — the design's only job is to bring that
+outcome to life. Read it and internalize it before anything else; every question you ask
+and every section you write must trace back to it. If the outcome is missing, or too
+vague to design against, STOP. The framing gate comes before the solution gate: if the
+outcome is missing or still vague (intent at \`new\`), step aside to \`orbitmap-brainstorm\` to
+settle it first — do not design a solution for an outcome that is not solid yet.
+
+## The framing notes are your highest-priority input
+When the \`orbitmap-brainstorm\` gate ran first, the intent's \`design\` field arrives holding
+framing notes — NOT a design doc: the user's notes (marked as the user's) plus any notes
+the framing agent added. Read them FIRST. The USER-marked notes are your HIGHEST-PRIORITY
+input — they outrank your own ideas and the agent notes; treat the agent notes as normal
+input. Absorb all of them — honor and reflect them in the design you build — then let your
+finished design doc REPLACE them in the field (absorb, then replace). If the field already
+holds a real design doc instead of raw notes, treat it as existing design to refine.
+
+## Key principles
+- **Serve the outcome.** Every question and every section traces back to the outcome; if
+  it does not, cut it or go fix the outcome first.
+- **One question at a time.** Refine by dialogue, never a questionnaire dump.
+- **Prefer multiple choice — open questions are a LAST RESORT.** When a question's options
+  can be enumerated, ALWAYS offer them as a multiple choice with a recommended default; ask
+  an open-ended question only when the option space genuinely cannot be enumerated. Always
+  include a free-text "or something else — tell me" escape.
+- **Ask sparingly — earn every question.** Before asking: (1) answer it yourself from the
+  outcome, the notes and the repo — never ask what you can already determine; (2) drop it
+  if the answer would not change the design; (3) batch tightly-related micro-decisions into
+  ONE question. Prefer proposing a sensible default for the user to correct over an open
+  interrogation. Aim for the few highest-leverage questions — "one question at a time" sets
+  the pace, not the total count.
+- **Lead with a recommendation.** When you propose approaches or technical options, lead
+  with the one you recommend and WHY — never a flat, neutral menu with no steer.
+- **YAGNI.** Cut every part of the design that does not serve the outcome; a smaller
+  design ships.
+- **Ground the spec in verified current code — never assume.** Read/grep every file and
+  behavior you rely on before asserting it; a design with a false claim about the code
+  misleads the builder and is worse than none. Carry nothing forward from the outcome stage
+  unchecked.
+- **Concrete and verbatim.** Name the exact files, classes, schemas/tokens and locked copy —
+  not prose behavior — so a builder can execute the design without re-deriving it.
+- **Ground every proposal in the existing codebase.** Follow the patterns already there;
+  name the real files and classes; do not invent structure the repo does not use.
+
+## Working in existing codebases
+Explore the current structure BEFORE proposing anything, and follow the patterns already
+there — the canonical CRUD module, the sibling component you are mirroring, the existing
+route. Name the concrete files and classes your design will touch or create, each grounded
+in the equivalent existing pattern, so the design is buildable without re-derivation. Where
+existing code in your path has a real problem (a file grown too large, a tangled boundary),
+include a targeted fix as part of the design — but never propose unrelated refactoring;
+stay focused on what serves this outcome.
+
+## Design for isolation and clarity
+Break the solution into small units that each have ONE clear purpose, communicate through
+well-defined interfaces, and can be understood and tested independently. For each unit you
+should be able to say what it does, how it is used, and what it depends on. Two tests: can
+someone understand what a unit does without reading its internals, and can you change its
+internals without breaking its consumers? If not, the boundaries need work. Smaller,
+well-bounded units are easier to build, review, and reason about.
+
+## Flow
+1. Gather context.
+   - \`orbitmap intent show IN-x\` → the outcome and the design field; \`orbitmap context\`
+     for the workspace and mission. If the design field holds framing notes, absorb them
+     as highest-priority input (see above).
+   - Check the repo — relevant files, existing patterns, docs, recent commits. You design
+     against real code, so read it before proposing.
+   - Pull the relevant OrbitMap docs: from the doc lists (\`available_docs\` /
+     \`workspace_knowledge\` / \`orbit_docs\` — in the intent context if present, else
+     \`orbitmap docs\`, plus any slugs the framing notes flagged), READ the bodies that matter
+     with \`orbitmap doc <slug>\` (TOC → section → full) to ground the spec. Metadata is not
+     enough at the design gate.
+   - Know the neighbourhood (status matters): the MISSION's outcome + status (the design
+     must serve it), the SIBLING intents under the mission/orbit with their statuses, and
+     the intent's OWN tasks + issues with statuses — from the intent context if present,
+     else \`orbitmap mission show MS-x\` / \`orbitmap intents\` / the intent's linked items.
+     Design AROUND existing tasks — never silently re-decompose work that already exists.
+   - Verify, do not assume: Read/grep each "existing" file, route or component before you
+     rely on it, and re-check any claim the outcome stage carried forward.
+2. Clarify ONE question at a time, each anchored to the outcome — "to achieve <outcome>,
+   how should X work?" Cover technical decisions, UX (only if the intent has UI), edge
+   cases, data/API shape. Continuously check whether the emerging design actually delivers
+   the outcome, and surface any gap where it would not. Capture the user's decisions and
+   the reasoning behind them as you go — those decisions are part of the design.
+   - KEEP/DROP TEST — log a \`decision\` when ANY of these is true: an alternative was
+     considered and REJECTED (record which, and why it lost); a non-obvious assumption or
+     constraint was LOCKED IN; a choice was made that a later reader would otherwise
+     re-litigate. Do NOT log: restating the outcome, design or plan (they are already
+     fields on the intent); confirming something already written down elsewhere; mechanical
+     facts recoverable from git, CI or the tracker (test counts, file lists, commit hashes);
+     progress narration ("started X", "working on Y").
+     KEEP → "Parallelised the build across four subagents; the Laravel slices were split by
+     file ownership to avoid collisions in one working tree." — records the rejected
+     alternative (one agent per repo) and why it lost.
+     DROP → "make verify green at 2415 passed after merging all four agents." — a mechanical
+     fact already in the commit message and the CI output.
+   - LOG IT THE MOMENT IT IS AGREED, not batched at the end: \`orbitmap log IN-x "<the choice
+     and why, incl. what it rules out>" --type decision\`. An abandoned session must still
+     leave its decisions recorded.
+   - Progress stops (a blocking unknown, missing access, a contradicting design) →
+     \`orbitmap log IN-x "Blocked: <what stopped and why>" --type blocker\`.
+   - \`note\` is the CATCH-ALL — anything useful that is not \`code_change\` / \`decision\` /
+     \`blocker\` goes in as \`note\`, with \`--meta\` for unusual structure. There is deliberately
+     NO \`other\` type. NEVER write \`status_change\`: the server authors it on every transition.
+3. Explore approaches: propose 2-3 concrete approaches with their trade-offs, lead with the
+   one you recommend and WHY, and let the user pick before you spec anything. YAGNI the
+   rest — and record which approaches you weighed and why you rejected them.
+4. Draft ONE markdown design doc with these sections, in order:
+   - Outcome (restated)
+   - How this design delivers the outcome — MANDATORY: trace the design back to the
+     outcome explicitly; never skip this section
+   - Approach — the chosen approach and why
+   - Key decisions — the decisions taken with the user during design, each with its
+     rationale, so no one silently re-litigates or reverses them later
+   - Technical spec — name the concrete files / classes / components to touch or create,
+     each grounded in the existing pattern it mirrors; give exact class/method names,
+     schemas/tokens and locked copy for anything UI- or contract-facing, not prose alone
+   - UX design (only if the intent has UI)
+   - Alternatives considered / rejected — options weighed and declined, and WHY, so a
+     future contributor does not re-introduce a declined option
+   - Testing / verification approach — the tests to add and the gating commands to run
+     (e.g. \`make contract\`, \`make verify\`)
+   - Risks / open questions
+5. Present the draft in sections scaled to their complexity (a few sentences when simple,
+   more when nuanced); after each section ask whether it looks right, and get the user's
+   approval before writing anything.
+6. Write it: \`orbitmap intent update IN-x --design "<doc>"\`. This REPLACES any framing
+   notes that were in the field — you have already absorbed them into the doc.
+7. Advance the lifecycle, carrying this gate's entries — \`--log <type>:<content>\` is
+   REPEATABLE and \`design → plan\` is decision-heavy (technical choices, rejected
+   alternatives):
+   \`orbitmap intent update IN-x --status plan --log decision:"<technical choice + why>" --log decision:"<alternative rejected + why>"\`.
+   A transition carrying no \`--log\` is REFUSED (422) and writes nothing — not the status,
+   not an entry — so this is not optional.
+8. Ask the user whether to review the design further or start planning — offer the
+   \`orbitmap-plan\` skill by name. Do NOT auto-chain into it yourself.
+
+## Process flow
+\`\`\`dot
+digraph orbitmap_design {
+    "Gather context: outcome + notes + repo (files, patterns, docs)" [shape=box];
+    "Internalize the outcome (north star)" [shape=box];
+    "Outcome solid enough to design?" [shape=diamond];
+    "Step aside to orbitmap-brainstorm" [shape=box];
+    "Clarify one question at a time, anchored to the outcome" [shape=box];
+    "Log decisions passing the keep/drop test, as they land" [shape=box];
+    "Explore approaches (2-3, recommend, user picks)" [shape=box];
+    "Draft the design doc (outcome-delivery trace mandatory)" [shape=box];
+    "User approves the draft?" [shape=diamond];
+    "Write design field (replaces framing notes)" [shape=box];
+    "Advance status design to plan, with --log entries (refused if none)" [shape=box];
+    "Offer orbitmap-plan (review or plan?)" [shape=doublecircle];
+
+    "Gather context: outcome + notes + repo (files, patterns, docs)" -> "Internalize the outcome (north star)";
+    "Internalize the outcome (north star)" -> "Outcome solid enough to design?";
+    "Outcome solid enough to design?" -> "Step aside to orbitmap-brainstorm" [label="no"];
+    "Outcome solid enough to design?" -> "Clarify one question at a time, anchored to the outcome" [label="yes"];
+    "Clarify one question at a time, anchored to the outcome" -> "Log decisions passing the keep/drop test, as they land";
+    "Log decisions passing the keep/drop test, as they land" -> "Explore approaches (2-3, recommend, user picks)";
+    "Explore approaches (2-3, recommend, user picks)" -> "Draft the design doc (outcome-delivery trace mandatory)";
+    "Draft the design doc (outcome-delivery trace mandatory)" -> "User approves the draft?";
+    "User approves the draft?" -> "Clarify one question at a time, anchored to the outcome" [label="no, refine"];
+    "User approves the draft?" -> "Write design field (replaces framing notes)" [label="yes"];
+    "Write design field (replaces framing notes)" -> "Advance status design to plan, with --log entries (refused if none)";
+    "Advance status design to plan, with --log entries (refused if none)" -> "Offer orbitmap-plan (review or plan?)";
+}
+\`\`\`
+
+## Format
+One markdown document holds both the technical spec and the UX design (when the intent
+has UI) — there is no separate field for either. It renders wherever the intent's design
+is shown, so write it as a document a human would actually want to read.
+
+## Before you hand off
+Review the draft with fresh eyes before you write it:
+- **Placeholders?** Any TBD / TODO / vague requirement? Fix them inline.
+- **Delivers the outcome?** Does the "how this design delivers the outcome" trace actually
+  hold end to end? If there is a gap where it would not, close it.
+- **Internally consistent?** Do any sections contradict, or the approach not match the
+  spec? Reconcile them.
+- **Too big or ambiguous?** If it needs more than one implementation plan, note the split;
+  if a requirement reads two ways, pick one and make it explicit.
+- **Schema & tenancy guardrails?** For any schema / FK / migration change, verify multi-tenancy
+  (\`account_id\` isolation), RLS policies and Postgres triggers against the repo's audit
+  rules before handing off; and name the gating commands the plan must run.
+- **Verified, not assumed?** Is every claim about existing code checked against the repo,
+  not recalled? Fix any you have not actually Read/grepped.
+- **Concrete enough to build?** Does the Technical spec name real files/classes with exact
+  names, schemas and locked copy, and does the doc carry the Key decisions,
+  Alternatives-rejected, and Testing sections? If any is missing, it is not ready.
+Then write it (Flow step 6), advance \`design → plan\`, and hand the baton to
+\`orbitmap-plan\` — never auto-chain.
+
+## Rules
+- One question at a time — never dump a checklist of questions on the user in one turn.
+- If the outcome is missing or vague (intent at \`new\`), step aside to \`orbitmap-brainstorm\`
+  first — do not design against an unsettled outcome.
+- If the design field holds framing notes from the \`orbitmap-brainstorm\` gate, they are your
+  highest-priority input: absorb them, then let the finished doc replace them.
+- Every question, and every section of the draft, must serve the outcome; if it does
+  not, cut it or go fix the outcome first.
+- The "how this design delivers the outcome" section is mandatory, not optional.
+- Ground every claim about existing code in an actual Read/grep — never assert from memory.
+- Name concrete files/classes to touch in the Technical spec, grounded in the existing
+  pattern, with exact names/schemas and locked copy for UI/contract-facing pieces — never
+  ship a prose-only spec.
+- Capture the user's design decisions with their rationale, and record the alternatives you
+  rejected and why.
+- Log \`decision\` entries that pass the keep/drop test (Flow step 2) as they are agreed, never
+  batched; \`blocker\` whenever progress stops — an abandoned session must still leave a record.
+- The \`design → plan\` transition must carry the gate's entries as repeatable
+  \`--log <type>:<content>\`; without at least one it is refused (422) and nothing is written.
+  Never author \`status_change\` — the server writes it.
+- Follow existing codebase patterns; propose no unrelated refactoring.
+- Never advance the intent past \`design\` status until the user has approved the draft.
+- Never auto-chain into planning after writing the design — always ask first.`;
 // ── Skill: orbitmap-docs — §8.6 ────────────────────────────────────────────────
 export const SKILL_DOCS_FRONTMATTER = `---
 name: orbitmap-docs
@@ -246,6 +1165,18 @@ description: >
 ---`;
 export const SKILL_DOCS_BODY = `# OrbitMap documents
 
+Documents are workspace-level: exactly ONE copy per workspace, never per-area. No document
+command takes an area, and \`orbitmap context\` already lists them.
+
+## Goal
+Read and update OrbitMap documents efficiently: pull only the context you need (TOC →
+section → full, never dump a whole doc into the conversation), and make every change
+through the CLI — never by editing the workspace files directly.
+
+**Interface:** every action below is an OrbitMap operation — run the \`orbitmap\` CLI command
+shown, or its equivalent MCP tool when this session uses MCP; \`orbitmap <cmd> --help\` and the
+MCP tool schemas are the authority. Never edit the workspace data files directly.
+
 ## Choosing what to read
 \`orbitmap docs\` lists documents with their \`context\` (when the doc is relevant) and
 \`sections_count\`. Use context to pick the right document; use sections_count to decide
@@ -273,14 +1204,25 @@ export const SKILLS = [
         body: SKILL_ORBITMAP_BODY,
     },
     {
-        name: 'orbitmap-working',
-        frontmatter: SKILL_WORKING_FRONTMATTER,
-        body: SKILL_WORKING_BODY,
+        name: 'orbitmap-execute',
+        frontmatter: SKILL_EXECUTE_FRONTMATTER,
+        body: SKILL_EXECUTE_BODY,
+        references: SKILL_EXECUTE_REFERENCES,
+    },
+    {
+        name: 'orbitmap-plan',
+        frontmatter: SKILL_PLAN_FRONTMATTER,
+        body: SKILL_PLAN_BODY,
+    },
+    {
+        name: 'orbitmap-brainstorm',
+        frontmatter: SKILL_BRAINSTORM_FRONTMATTER,
+        body: SKILL_BRAINSTORM_BODY,
     },
     {
-        name: 'orbitmap-planning',
-        frontmatter: SKILL_PLANNING_FRONTMATTER,
-        body: SKILL_PLANNING_BODY,
+        name: 'orbitmap-design',
+        frontmatter: SKILL_DESIGN_FRONTMATTER,
+        body: SKILL_DESIGN_BODY,
     },
     {
         name: 'orbitmap-docs',
@@ -292,40 +1234,61 @@ export const SKILLS = [
 // Claude variant — §8.2, verbatim (without the markers, which buildClaudeHook adds).
 export const THIN_HOOK_CLAUDE = `## OrbitMap
 
-This project tracks work in OrbitMap via the \`orbitmap\` CLI (works the same whether data
-is in the cloud or in local files). When the user mentions tasks, backlog, missions,
-intents, ideas, issues, vibes, or asks you to work on / log / plan something, load the
-matching skill: \`orbitmap\` (context & commands), \`orbitmap-working\` (doing tasks),
-\`orbitmap-planning\` (missions/intents/ideas/issues), \`orbitmap-docs\` (documents).
-Golden rules: work on ONE task at a time; NEVER finish a task session without a final
-\`orbitmap log\` entry and an \`orbitmap status\` update; finished work defaults to
-\`in_review\`, not \`done\`. NEVER edit files inside the OrbitMap workspace directory
-directly — always go through \`orbitmap\` commands.`;
+This project tracks work in OrbitMap via the \`orbitmap\` CLI (cloud or local files alike).
+You work in a WORKSPACE: run \`orbitmap context\` first — one call gives the workspace, your
+areas, the active mission, open intents, tasks and documents. Never ask which area — it
+follows from the directory (map in \`.orbitmap/config.json\`); missions, intents and docs
+need none. When the user mentions tasks, backlog, missions, intents, ideas, issues, vibes,
+or design, load the matching skill: \`orbitmap\` (core), \`orbitmap-execute\` (tasks),
+\`orbitmap-plan\` (missions/intents/ideas/issues), \`orbitmap-brainstorm\` (idea → outcome),
+\`orbitmap-design\` (intent solutions), \`orbitmap-docs\` (documents).
+Golden rules: ONE task at a time per worker — the execute skill orchestrates intents; NEVER
+finish without a final \`orbitmap log\` entry and \`orbitmap status\` update — finished work
+defaults to \`in_review\`, not \`done\`. NEVER edit workspace files directly — always use \`orbitmap\`.`;
 // Non-Claude variant: same rules, but points at the inlined sections below instead of
 // skills that these agents cannot load.
 export const THIN_HOOK_GENERIC = `## OrbitMap
 
-This project tracks work in OrbitMap via the \`orbitmap\` CLI (works the same whether data
-is in the cloud or in local files). When the user mentions tasks, backlog, missions,
-intents, ideas, issues, vibes, or asks you to work on / log / plan something, follow the
-sections below: core (context & commands), working on tasks, planning
-(missions/intents/ideas/issues), and documents.
-Golden rules: work on ONE task at a time; NEVER finish a task session without a final
-\`orbitmap log\` entry and an \`orbitmap status\` update; finished work defaults to
-\`in_review\`, not \`done\`. NEVER edit files inside the OrbitMap workspace directory
-directly — always go through \`orbitmap\` commands.`;
+This project tracks work in OrbitMap via the \`orbitmap\` CLI (cloud or local files alike).
+You work in a WORKSPACE: run \`orbitmap context\` first — one call gives the workspace, your
+areas, the active mission, open intents, tasks and documents. Never ask which area — it
+follows from the directory (map in \`.orbitmap/config.json\`); missions, intents and docs
+need none. When the user mentions tasks, backlog, missions, intents, ideas, issues, vibes,
+or design, follow the sections below: core (context & commands), working on tasks,
+planning (missions/intents/ideas/issues), framing an idea into an outcome, designing an
+intent's solution, and documents.
+Golden rules: ONE task at a time per worker — intent execution orchestrates its tasks; NEVER
+finish a task session without a final \`orbitmap log\` entry and an \`orbitmap status\` update;
+finished work defaults to \`in_review\`, not \`done\`. NEVER edit workspace files directly — always use \`orbitmap\`.`;
 // ── Assembly helpers ───────────────────────────────────────────────────────────
 /** Build one SKILL.md file (frontmatter + body) for Claude. */
 export function buildSkillFile(skill) {
     return `${skill.frontmatter}\n\n${skill.body}\n`;
 }
-/** Build the thin always-on block for a Claude config file (CLAUDE.md). */
-export function buildClaudeHook() {
-    return `${MARKER_START}\n${THIN_HOOK_CLAUDE}\n${MARKER_END}`;
+/**
+ * One extra line appended to the Claude hook when the skills were installed at PROJECT
+ * scope. `CLAUDE.md` is inherited by every sub-directory, but a project-level
+ * `.claude/skills/` directory is not: a session started in a sibling or child repository
+ * reads this hook and cannot load the skills it names. The hook must therefore say where
+ * the skills actually are, and how to make them visible everywhere. At user scope the
+ * skills are visible wherever the hook is, so no caveat is needed.
+ */
+export const SKILL_SCOPE_CAVEAT_PROJECT = 'These skills are installed at PROJECT scope, in this directory\'s `.claude/skills/`. ' +
+    'If you cannot load them (e.g. this session started in a different directory), do not ' +
+    'guess the workflow — ask the user to run `orbitmap setup-agent --scope user`, which ' +
+    'installs them into `~/.claude/skills/` where every session can see them.';
+/**
+ * Build the thin always-on block for a Claude config file (CLAUDE.md).
+ * `scope` is where the accompanying skill files were installed — see
+ * {@link SKILL_SCOPE_CAVEAT_PROJECT}.
+ */
+export function buildClaudeHook(scope = 'user') {
+    const body = scope === 'project' ? `${THIN_HOOK_CLAUDE}\n${SKILL_SCOPE_CAVEAT_PROJECT}` : THIN_HOOK_CLAUDE;
+    return `${MARKER_START}\n${body}\n${MARKER_END}`;
 }
 /**
- * Build the markdown fallback block for non-Claude agents: the thin hook plus all four
- * skill bodies inlined (no skill ecosystem to lean on).
+ * Build the markdown fallback block for non-Claude agents: the thin hook plus every
+ * skill body inlined (no skill ecosystem to lean on).
  */
 export function buildGenericBlock() {
     const bodies = SKILLS.map((skill) => skill.body).join('\n\n---\n\n');