1# Agent OpenSpec Tools23## Purpose45The plugin SHALL expose OpenSpec-aware Hermes tools that let agents discover, inspect, validate, and act on repo-local OpenSpec artifacts without manually assembling shell commands. Tools are expected to be safe for maintainers to use across multiple registered repositories and predictable enough for other agents to depend on.6## Requirements7### Requirement: Registered-source context resolution8The plugin SHALL provide an `openspec_context` tool that resolves user-facing OpenSpec identifiers into the source repository path and relevant artifact content.910#### Scenario: Resolve a bare source name11- **GIVEN** a source is registered with a vanity name or falls back to its path basename12- **WHEN** an agent calls `openspec_context` with that source name13- **THEN** the tool returns the repository path, workdir hint, active changes with tokens, and current specs with tokens1415#### Scenario: Resolve a change token16- **GIVEN** a registered source contains an active or archived change directory with `proposal.md`17- **WHEN** an agent calls `openspec_context` with `<source>/<os_token>` for that change18- **THEN** the tool returns the change name, archive status, proposal content, tasks content, design content, and each delta spec file's relative path and content1920#### Scenario: Resolve a spec token21- **GIVEN** a registered source contains a spec under `openspec/specs/`22- **WHEN** an agent calls `openspec_context` with `<source>/<os_token>` for that spec23- **THEN** the tool returns the spec path and full spec content2425#### Scenario: Missing source or artifact26- **WHEN** an agent calls `openspec_context` with an unknown source or unknown artifact token27- **THEN** the tool returns `ok: false` and a direct error explaining what could not be resolved2829### Requirement: CLI-backed tool gating30The plugin SHALL only expose CLI-backed tools when an executable OpenSpec CLI binary is available.3132#### Scenario: OpenSpec binary available33- **GIVEN** `OPENSPEC_BIN`, `PATH`, or the user's `~/.npm-global/bin/openspec` points to an executable binary34- **WHEN** Hermes registers plugin tools35- **THEN** `openspec_list`, `openspec_show`, `openspec_validate`, `openspec_status`, and `openspec_instructions` are available3637#### Scenario: OpenSpec binary unavailable38- **GIVEN** no executable OpenSpec CLI binary is found39- **WHEN** Hermes registers plugin tools40- **THEN** only `openspec_context` remains available because it reads the registry database and filesystem directly4142### Requirement: CLI command execution contract43CLI-backed tools SHALL execute OpenSpec commands in a resolved project workdir and return structured JSON-compatible results.4445#### Scenario: Successful command46- **WHEN** a CLI-backed tool runs an OpenSpec command successfully47- **THEN** the tool returns `ok: true`, the command, workdir, exit code, parsed stdout when stdout is JSON, stderr, and truncation status4849#### Scenario: Failed command50- **WHEN** a CLI-backed tool receives a non-zero OpenSpec CLI exit code51- **THEN** the tool returns `ok: false` with the same command, workdir, stdout, stderr, exit code, and truncation status5253#### Scenario: Invalid workdir54- **WHEN** a CLI-backed tool is called with a missing or non-directory workdir55- **THEN** the tool returns `ok: false` and does not execute the OpenSpec CLI5657#### Scenario: Command timeout58- **WHEN** an OpenSpec CLI command runs longer than the configured timeout59- **THEN** the tool returns `ok: false` with the command, workdir, and timeout error6061### Requirement: Artifact listing and inspection62The 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.6364#### Scenario: List changes or specs65- **WHEN** an agent calls `openspec_list` with kind `changes` or `specs`66- **THEN** the tool invokes the OpenSpec CLI JSON list command for that kind and respects supported sort options6768#### Scenario: Show a change or spec69- **WHEN** an agent calls `openspec_show` with a target name and optional flags70- **THEN** the tool invokes the OpenSpec CLI JSON show command with the requested type, delta, requirements, scenario, or requirement filters7172#### Scenario: Validate artifacts73- **WHEN** an agent calls `openspec_validate`74- **THEN** the tool invokes the OpenSpec CLI validation command with strict JSON non-interactive output and the requested target or scope7576#### Scenario: Retrieve implementation instructions77- **WHEN** an agent calls `openspec_instructions`78- **THEN** the tool returns OpenSpec's enriched instructions for the requested artifact, schema, and optional change7980#### Scenario: Accept singular spec artifact alias81- **WHEN** an agent calls `openspec_instructions` with artifact `spec`82- **THEN** the tool treats it as the OpenSpec CLI artifact `specs`8384#### Scenario: Fresh repository instructions fallback85- **GIVEN** a repository has been initialized but contains no changes86- **WHEN** an agent calls `openspec_instructions` for a known artifact87- **THEN** the tool returns `ok: true` with template-backed guidance for that artifact instead of failing only because no change exists88