orbitmap 0.3.0 → 0.4.1

package/dist/agent-instructions.js

@@ -5,282 +5,330 @@
 //                       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. CORE_INSTRUCTIONS — the deep, on-demand layer. Equivalent of the MCP tool
-//                       catalogue. Mirrors the MCP `full` profile 1:1, mapping all
-//                       27 MCP tools onto CLI commands. Shipped two ways:
-//                         - Claude:     installed as a `.claude/skills/orbitmap` skill,
+//   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
+//                       Shipped two ways:
+//                         - Claude:     one `.claude/skills/<name>/SKILL.md` per skill,
 //                                       loaded on demand (zero per-turn context cost).
-//                         - non-Claude: inlined into the agent config file as a
-//                                       markdown fallback (no skill ecosystem).
+//                         - non-Claude: all four bodies concatenated into the agent
+//                                       config file (no skill ecosystem to lean on).
 //
-// Reference: the OrbitMap MCP document
-// `orbitmap-mcp-system-instructions-i-tools-full-lite-manager` (INSTRUCTIONS_FULL).
-export const SKILL_NAME = 'orbitmap';
+// 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.
 export const MARKER_START = '<!-- ORBITMAP_START -->';
 export const MARKER_END = '<!-- ORBITMAP_END -->';
-// Skill frontmatter `description` — this is what Claude reads every turn to decide
-// whether to load the skill. Keep it dense with trigger words (mirrors the MCP
-// "when to use Orbitmap tools" guidance).
-export const SKILL_DESCRIPTION = 'Manage project work tracked in OrbitMap via the `orbitmap` CLI — tasks, ' +
-    'backlog, subtasks, work logs, issues, ideas, vibes, documents, orbits, and ' +
-    'delivery status. Use whenever the user mentions OrbitMap, "orbit", a task, the ' +
-    'backlog, or asks to start/resume/finish/log/assign work, create or update ' +
-    'tasks, or read/edit project docs. Covers the full task lifecycle, the ' +
-    'commit-message and delivery-status conventions, and the complete MCP-to-CLI ' +
-    'command mapping.';
-// ── The deep instruction body (single source for skill + markdown fallback) ──
-export const CORE_INSTRUCTIONS = `# OrbitMap (CLI)
-
-OrbitMap is an agentic project management platform. This project tracks its work in
-OrbitMap, and you reach it through the \`orbitmap\` CLI from the shell — invoke it as
-\`npx orbitmap <command>\` (or \`orbitmap <command>\` if installed globally). This is the
-CLI equivalent of the OrbitMap MCP server's **full** profile: every command below maps
-to an MCP tool. Add \`--json\` to any command for machine-readable output.
+/** The core skill name (entry point). Kept for backwards compatibility. */
+export const SKILL_NAME = 'orbitmap';
+// ── Skill: orbitmap (core) — §8.3 ──────────────────────────────────────────────
+export const SKILL_ORBITMAP_FRONTMATTER = `---
+name: orbitmap
+description: >
+  OrbitMap project management via the orbitmap CLI. Use when the user mentions OrbitMap,
+  orbit, tasks, backlog, missions, intents, ideas, issues, vibes, or asks to track,
+  plan, or log work. Entry point: object model, context resolution, command reference.
+---`;
+export const SKILL_ORBITMAP_BODY = `# OrbitMap CLI — core
+
+OrbitMap is an agentic project management platform. You interact with it exclusively
+through the \`orbitmap\` CLI (run with \`npx orbitmap …\` if not on PATH). The CLI works
+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.
 
 ## General behaviour
 - Always prioritise the user's direct request. If the user asks you to do something
-  (e.g. read a file, write code, answer a question), handle that request first.
-- Only interact with OrbitMap tasks when the user explicitly asks you to
-  (e.g. "check my tasks", "start a task", "what's on my backlog", "update docs", "create subtasks").
-- When the user mentions "OrbitMap", "orbit", "task", "backlog", or project management
-  concepts in the context of tracking work, use the \`orbitmap\` CLI to handle the request.
-
-## Project context
-- The CLI resolves the active project automatically from \`~/.orbitmap/config.json\`
-  (\`project_id\`) or the \`ORBITMAP_PROJECT_ID\` env var. You normally don't pass it.
-- Override it for a single command with \`--project <id-or-slug>\`.
-- If a command errors asking for project context, run \`orbitmap projects\` to discover
-  your projects, then retry with \`--project <id>\`.
-- Priority: explicit \`--project\` flag > \`ORBITMAP_PROJECT_ID\` env var > config file > auto-detect (single project).
+  (read a file, write code, answer a question), handle that first.
+- Only interact with OrbitMap when the user explicitly asks you to (e.g. "check my
+  tasks", "start a task", "what's on my backlog", "log this idea").
+- When the user mentions OrbitMap, orbit, task, backlog, or project-management concepts
+  in the context of tracking work, use \`orbitmap\` commands to handle the request.
+
+## Object model
+- Workspace = team level. Area = repo-level scope (formerly Project) — tasks, vibes and
+  most issues live in an area. Mission (MS-) = time-boxed workspace focus; at most one
+  active. Intent (IN-) = workspace-level goal grouping tasks/issues. Idea (ID-) = future
+  possibility, not a problem. Issue (IS-) = problem/bug. Vibe (VB-) = ad-hoc work log
+  outside a task. Task (TS-) = unit of work.
+- 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.
 
 ## Task statuses
-Valid task statuses: \`backlog\`, \`todo\`, \`in_progress\`, \`in_review\`, \`review_changes\`, \`done\`, \`blocked\`.
-The default filter for \`orbitmap tasks\` is \`todo,in_progress\`. Pass \`--status <value>\`
-when the user explicitly asks for something else (e.g. \`orbitmap tasks --status backlog\`).
+backlog, todo, in_progress, in_review, review_changes, done, blocked.
+\`orbitmap tasks\` defaults to todo,in_progress. Ask for others explicitly, e.g.
+\`orbitmap tasks --status backlog\` when the user asks about the backlog.
+
+## Command reference (all commands accept --json)
+- Context: \`orbitmap context\`, \`orbitmap areas\`, \`orbitmap overview\`
+- 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]\`,
+  \`orbitmap subtask TS-parent "title"\`, \`orbitmap assign TS-x [agent]\`,
+  \`orbitmap dep add|remove TS-a TS-b\`, \`orbitmap log TS-x "msg" --type <t>\`
+- Issues: \`orbitmap issue register|list|show|status|resolve\`
+- Ideas: \`orbitmap idea add|list|show|status\`
+- Vibes: \`orbitmap vibe log|list|show\`
+- Missions: \`orbitmap mission list|show|create|update|status|link|unlink\`
+- Intents: \`orbitmap intent list|show|create|update|link|unlink\`
+- Documents: \`orbitmap docs\`, \`orbitmap doc <slug> [--section "## H"|--full]\`,
+  \`orbitmap doc-import\`, \`orbitmap doc-update\`
+
+## Error handling
+- 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
+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.
+---`;
+export const SKILL_WORKING_BODY = `# Working on OrbitMap tasks
 
 ## 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 <id>\` → read the logs → resume.
-3. If not → \`orbitmap start\` — auto-picks the first todo task, fetches context, sets status to in_progress.
+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.
 
-Use \`orbitmap start [task-id]\` to begin work. Use \`orbitmap task <id>\` to inspect tasks you are not starting.
+## 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
-- \`orbitmap log <task-id> "<message>" --type <type>\` — for work WITHIN a task
-  (types: \`note\`, \`code_change\`, \`decision\`, \`blocker\`).
-- \`orbitmap vibe log --content "<message>" --type <type>\` — for ad-hoc work outside a
-  task (vibe types: \`discovery\`, \`exploration\`, \`fix\`).
-- \`orbitmap idea add --content "<idea>"\` — for future possibilities, NOT problems
-  (use \`orbitmap issue register\` for those).
-- To convert an idea into work: \`orbitmap create <title>\` → \`orbitmap idea status <id> --status used\`.
-- When starting to investigate an issue: \`orbitmap issue status <id> investigating\`.
+- \`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.
 
-## End of session or task
-- Task finished → **default to \`in_review\`** so a human can verify the work before closing:
-  \`orbitmap log <id> "Ready for review: ..." --type note\` → \`orbitmap status <id> in_review\`.
-- Task finished AND the user's prompt or agent_instructions explicitly say to close/complete
-  without review → \`orbitmap log <id> "Summary: ..." --type note\` → \`orbitmap status <id> done\`.
-- Task blocked by an external dependency you cannot resolve (waiting on another task, missing
-  access/credentials, unclear requirements needing human input, a failing external service)
-  → \`orbitmap log <id> "Blocked: <reason>" --type blocker\` → \`orbitmap status <id> blocked\`.
-- Session ending, task not done but NOT blocked → \`orbitmap log <id> "Resume point: ..." --type note\`
-  — leave status as \`in_progress\`.
+## 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\`.
+- 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: …"
+  --type note\` — leave status in_progress.
 - NEVER leave a task without a final log entry.
 
 ### Status decision guide
-- Use \`in_review\` when work is finished. **This is the default for completed work.** The
-  person who requested the task should verify the result before it is closed.
-- Use \`done\` only when the user's prompt or task-level agent_instructions explicitly allow
-  closing without review (e.g. "auto-close", "mark as done", "no review needed"). A user
-  saying "do this task" is NOT permission to auto-close — only explicit opt-in counts.
-- Use \`blocked\` when you cannot continue due to an external factor outside your control.
-  Always log the specific blocker so the team knows what to unblock.
-- Keep \`in_progress\` when the session is ending but you can resume work autonomously next time.
+- **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_progress** (keep): session ends but you can resume autonomously next time.
 
 ## Git workflow
-- When the task has a \`branch_name\`, create or switch to it:
-  \`git checkout -b <branch_name>\` (or \`git checkout <branch_name>\` if it already exists).
-- If the task has NO \`branch_name\`, work on the current branch — do not create one.
+- 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
-- **Commit messages**: prefix the entity number with its type tag: \`TS-\` (task), \`IS-\` (issue),
-  \`ID-\` (idea), \`VB-\` (vibe). E.g. \`[TS-r5d8zf] Add delivery status field\`.
-- **Finishing a task with commits**: when you committed and/or pushed code during the task,
-  add \`--delivery on_branch\`: \`orbitmap status <id> in_review --delivery on_branch\`.
-- **Branch scanning**: when the user asks what's in a branch or PR, run
-  \`git log target..source --oneline\`, parse \`[TS-xxxxx]\`/\`[IS-xxxxx]\` tags, and report matched entities.
-- **Delivery updates**: when the user tells you about a merge or release, update delivery
-  status: \`orbitmap status <id> done --delivery merged\` / \`orbitmap status <id> done --delivery released\`.
-
-## Planning mode (Claude Code / agents with plan mode)
-When you create an implementation plan (e.g. entering plan mode), you MUST include OrbitMap
-lifecycle steps as explicit items in the plan:
-- **First step**: reference the OrbitMap task ID and title so the plan stays linked to the task.
-- **Last steps** (always include these):
-  1. \`orbitmap log <id> "..." --type code_change\` with a summary of all changes made.
-  2. \`orbitmap status <id> <status>\` — set \`done\`, \`in_review\`, or \`blocked\` per the status
-     decision guide (or log a resume point if incomplete).
-
-## Documents
-- List docs with \`orbitmap docs\` — check each doc's \`context\` (when it's relevant) and
-  \`sections_count\` (whether to read the TOC first or go straight to full).
-- **Token-efficient reading flow:**
-  1. \`orbitmap doc <id-or-slug>\` → context + table of contents (TOC, cheap).
-  2. \`orbitmap doc <id-or-slug> --section "## Auth"\` → just that section.
-  3. \`orbitmap doc <id-or-slug> --full\` → full content (for large docs, prints a download URL).
-  Use the lightest mode that gives you what you need.
-- When \`--full\` returns a download URL for a large doc, download it locally
-  (\`orbitmap docs pull <slug>\` caches it under \`.orbitmap/docs/\`) and read the local file.
-  Do NOT paste full document content into the conversation.
-- **Section-based editing flow:**
-  1. \`orbitmap doc <id-or-slug>\` → read the TOC to find the section heading.
-  2. \`orbitmap doc <id-or-slug> --section "## Auth"\` → read the section you want to edit.
-  3. \`orbitmap doc-patch <id-or-slug> --base-version <n> --replace-section "## Auth" --content "..."\`.
-  Patch operations: \`--replace-section\`, \`--insert-section\`, \`--delete-section\`, \`--append\`.
-- For a full rewrite use \`orbitmap doc-update <id-or-slug> --file <path>\`. To update an
-  OrbitMap document, ALWAYS use \`doc-update\`/\`doc-patch\` — NEVER edit the cached local file directly.
-- **Workspace documents**: \`orbitmap start\`/\`orbitmap task <id>\` may surface workspace-level
-  knowledge (cross-project docs). Read them the same way as project docs.
-
-## Rules
-- Work on ONE task at a time.
-- Always read \`agent_instructions\` from the task before implementing.
-- Task-level \`agent_instructions\` take precedence over project-level instructions.
-- When working on subtasks, only work on subtasks assigned to you (the current agent) — do
-  not pick up subtasks assigned to other agents.
-- Do NOT mark a parent task as \`done\` if it still has unfinished subtasks, unless the user
-  explicitly asks you to.
-
-## Error handling
-- If the OrbitMap API is unreachable, inform the user and continue working without logging.
-- Do NOT retry failed OrbitMap commands in a loop — report the issue and proceed with the task.
-
-## Example workflows
-
-### Completing a task (default → in_review)
-User: "Work on my next task"
-1. \`orbitmap tasks --status in_progress\` → empty list
-2. \`orbitmap start\` → returns task context (title, description, agent_instructions, ...)
-3. Read agent_instructions, understand the task
-4. [implement the work — write code, edit files, run tests, commit & push]
-5. \`orbitmap log <id> "Implemented X by doing Y..." --type code_change\`
-6. \`orbitmap log <id> "Ready for review: completed task, all tests pass." --type note\`
-7. \`orbitmap status <id> in_review --delivery on_branch\`
-
-### Hitting a blocker
-4. [start work, discover missing API credentials]
-5. \`orbitmap log <id> "Blocked: need API key for service X, not in env vars or secrets." --type blocker\`
-6. \`orbitmap status <id> blocked\`
-
-## Command reference (MCP tool → CLI command)
-All 27 MCP \`full\`-profile tools map onto these commands.
-
-### Context & projects
-| MCP tool | CLI command |
-|----------|-------------|
-| \`get_my_context\` | \`orbitmap context\` |
-| \`get_my_projects\` | \`orbitmap projects\` |
-| \`create_project\` | \`orbitmap create-project <name> [--desc <text>] [--slug <slug>]\` |
-| \`list_project_members\` | \`orbitmap members <project-id>\` |
-
-### Tasks
-| MCP tool | CLI command |
-|----------|-------------|
-| \`get_tasks\` (list) | \`orbitmap tasks [--status <s>] [--priority <p>] [--orbit <id-or-slug>]\` |
-| \`get_tasks\` (detail) | \`orbitmap task <id>\` (or \`orbitmap get TS-xxxxx\`) |
-| \`start_task\` | \`orbitmap start [task-id]\` |
-| \`update_task_status\` | \`orbitmap status <task-id> <status> [--delivery <on_branch\\|merged\\|released>]\` |
-| \`create_task\` | \`orbitmap create <title> [--desc] [--priority] [--status] [--effort] [--agent-id] [--branch] [--instructions] [--from-issue]\` |
-| \`create_subtasks\` | \`orbitmap subtask <parent-id> <title> [--desc] [--priority] [--effort]\` |
-| \`manage_task_dependencies\` | \`orbitmap dep add\\|remove <task-id> <target-task-id> [--type depends_on\\|related] [--note]\` |
-| \`edit_task_content\` | \`orbitmap task-edit-content <task-id> [--title] [--description] [--agent-instructions]\` |
-| \`assign_task\` | \`orbitmap assign <task-id> [agent-id] [--user-id <id>]\` |
-
-### Work log
-| MCP tool | CLI command |
-|----------|-------------|
-| \`log_work\` (task-bound) | \`orbitmap log <task-id> "<message>" --type note\\|code_change\\|decision\\|blocker [--meta <json>]\` |
-| \`log_work\` (vibe) | \`orbitmap vibe log --content "<message>" --type discovery\\|exploration\\|fix [--title] [--task <id>]\` |
-
-### Documents
-| MCP tool | CLI command |
-|----------|-------------|
-| \`get_project_docs\` | \`orbitmap docs [--type <t>] [--search <q>]\` |
-| \`get_document\` | \`orbitmap doc <id-or-slug> [--full] [--section "## Heading"]\` |
-| \`import_document\` | \`orbitmap doc-import <title> --type <t> --file <path> [--context] [--source-path] [--workspace-id]\` |
-| \`edit_document\` (replace) | \`orbitmap doc-update <id-or-slug> --file <path> [--changelog]\` |
-| \`edit_document\` (patch) | \`orbitmap doc-patch <id-or-slug> --base-version <n> --replace-section\\|--insert-section\\|--delete-section\\|--append [--content] [--after] [--changelog]\` |
-| \`manage_document_sharing\` | \`orbitmap doc-share <doc-id> <project-id> [--agents]\` · \`orbitmap doc-unshare <doc-id> <project-id>\` · \`orbitmap doc-visibility <doc-id> <project-id> [--agents]\` |
-
-### Issues
-| MCP tool | CLI command |
-|----------|-------------|
-| \`register_issue\` | \`orbitmap issue register --title <t> --description <d> [--severity] [--related-task]\` |
-| \`get_issues\` (list) | \`orbitmap issues [--status] [--severity] [--limit]\` |
-| \`get_issues\` (detail) | \`orbitmap issue show <id-or-number>\` (or \`orbitmap get IS-xxxxx\`) |
-| \`update_issue_status\` | \`orbitmap issue status <id> <status>\` · \`orbitmap issue resolve <id> --status resolved\\|wont_fix\\|duplicate [--resolution] [--resolved-task]\` |
-
-### Vibes
-| MCP tool | CLI command |
-|----------|-------------|
-| \`get_vibes\` (list) | \`orbitmap vibes [--type] [--since] [--limit]\` |
-| \`get_vibes\` (detail) | \`orbitmap vibe show <id>\` (or \`orbitmap get VB-xxxxx\`) |
-
-### Ideas
-| MCP tool | CLI command |
-|----------|-------------|
-| \`log_idea\` | \`orbitmap idea add --content <text> [--title] [--priority]\` |
-| \`get_ideas\` (list) | \`orbitmap ideas [--status] [--priority] [--limit]\` |
-| \`get_ideas\` (detail) | \`orbitmap idea show <id-or-number>\` (or \`orbitmap get ID-xxxxx\`) |
-| \`update_idea_status\` | \`orbitmap idea status <id> --status pending\\|accepted\\|used\\|rejected\` |
-
-### Orbits
-| MCP tool | CLI command |
-|----------|-------------|
-| \`manage_orbit_item\` | \`orbitmap orbit attach\\|detach <orbit-id-or-slug> --type task\\|issue\\|vibe\\|document --id <uuid> [--note]\` |
-| \`get_orbit_items\` | \`orbitmap orbit items <orbit-id-or-slug> [--type]\` |
-
-Run \`orbitmap --help\` (or \`orbitmap <command> --help\`) for exact flags.`;
-// ── The thin always-on hook (CLAUDE.md / AGENTS.md) ──
-// Claude variant: points at the on-demand skill instead of inlining the full body.
+- 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
+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.
+---`;
+export const SKILL_PLANNING_BODY = `# Planning in OrbitMap
+
+## 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).`;
+// ── Skill: orbitmap-docs — §8.6 ────────────────────────────────────────────────
+export const SKILL_DOCS_FRONTMATTER = `---
+name: orbitmap-docs
+description: >
+  Reading and updating OrbitMap documents (specs, architecture, guides, decisions).
+  Use when the user asks to read, import, or update project documentation tracked in
+  OrbitMap.
+---`;
+export const SKILL_DOCS_BODY = `# OrbitMap documents
+
+## 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
+whether to fetch the TOC first (many sections) or go straight to full.
+
+## Token-efficient reading flow
+1. \`orbitmap doc <slug>\` → context + table of contents (cheap).
+2. \`orbitmap doc <slug> --section "## Auth"\` → just that section.
+3. \`orbitmap doc <slug> --full\` → full content (expensive — last resort).
+Use the lightest mode that answers your question. When the CLI reports a local file path
+for the full content, read that file instead of printing the content into the
+conversation.
+
+## Editing
+- Import a new document: \`orbitmap doc-import <file.md> --title "…" --type
+  spec|architecture|api|guide|decision|changelog|other [--context "…"]\`.
+- Update: \`orbitmap doc-update <slug> --file <file.md>\` (replaces content, bumps
+  version).
+- To change an OrbitMap document, ALWAYS go through these commands — NEVER edit files
+  inside the OrbitMap workspace/cache directories directly.`;
+export const SKILLS = [
+    {
+        name: 'orbitmap',
+        frontmatter: SKILL_ORBITMAP_FRONTMATTER,
+        body: SKILL_ORBITMAP_BODY,
+    },
+    {
+        name: 'orbitmap-working',
+        frontmatter: SKILL_WORKING_FRONTMATTER,
+        body: SKILL_WORKING_BODY,
+    },
+    {
+        name: 'orbitmap-planning',
+        frontmatter: SKILL_PLANNING_FRONTMATTER,
+        body: SKILL_PLANNING_BODY,
+    },
+    {
+        name: 'orbitmap-docs',
+        frontmatter: SKILL_DOCS_FRONTMATTER,
+        body: SKILL_DOCS_BODY,
+    },
+];
+// ── The thin always-on hook (CLAUDE.md / AGENTS.md) ────────────────────────────
+// Claude variant — §8.2, verbatim (without the markers, which buildClaudeHook adds).
 export const THIN_HOOK_CLAUDE = `## OrbitMap
-This project tracks its work in **OrbitMap**, reached via the \`orbitmap\` CLI (\`npx orbitmap <command>\`).
-When the user mentions OrbitMap, a task, the backlog, issues, ideas, or asks to start/resume/finish/log work — use it.
-
-Core loop: \`orbitmap tasks --status in_progress\` (resume) → \`orbitmap start\` (next todo) → read the task's
-\`agent_instructions\` → implement → \`orbitmap log <id> "..." --type code_change\` → \`orbitmap status <id> in_review\`.
-One task at a time; always log before finishing. Commit messages: \`[TS-<task_number>] summary\`.
 
-For the full workflow, rules, and every command, **use the \`orbitmap\` skill** — it loads on demand.`;
-// Non-Claude variant: same hook, but points at the inlined block below instead of a skill.
+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.`;
+// 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 its work in **OrbitMap**, reached via the \`orbitmap\` CLI (\`npx orbitmap <command>\`).
-When the user mentions OrbitMap, a task, the backlog, issues, ideas, or asks to start/resume/finish/log work — use it.
-
-Core loop: \`orbitmap tasks --status in_progress\` (resume) → \`orbitmap start\` (next todo) → read the task's
-\`agent_instructions\` → implement → \`orbitmap log <id> "..." --type code_change\` → \`orbitmap status <id> in_review\`.
-One task at a time; always log before finishing. Commit messages: \`[TS-<task_number>] summary\`.
 
-The full workflow, rules, and command reference follow below.`;
-// ── Assembly helpers ──
-/** Build the full SKILL.md file (frontmatter + body) for Claude. */
-export function buildSkillFile() {
-    return `---\nname: ${SKILL_NAME}\ndescription: ${SKILL_DESCRIPTION}\n---\n\n${CORE_INSTRUCTIONS}\n`;
+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.`;
+// ── 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}`;
 }
 /**
- * Build the markdown fallback block for non-Claude agents: the thin hook plus the
- * full inlined instructions (no skill ecosystem to lean on).
+ * Build the markdown fallback block for non-Claude agents: the thin hook plus all four
+ * skill bodies inlined (no skill ecosystem to lean on).
  */
 export function buildGenericBlock() {
-    return `${MARKER_START}\n${THIN_HOOK_GENERIC}\n\n${CORE_INSTRUCTIONS}\n${MARKER_END}`;
+    const bodies = SKILLS.map((skill) => skill.body).join('\n\n---\n\n');
+    return `${MARKER_START}\n${THIN_HOOK_GENERIC}\n\n${bodies}\n${MARKER_END}`;
 }
 //# sourceMappingURL=agent-instructions.js.map