elegy-planning

Files (1)

• SKILL.md

SKILL.md (first lines)

---
name: elegy-planning
description: 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.
---

# Elegy Planning

> 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.

SQLite is the durable authority. Markdown and JSON projections are
generated, derived outputs. Omitted scope defaults to `default` and
that silent default is a common source of agent mistakes — always pass
`--scope <scope-key>` explicitly.

## Setup and authority

- Run from the Elegy repo root during development:
  `cargo run -p elegy-planning -- --help`.
- Use `--db <path>` when the default repo-local SQLite database is not the
  intended planning authority.
- Use `--scope <scope-key>` on every call. Scope is part of the planning
  identity, not display metadata.
- Use `--json --non-interactive --correlation-id <id>` on every mutating call.
- Do not edit SQLite directly. Use CLI commands so validation, FTS, tags, and
  event history stay synchronized.
- Serialize mutating calls. SQLite has a busy timeout, but agent workflows
  should not launch parallel writes.

## Ideology

- `elegy-planning` is an agent contract, not a note-taking format.
- SQLite is authority; projections, templates, and skill docs are routing
  surfaces.
- Durable writes should append events. Events are the review trail for later
  agents.
- Validation is advisory but persistent. Structural write invariants block bad
  records; planning-quality findings guide follow-up work.
- Stable explicit IDs are automation handles. Prefer them over generated IDs
  in agent-authored workflows.
- Batch authoring should be previewable. Use `roadmap scaffold --dry-run`,
  inspect `rejected`, then apply.

## Quick start

1. Resolve the scope key. Use
   `elegy-planning --scope <scope-key> scope list --json` to confirm the
   scope exists. If the user did not name one, ask.
2. Create a goal:
   `elegy-planning --scope <scope-key> --json --non-interactive --correlation-id <id> goal create --id <slug> --title <t> --description <d> --acceptance <a> --acceptance <a> --rejection <r> --rejection <r>`.
   Repeat `--acceptance` and `--rejection` for multiple criteria. Do
   not comma-join values.
3. Add a work point to a roadmap:
   `elegy-planning --scope <scope-key> --json --non-interactive --correlation-id <id> roadmap add-section --roadmap-id <r> --id <s> --slug <slug> --title <t>` followed by
   `roadmap add-work-point --roadmap-id <r> --id <wp> --title <t> --summary <s> --effort-tier <fast|balanced|deep> --file-scope <type:intent:selector>`.
4. For batch roadmap authoring, render `roadmap-workflow` and apply it:
   `elegy-planning template render --template roadmap-workflow --output roadmap.yaml`, then
   `elegy-planning --scope <scope-key> --json --non-interactive --correlation-id <id> roadmap scaffold --file roadmap.yaml --dry-run`.
5. Inspect context before deep work:
   `elegy-planning --scope <scope-key> --json context --entity-type goal --entity-id <id>` to load the goal plus related insights and
   token estimates.
6. Run a full validation pass:
   `elegy-planning --scope <scope-key> --json validate all` to surface
   referential integrity issues and stale references.

## Tool-call guardrails

### Read family (goal/roadmap/plan/work-point/todo/issue/review-point
show & list, scope, search-extended, tags-list, context, work-graph,
next-runnable)

- Argument shape: `<entity> show --<entity>-id <id> --json`. `show --id <id>`
  is also accepted for goal, roadmap, work-point, plan, issue, insight, graph
  node, graph edge, acceptance, and evidence show commands.
  The `--json` flag is required for machine-mode parsing; do not omit it even
  on a "quick check".
- For list commands, pass `--limit <n>` to cap the result set; the
  default limit is conservative but explicit is safer.
- `search` and entity-local `search` commands support `--title`, `--tag`,
  `--status`, and `--fts`. Pass each filter as a separate flag; do not stack
  them in `--query`.
- `context --entity-type <type> --entity-id <id>` returns progressive
  disclosure bundles with token estimates. The estimate is
  informational; do not parse it.
- `work-graph` and `next-runnable` are read-only but can return
  large payloads; always pass `--limit` for `next-runnable` to avoid
  pulling the whole work queue.
- `insight list --all` lists all insights in the active scope.
  Omit `--all` and pass `--parent-type` + `--parent-id` for
  parent-specific listing (existing behavior).
- Side-effect class: `read_only`.
- Approval posture: `none`.

### Mutate family (create / update-status / plan-revise / insight-record)

- Always pass `--json --non-interactive --correlation-id <id>` on every
  mutating call. The CLI refuses interactive prompts when
  `--non-interactive` is set, and a missing `--correlation-id` causes
  the call to fail under machine mode. Both flags together are the
  contract.
- Multi-value flags (`--acceptance`, `--rejection`, `--tag`,
  `--file-scope`, `--related-entity`) must be **repeated** per value:
  `--acceptance <a1> --acceptance <a2>`. Comma-joining is silently
  dropped.
- `plan-revise` removal semantics: passing `--routing-hint ""` or
  omitting `--file-scopes` does **not** clear existing values. Use
  `--clear-routing-hint` and `--clear-file-scopes` to remove
  previously set values. These two flags are the only reliable way
  to clear.
- `--effort-tier` is required for `roadmap add-work-point` and
  recommended for plan and todo authoring. Valid values are
  `fast`, `balanced`, `deep`. The value affects validation depth,
  not the durable record.
- `roadmap add-work-point --dependency-id <id>` only accepts dependencies
  that belong to the same roadmap. Cross-roadmap dependencies are
  rejected at write time with `"status": "invalid"` and a
  descriptive `error` message.
- Use `work-point revise --work-point-id <id> --dependency-id <id>...`
  to add, replace, or `--clear-dependencies` to remove work-point
  dependencies. Do not attempt direct SQLite repair.
- File-scope selector grammar: `<type>:<intent>:<selector>`. Types

From Sofreshx/Elegy, Apache-2.0.

More from Sofreshx/Elegy