[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6GV59H2X6CJAYJCX7S4ERJE":3,"skill-same:01M6GV59H2X6CJAYJCX7S4ERJE":62},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":37,"linkOnly":38,"markdownContent":39,"markdownBody":40,"frontMatter":41,"refName":42,"commitSha":43,"skillDirectory":44,"forksCount":14,"repositoryHtmlUrl":45,"repositoryHomepageUrl":6,"ownerHtmlUrl":46,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":47,"install":48,"resources":61},"01M6GV59H2X6CJAYJCX7S4ERJE","elegy-planning",null,"Use when an agent needs to create, inspect, update, validate, or export durable planning state — goals, roadmaps, plans, work points, todos, issues, review points, insights, and project runs — through the dedicated elegy-planning CLI over SQLite.","Sofreshx\u002FElegy","Sofreshx","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F46634397?v=4","01M6GV3ACQ2VKGTY22KKQDDPPG","Sfrsh","01M6GV3AYZA1GPCMY0JP2PQSVC",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002FSofreshx\u002FElegy\u002Fblob\u002Fmain\u002Fplugins\u002Fplanning\u002Fskills\u002Felegy-planning\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36],"elegy planning","planning","work","inspect","insights","plans","project","goals","export","use","review","sqlite","issues","state","update","create","validate","cli","2026-11-10 10:12:30",false,"---\r\nname: elegy-planning\r\ndescription: Use when an agent needs to create, inspect, update, validate, or export durable planning state — goals, roadmaps, plans, work points, todos, issues, review points, insights, and project runs — through the dedicated elegy-planning CLI over SQLite.\r\n---\r\n\r\n# Elegy Planning\r\n\r\n> Use when an agent needs to create, inspect, update, validate, or export durable planning state — goals, roadmaps, plans, work points, todos, issues, review points, insights, and project runs — through the dedicated `elegy-planning` CLI over SQLite.\r\n\r\nSQLite is the durable authority. Markdown and JSON projections are\ngenerated, derived outputs. Omitted scope defaults to `default` and\nthat silent default is a common source of agent mistakes — always pass\n`--scope \u003Cscope-key>` explicitly.\n\n## Setup and authority\n\n- Run from the Elegy repo root during development:\n  `cargo run -p elegy-planning -- --help`.\n- Use `--db \u003Cpath>` when the default repo-local SQLite database is not the\n  intended planning authority.\n- Use `--scope \u003Cscope-key>` on every call. Scope is part of the planning\n  identity, not display metadata.\n- Use `--json --non-interactive --correlation-id \u003Cid>` on every mutating call.\n- Do not edit SQLite directly. Use CLI commands so validation, FTS, tags, and\n  event history stay synchronized.\n- Serialize mutating calls. SQLite has a busy timeout, but agent workflows\n  should not launch parallel writes.\n\n## Ideology\n\n- `elegy-planning` is an agent contract, not a note-taking format.\n- SQLite is authority; projections, templates, and skill docs are routing\n  surfaces.\n- Durable writes should append events. Events are the review trail for later\n  agents.\n- Validation is advisory but persistent. Structural write invariants block bad\n  records; planning-quality findings guide follow-up work.\n- Stable explicit IDs are automation handles. Prefer them over generated IDs\n  in agent-authored workflows.\n- Batch authoring should be previewable. Use `roadmap scaffold --dry-run`,\n  inspect `rejected`, then apply.\n\n## Quick start\n\r\n1. Resolve the scope key. Use\r\n   `elegy-planning --scope \u003Cscope-key> scope list --json` to confirm the\r\n   scope exists. If the user did not name one, ask.\r\n2. Create a goal:\r\n   `elegy-planning --scope \u003Cscope-key> --json --non-interactive --correlation-id \u003Cid> goal create --id \u003Cslug> --title \u003Ct> --description \u003Cd> --acceptance \u003Ca> --acceptance \u003Ca> --rejection \u003Cr> --rejection \u003Cr>`.\r\n   Repeat `--acceptance` and `--rejection` for multiple criteria. Do\r\n   not comma-join values.\r\n3. Add a work point to a roadmap:\n   `elegy-planning --scope \u003Cscope-key> --json --non-interactive --correlation-id \u003Cid> roadmap add-section --roadmap-id \u003Cr> --id \u003Cs> --slug \u003Cslug> --title \u003Ct>` followed by\n   `roadmap add-work-point --roadmap-id \u003Cr> --id \u003Cwp> --title \u003Ct> --summary \u003Cs> --effort-tier \u003Cfast|balanced|deep> --file-scope \u003Ctype:intent:selector>`.\n4. For batch roadmap authoring, render `roadmap-workflow` and apply it:\n   `elegy-planning template render --template roadmap-workflow --output roadmap.yaml`, then\n   `elegy-planning --scope \u003Cscope-key> --json --non-interactive --correlation-id \u003Cid> roadmap scaffold --file roadmap.yaml --dry-run`.\n5. Inspect context before deep work:\n   `elegy-planning --scope \u003Cscope-key> --json context --entity-type goal --entity-id \u003Cid>` to load the goal plus related insights and\n   token estimates.\n6. Run a full validation pass:\n   `elegy-planning --scope \u003Cscope-key> --json validate all` to surface\n   referential integrity issues and stale references.\n\r\n## Tool-call guardrails\r\n\r\n### Read family (goal\u002Froadmap\u002Fplan\u002Fwork-point\u002Ftodo\u002Fissue\u002Freview-point\r\nshow & list, scope, search-extended, tags-list, context, work-graph,\r\nnext-runnable)\r\n\r\n- Argument shape: `\u003Centity> show --\u003Centity>-id \u003Cid> --json`. `show --id \u003Cid>`\n  is also accepted for goal, roadmap, work-point, plan, issue, insight, graph\n  node, graph edge, acceptance, and evidence show commands.\n  The `--json` flag is required for machine-mode parsing; do not omit it even\n  on a \"quick check\".\n- For list commands, pass `--limit \u003Cn>` to cap the result set; the\r\n  default limit is conservative but explicit is safer.\r\n- `search` and entity-local `search` commands support `--title`, `--tag`,\n  `--status`, and `--fts`. Pass each filter as a separate flag; do not stack\n  them in `--query`.\n- `context --entity-type \u003Ctype> --entity-id \u003Cid>` returns progressive\r\n  disclosure bundles with token estimates. The estimate is\r\n  informational; do not parse it.\r\n- `work-graph` and `next-runnable` are read-only but can return\r\n  large payloads; always pass `--limit` for `next-runnable` to avoid\r\n  pulling the whole work queue.\r\n- `insight list --all` lists all insights in the active scope.\r\n  Omit `--all` and pass `--parent-type` + `--parent-id` for\r\n  parent-specific listing (existing behavior).\r\n- Side-effect class: `read_only`.\r\n- Approval posture: `none`.\r\n\r\n### Mutate family (create \u002F update-status \u002F plan-revise \u002F insight-record)\r\n\r\n- Always pass `--json --non-interactive --correlation-id \u003Cid>` on every\n  mutating call. The CLI refuses interactive prompts when\r\n  `--non-interactive` is set, and a missing `--correlation-id` causes\r\n  the call to fail under machine mode. Both flags together are the\r\n  contract.\r\n- Multi-value flags (`--acceptance`, `--rejection`, `--tag`,\r\n  `--file-scope`, `--related-entity`) must be **repeated** per value:\r\n  `--acceptance \u003Ca1> --acceptance \u003Ca2>`. Comma-joining is silently\r\n  dropped.\r\n- `plan-revise` removal semantics: passing `--routing-hint \"\"` or\r\n  omitting `--file-scopes` does **not** clear existing values. Use\r\n  `--clear-routing-hint` and `--clear-file-scopes` to remove\r\n  previously set values. These two flags are the only reliable way\r\n  to clear.\r\n- `--effort-tier` is required for `roadmap add-work-point` and\r\n  recommended for plan and todo authoring. Valid values are\r\n  `fast`, `balanced`, `deep`. The value affects validation depth,\r\n  not the durable record.\r\n- `roadmap add-work-point --dependency-id \u003Cid>` only accepts dependencies\r\n  that belong to the same roadmap. Cross-roadmap dependencies are\r\n  rejected at write time with `\"status\": \"invalid\"` and a\r\n  descriptive `error` message.\r\n- Use `work-point revise --work-point-id \u003Cid> --dependency-id \u003Cid>...`\r\n  to add, replace, or `--clear-dependencies` to remove work-point\r\n  dependencies. Do not attempt direct SQLite repair.\r\n- File-scope selector grammar: `\u003Ctype>:\u003Cintent>:\u003Cselector>`. Types\r\n  are `exact` or `glob`. Intents are `primary`, `review`, or\r\n  `affected`. Example: `--file-scope glob:primary:shared\u002Fcore\u002F**`.\r\n- `--status` on `*-update-status` accepts the entity's lifecycle\r\n  states (e.g. `draft`, `proposed`, `active`, `validated`,\r\n  `invalidated`, `superseded`, `abandoned` for goals). Do not\r\n  transition to a state the entity is not currently allowed to\r\n  leave.\r\n- `scope create --metadata-file \u003Cpath>` reads metadata from a JSON\r\n  file. Mutually exclusive with `--metadata-json`. Errors include\r\n  the file path for faster diagnosis.\r\n- Side-effect class: `disk_write` against the SQLite database.\n- Approval posture: `advisory`. The host may require approval for\n  specific transitions (e.g. `validated`, `invalidated`).\n- Run mutating commands and read-after-write checks sequentially. SQLite uses a\n  local file lock; parallel show\u002Flist calls during writes can still race on busy\n  workstations.\n\n### Roadmap scaffold family\n\n- Use `roadmap scaffold --file \u003Cyaml|json> --dry-run` before `--apply`.\n- The scaffold file creates v1 records: scope, goal, roadmap, sections,\n  work-points, plan, and todos. It is separate from graph `manifest`.\n- Dry-run and apply use the same transaction path. Apply rolls back all\n  scaffold-created or scaffold-updated rows when any entity is rejected.\n- Work-point dependencies may reference work-points declared later in the same\n  scaffold file.\n- Omitted ordering on update preserves the existing order.\n- Dry-run and apply return `created`, `updated`, `unchanged`, `skipped`,\n  `rejected`, `validationFindings`, and `nextRunnableWorkPoints`.\n- `--if-exists fail` is the default for planning records. Use\n  `--if-exists skip` for idempotent create-only automation.\n- `--if-exists update` updates supported content fields, reports `updated`\n  only when a persisted change occurred, and rejects parent-link drift such as\n  moving a roadmap to another goal.\n- Scaffold `validationFindings` are limited to touched scaffold entities and\n  directly affected parents. Run `validate all` for a full-scope audit.\n- Side-effect class: `disk_write` with `--apply`; read-only planning preview\n  with `--dry-run`.\n- Approval posture: `advisory`.\n\r\n### Project-run family (claim \u002F activate \u002F release \u002F add-evidence)\n\r\n- `project-run-claim` is a durable lease. It is **not** a soft\r\n  reservation; if the lease exists, the work point is considered\r\n  in-flight until `release` is called. Always pass the full\r\n  scope: `--goal-id`, `--roadmap-id`, `--work-point-id`, `--repo`,\r\n  `--branch`, `--worktree`, `--session`, `--profile`.\r\n- `project-run-add-evidence` appends evidence to a run; evidence is\r\n  immutable once recorded. Do not \"fix\" a run by re-adding evidence\r\n  — open a new run or supersede the old one.\r\n- Side-effect class: `disk_write` plus cross-host lease visibility.\n- Approval posture: `required`. The host must explicitly approve\n  lease creation or release.\n\n### Workflow mode family (view \u002F prepare \u002F record-result)\n\n- Use workflow mode for multi-step, multi-session, or delegation-heavy work.\n  Keep trivial single-thread edits in the current harness with a small local\n  plan.\n- Start with `workflow view` to inspect `workflow-view\u002Fv1` before delegating:\n  `elegy-planning --scope \u003Cscope-key> --json --non-interactive workflow view --entity-type roadmap --entity-id \u003Croadmap-id>`.\n  Treat `adapterPolicy`, `executionPlan`, `delegationHints`, `budgets`, and\n  `metrics` as advisory host input, not as a second source of truth.\n- Use `workflow prepare` for the native path. It claims and activates a\n  bounded batch transactionally and returns `orchestrator-dispatch\u002Fv1`:\n  `elegy-planning --scope \u003Cscope-key> --json --non-interactive --correlation-id \u003Cid> workflow prepare --entity-type roadmap --entity-id \u003Croadmap-id> --max-workers 3`.\n- Pass `--adapter-id \u003Chost-adapter>` and repeated `--capability \u003Cname>` flags\n  when the host needs browser, container, E2E, or other validation support.\n- Keep the portable cap at three workers. Use one worker unless the phase has\n  explicit `parallel-safe-with` edges and disjoint declared file scopes.\n  Unknown or overlapping scopes remain sequential.\n- The main Codex thread remains orchestrator. It owns requirements,\n  architecture, integration, final judgment, and release decisions. Worker\n  agents only receive bounded worker handoffs.\n- Use one worker hop. Do not let worker output create a second delegation tree.\n  If a worker finds new scope, write evidence and refresh `workflow view`\n  instead of improvising nested work.\n- Codex should pass the compact dispatch handoff to a native child agent and\n  keep worker reasoning low or medium by default. The portable dispatch never\n  assigns `xhigh` to a worker.\n- Each worker writes `orchestrator-worker-result\u002Fv1` JSON. Submit it with\n  `workflow record-result --file \u003Cworker-result.json>`. The result must carry\n  the dispatch ID, project-run ID, source revision, fencing token, and\n  idempotency key. Replays are safe; stale fences fail closed.\n- `workflow bundle` remains an inspection\u002Fcompatibility projection only. Its\n  worker paths are relative to the bundle root; it does not execute workers.\n- Use `workflow import-artifact --file \u003Cartifact.md> --dry-run` for\n  `instruction-engine` roadmap workflow artifacts before applying them. Apply\n  only through `--apply --if-exists update` after inspecting the scaffold.\n- Refresh `workflow view` after writeback. Never continue from a stale\n  execution plan after a worker reports blockers, degraded mode, failed tests,\n  or changed file scopes.\n- Efficiency signals to watch: `estimatedContextTokens`,\n  `parallelSafeCandidateCount`, worker wall time, worker count, result bytes,\n  validation outcome, and duplicate or superseded evidence. Prefer smaller\n  handoffs and bounded worker count before raising reasoning class.\n- Side-effect class: `query` for `workflow view`; `mutation` for bundle files;\n  `fenced-mutation` for `workflow prepare` and `workflow record-result`.\n- Approval posture: advisory for view and bundle inspection; required for\n  prepare\u002Fresult execution when the host can mutate the repo, install\n  dependencies, call browsers, create containers, or spend external resources.\n\n### Validation \u002F health \u002F export (validate all, health, project-export,\nproject-render)\n\r\n- `validate all` validates only the active scope by default. Use\r\n  `validate all --all-scopes` for explicit global audits across\r\n  every scope. The output includes `scopeMode` (`\"single\"` or\r\n  `\"all\"`) and `scopeKey` to confirm which scope(s) were checked.\r\n- `health` is read-only but expensive on large databases. Schedule\n  it, do not run it per-keystroke.\n- `health.data.fts` reports `tablesPresent`, aggregate counts, per-entity\n  `byEntityType` drift, and `findings`. Treat FTS drift as a search reliability\n  issue.\n- `project-export` and `project-render` write to disk under the path\r\n  passed via `--output \u003Cpath>`. Confirm the path with the user\r\n  before invoking; the file is overwritten if it exists.\r\n- `project-export` emits JSON; `project-render` emits Markdown.\r\n  Pick the right one for the consumer.\r\n- Side-effect class: `disk_write` for export\u002Frender; `read_only` for\r\n  validate\u002Fhealth.\r\n- Approval posture: `advisory` for validate\u002Fhealth; `required` for\r\n  export\u002Frender if the output path is outside the user's working\r\n  directory.\r\n\r\n## Workflow\r\n\r\n1. Resolve scope.\r\n   - If the user did not name a scope, call `scope list --json` and\r\n     ask. Never let `--scope` default to `default` silently.\r\n2. Author top-down.\r\n   - Goal first, then roadmap, then plan, then work points, then\r\n     todos. Authoring in this order lets `--file-scope` selectors\r\n     reference the upstream entity and lets validation catch\r\n     referential breaks early.\r\n3. Record insights as you go.\r\n   - Every time the user makes a non-obvious decision, call\r\n     `insight record` with `--insight-type \u003Ctype> --tag \u003Ctag>`. The\r\n     next session's `context` call will surface them.\r\n4. Validate before declaring done.\r\n   - Run `validate all` and check that the result has no Critical\r\n     findings. Treat High findings as blockers for a \"done\" claim.\r\n5. Render or export for human consumption.\r\n   - `project-render` for Markdown review, `project-export` for\r\n     machine-readable handoff. The output is a derived artifact,\r\n     not authority.\r\n\r\n## Capability index\r\n\r\n| id | side-effect | purpose |\r\n| -- | -- | -- |\r\n| `planning-goal-create` | disk_write | Create a durable goal with acceptance and rejection criteria |\r\n| `planning-goal-show` | read-only | Show one goal plus linked context |\r\n| `planning-goal-list` | read-only | List goals in the active scope |\r\n| `planning-goal-update-status` | disk_write | Transition a goal to a new lifecycle state |\r\n| `planning-roadmap-create` | disk_write | Create a roadmap under a goal |\r\n| `planning-roadmap-add-section` | disk_write | Add a section to a roadmap |\n| `planning-roadmap-add-work-point` | disk_write | Attach a work point with file scopes and effort tier |\n| `planning-roadmap-scaffold` | disk_write | Batch create a v1 goal, roadmap, sections, work-points, plan, and todos from YAML or JSON |\n| `planning-roadmap-show` | read-only | Show one roadmap with sections and work points |\n| `planning-roadmap-list` | read-only | List roadmaps in the active scope |\r\n| `planning-roadmap-update-status` | disk_write | Transition a roadmap |\r\n| `planning-plan-create` | disk_write | Create a plan under a roadmap section |\r\n| `planning-plan-show` | read-only | Show one plan with todos and evidence |\r\n| `planning-plan-list` | read-only | List plans in the active scope |\r\n| `planning-plan-revise` | disk_write | Revise a plan; use `--clear-routing-hint` \u002F `--clear-file-scopes` to remove |\r\n| `planning-plan-update-status` | disk_write | Transition a plan |\r\n| `planning-work-point-list` | read-only | List work points in the active scope |\r\n| `planning-work-point-show` | read-only | Show one work point with file scopes |\r\n| `planning-work-point-update-status` | disk_write | Transition a work point |\r\n| `planning-work-point-next-runnable` | read-only | List runnable work points ordered by effort and readiness |\r\n| `planning-work-point-revise` | disk_write | Revise a work point's dependency list or other fields |\r\n| `planning-work-point-work-graph` | read-only | Render the work graph for the active scope |\r\n| `planning-todo-create` | disk_write | Create a todo under a plan |\r\n| `planning-todo-list` | read-only | List todos in the active scope |\r\n| `planning-todo-update-status` | disk_write | Transition a todo |\r\n| `planning-issue-record` | disk_write | Record an issue tied to a planning entity |\r\n| `planning-issue-list` | read-only | List issues in the active scope |\r\n| `planning-issue-update-status` | disk_write | Transition an issue |\r\n| `planning-review-point-record` | disk_write | Record a review point on a planning entity |\r\n| `planning-review-point-update-status` | disk_write | Transition a review point |\r\n| `planning-insight-record` | disk_write | Record a reasoning insight attached to any planning entity |\r\n| `planning-events-list` | read-only | List the planning event log for the active scope |\r\n| `planning-scope-list` | read-only | List all known scopes |\r\n| `planning-scope-show` | read-only | Show one scope with its entities |\r\n| `planning-scope-create` | disk_write | Create a new scope |\r\n| `planning-tags-list` | read-only | List all indexed tags across entities |\r\n| `planning-search-extended` | read-only | Title \u002F tag \u002F status \u002F FTS search |\r\n| `planning-context-entity` | read-only | Progressive disclosure bundle for one entity |\r\n| `planning-context-session` | read-only | Progressive disclosure bundle for a session |\r\n| `planning-validate-all` | read-only | Run referential integrity and freshness validation |\r\n| `planning-health` | read-only | Surface database health, FTS5 index drift, lease state |\n| `planning-project-export` | disk_write | Export a scope to JSON |\n| `planning-project-render` | disk_write | Render a scope to Markdown |\n| `planning-workflow-export` | disk_write | Export a workflow-oriented projection |\n| `planning-workflow-render` | disk_write | Render a workflow-oriented projection |\n| `planning-workflow-view` | read-only | Return a host-neutral workflow-view\u002Fv1 projection with adapter policy, execution plan, delegation hints, budgets, and metrics |\n| `planning-workflow-bundle` | disk_write | Write dispatch, runbook, worker handoff, and writeback-template files for a host adapter |\n| `planning-workflow-prepare` | fenced-mutation | Compile a bounded native dispatch batch and claim\u002Factivate fenced project runs |\n| `planning-workflow-record-result` | fenced-mutation | Atomically validate and write back a native worker result, evidence, graph status, and project-run terminal state |\n| `planning-workflow-import-artifact` | disk_write | Import an instruction-engine roadmap workflow artifact through the roadmap scaffold transaction path |\n| `planning-workflow-export-artifact` | disk_write | Export a roadmap\u002Fwork point as an instruction-engine roadmap workflow markdown artifact |\n| `planning-project-run-claim` | disk_write | Claim a durable execution lease on a work point |\n| `planning-project-run-activate` | disk_write | Activate a claimed run |\r\n| `planning-project-run-release` | disk_write | Release a lease |\r\n| `planning-project-run-add-evidence` | disk_write | Append immutable evidence to a run |\r\n| `planning-project-run-list` | read-only | List active project runs |\r\n| `planning-project-run-show` | read-only | Show one project run with full evidence trail |\r\n\r\n## Output envelope\r\n\r\n- Envelope: `planning-result\u002Fv1` (declared in\r\n  `plugins\u002Fplanning\u002Fschemas\u002Fplanning-result.schema.json`).\r\n- `status`: `ok`, `partial`, or `error`. Partial means the call\r\n  succeeded but some inner sub-result failed; surface the inner\r\n  failures.\r\n- `data`: entity payload or list of payloads, depending on the call.\r\n- `validation`: validation findings, when the call performed any\r\n  validation (e.g. `validate all`).\r\n- `correlationId`: echoes the `--correlation-id` passed to the call.\r\n  Use this for cross-call lineage.\r\n- `error`: machine-readable error code plus human message. The\r\n  machine code is in `error.code`; the message is in `error.message`.\r\n- `data.scopeMode` (for `validate all`): `\"single\"` or `\"all\"`,\r\n  indicating validation scope.\r\n- `data.scopeKey`: the active scope key, or `\"all\"` for global audits.\r\n- `data.insights`: list of insight records (for `insight list --all`).\r\n- `data.scopeKey` in each finding: the scope the finding belongs to.\r\n- `data.fingerprint` in each finding: stable identifier for\r\n  deduplication (`entityType::entityId::scopeKey::code`).\r\n\r\n## Common issues\r\n\r\n| Symptom | Cause | Solution |\r\n| -- | -- | -- |\r\n| The call returns results from a different scope than the user asked about. | `--scope` was omitted and the CLI defaulted to `default`. | Always pass `--scope \u003Cscope-key>` explicitly. The silent default is the most common planning bug. |\r\n| `goal create` rejects the call with \"missing correlation-id\" even though the user did not specify one. | Machine mode requires `--correlation-id` on every mutation. | Generate a fresh id (`uuidgen` or the host's equivalent) and pass it on every mutating call. |\r\n| `plan revise` appears to succeed but the routing hint or file scopes are not actually cleared. | Empty values are dropped; only the explicit `--clear-routing-hint` and `--clear-file-scopes` flags clear. | Add the explicit clear flags. Re-run `plan show` to confirm the cleared state. |\r\n| Multi-value flags silently drop all but the first value. | The agent joined values with commas or `;` instead of repeating the flag. | Repeat the flag once per value. The CLI does not warn. |\r\n| `roadmap add-work-point` rejects with \"selector grammar invalid\". | The `\u003Ctype>:\u003Cintent>:\u003Cselector>` shape was malformed (missing colons, unknown type, unknown intent). | Re-emit with the exact grammar. Types are `exact` or `glob`. Intents are `primary`, `review`, or `affected`. |\r\n| `context --entity-type goal --entity-id \u003Cid>` returns a huge payload. | The goal has many linked insights and a wide work graph. | Pass `--include \u003Centity-type>[,\u003Centity-type>...]` to narrow the bundle. The default is \"all linked entities\". |\r\n| `validate all` returns Critical findings that did not exist yesterday. | A recent mutation broke referential integrity (orphan work point, dangling roadmap reference). | Re-author the broken upstream entity and re-run validation. Do not delete the broken record without surfacing it to the user first. |\r\n| `project-run-claim` returns \"lease already held\". | Another session claimed the same work point. | List active runs (`project-run list`) and either wait for release, pick a different work point, or coordinate with the holding session. Do not force-release another session's lease. |\r\n| `project-export` overwrites an existing file the user cared about. | `--output` points at an existing path and the CLI does not prompt in non-interactive mode. | Confirm the path with the user before invoking. Pick a fresh `--output` path for each export. |\r\n| `health` shows FTS5 index drift. | The FTS5 mirror was not updated after a bulk insert. | Run the FTS5 rebuild command documented in the planning health reference, or recreate the FTS5 mirror from the source table. |\r\n| `next-runnable` returns work points that look ready but are blocked. | The work point's upstream dependencies have not all reached `validated`. | Inspect the work graph with `work-graph`; the ready-set excludes unvalidated upstream by default but a `--include-blocked` flag changes that. |\r\n| `roadmap add-work-point --dependency-id` is rejected even though the work point exists. | The dependency work point belongs to a different roadmap. | Use only same-roadmap dependencies for now. Cross-roadmap sequencing is deferred to a later model. |\r\n| `validate all` returns findings from a different scope. | `--all-scopes` was passed (or omitted unintentionally). | By default, `validate all` only validates the active scope. Pass `--all-scopes` to include all scopes. |\r\n\r\n## Version compatibility\r\n\r\n- Minimum supported `elegy-planning` version: `0.1.0`. The CLI is\r\n  pinned to its companion Rust workspace; check `elegy --version`\r\n  before invoking.\r\n- SQLite is the only durable backend in scope. There is no\r\n  PostgreSQL or remote-database path; the host-local SQLite file is\r\n  the source of truth.\r\n- Semver rule: minor must be ≥ the version that introduced the\r\n  capability (e.g. `planning-project-run-claim` is only present in\r\n  versions that ship the project-run feature). Patch is unconstrained.\r\n\r\n## Examples\r\n\r\n### Example 1 — create a goal and a roadmap\r\n\r\n```text\r\nelegy-planning --scope repo:elegy --json --non-interactive \\\r\n  --correlation-id $(uuidgen) \\\r\n  goal create \\\r\n  --id skill-rename-v1 \\\r\n  --title \"Rename skill-definition-v2 to skill across the repo\" \\\r\n  --description \"Drop the v2 suffix in filenames, manifests, and prose.\" \\\r\n  --acceptance \"All fixtures renamed to skill.\u003Csurface>.json\" \\\r\n  --acceptance \"cargo test --workspace passes\" \\\r\n  --rejection \"v2 suffix reintroduced in any new file\" \\\r\n  --tag migration --tag skills\r\n```\r\n\r\nExpected: `status: \"ok\"`, `data.goal.id = \"skill-rename-v1\"`,\r\n`correlationId` echoes the input.\r\n\r\n### Example 2 — add a work point with file scopes\r\n\r\n```text\r\nelegy-planning --scope repo:elegy --json --non-interactive \\\r\n  --correlation-id $(uuidgen) \\\r\n  roadmap add-work-point \\\r\n  --roadmap-id skill-rename-roadmap \\\r\n  --work-point-id update-fixtures \\\r\n  --effort-tier balanced \\\r\n  --file-scope glob:primary:plugins\u002Fplanning\u002Ffixtures\u002Fskill.*.json\r\n```\r\n\r\nExpected: `status: \"ok\"`, `data.workPoint.fileScopes` lists the\r\nselector in declaration order.\r\n\r\n### Example 3 — clear file scopes on a plan\r\n\r\n```text\r\nelegy-planning --scope repo:elegy --json --non-interactive \\\r\n  --correlation-id $(uuidgen) \\\r\n  plan revise \\\r\n  --plan-id update-fixtures \\\r\n  --clear-file-scopes\r\n```\r\n\r\nExpected: `status: \"ok\"`, `data.plan.fileScopes = []`. Re-running\r\n`plan show` should confirm the empty list.\r\n\r\n### Example 4 — revise work-point dependencies\r\n\r\n```text\r\nelegy-planning --scope repo:elegy --json --non-interactive \\\r\n  --correlation-id $(uuidgen) \\\r\n  work-point revise \\\r\n  --work-point-id wp-b \\\r\n  --clear-dependencies\r\n```\r\n\r\nExpected: `status: \"ok\"`, `data.record.dependencyIds = []`.\r\n\r\n### Example 5 — validate specific scope\r\n\r\n```text\r\nelegy-planning --scope repo:elegy --json --non-interactive \\\r\n  --correlation-id $(uuidgen) \\\r\n  validate all\r\n```\r\n\r\nExpected: `status: \"ok\"`, `data.scopeMode = \"single\"`, `data.scopeKey = \"repo:elegy\"`, findings include only `repo:elegy` entities.\r\n\r\n### Example 6 — global validation audit\r\n\r\n```text\r\nelegy-planning --json --non-interactive \\\r\n  --correlation-id $(uuidgen) \\\r\n  validate all --all-scopes\r\n```\r\n\r\nExpected: `status: \"ok\"`, `data.scopeMode = \"all\"`, `data.scopeKey = \"all\"`, findings span all known scopes.\r\n\r\n## Boundaries\r\n\r\n- This skill owns: durable planning records (goals, roadmaps, plans,\r\n  work points, todos, issues, review points, insights, project runs)\r\n  and their SQLite storage.\r\n- This skill does not own: vault operations, repo operations, agent\r\n  host projection, or MCP tool registration. Those live in their\r\n  own skills.\r\n- This skill does not own: planning state on other systems. Even when\r\n  another system mirrors planning state, the SQLite file under the\r\n  active scope is authority.\r\n- Companion skills:\r\n  - `elegy-memory` — for facts, preferences, and procedural\r\n    memories that span planning sessions.\r\n  - `elegy-obsidian` — for vault-side mirrors; planning is the\r\n    authority and Obsidian is the read\u002Fwrite target.\r\n  - `elegy-skill-authoring` — for SKILL.md audit and review.\n\r\n## References\r\n\r\n- Surface classification and readiness: `distribution\u002Fsurfaces.json` and\n  `plugins\u002Fplanning\u002Freadiness.json`.\n- Tool capability catalog: `plugins\u002Fplanning\u002Fcapability-catalog.json`. The\n  catalog describes executable operations; it does not make Planning a plugin.\n- Architecture: `plugins\u002Fplanning\u002Fdocs\u002Farchitecture\u002FARCHITECTURE.md`.\n- MVP boundary: `plugins\u002Fplanning\u002Fdocs\u002Farchitecture\u002Fmvp-scope.md`.\n- Spec: `plugins\u002Fplanning\u002Fdocs\u002Fspecs\u002Findex.md`.\n- Workflow projection spec: `plugins\u002Fplanning\u002Fdocs\u002Fspecs\u002Fworkflow-view.md`.\n- Result envelope schema:\n  `plugins\u002Fplanning\u002Fschemas\u002Fplanning-result.schema.json`.\n- Companion: `elegy-doc-practices` for cross-repo documentation\r\n  doctrine when planning work touches ADRs or specs.\r\n","# Elegy Planning\r\n\r\n> Use when an agent needs to create, inspect, update, validate, or export durable planning state — goals, roadmaps, plans, work points, todos, issues, review points, insights, and project runs — through the dedicated `elegy-planning` CLI over SQLite.\r\n\r\nSQLite is the durable authority. Markdown and JSON projections are\ngenerated, derived outputs. Omitted scope defaults to `default` and\nthat silent default is a common source of agent mistakes — always pass\n`--scope \u003Cscope-key>` explicitly.\n\n## Setup and authority\n\n- Run from the Elegy repo root during development:\n  `cargo run -p elegy-planning -- --help`.\n- Use `--db \u003Cpath>` when the default repo-local SQLite database is not the\n  intended planning authority.\n- Use `--scope \u003Cscope-key>` on every call. Scope is part of the planning\n  identity, not display metadata.\n- Use `--json --non-interactive --correlation-id \u003Cid>` on every mutating call.\n- Do not edit SQLite directly. Use CLI commands so validation, FTS, tags, and\n  event history stay synchronized.\n- Serialize mutating calls. SQLite has a busy timeout, but agent workflows\n  should not launch parallel writes.\n\n## Ideology\n\n- `elegy-planning` is an agent contract, not a note-taking format.\n- SQLite is authority; projections, templates, and skill docs are routing\n  surfaces.\n- Durable writes should append events. Events are the review trail for later\n  agents.\n- Validation is advisory but persistent. Structural write invariants block bad\n  records; planning-quality findings guide follow-up work.\n- Stable explicit IDs are automation handles. Prefer them over generated IDs\n  in agent-authored workflows.\n- Batch authoring should be previewable. Use `roadmap scaffold --dry-run`,\n  inspect `rejected`, then apply.\n\n## Quick start\n\r\n1. Resolve the scope key. Use\r\n   `elegy-planning --scope \u003Cscope-key> scope list --json` to confirm the\r\n   scope exists. If the user did not name one, ask.\r\n2. Create a goal:\r\n   `elegy-planning --scope \u003Cscope-key> --json --non-interactive --correlation-id \u003Cid> goal create --id \u003Cslug> --title \u003Ct> --description \u003Cd> --acceptance \u003Ca> --acceptance \u003Ca> --rejection \u003Cr> --rejection \u003Cr>`.\r\n   Repeat `--acceptance` and `--rejection` for multiple criteria. Do\r\n   not comma-join values.\r\n3. Add a work point to a roadmap:\n   `elegy-planning --scope \u003Cscope-key> --json --non-interactive --correlation-id \u003Cid> roadmap add-section --roadmap-id \u003Cr> --id \u003Cs> --slug \u003Cslug> --title \u003Ct>` followed by\n   `roadmap add-work-point --roadmap-id \u003Cr> --id \u003Cwp> --title \u003Ct> --summary \u003Cs> --effort-tier \u003Cfast|balanced|deep> --file-scope \u003Ctype:intent:selector>`.\n4. For batch roadmap authoring, render `roadmap-workflow` and apply it:\n   `elegy-planning template render --template roadmap-workflow --output roadmap.yaml`, then\n   `elegy-planning --scope \u003Cscope-key> --json --non-interactive --correlation-id \u003Cid> roadmap scaffold --file roadmap.yaml --dry-run`.\n5. Inspect context before deep work:\n   `elegy-planning --scope \u003Cscope-key> --json context --entity-type goal --entity-id \u003Cid>` to load the goal plus related insights and\n   token estimates.\n6. Run a full validation pass:\n   `elegy-planning --scope \u003Cscope-key> --json validate all` to surface\n   referential integrity issues and stale references.\n\r\n## Tool-call guardrails\r\n\r\n### Read family (goal\u002Froadmap\u002Fplan\u002Fwork-point\u002Ftodo\u002Fissue\u002Freview-point\r\nshow & list, scope, search-extended, tags-list, context, work-graph,\r\nnext-runnable)\r\n\r\n- Argument shape: `\u003Centity> show --\u003Centity>-id \u003Cid> --json`. `show --id \u003Cid>`\n  is also accepted for goal, roadmap, work-point, plan, issue, insight, graph\n  node, graph edge, acceptance, and evidence show commands.\n  The `--json` flag is required for machine-mode parsing; do not omit it even\n  on a \"quick check\".\n- For list commands, pass `--limit \u003Cn>` to cap the result set; the\r\n  default limit is conservative but explicit is safer.\r\n- `search` and entity-local `search` commands support `--title`, `--tag`,\n  `--status`, and `--fts`. Pass each filter as a separate flag; do not stack\n  them in `--query`.\n- `context --entity-type \u003Ctype> --entity-id \u003Cid>` returns progressive\r\n  disclosure bundles with token estimates. The estimate is\r\n  informational; do not parse it.\r\n- `work-graph` and `next-runnable` are read-only but can return\r\n  large payloads; always pass `--limit` for `next-runnable` to avoid\r\n  pulling the whole work queue.\r\n- `insight list --all` lists all insights in the active scope.\r\n  Omit `--all` and pass `--parent-type` + `--parent-id` for\r\n  parent-specific listing (existing behavior).\r\n- Side-effect class: `read_only`.\r\n- Approval posture: `none`.\r\n\r\n### Mutate family (create \u002F update-status \u002F plan-revise \u002F insight-record)\r\n\r\n- Always pass `--json --non-interactive --correlation-id \u003Cid>` on every\n  mutating call. The CLI refuses interactive prompts when\r\n  `--non-interactive` is set, and a missing `--correlation-id` causes\r\n  the call to fail under machine mode. Both flags together are the\r\n  contract.\r\n- Multi-value flags (`--acceptance`, `--rejection`, `--tag`,\r\n  `--file-scope`, `--related-entity`) must be **repeated** per value:\r\n  `--acceptance \u003Ca1> --acceptance \u003Ca2>`. Comma-joining is silently\r\n  dropped.\r\n- `plan-revise` removal semantics: passing `--routing-hint \"\"` or\r\n  omitting `--file-scopes` does **not** clear existing values. Use\r\n  `--clear-routing-hint` and `--clear-file-scopes` to remove\r\n  previously set values. These two flags are the only reliable way\r\n  to clear.\r\n- `--effort-tier` is required for `roadmap add-work-point` and\r\n  recommended for plan and todo authoring. Valid values are\r\n  `fast`, `balanced`, `deep`. The value affects validation depth,\r\n  not the durable record.\r\n- `roadmap add-work-point --dependency-id \u003Cid>` only accepts dependencies\r\n  that belong to the same roadmap. Cross-roadmap dependencies are\r\n  rejected at write time with `\"status\": \"invalid\"` and a\r\n  descriptive `error` message.\r\n- Use `work-point revise --work-point-id \u003Cid> --dependency-id \u003Cid>...`\r\n  to add, replace, or `--clear-dependencies` to remove work-point\r\n  dependencies. Do not attempt direct SQLite repair.\r\n- File-scope selector grammar: `\u003Ctype>:\u003Cintent>:\u003Cselector>`. Types\r\n  are `exact` or `glob`. Intents are `primary`, `review`, or\r\n  `affected`. Example: `--file-scope glob:primary:shared\u002Fcore\u002F**`.\r\n- `--status` on `*-update-status` accepts the entity's lifecycle\r\n  states (e.g. `draft`, `proposed`, `active`, `validated`,\r\n  `invalidated`, `superseded`, `abandoned` for goals). Do not\r\n  transition to a state the entity is not currently allowed to\r\n  leave.\r\n- `scope create --metadata-file \u003Cpath>` reads metadata from a JSON\r\n  file. Mutually exclusive with `--metadata-json`. Errors include\r\n  the file path for faster diagnosis.\r\n- Side-effect class: `disk_write` against the SQLite database.\n- Approval posture: `advisory`. The host may require approval for\n  specific transitions (e.g. `validated`, `invalidated`).\n- Run mutating commands and read-after-write checks sequentially. SQLite uses a\n  local file lock; parallel show\u002Flist calls during writes can still race on busy\n  workstations.\n\n### Roadmap scaffold family\n\n- Use `roadmap scaffold --file \u003Cyaml|json> --dry-run` before `--apply`.\n- The scaffold file creates v1 records: scope, goal, roadmap, sections,\n  work-points, plan, and todos. It is separate from graph `manifest`.\n- Dry-run and apply use the same transaction path. Apply rolls back all\n  scaffold-created or scaffold-updated rows when any entity is rejected.\n- Work-point dependencies may reference work-points declared later in the same\n  scaffold file.\n- Omitted ordering on update preserves the existing order.\n- Dry-run and apply return `created`, `updated`, `unchanged`, `skipped`,\n  `rejected`, `validationFindings`, and `nextRunnableWorkPoints`.\n- `--if-exists fail` is the default for planning records. Use\n  `--if-exists skip` for idempotent create-only automation.\n- `--if-exists update` updates supported content fields, reports `updated`\n  only when a persisted change occurred, and rejects parent-link drift such as\n  moving a roadmap to another goal.\n- Scaffold `validationFindings` are limited to touched scaffold entities and\n  directly affected parents. Run `validate all` for a full-scope audit.\n- Side-effect class: `disk_write` with `--apply`; read-only planning preview\n  with `--dry-run`.\n- Approval posture: `advisory`.\n\r\n### Project-run family (claim \u002F activate \u002F release \u002F add-evidence)\n\r\n- `project-run-claim` is a durable lease. It is **not** a soft\r\n  reservation; if the lease exists, the work point is considered\r\n  in-flight until `release` is called. Always pass the full\r\n  scope: `--goal-id`, `--roadmap-id`, `--work-point-id`, `--repo`,\r\n  `--branch`, `--worktree`, `--session`, `--profile`.\r\n- `project-run-add-evidence` appends evidence to a run; evidence is\r\n  immutable once recorded. Do not \"fix\" a run by re-adding evidence\r\n  — open a new run or supersede the old one.\r\n- Side-effect class: `disk_write` plus cross-host lease visibility.\n- Approval posture: `required`. The host must explicitly approve\n  lease creation or release.\n\n### Workflow mode family (view \u002F prepare \u002F record-result)\n\n- Use workflow mode for multi-step, multi-session, or delegation-heavy work.\n  Keep trivial single-thread edits in the current harness with a small local\n  plan.\n- Start with `workflow view` to inspect `workflow-view\u002Fv1` before delegating:\n  `elegy-planning --scope \u003Cscope-key> --json --non-interactive workflow view --entity-type roadmap --entity-id \u003Croadmap-id>`.\n  Treat `adapterPolicy`, `executionPlan`, `delegationHints`, `budgets`, and\n  `metrics` as advisory host input, not as a second source of truth.\n- Use `workflow prepare` for the native path. It claims and activates a\n  bounded batch transactionally and returns `orchestrator-dispatch\u002Fv1`:\n  `elegy-planning --scope \u003Cscope-key> --json --non-interactive --correlation-id \u003Cid> workflow prepare --entity-type roadmap --entity-id \u003Croadmap-id> --max-workers 3`.\n- Pass `--adapter-id \u003Chost-adapter>` and repeated `--capability \u003Cname>` flags\n  when the host needs browser, container, E2E, or other validation support.\n- Keep the portable cap at three workers. Use one worker unless the phase has\n  explicit `parallel-safe-with` edges and disjoint declared file scopes.\n  Unknown or overlapping scopes remain sequential.\n- The main Codex thread remains orchestrator. It owns requirements,\n  architecture, integration, final judgment, and release decisions. Worker\n  agents only receive bounded worker handoffs.\n- Use one worker hop. Do not let worker output create a second delegation tree.\n  If a worker finds new scope, write evidence and refresh `workflow view`\n  instead of improvising nested work.\n- Codex should pass the compact dispatch handoff to a native child agent and\n  keep worker reasoning low or medium by default. The portable dispatch never\n  assigns `xhigh` to a worker.\n- Each worker writes `orchestrator-worker-result\u002Fv1` JSON. Submit it with\n  `workflow record-result --file \u003Cworker-result.json>`. The result must carry\n  the dispatch ID, project-run ID, source revision, fencing token, and\n  idempotency key. Replays are safe; stale fences fail closed.\n- `workflow bundle` remains an inspection\u002Fcompatibility projection only. Its\n  worker paths are relative to the bundle root; it does not execute workers.\n- Use `workflow import-artifact --file \u003Cartifact.md> --dry-run` for\n  `instruction-engine` roadmap workflow artifacts before applying them. Apply\n  only through `--apply --if-exists update` after inspecting the scaffold.\n- Refresh `workflow view` after writeback. Never continue from a stale\n  execution plan after a worker reports blockers, degraded mode, failed tests,\n  or changed file scopes.\n- Efficiency signals to watch: `estimatedContextTokens`,\n  `parallelSafeCandidateCount`, worker wall time, worker count, result bytes,\n  validation outcome, and duplicate or superseded evidence. Prefer smaller\n  handoffs and bounded worker count before raising reasoning class.\n- Side-effect class: `query` for `workflow view`; `mutation` for bundle files;\n  `fenced-mutation` for `workflow prepare` and `workflow record-result`.\n- Approval posture: advisory for view and bundle inspection; required for\n  prepare\u002Fresult execution when the host can mutate the repo, install\n  dependencies, call browsers, create containers, or spend external resources.\n\n### Validation \u002F health \u002F export (validate all, health, project-export,\nproject-render)\n\r\n- `validate all` validates only the active scope by default. Use\r\n  `validate all --all-scopes` for explicit global audits across\r\n  every scope. The output includes `scopeMode` (`\"single\"` or\r\n  `\"all\"`) and `scopeKey` to confirm which scope(s) were checked.\r\n- `health` is read-only but expensive on large databases. Schedule\n  it, do not run it per-keystroke.\n- `health.data.fts` reports `tablesPresent`, aggregate counts, per-entity\n  `byEntityType` drift, and `findings`. Treat FTS drift as a search reliability\n  issue.\n- `project-export` and `project-render` write to disk under the path\r\n  passed via `--output \u003Cpath>`. Confirm the path with the user\r\n  before invoking; the file is overwritten if it exists.\r\n- `project-export` emits JSON; `project-render` emits Markdown.\r\n  Pick the right one for the consumer.\r\n- Side-effect class: `disk_write` for export\u002Frender; `read_only` for\r\n  validate\u002Fhealth.\r\n- Approval posture: `advisory` for validate\u002Fhealth; `required` for\r\n  export\u002Frender if the output path is outside the user's working\r\n  directory.\r\n\r\n## Workflow\r\n\r\n1. Resolve scope.\r\n   - If the user did not name a scope, call `scope list --json` and\r\n     ask. Never let `--scope` default to `default` silently.\r\n2. Author top-down.\r\n   - Goal first, then roadmap, then plan, then work points, then\r\n     todos. Authoring in this order lets `--file-scope` selectors\r\n     reference the upstream entity and lets validation catch\r\n     referential breaks early.\r\n3. Record insights as you go.\r\n   - Every time the user makes a non-obvious decision, call\r\n     `insight record` with `--insight-type \u003Ctype> --tag \u003Ctag>`. The\r\n     next session's `context` call will surface them.\r\n4. Validate before declaring done.\r\n   - Run `validate all` and check that the result has no Critical\r\n     findings. Treat High findings as blockers for a \"done\" claim.\r\n5. Render or export for human consumption.\r\n   - `project-render` for Markdown review, `project-export` for\r\n     machine-readable handoff. The output is a derived artifact,\r\n     not authority.\r\n\r\n## Capability index\r\n\r\n| id | side-effect | purpose |\r\n| -- | -- | -- |\r\n| `planning-goal-create` | disk_write | Create a durable goal with acceptance and rejection criteria |\r\n| `planning-goal-show` | read-only | Show one goal plus linked context |\r\n| `planning-goal-list` | read-only | List goals in the active scope |\r\n| `planning-goal-update-status` | disk_write | Transition a goal to a new lifecycle state |\r\n| `planning-roadmap-create` | disk_write | Create a roadmap under a goal |\r\n| `planning-roadmap-add-section` | disk_write | Add a section to a roadmap |\n| `planning-roadmap-add-work-point` | disk_write | Attach a work point with file scopes and effort tier |\n| `planning-roadmap-scaffold` | disk_write | Batch create a v1 goal, roadmap, sections, work-points, plan, and todos from YAML or JSON |\n| `planning-roadmap-show` | read-only | Show one roadmap with sections and work points |\n| `planning-roadmap-list` | read-only | List roadmaps in the active scope |\r\n| `planning-roadmap-update-status` | disk_write | Transition a roadmap |\r\n| `planning-plan-create` | disk_write | Create a plan under a roadmap section |\r\n| `planning-plan-show` | read-only | Show one plan with todos and evidence |\r\n| `planning-plan-list` | read-only | List plans in the active scope |\r\n| `planning-plan-revise` | disk_write | Revise a plan; use `--clear-routing-hint` \u002F `--clear-file-scopes` to remove |\r\n| `planning-plan-update-status` | disk_write | Transition a plan |\r\n| `planning-work-point-list` | read-only | List work points in the active scope |\r\n| `planning-work-point-show` | read-only | Show one work point with file scopes |\r\n| `planning-work-point-update-status` | disk_write | Transition a work point |\r\n| `planning-work-point-next-runnable` | read-only | List runnable work points ordered by effort and readiness |\r\n| `planning-work-point-revise` | disk_write | Revise a work point's dependency list or other fields |\r\n| `planning-work-point-work-graph` | read-only | Render the work graph for the active scope |\r\n| `planning-todo-create` | disk_write | Create a todo under a plan |\r\n| `planning-todo-list` | read-only | List todos in the active scope |\r\n| `planning-todo-update-status` | disk_write | Transition a todo |\r\n| `planning-issue-record` | disk_write | Record an issue tied to a planning entity |\r\n| `planning-issue-list` | read-only | List issues in the active scope |\r\n| `planning-issue-update-status` | disk_write | Transition an issue |\r\n| `planning-review-point-record` | disk_write | Record a review point on a planning entity |\r\n| `planning-review-point-update-status` | disk_write | Transition a review point |\r\n| `planning-insight-record` | disk_write | Record a reasoning insight attached to any planning entity |\r\n| `planning-events-list` | read-only | List the planning event log for the active scope |\r\n| `planning-scope-list` | read-only | List all known scopes |\r\n| `planning-scope-show` | read-only | Show one scope with its entities |\r\n| `planning-scope-create` | disk_write | Create a new scope |\r\n| `planning-tags-list` | read-only | List all indexed tags across entities |\r\n| `planning-search-extended` | read-only | Title \u002F tag \u002F status \u002F FTS search |\r\n| `planning-context-entity` | read-only | Progressive disclosure bundle for one entity |\r\n| `planning-context-session` | read-only | Progressive disclosure bundle for a session |\r\n| `planning-validate-all` | read-only | Run referential integrity and freshness validation |\r\n| `planning-health` | read-only | Surface database health, FTS5 index drift, lease state |\n| `planning-project-export` | disk_write | Export a scope to JSON |\n| `planning-project-render` | disk_write | Render a scope to Markdown |\n| `planning-workflow-export` | disk_write | Export a workflow-oriented projection |\n| `planning-workflow-render` | disk_write | Render a workflow-oriented projection |\n| `planning-workflow-view` | read-only | Return a host-neutral workflow-view\u002Fv1 projection with adapter policy, execution plan, delegation hints, budgets, and metrics |\n| `planning-workflow-bundle` | disk_write | Write dispatch, runbook, worker handoff, and writeback-template files for a host adapter |\n| `planning-workflow-prepare` | fenced-mutation | Compile a bounded native dispatch batch and claim\u002Factivate fenced project runs |\n| `planning-workflow-record-result` | fenced-mutation | Atomically validate and write back a native worker result, evidence, graph status, and project-run terminal state |\n| `planning-workflow-import-artifact` | disk_write | Import an instruction-engine roadmap workflow artifact through the roadmap scaffold transaction path |\n| `planning-workflow-export-artifact` | disk_write | Export a roadmap\u002Fwork point as an instruction-engine roadmap workflow markdown artifact |\n| `planning-project-run-claim` | disk_write | Claim a durable execution lease on a work point |\n| `planning-project-run-activate` | disk_write | Activate a claimed run |\r\n| `planning-project-run-release` | disk_write | Release a lease |\r\n| `planning-project-run-add-evidence` | disk_write | Append immutable evidence to a run |\r\n| `planning-project-run-list` | read-only | List active project runs |\r\n| `planning-project-run-show` | read-only | Show one project run with full evidence trail |\r\n\r\n## Output envelope\r\n\r\n- Envelope: `planning-result\u002Fv1` (declared in\r\n  `plugins\u002Fplanning\u002Fschemas\u002Fplanning-result.schema.json`).\r\n- `status`: `ok`, `partial`, or `error`. Partial means the call\r\n  succeeded but some inner sub-result failed; surface the inner\r\n  failures.\r\n- `data`: entity payload or list of payloads, depending on the call.\r\n- `validation`: validation findings, when the call performed any\r\n  validation (e.g. `validate all`).\r\n- `correlationId`: echoes the `--correlation-id` passed to the call.\r\n  Use this for cross-call lineage.\r\n- `error`: machine-readable error code plus human message. The\r\n  machine code is in `error.code`; the message is in `error.message`.\r\n- `data.scopeMode` (for `validate all`): `\"single\"` or `\"all\"`,\r\n  indicating validation scope.\r\n- `data.scopeKey`: the active scope key, or `\"all\"` for global audits.\r\n- `data.insights`: list of insight records (for `insight list --all`).\r\n- `data.scopeKey` in each finding: the scope the finding belongs to.\r\n- `data.fingerprint` in each finding: stable identifier for\r\n  deduplication (`entityType::entityId::scopeKey::code`).\r\n\r\n## Common issues\r\n\r\n| Symptom | Cause | Solution |\r\n| -- | -- | -- |\r\n| The call returns results from a different scope than the user asked about. | `--scope` was omitted and the CLI defaulted to `default`. | Always pass `--scope \u003Cscope-key>` explicitly. The silent default is the most common planning bug. |\r\n| `goal create` rejects the call with \"missing correlation-id\" even though the user did not specify one. | Machine mode requires `--correlation-id` on every mutation. | Generate a fresh id (`uuidgen` or the host's equivalent) and pass it on every mutating call. |\r\n| `plan revise` appears to succeed but the routing hint or file scopes are not actually cleared. | Empty values are dropped; only the explicit `--clear-routing-hint` and `--clear-file-scopes` flags clear. | Add the explicit clear flags. Re-run `plan show` to confirm the cleared state. |\r\n| Multi-value flags silently drop all but the first value. | The agent joined values with commas or `;` instead of repeating the flag. | Repeat the flag once per value. The CLI does not warn. |\r\n| `roadmap add-work-point` rejects with \"selector grammar invalid\". | The `\u003Ctype>:\u003Cintent>:\u003Cselector>` shape was malformed (missing colons, unknown type, unknown intent). | Re-emit with the exact grammar. Types are `exact` or `glob`. Intents are `primary`, `review`, or `affected`. |\r\n| `context --entity-type goal --entity-id \u003Cid>` returns a huge payload. | The goal has many linked insights and a wide work graph. | Pass `--include \u003Centity-type>[,\u003Centity-type>...]` to narrow the bundle. The default is \"all linked entities\". |\r\n| `validate all` returns Critical findings that did not exist yesterday. | A recent mutation broke referential integrity (orphan work point, dangling roadmap reference). | Re-author the broken upstream entity and re-run validation. Do not delete the broken record without surfacing it to the user first. |\r\n| `project-run-claim` returns \"lease already held\". | Another session claimed the same work point. | List active runs (`project-run list`) and either wait for release, pick a different work point, or coordinate with the holding session. Do not force-release another session's lease. |\r\n| `project-export` overwrites an existing file the user cared about. | `--output` points at an existing path and the CLI does not prompt in non-interactive mode. | Confirm the path with the user before invoking. Pick a fresh `--output` path for each export. |\r\n| `health` shows FTS5 index drift. | The FTS5 mirror was not updated after a bulk insert. | Run the FTS5 rebuild command documented in the planning health reference, or recreate the FTS5 mirror from the source table. |\r\n| `next-runnable` returns work points that look ready but are blocked. | The work point's upstream dependencies have not all reached `validated`. | Inspect the work graph with `work-graph`; the ready-set excludes unvalidated upstream by default but a `--include-blocked` flag changes that. |\r\n| `roadmap add-work-point --dependency-id` is rejected even though the work point exists. | The dependency work point belongs to a different roadmap. | Use only same-roadmap dependencies for now. Cross-roadmap sequencing is deferred to a later model. |\r\n| `validate all` returns findings from a different scope. | `--all-scopes` was passed (or omitted unintentionally). | By default, `validate all` only validates the active scope. Pass `--all-scopes` to include all scopes. |\r\n\r\n## Version compatibility\r\n\r\n- Minimum supported `elegy-planning` version: `0.1.0`. The CLI is\r\n  pinned to its companion Rust workspace; check `elegy --version`\r\n  before invoking.\r\n- SQLite is the only durable backend in scope. There is no\r\n  PostgreSQL or remote-database path; the host-local SQLite file is\r\n  the source of truth.\r\n- Semver rule: minor must be ≥ the version that introduced the\r\n  capability (e.g. `planning-project-run-claim` is only present in\r\n  versions that ship the project-run feature). Patch is unconstrained.\r\n\r\n## Examples\r\n\r\n### Example 1 — create a goal and a roadmap\r\n\r\n```text\r\nelegy-planning --scope repo:elegy --json --non-interactive \\\r\n  --correlation-id $(uuidgen) \\\r\n  goal create \\\r\n  --id skill-rename-v1 \\\r\n  --title \"Rename skill-definition-v2 to skill across the repo\" \\\r\n  --description \"Drop the v2 suffix in filenames, manifests, and prose.\" \\\r\n  --acceptance \"All fixtures renamed to skill.\u003Csurface>.json\" \\\r\n  --acceptance \"cargo test --workspace passes\" \\\r\n  --rejection \"v2 suffix reintroduced in any new file\" \\\r\n  --tag migration --tag skills\r\n```\r\n\r\nExpected: `status: \"ok\"`, `data.goal.id = \"skill-rename-v1\"`,\r\n`correlationId` echoes the input.\r\n\r\n### Example 2 — add a work point with file scopes\r\n\r\n```text\r\nelegy-planning --scope repo:elegy --json --non-interactive \\\r\n  --correlation-id $(uuidgen) \\\r\n  roadmap add-work-point \\\r\n  --roadmap-id skill-rename-roadmap \\\r\n  --work-point-id update-fixtures \\\r\n  --effort-tier balanced \\\r\n  --file-scope glob:primary:plugins\u002Fplanning\u002Ffixtures\u002Fskill.*.json\r\n```\r\n\r\nExpected: `status: \"ok\"`, `data.workPoint.fileScopes` lists the\r\nselector in declaration order.\r\n\r\n### Example 3 — clear file scopes on a plan\r\n\r\n```text\r\nelegy-planning --scope repo:elegy --json --non-interactive \\\r\n  --correlation-id $(uuidgen) \\\r\n  plan revise \\\r\n  --plan-id update-fixtures \\\r\n  --clear-file-scopes\r\n```\r\n\r\nExpected: `status: \"ok\"`, `data.plan.fileScopes = []`. Re-running\r\n`plan show` should confirm the empty list.\r\n\r\n### Example 4 — revise work-point dependencies\r\n\r\n```text\r\nelegy-planning --scope repo:elegy --json --non-interactive \\\r\n  --correlation-id $(uuidgen) \\\r\n  work-point revise \\\r\n  --work-point-id wp-b \\\r\n  --clear-dependencies\r\n```\r\n\r\nExpected: `status: \"ok\"`, `data.record.dependencyIds = []`.\r\n\r\n### Example 5 — validate specific scope\r\n\r\n```text\r\nelegy-planning --scope repo:elegy --json --non-interactive \\\r\n  --correlation-id $(uuidgen) \\\r\n  validate all\r\n```\r\n\r\nExpected: `status: \"ok\"`, `data.scopeMode = \"single\"`, `data.scopeKey = \"repo:elegy\"`, findings include only `repo:elegy` entities.\r\n\r\n### Example 6 — global validation audit\r\n\r\n```text\r\nelegy-planning --json --non-interactive \\\r\n  --correlation-id $(uuidgen) \\\r\n  validate all --all-scopes\r\n```\r\n\r\nExpected: `status: \"ok\"`, `data.scopeMode = \"all\"`, `data.scopeKey = \"all\"`, findings span all known scopes.\r\n\r\n## Boundaries\r\n\r\n- This skill owns: durable planning records (goals, roadmaps, plans,\r\n  work points, todos, issues, review points, insights, project runs)\r\n  and their SQLite storage.\r\n- This skill does not own: vault operations, repo operations, agent\r\n  host projection, or MCP tool registration. Those live in their\r\n  own skills.\r\n- This skill does not own: planning state on other systems. Even when\r\n  another system mirrors planning state, the SQLite file under the\r\n  active scope is authority.\r\n- Companion skills:\r\n  - `elegy-memory` — for facts, preferences, and procedural\r\n    memories that span planning sessions.\r\n  - `elegy-obsidian` — for vault-side mirrors; planning is the\r\n    authority and Obsidian is the read\u002Fwrite target.\r\n  - `elegy-skill-authoring` — for SKILL.md audit and review.\n\r\n## References\r\n\r\n- Surface classification and readiness: `distribution\u002Fsurfaces.json` and\n  `plugins\u002Fplanning\u002Freadiness.json`.\n- Tool capability catalog: `plugins\u002Fplanning\u002Fcapability-catalog.json`. The\n  catalog describes executable operations; it does not make Planning a plugin.\n- Architecture: `plugins\u002Fplanning\u002Fdocs\u002Farchitecture\u002FARCHITECTURE.md`.\n- MVP boundary: `plugins\u002Fplanning\u002Fdocs\u002Farchitecture\u002Fmvp-scope.md`.\n- Spec: `plugins\u002Fplanning\u002Fdocs\u002Fspecs\u002Findex.md`.\n- Workflow projection spec: `plugins\u002Fplanning\u002Fdocs\u002Fspecs\u002Fworkflow-view.md`.\n- Result envelope schema:\n  `plugins\u002Fplanning\u002Fschemas\u002Fplanning-result.schema.json`.\n- Companion: `elegy-doc-practices` for cross-repo documentation\r\n  doctrine when planning work touches ADRs or specs.\r\n",{"name":5,"description":7},"main","cdaaaccc462c986f4a2c0032b75698f15c71f62b","plugins\u002Fplanning\u002Fskills\u002Felegy-planning","https:\u002F\u002Fgithub.com\u002FSofreshx\u002FElegy","https:\u002F\u002Fgithub.com\u002FSofreshx","2026-11-02 22:33:10",{"source":8,"skillName":5,"commands":49,"prompt":59,"zipAvailable":60},[50,53,56],{"tool":51,"command":52},"npx","npx skills add Sofreshx\u002FElegy --skill elegy-planning",{"tool":54,"command":55},"bunx","bunx skills add Sofreshx\u002FElegy --skill elegy-planning",{"tool":57,"command":58},"pnpm","pnpm dlx skills add Sofreshx\u002FElegy --skill elegy-planning","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FSofreshx\u002FElegy\u002Fblob\u002Fmain\u002Fplugins\u002Fplanning\u002Fskills\u002Felegy-planning\u002FSKILL.md",true,[],[63,83,104,126,144,160],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":74,"publishedAt":37},"01M6GV77GEYNKPE96EFA282AY0","elegy-skill-authoring","Doctrine for drafting, auditing, and fixing Elegy skills. Use when creating a new skill, running an audit against an existing one, or triaging structural and content findings.","https:\u002F\u002Fgithub.com\u002FSofreshx\u002FElegy\u002Fblob\u002Fmain\u002Fskills\u002Felegy-skill-authoring\u002FSKILL.md",[69],{"categoryNo":70,"categoryName":71,"taxonomyType":72,"taxonomyTypeDesc":73},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[75,76,77,78,79,80,28,81,82],"elegy skill authoring","authoring","skill authoring","structural","new skill","doctrine","audit","content",{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":92,"publishedAt":37},"01M6GV6VG31WQVTQ0RGEEEWKQ8","elegy-plugin-authoring","Use when creating or reviewing an Elegy system-adapter plugin that connects an agent to a data source, database, platform, API, local system, or executable boundary.","https:\u002F\u002Fgithub.com\u002FSofreshx\u002FElegy\u002Fblob\u002Fmain\u002Fskills\u002Felegy-plugin-authoring\u002FSKILL.md",[89],{"categoryNo":90,"categoryName":91,"taxonomyType":72,"taxonomyTypeDesc":73},"01JBSEEDCAT000000000000010","后端与接口",[93,76,94,95,96,97,98,99,28,100,101,102,103],"elegy plugin authoring","plugin authoring","plugin","api","boundary","data","database","system","adapter","platform","local",{"skillNo":105,"name":106,"nameZh":6,"description":107,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":108,"categories":109,"keywords":110,"publishedAt":37},"01M6GV6FK50JQ7XPFA0EVCFDBJ","elegy-obsidian","Read, write, and search a local Obsidian vault via the official Obsidian Desktop CLI (v1.12.7+). Non-authoritative convenience layer; durable planning state continues to flow through elegy-planning and SQLite. User-invoked; do not auto-load.","https:\u002F\u002Fgithub.com\u002FSofreshx\u002FElegy\u002Fblob\u002Fmain\u002Fskills\u002Felegy-obsidian\u002FSKILL.md",[],[111,112,113,114,115,116,103,117,118,119,30,120,121,36,122,123,124,125,20,32],"obsidian","elegy obsidian","true","load","mirror","tags","do","auto","obsidian vault","vault","search","official","notes","tasks","desktop",{"skillNo":127,"name":128,"nameZh":6,"description":129,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":130,"categories":131,"keywords":132,"publishedAt":37},"01M6GV61N0F34CMFA7F4AT7C2D","elegy-doc-practices","Use when an agent or contributor needs to classify, place, scaffold, or validate documentation in the Elegy ecosystem — the central doctrine for ADRs, specs, guides, notes, and roadmap material across Elegy and downstream repos.","https:\u002F\u002Fgithub.com\u002FSofreshx\u002FElegy\u002Fblob\u002Fmain\u002Fskills\u002Felegy-doc-practices\u002FSKILL.md",[],[133,134,28,123,135,136,137,35,138,80,139,140,141,142,143],"elegy doc practices","doc","documentation","scaffold","repos","roadmap","across","classify","material","guides","ecosystem",{"skillNo":145,"name":146,"nameZh":6,"description":147,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":148,"categories":149,"keywords":154,"publishedAt":37},"01M6GV5RR6R3XF7Q1EP9QZ4GVK","test-skill","A test skill for the app-binding fixture.","https:\u002F\u002Fgithub.com\u002FSofreshx\u002FElegy\u002Fblob\u002Fmain\u002Fshared\u002Fplugin-sdk\u002Ftests\u002Ffixtures\u002Fapp-binding-plugin\u002Fskills\u002Ftest-skill\u002FSKILL.md",[150,153],{"categoryNo":151,"categoryName":152,"taxonomyType":72,"taxonomyTypeDesc":73},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":70,"categoryName":71,"taxonomyType":72,"taxonomyTypeDesc":73},[155,156,157,158,159],"Test Skill","test","app","binding","fixture",{"skillNo":161,"name":162,"nameZh":6,"description":163,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":164,"categories":165,"keywords":166,"publishedAt":37},"01M6GV4X2GKY7SF0RM1FCHMXHF","elegy-observe","Observe desktop and OS state for agentic workflows. Snapshot running processes, track foreground and visible windows, capture screen, read clipboard, diff filesystem changes, and query system information.","https:\u002F\u002Fgithub.com\u002FSofreshx\u002FElegy\u002Fblob\u002Fmain\u002Fplugins\u002Fobserve\u002Fskills\u002Felegy-observe\u002FSKILL.md",[],[167,168,169,170,171,172,173,125,32,100,174,175,176,177,178,179,180,181,182,183],"elegy observe","observe","filesystem","capture","windows","workflows","agentic workflows","snapshot","diff","clipboard","information","capture screen","processes","screen","os","read","agentic"]