All 15 tools now have a two-part description: what it does and when to call it, so agents and contributors can pick the right tool without reading the schema.
- commit
- 294cbb96a36265964fed2a46c333e9d1df95d630
- parent
- b58d75f0d28210b672c8f62d9fe0879ed0a39fff
- author
- dami etoile <dami.etoile@gmail.com>
| M | README.md | 36 | +++++++++++++++--------------- |
@@ -13,27 +13,27 @@ This plugin closes both gaps:
1313 1414 ## What you get1515 16-**Agent tools**:16+**Agent tools** — 15 tools covering the full OpenSpec lifecycle:1717 1818 | Tool | Does |1919 |---|---|20-| `openspec_context` | Resolve a copyable `os_*` identifier (e.g. `puzzletea/os_a1b2c3`) into repo path + change/spec content. Entry point — call this first. |21-| `openspec_list` | List changes or specs in a project, sorted by recent or name. |22-| `openspec_show` | Show a change or spec as JSON — proposals, tasks, designs, deltas, requirements. |23-| `openspec_validate` | Validate OpenSpec changes or specs in a project. |24-| `openspec_status` | Show artifact completion status for a change (turns into kanban updates). |25-| `openspec_instructions` | Enriched instructions for creating artifacts or applying tasks. |26-| `openspec_idea_create` | Create a markdown idea under `openspec/ideas/` from a title and prompt. |27-| `openspec_idea_enrich` | Write or update a structured idea enrichment report with feasibility, T-shirt size, risks, questions, and next step. |28-| `openspec_idea_promote` | Promote an idea into a new OpenSpec change scaffold with proposal/tasks/spec traceability. |29-| `openspec_task_list` | List checklist tasks for a change with ids, text, status, and completion counts. |30-| `openspec_task_set_status` | Mark selected task ids as `todo` or `done`. |31-| `openspec_change_create` | Create a draft OpenSpec change scaffold directly from a title/summary. |32-| `openspec_change_promote` | Promote a draft change to todo by ensuring tasks and a valid spec placeholder exist. |33-| `openspec_change_archive` | Archive a completed change, refusing incomplete tasks unless forced. |34-| `openspec_change_unarchive` | Restore an archived change to the active changes directory. |35-36-`openspec_context` and lifecycle write tools are filesystem-backed and always available. `openspec_list`, `openspec_show`, `openspec_validate`, `openspec_status`, and `openspec_instructions` require the `openspec` CLI binary.20+| `openspec_context` | Resolve a copyable identifier (`puzzletea`, `puzzletea/os_a1b2c3`) into repo path and change/spec content. Always call this first when the user gives you an `os_` identifier — it returns the `workdir` the other tools need. |21+| `openspec_list` | List changes or specs in a project (sorted by recent or name). Call before picking a change or spec to inspect, validate, or coordinate with kanban. |22+| `openspec_show` | Show a change or spec as JSON — proposal, tasks, design, spec deltas, requirements, and scenarios. Call to read the full content of a specific change or spec. |23+| `openspec_validate` | Validate OpenSpec artifacts (a single target, or all changes/specs). Call after editing specs/proposals/tasks or before completing kanban tasks tied to OpenSpec work. |24+| `openspec_status` | Show artifact completion status for a change as JSON (which artifacts exist, which are missing, readiness). Call to turn proposal/task progress into kanban updates. |25+| `openspec_instructions` | Return enriched instructions for creating an artifact (proposal, design, tasks, specs) or applying a change. Call before implementing a spec-driven change to get the authoring guide. |26+| `openspec_idea_create` | Create a markdown idea under `openspec/ideas/` from a title and raw prompt text. Call to capture a feature idea before it's been scoped or evaluated. |27+| `openspec_idea_enrich` | Write or update a structured enrichment report for an existing idea — problem statement, proposed direction, feasibility, T-shirt size, risks, key questions, and next step. Call to evaluate whether an idea is worth promoting. |28+| `openspec_idea_promote` | Promote an idea into a new OpenSpec change scaffold with proposal/tasks/spec traceability. Call when an enriched idea is ready to become an actionable change. |29+| `openspec_task_list` | List checklist tasks for a change — task ids, text, status, and completion counts. Call before marking tasks done or to see what's left. |30+| `openspec_task_set_status` | Set selected task ids in a change to `todo` or `done`. Call to update progress as you complete work items. |31+| `openspec_change_create` | Create a draft OpenSpec change scaffold directly from a title/summary (optional tasks and spec placeholder). Call to start a new change without going through the idea pipeline. |32+| `openspec_change_promote` | Promote a draft change to `todo` by ensuring tasks and a valid spec placeholder exist. Call when a draft is ready for implementation. |33+| `openspec_change_archive` | Archive a completed change, refusing if tasks are incomplete unless `force` is set. Call when a change is done and should be moved out of the active board. |34+| `openspec_change_unarchive` | Move an archived change back to the active changes directory. Call to reopen a change that was archived prematurely. |35+36+`openspec_context` and the lifecycle write tools (idea/change/task) are filesystem-backed and always available. `openspec_list`, `openspec_show`, `openspec_validate`, `openspec_status`, and `openspec_instructions` require the `openspec` CLI binary.3737 3838 **Dashboard tab** (`/openspec`):3939