orbitmap 0.2.0 → 0.4.0-next.0

package/dist/agent-instructions.d.ts

@@ -0,0 +1,32 @@
+export declare const MARKER_START = "<!-- ORBITMAP_START -->";
+export declare const MARKER_END = "<!-- ORBITMAP_END -->";
+/** The core skill name (entry point). Kept for backwards compatibility. */
+export declare const SKILL_NAME = "orbitmap";
+export declare const SKILL_ORBITMAP_FRONTMATTER = "---\nname: orbitmap\ndescription: >\n  OrbitMap project management via the orbitmap CLI. Use when the user mentions OrbitMap,\n  orbit, tasks, backlog, missions, intents, ideas, issues, vibes, or asks to track,\n  plan, or log work. Entry point: object model, context resolution, command reference.\n---";
+export declare const SKILL_ORBITMAP_BODY = "# OrbitMap CLI \u2014 core\n\nOrbitMap is an agentic project management platform. You interact with it exclusively\nthrough the `orbitmap` CLI (run with `npx orbitmap \u2026` if not on PATH). The CLI works\nidentically in cloud mode and local-files mode \u2014 never assume which one is active, and\nnever read or write the workspace's data files directly. The CLI is the only interface.\n\n## General behaviour\n- Always prioritise the user's direct request. If the user asks you to do something\n  (read a file, write code, answer a question), handle that first.\n- Only interact with OrbitMap when the user explicitly asks you to (e.g. \"check my\n  tasks\", \"start a task\", \"what's on my backlog\", \"log this idea\").\n- When the user mentions OrbitMap, orbit, task, backlog, or project-management concepts\n  in the context of tracking work, use `orbitmap` commands to handle the request.\n\n## Object model\n- Workspace = team level. Area = repo-level scope (formerly Project) \u2014 tasks, vibes and\n  most issues live in an area. Mission (MS-) = time-boxed workspace focus; at most one\n  active. Intent (IN-) = workspace-level goal grouping tasks/issues. Idea (ID-) = future\n  possibility, not a problem. Issue (IS-) = problem/bug. Vibe (VB-) = ad-hoc work log\n  outside a task. Task (TS-) = unit of work.\n- Entity numbers (TS-xxxxxx etc.) are accepted by every command that takes an id.\n\n## Context\n- Area resolves automatically (config/env). Override per call with `--area <slug>`.\n- If a command fails asking for area context, run `orbitmap areas` to list areas, then\n  retry with `--area`.\n- `orbitmap context` shows who you are, the workspace, and the active area. Run it when\n  unsure.\n\n## Task statuses\nbacklog, todo, in_progress, in_review, review_changes, done, blocked.\n`orbitmap tasks` defaults to todo,in_progress. Ask for others explicitly, e.g.\n`orbitmap tasks --status backlog` when the user asks about the backlog.\n\n## Command reference (all commands accept --json)\n- Context: `orbitmap context`, `orbitmap areas`, `orbitmap overview`\n- Tasks: `orbitmap tasks [--status s1,s2]`, `orbitmap task TS-x`, `orbitmap get <ID>`,\n  `orbitmap start [TS-x]`, `orbitmap status TS-x <status> [--delivery <d>]`,\n  `orbitmap create \"title\" [--intent IN-x|--mission MS-x] [--priority p]`,\n  `orbitmap subtask TS-parent \"title\"`, `orbitmap assign TS-x [agent]`,\n  `orbitmap dep add|remove TS-a TS-b`, `orbitmap log TS-x \"msg\" --type <t>`\n- Issues: `orbitmap issue register|list|show|status|resolve`\n- Ideas: `orbitmap idea add|list|show|status`\n- Vibes: `orbitmap vibe log|list|show`\n- Missions: `orbitmap mission list|show|create|update|status|link|unlink`\n- Intents: `orbitmap intent list|show|create|update|link|unlink`\n- Documents: `orbitmap docs`, `orbitmap doc <slug> [--section \"## H\"|--full]`,\n  `orbitmap doc-import`, `orbitmap doc-update`\n\n## Error handling\n- If OrbitMap is unreachable (network down / workspace directory unavailable), inform\n  the user and continue the primary work without logging. Do NOT retry failed orbitmap\n  calls in a loop \u2014 report the issue and proceed with the task.";
+export declare const SKILL_WORKING_FRONTMATTER = "---\nname: orbitmap-working\ndescription: >\n  Working on OrbitMap tasks: starting/resuming, logging work, decisions and blockers,\n  finishing with the correct status, git branches and delivery status. Use whenever\n  implementing, resuming, or finishing a tracked task.\n---";
+export declare const SKILL_WORKING_BODY = "# Working on OrbitMap tasks\n\n## Task workflow (on user request)\nWhen the user asks you to work on tasks:\n1. `orbitmap tasks --status in_progress` \u2014 check for unfinished work.\n2. If found \u2192 `orbitmap task TS-x` \u2192 read the work log \u2192 resume from the resume point.\n3. If not \u2192 `orbitmap start` \u2014 auto-picks the first todo task, sets it in_progress and\n   prints full context (description, agent_instructions, logs).\n4. If no tasks \u2192 inform the user.\nUse `orbitmap start TS-x` to begin a specific task; `orbitmap task TS-x` only inspects.\n\n## Rules\n- Work on ONE task at a time.\n- Always read agent_instructions from the task before implementing. Task-level\n  agent_instructions take precedence over area-level instructions.\n- Only work on subtasks assigned to you; do not pick up other agents' subtasks.\n- Do NOT mark a parent task done while it has unfinished subtasks, unless the user\n  explicitly asks.\n\n## Logging\n- `orbitmap log TS-x \"\u2026\" --type note|code_change|decision|blocker` \u2014 work WITHIN a task.\n- `orbitmap vibe log \"\u2026\" --type discovery|exploration|fix` \u2014 ad-hoc work outside a task.\n- Use `--type decision` when you pick between approaches, reject an alternative, or lock\n  in a non-obvious assumption \u2014 record the choice AND the why, not just the outcome.\n- `orbitmap idea add` \u2014 future possibilities, NOT problems (problems \u2192\n  `orbitmap issue register`).\n- Keep log content concrete, concise, and useful for someone resuming work later.\n\n## End of session or task \u2014 MANDATORY\n- Task finished \u2192 default to **in_review** so a human verifies before closing:\n  `orbitmap log TS-x \"Ready for review: \u2026\" --type note` then\n  `orbitmap status TS-x in_review`.\n- Task finished AND the user's prompt or the task's agent_instructions explicitly say to\n  close without review \u2192 `orbitmap log TS-x \"Summary: \u2026\" --type note` then\n  `orbitmap status TS-x done`.\n- Blocked by an external dependency you cannot resolve (waiting on another task, missing\n  access/credentials, unclear requirements, failing external service) \u2192\n  `orbitmap log TS-x \"Blocked: <reason>\" --type blocker` then\n  `orbitmap status TS-x blocked`.\n- Session ending, task not done but NOT blocked \u2192 `orbitmap log TS-x \"Resume point: \u2026\"\n  --type note` \u2014 leave status in_progress.\n- NEVER leave a task without a final log entry.\n\n### Status decision guide\n- **in_review**: work is finished. THE DEFAULT for completed work. The requester should\n  verify before closing.\n- **done**: only when the prompt or task agent_instructions explicitly allow closing\n  without review (\"auto-close\", \"mark as done\", \"no review needed\"). A user saying \"do\n  this task\" is NOT permission to auto-close.\n- **blocked**: an external factor outside your control stops you. Always log the\n  specific blocker.\n- **in_progress** (keep): session ends but you can resume autonomously next time.\n\n## Git workflow\n- When the task context contains a branch_name, create or switch to it:\n  `git checkout -b <branch_name>` (or `git checkout <branch_name>` if it exists).\n- If the task has NO branch_name, work on the current branch \u2014 do not create one.\n- Do NOT work directly on main/master/develop unless the task has no branch_name and you\n  are already on a feature branch.\n\n## Delivery flow\n- Commit messages: prefix the entity number with its type tag \u2014\n  `[TS-r5d8zf] Add delivery status field` (also `[IS-\u2026]`, `[ID-\u2026]`, `[VB-\u2026]`).\n- When you committed/pushed code during the task, finish with\n  `orbitmap status TS-x <status> --delivery on_branch`.\n- When the user asks what's in a branch/PR: `git log target..source --oneline`, parse\n  `[TS-\u2026]`/`[IS-\u2026]` tags, report the matched entities.\n- When the user reports a merge or release: update the relevant tasks with\n  `--delivery merged` or `--delivery released`.\n\n## Planning mode (agents with a plan mode)\nWhen you create an implementation plan for a tracked task, you MUST include OrbitMap\nlifecycle steps as explicit plan items:\n- First step: reference the OrbitMap task number and title.\n- Last steps, always: (1) `orbitmap log` with a summary of all changes; (2)\n  `orbitmap status` set per the status decision guide (or a resume-point log if\n  incomplete).\n\n## Example: completing a task (default \u2192 in_review)\n1. `orbitmap tasks --status in_progress` \u2192 empty\n2. `orbitmap start` \u2192 task context\n3. read agent_instructions; implement; run tests; commit with `[TS-x]` prefix\n4. `orbitmap log TS-x \"Implemented X by doing Y\" --type code_change`\n5. `orbitmap log TS-x \"Ready for review: all tests pass.\" --type note`\n6. `orbitmap status TS-x in_review --delivery on_branch`";
+export declare const SKILL_PLANNING_FRONTMATTER = "---\nname: orbitmap-planning\ndescription: >\n  Planning with OrbitMap: missions (time-boxed focus), intents (goals grouping work),\n  promoting ideas to tasks, triaging issues, decomposing work into tasks and subtasks.\n  Use for \"plan\", \"roadmap\", \"mission\", \"intent\", \"break this down\", idea or issue\n  triage requests.\n---";
+export declare const SKILL_PLANNING_BODY = "# Planning in OrbitMap\n\n## Hierarchy\nMission (MS-) \u2192 Intent (IN-) \u2192 Task (TS-) / Issue (IS-). Missions and intents are\nworkspace-level; tasks live in areas. An intent groups the tasks/issues that realise one\ngoal; a mission time-boxes a set of intents (and directly-attached items) toward an\noutcome. At most ONE mission is active at a time.\n\n## Missions\n- `orbitmap mission list` / `orbitmap mission show MS-x`\n- `orbitmap mission create \"name\" [--outcome \"\u2026\"] [--start d] [--end d]`\n- `orbitmap mission status MS-x active|completed|cancelled` \u2014 activating fails while\n  another mission is active; complete or cancel it first.\n- `orbitmap mission link MS-x IN-y|TS-y|IS-y|ID-y` / `mission unlink` \u2014 attach items.\n\n## Intents\n- `orbitmap intent create \"name\" [--mission MS-x]`, statuses:\n  new \u2192 design \u2192 plan \u2192 build \u2192 done (or cancelled); update with\n  `orbitmap intent update IN-x --status build`.\n- `orbitmap intent link IN-x TS-y|IS-y` attaches work items to the intent.\n- RULE (intent-exclusive): an item linked to an intent gets its mission THROUGH the\n  intent \u2014 never set a direct mission on a task/issue that has an intent. The CLI\n  enforces this; do not fight it.\n\n## Planning workflow (recommended when the user asks to plan a body of work)\n1. Clarify the outcome \u2192 `orbitmap mission create` (or pick the active mission).\n2. Split into goals \u2192 `orbitmap intent create` per goal, `mission link` them.\n3. Decompose each intent into concrete tasks \u2192\n   `orbitmap create \"title\" --intent IN-x [--priority p]`, subtasks via\n   `orbitmap subtask`.\n4. Wire ordering constraints \u2192 `orbitmap dep add TS-a TS-b` (a depends on b).\n5. Review: `orbitmap mission show MS-x` and `orbitmap overview`.\n\n## Ideas (opportunities, not problems)\n- Capture: `orbitmap idea add \"\u2026\" [--priority p]`.\n- Review: `orbitmap idea list` (default pending).\n- Promote to work: analyse the codebase first, then `orbitmap create \"task title\"\n  --intent \u2026` referencing the idea in the description, then\n  `orbitmap idea status ID-x used`. Reject with `\u2026 rejected`.\n\n## Issues (problems)\n- Report: `orbitmap issue register \"title\" --severity critical|high|medium|low\n  [--description \"\u2026\"]`.\n- Start investigating: `orbitmap issue status IS-x investigating`.\n- Convert to work: `orbitmap create` a fix task, link it, and resolve with\n  `orbitmap issue resolve IS-x --task TS-y --resolution \"\u2026\"` (or status wont_fix /\n  duplicate with a reason).";
+export declare const SKILL_DOCS_FRONTMATTER = "---\nname: orbitmap-docs\ndescription: >\n  Reading and updating OrbitMap documents (specs, architecture, guides, decisions).\n  Use when the user asks to read, import, or update project documentation tracked in\n  OrbitMap.\n---";
+export declare const SKILL_DOCS_BODY = "# OrbitMap documents\n\n## Choosing what to read\n`orbitmap docs` lists documents with their `context` (when the doc is relevant) and\n`sections_count`. Use context to pick the right document; use sections_count to decide\nwhether to fetch the TOC first (many sections) or go straight to full.\n\n## Token-efficient reading flow\n1. `orbitmap doc <slug>` \u2192 context + table of contents (cheap).\n2. `orbitmap doc <slug> --section \"## Auth\"` \u2192 just that section.\n3. `orbitmap doc <slug> --full` \u2192 full content (expensive \u2014 last resort).\nUse the lightest mode that answers your question. When the CLI reports a local file path\nfor the full content, read that file instead of printing the content into the\nconversation.\n\n## Editing\n- Import a new document: `orbitmap doc-import <file.md> --title \"\u2026\" --type\n  spec|architecture|api|guide|decision|changelog|other [--context \"\u2026\"]`.\n- Update: `orbitmap doc-update <slug> --file <file.md>` (replaces content, bumps\n  version).\n- To change an OrbitMap document, ALWAYS go through these commands \u2014 NEVER edit files\n  inside the OrbitMap workspace/cache directories directly.";
+export interface SkillDef {
+    /** Skill name = directory name under `.claude/skills/`. */
+    name: string;
+    /** Verbatim YAML frontmatter block, including the `---` fences. */
+    frontmatter: string;
+    /** Verbatim markdown body. */
+    body: string;
+}
+export declare const SKILLS: readonly SkillDef[];
+export declare const THIN_HOOK_CLAUDE = "## OrbitMap\n\nThis project tracks work in OrbitMap via the `orbitmap` CLI (works the same whether data\nis in the cloud or in local files). When the user mentions tasks, backlog, missions,\nintents, ideas, issues, vibes, or asks you to work on / log / plan something, load the\nmatching skill: `orbitmap` (context & commands), `orbitmap-working` (doing tasks),\n`orbitmap-planning` (missions/intents/ideas/issues), `orbitmap-docs` (documents).\nGolden rules: work on ONE task at a time; NEVER finish a task session without a final\n`orbitmap log` entry and an `orbitmap status` update; finished work defaults to\n`in_review`, not `done`. NEVER edit files inside the OrbitMap workspace directory\ndirectly \u2014 always go through `orbitmap` commands.";
+export declare const THIN_HOOK_GENERIC = "## OrbitMap\n\nThis project tracks work in OrbitMap via the `orbitmap` CLI (works the same whether data\nis in the cloud or in local files). When the user mentions tasks, backlog, missions,\nintents, ideas, issues, vibes, or asks you to work on / log / plan something, follow the\nsections below: core (context & commands), working on tasks, planning\n(missions/intents/ideas/issues), and documents.\nGolden rules: work on ONE task at a time; NEVER finish a task session without a final\n`orbitmap log` entry and an `orbitmap status` update; finished work defaults to\n`in_review`, not `done`. NEVER edit files inside the OrbitMap workspace directory\ndirectly \u2014 always go through `orbitmap` commands.";
+/** Build one SKILL.md file (frontmatter + body) for Claude. */
+export declare function buildSkillFile(skill: SkillDef): string;
+/** Build the thin always-on block for a Claude config file (CLAUDE.md). */
+export declare function buildClaudeHook(): string;
+/**
+ * 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 declare function buildGenericBlock(): string;

package/dist/agent-instructions.js

@@ -0,0 +1,334 @@
+// Single source of truth for all OrbitMap agent-facing instruction text.
+//
+// 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
+//                       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
+//                                       config file (no skill ecosystem to lean on).
+//
+// 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 -->';
+/** 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
+  (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
+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 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.
+
+## 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 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 — 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
+- **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 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-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 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 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 all four
+ * skill bodies inlined (no skill ecosystem to lean on).
+ */
+export function buildGenericBlock() {
+    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

package/dist/agent-instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-instructions.js","sourceRoot":"","sources":["../src/agent-instructions.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,EAAE;AACF,2DAA2D;AAC3D,oFAAoF;AACpF,oFAAoF;AACpF,oFAAoF;AACpF,+EAA+E;AAC/E,+EAA+E;AAC/E,uEAAuE;AACvE,iFAAiF;AACjF,oFAAoF;AACpF,+EAA+E;AAC/E,wDAAwD;AACxD,0CAA0C;AAC1C,wFAAwF;AACxF,uFAAuF;AACvF,oFAAoF;AACpF,qFAAqF;AACrF,EAAE;AACF,+DAA+D;AAC/D,gEAAgE;AAChE,uFAAuF;AACvF,uEAAuE;AAEvE,MAAM,CAAC,MAAM,YAAY,GAAG,yBAAyB,CAAC;AACtD,MAAM,CAAC,MAAM,UAAU,GAAG,uBAAuB,CAAC;AAElD,2EAA2E;AAC3E,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAC;AAErC,kFAAkF;AAElF,MAAM,CAAC,MAAM,0BAA0B,GAAG;;;;;;IAMtC,CAAC;AAEL,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gEAqD6B,CAAC;AAEjE,kFAAkF;AAElF,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;IAMrC,CAAC;AAEL,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2DAoFyB,CAAC;AAE5D,kFAAkF;AAElF,MAAM,CAAC,MAAM,0BAA0B,GAAG;;;;;;;IAOtC,CAAC;AAEL,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BA8CP,CAAC;AAE7B,kFAAkF;AAElF,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;IAMlC,CAAC;AAEL,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;4DAqB6B,CAAC;AAa7D,MAAM,CAAC,MAAM,MAAM,GAAwB;IACzC;QACE,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,0BAA0B;QACvC,IAAI,EAAE,mBAAmB;KAC1B;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,WAAW,EAAE,yBAAyB;QACtC,IAAI,EAAE,kBAAkB;KACzB;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE,0BAA0B;QACvC,IAAI,EAAE,mBAAmB;KAC1B;IACD;QACE,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,sBAAsB;QACnC,IAAI,EAAE,eAAe;KACtB;CACO,CAAC;AAEX,kFAAkF;AAElF,qFAAqF;AACrF,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;oDAUoB,CAAC;AAErD,sFAAsF;AACtF,wCAAwC;AACxC,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;oDAUmB,CAAC;AAErD,kFAAkF;AAElF,+DAA+D;AAC/D,MAAM,UAAU,cAAc,CAAC,KAAe;IAC5C,OAAO,GAAG,KAAK,CAAC,WAAW,OAAO,KAAK,CAAC,IAAI,IAAI,CAAC;AACnD,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,eAAe;IAC7B,OAAO,GAAG,YAAY,KAAK,gBAAgB,KAAK,UAAU,EAAE,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACrE,OAAO,GAAG,YAAY,KAAK,iBAAiB,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;AAC7E,CAAC"}

package/dist/api-client.d.ts

@@ -1,239 +1,8 @@
-export declare class OrbitMapClient {
-    private readonly apiKey;
-    private readonly baseUrl;
-    private readonly projectId?;
-    constructor(apiKey: string, projectId?: string, apiUrl?: string);
-    private request;
-    getContext(projectId?: string): Promise<unknown>;
-    getTasks(options?: {
-        status?: string;
-        priority?: string;
-        projectId?: string;
-        orbit?: string;
-    }): Promise<unknown>;
-    getTask(taskId: string): Promise<unknown>;
-    getTaskByNumber(taskNumber: string): Promise<unknown>;
-    startTask(taskId?: string): Promise<unknown>;
-    updateTaskStatus(taskId: string, status?: string, deliveryStatus?: string | null): Promise<unknown>;
-    createSubtasks(parentId: string, subtasks: Array<{
-        title: string;
-        description?: string;
-        priority?: string;
-        estimated_effort?: string;
-    }>): Promise<unknown>;
-    createTask(data: {
-        title: string;
-        description?: string;
-        status?: string;
-        priority?: string;
-        agent_instructions?: string;
-        branch_name?: string;
-        estimated_effort?: string;
-        agent_id?: string;
-        project_id?: string;
-        source_issue_id?: string;
-    }): Promise<unknown>;
-    assignTask(taskId: string, assignment: {
-        agent_id: string;
-    } | {
-        user_id: number;
-    }): Promise<unknown>;
-    editTaskContent(taskId: string, data: {
-        title?: string;
-        description?: string;
-        agent_instructions?: string;
-    }): Promise<unknown>;
-    addTaskDependency(taskId: string, data: {
-        target_task_id: string;
-        type?: string;
-        note?: string;
-    }): Promise<unknown>;
-    removeTaskDependency(taskId: string, targetTaskId: string, type?: string): Promise<unknown>;
-    logWork(taskId: string, type: string, content: string, metadata?: Record<string, unknown>): Promise<unknown>;
-    getDocuments(options?: {
-        type?: string;
-        search?: string;
-        projectId?: string;
-    }): Promise<unknown>;
-    getDocument(idOrSlug: string, mode?: 'inline' | 'file', options?: {
-        full?: boolean;
-        section?: string;
-    }): Promise<unknown>;
-    importDocument(data: {
-        title: string;
-        type: string;
-        content: string;
-        source_path?: string;
-        context?: string;
-        workspace_id?: string;
-    }): Promise<unknown>;
-    updateDocument(idOrSlug: string, content: string, changelog?: string): Promise<unknown>;
-    patchDocument(idOrSlug: string, operations: Array<Record<string, unknown>>, baseVersion: number, changelog?: string): Promise<unknown>;
-    requestUploadUrl(data: {
-        title: string;
-        type: string;
-        filename?: string;
-        source_path?: string;
-        context?: string;
-        workspace_id?: string;
-    }): Promise<{
-        data: {
-            upload_id: string;
-            document_id: string;
-            presigned_url: string;
-            storage_path: string;
-            expires_at: string;
-        };
-    }>;
-    confirmUpload(uploadId: string): Promise<{
-        data: {
-            document_id: string;
-            slug: string;
-            imported: boolean;
-        };
-    }>;
-    requestUpdateUploadUrl(idOrSlug: string, changelog?: string): Promise<{
-        data: {
-            upload_id: string;
-            document_id: string;
-            version: number;
-            presigned_url: string;
-            storage_path: string;
-            expires_at: string;
-        };
-    }>;
-    confirmUpdateUpload(idOrSlug: string, uploadId: string): Promise<{
-        data: {
-            document_id: string;
-            version: number;
-            updated: boolean;
-        };
-    }>;
-    uploadToPresignedUrl(presignedUrl: string, filePath: string, onProgress?: (bytesUploaded: number, totalBytes: number) => void): Promise<void>;
-    /**
-     * Attempts presigned URL upload for a new document.
-     * Returns null if the endpoint is not available (404), signaling caller to fall back.
-     */
-    presignedImport(filePath: string, data: {
-        title: string;
-        type: string;
-        source_path?: string;
-        context?: string;
-        workspace_id?: string;
-    }, onProgress?: (bytesUploaded: number, totalBytes: number) => void): Promise<{
-        data: {
-            document_id: string;
-            slug: string;
-            imported: boolean;
-        };
-        upload_method: string;
-    } | null>;
-    /**
-     * Attempts presigned URL upload for updating a document.
-     * Returns null if the endpoint is not available (404), signaling caller to fall back.
-     */
-    presignedUpdate(idOrSlug: string, filePath: string, changelog?: string, onProgress?: (bytesUploaded: number, totalBytes: number) => void): Promise<{
-        data: {
-            document_id: string;
-            version: number;
-            updated: boolean;
-        };
-        upload_method: string;
-    } | null>;
-    shareDocument(documentId: string, projectId: string, agentIds?: string[]): Promise<unknown>;
-    unshareDocument(documentId: string, projectId: string): Promise<unknown>;
-    setDocumentVisibility(documentId: string, projectId: string, agentIds: string[]): Promise<unknown>;
-    getProjects(): Promise<unknown>;
-    getProjectMembers(projectId: string): Promise<unknown>;
-    getProjectOverview(projectId: string): Promise<unknown>;
-    createProject(data: {
-        name: string;
-        description?: string;
-        slug?: string;
-    }): Promise<unknown>;
-    registerIssue(data: {
-        title: string;
-        description: string;
-        severity?: string;
-        related_task_id?: string;
-    }): Promise<unknown>;
-    listIssues(options?: {
-        status?: string;
-        severity?: string;
-        limit?: string;
-    }): Promise<unknown>;
-    getIssue(idOrNumber: string): Promise<unknown>;
-    getIssueByNumber(issueNumber: string): Promise<unknown>;
-    resolveIssueByNumber(issueNumber: string, data: {
-        status: string;
-        resolution?: string;
-        resolved_by_task_id?: string;
-    }): Promise<unknown>;
-    resolveIssue(idOrNumber: string, data: {
-        status: string;
-        resolution?: string;
-        resolved_by_task_id?: string;
-    }): Promise<unknown>;
-    updateIssueStatus(idOrNumber: string, data: {
-        status: string;
-        resolution?: string;
-        resolved_task_id?: string;
-    }): Promise<unknown>;
-    updateIssueStatusByNumber(issueNumber: string, data: {
-        status: string;
-        resolution?: string;
-        resolved_task_id?: string;
-    }): Promise<unknown>;
-    logVibe(data: {
-        content: string;
-        type: string;
-        title?: string;
-        task_id?: string;
-    }): Promise<unknown>;
-    listVibes(options?: {
-        type?: string;
-        since?: string;
-        limit?: string;
-    }): Promise<unknown>;
-    getVibe(id: string): Promise<unknown>;
-    updateVibe(id: string, data: {
-        type?: string;
-        title?: string;
-        content?: string;
-        metadata?: Record<string, unknown>;
-    }): Promise<unknown>;
-    listIdeas(options?: {
-        status?: string;
-        priority?: string;
-        limit?: string;
-    }): Promise<unknown>;
-    getIdea(idOrNumber: string): Promise<unknown>;
-    getIdeaByNumber(ideaNumber: string): Promise<unknown>;
-    createIdea(data: {
-        content: string;
-        title?: string;
-        priority?: string;
-        metadata?: Record<string, unknown>;
-    }): Promise<unknown>;
-    updateIdeaStatus(idOrNumber: string, data: {
-        status: string;
-    }): Promise<unknown>;
-    updateIdeaStatusByNumber(ideaNumber: string, data: {
-        status: string;
-    }): Promise<unknown>;
-    getOrbitItems(orbitIdOrSlug: string, options?: {
-        type?: string;
-    }): Promise<unknown>;
-    orbitAttach(orbitIdOrSlug: string, data: {
-        item_type: string;
-        item_id: string;
-        note?: string;
-    }): Promise<unknown>;
-    orbitDetach(orbitIdOrSlug: string, data: {
-        item_type: string;
-        item_id: string;
-    }): Promise<unknown>;
-    getWorkPrompt(): Promise<unknown>;
-    getImportDocsPrompt(): Promise<unknown>;
-}
-export declare function createClient(explicitProjectId?: string): Promise<OrbitMapClient>;
+/**
+ * Compatibility shim.
+ *
+ * The API client now lives in `src/adapters/cloud.ts` as `CloudAdapter`
+ * (re-exported here under its historical name `OrbitMapClient`). New code
+ * should import `createAdapter` from `./adapters/factory.js` instead.
+ */
+export * from './adapters/cloud.js';