- commit
- be08e83798ef9cdd23a44df6c34760a9b566889a
- parent
- b6ca4cfe7d8aab8851a04d96876a6986cb33fdd2
- author
- dami etoile <dami.etoile@gmail.com>
| A | openspec/ | 2 | + |
| A | openspec/ | 30 | ++++++++++++++++++++ |
| A | openspec/ | 46 | ++++++++++++++++++++++++++++++ |
| A | openspec/ | 11 | +++++++ |
| A | openspec/ | 16 | ++++++++++ |
@@ -0,0 +1,30 @@
1+## Why2+3+Specs are the only core OpenSpec artifact without first-class agent tools. Changes have create→promote→archive. Ideas have create→enrich→promote. Specs require hand-writing markdown after calling `openspec_instructions(artifact=specs)` for the authoring guide — no structured create, no filesystem-backed read, no dedicated list. This blocks agents from programmatically creating and inspecting specs without the CLI binary.4+5+## What Changes6+7+- Add `openspec_spec_create` — structured input (title, purpose, requirements array with scenarios) → writes properly formatted `spec.md`. `change` param scopes to change delta specs; omitting it targets baseline specs.8+- Add `openspec_spec_show` — reads a spec as structured JSON using the existing `spec_parser.parse_spec`. Works on both change and baseline specs. Filesystem-backed (no CLI needed).9+- Add `openspec_spec_list` — lists specs within a change, or baseline specs. Filesystem-backed.10+- Add `spec_to_markdown` serializer to `spec_parser.py` — inverse of `parse_spec`, converts structured input to `### Requirement:` / `#### Scenario:` format.11+12+All three tools are filesystem-backed (always available, like idea/change tools). `spec_show` and `spec_list` reuse `spec_parser.py` from the semantic diff work.13+14+## Capabilities15+16+### New Capabilities17+- None.18+19+### Modified Capabilities20+- `agent-tools`: Add spec lifecycle tools for create, show, and list workflows.21+22+## Impact23+24+- `spec_parser.py` — add `spec_to_markdown` serializer25+- `schemas.py` — three new schemas26+- `tools.py` — three new handlers27+- `__init__.py` — register three new tools28+- `plugin.yaml` — declare three new tools29+- `README.md`, `docs/tool-reference.md` — tool count and table updates30+- Tests for structured create, parse round-trip, overwrite protection, change vs baseline scoping, and listing@@ -0,0 +1,46 @@
1+# Agent OpenSpec Tools Delta2+3+## MODIFIED Requirements4+5+### Requirement: Spec lifecycle tools6+The plugin SHALL provide filesystem-backed tools for creating, reading, and listing specs so agents can manage specs as first-class artifacts without the OpenSpec CLI binary.7+8+#### Scenario: Create a baseline spec9+- **GIVEN** a project with an `openspec/specs/` directory10+- **WHEN** an agent calls `openspec_spec_create` with a spec name, title, purpose, and requirements array (each with name, description, and optional scenarios)11+- **THEN** the tool writes a properly formatted `openspec/specs/<name>/spec.md` using `### Requirement:` and `#### Scenario:` markdown and returns `ok: true` with the spec name and relative path12+13+#### Scenario: Create a change-scoped spec14+- **GIVEN** a project with an active change15+- **WHEN** an agent calls `openspec_spec_create` with a `change` parameter and a spec name16+- **THEN** the tool writes the spec under `openspec/changes/<change>/specs/<name>/spec.md` instead of the baseline directory17+18+#### Scenario: Refuse to overwrite existing spec19+- **GIVEN** a spec already exists at the target path20+- **WHEN** an agent calls `openspec_spec_create` without a `force` flag21+- **THEN** the tool returns `ok: false` and does not modify the existing file22+23+#### Scenario: Show a spec as structured JSON24+- **WHEN** an agent calls `openspec_spec_show` with a spec name and optional `change` id25+- **THEN** the tool reads and parses the spec using `spec_parser.parse_spec` and returns `ok: true` with the title, purpose, and an array of requirements (each with name, description, and scenarios)26+27+#### Scenario: Show missing spec28+- **WHEN** an agent calls `openspec_spec_show` for a spec that does not exist29+- **THEN** the tool returns `ok: false` with a clear error30+31+#### Scenario: List baseline specs32+- **WHEN** an agent calls `openspec_spec_list` without a `change` parameter33+- **THEN** the tool returns `ok: true` with an array of spec names found under `openspec/specs/`34+35+#### Scenario: List change-scoped specs36+- **WHEN** an agent calls `openspec_spec_list` with a `change` parameter37+- **THEN** the tool returns `ok: true` with an array of spec names found under `openspec/changes/<change>/specs/`38+39+#### Scenario: List specs when none exist40+- **GIVEN** the target specs directory is empty or missing41+- **WHEN** an agent calls `openspec_spec_list`42+- **THEN** the tool returns `ok: true` with an empty array43+44+#### Scenario: Invalid workdir45+- **WHEN** any spec tool is called with a missing or non-directory workdir46+- **THEN** the tool returns `ok: false` and does not perform filesystem operations@@ -0,0 +1,11 @@
1+# Spec-first-class tools: create, show, list2+3+## ADDED Requirements4+5+### Requirement: Spec-first-class tools: create, show, list scope6+The system SHALL implement the approved behavior described by this change after this placeholder is refined into concrete requirements.7+8+#### Scenario: Placeholder refinement9+- **GIVEN** `spec-first-class-tools` has been created as an OpenSpec change10+- **WHEN** implementation begins11+- **THEN** this placeholder requirement is replaced or refined with concrete, testable behavior before the change is completed@@ -0,0 +1,16 @@
1+## 1. Tasks2+3+- [ ] 1.1 1.1 Add `openspec_spec_create` schema to schemas.py (structured input: title, purpose, requirements array with name/description/scenarios)4+- [ ] 1.2 1.2 Add `openspec_spec_show` schema (inputs: spec name, optional change id, optional workdir)5+- [ ] 1.3 1.3 Add `openspec_spec_list` schema (inputs: optional change id, optional workdir)6+- [ ] 1.4 1.4 Register all three tools in __init__.py and plugin.yaml7+- [ ] 1.5 2.1 Add `spec_to_markdown` serializer to spec_parser.py (inverse of parse_spec — structured input → formatted spec.md)8+- [ ] 1.6 2.2 Implement `openspec_spec_create` handler in tools.py (slug validation, change-scoped vs baseline, overwrite protection)9+- [ ] 1.7 2.3 Implement `openspec_spec_show` handler in tools.py (uses parse_spec, returns structured JSON)10+- [ ] 1.8 2.4 Implement `openspec_spec_list` handler in tools.py (directory walk: change specs or baseline specs)11+- [ ] 1.9 3.1 Add tests for spec_create (structured input → valid markdown, overwrite refusal, invalid slug)12+- [ ] 1.10 3.2 Add tests for spec_show (parse round-trip, missing spec, change vs baseline)13+- [ ] 1.11 3.3 Add tests for spec_list (change-scoped, baseline, empty)14+- [ ] 1.12 4.1 Update agent-tools spec with new requirements for create/show/list15+- [ ] 1.13 4.2 Update README and docs/tool-reference.md tool counts and tables16+- [ ] 1.14 4.3 Run full test suite and openspec validate --strict