1# Agent OpenSpec Tools Delta23## MODIFIED Requirements45### Requirement: Artifact listing and inspection6The plugin SHALL provide tools that map directly to OpenSpec list/show/status/instructions workflows while smoothing known CLI rough edges that would otherwise block fresh-repository agent workflows and SHALL expose lifecycle write tools with noun-action naming.78#### Scenario: List changes or specs9- **WHEN** an agent calls `openspec_list` with kind `changes` or `specs`10- **THEN** the tool invokes the OpenSpec CLI JSON list command for that kind and respects supported sort options1112#### Scenario: Show a change or spec13- **WHEN** an agent calls `openspec_show` with a target name and optional flags14- **THEN** the tool invokes the OpenSpec CLI JSON show command with the requested type, delta, requirements, scenario, or requirement filters1516#### Scenario: Validate artifacts17- **WHEN** an agent calls `openspec_validate`18- **THEN** the tool invokes the OpenSpec CLI validation command with strict JSON non-interactive output and the requested target or scope1920#### Scenario: Retrieve implementation instructions21- **WHEN** an agent calls `openspec_instructions`22- **THEN** the tool returns OpenSpec's enriched instructions for the requested artifact, schema, and optional change2324#### Scenario: Accept singular spec artifact alias25- **WHEN** an agent calls `openspec_instructions` with artifact `spec`26- **THEN** the tool treats it as the OpenSpec CLI artifact `specs`2728#### Scenario: Fresh repository instructions fallback29- **GIVEN** a repository has been initialized but contains no changes30- **WHEN** an agent calls `openspec_instructions` for a known artifact31- **THEN** the tool returns `ok: true` with template-backed guidance for that artifact instead of failing only because no change exists3233#### Scenario: Create an idea artifact34- **WHEN** an agent calls `openspec_idea_create` with a valid project/workdir, title, prompt, and optional origin/tags/notes35- **THEN** the tool creates a markdown idea under `openspec/ideas/`, uses a safe deterministic slug with collision handling, and returns `ok: true` with the idea slug, relative path, absolute path, and parsed metadata3637#### Scenario: Refuse invalid idea creation38- **WHEN** an agent calls `openspec_idea_create` with a missing project, empty title, empty prompt, or unsafe path input39- **THEN** the tool returns `ok: false` with a direct validation error and does not write an idea file4041#### Scenario: Enrich an existing idea42- **GIVEN** an idea exists under `openspec/ideas/`43- **WHEN** an agent calls `openspec_idea_enrich` with structured enrichment fields44- **THEN** the tool writes or updates an enrichment report containing problem, proposed direction, key questions, feasibility, T-shirt size, size justification, risks, and suggested next step4546#### Scenario: Promote an idea into a change47- **GIVEN** an idea exists under `openspec/ideas/`48- **WHEN** an agent calls `openspec_idea_promote` with a valid change id49- **THEN** the tool creates an OpenSpec change scaffold that includes proposal, tasks, metadata, and a valid placeholder spec delta, preserves traceability to the source idea, and returns the created artifact paths5051#### Scenario: Create a change directly52- **WHEN** an agent calls `openspec_change_create` with a valid change id, title, and summary53- **THEN** the tool creates a draft OpenSpec change scaffold with proposal metadata and optional tasks/spec placeholder artifacts according to the supplied inputs5455#### Scenario: Promote a draft change to todo56- **GIVEN** an active change has proposal content but no task checklist57- **WHEN** an agent calls `openspec_change_promote` with task descriptions58- **THEN** the tool creates or updates `tasks.md`, ensures at least one valid spec delta exists, and returns the change status as `todo`5960#### Scenario: List tasks for a change61- **GIVEN** a change has a `tasks.md` checklist62- **WHEN** an agent calls `openspec_task_list`63- **THEN** the tool returns ordered task ids, text, status, and aggregate completion counts6465#### Scenario: Set task status66- **GIVEN** a change has a `tasks.md` checklist67- **WHEN** an agent calls `openspec_task_set_status` with task ids and status `todo` or `done`68- **THEN** the tool updates only the requested checklist items and returns refreshed task counts and derived change status6970#### Scenario: Archive a completed change71- **GIVEN** an active change has all tasks complete72- **WHEN** an agent calls `openspec_change_archive`73- **THEN** the tool moves the change under `openspec/changes/archive/`, refuses incomplete tasks unless forced, and returns the archived path7475#### Scenario: Unarchive a change76- **GIVEN** a change exists under `openspec/changes/archive/`77- **WHEN** an agent calls `openspec_change_unarchive`78- **THEN** the tool moves the change back under `openspec/changes/` and refuses to overwrite an active change unless forced7980#### Scenario: Refuse unsafe lifecycle overwrites81- **GIVEN** a target idea, change, task, or archive path would overwrite existing data without explicit force82- **WHEN** an agent calls any lifecycle write tool83- **THEN** the tool returns `ok: false` and preserves existing files