From ef68ba24f953edc6a984dc3141bd26ab5640db14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabi=C3=A1n=20Silva=20Ortiz?= Date: Wed, 25 Feb 2026 16:48:17 -0300 Subject: [PATCH] docs: fix `openspec status` examples in cli.md to match actual CLI output The text and JSON output examples for the status command used incorrect field names, indicators, and structure. Updated to match real CLI output, validated against a test project with partial artifacts. Co-Authored-By: Claude Opus 4.6 --- .changeset/fix-cli-status-docs.md | 5 +++ docs/cli.md | 29 ++++++++--------- .../fix-cli-status-docs/.openspec.yaml | 2 ++ .../changes/fix-cli-status-docs/design.md | 32 +++++++++++++++++++ .../changes/fix-cli-status-docs/proposal.md | 23 +++++++++++++ .../specs/docs-agent-instructions/spec.md | 24 ++++++++++++++ openspec/changes/fix-cli-status-docs/tasks.md | 13 ++++++++ 7 files changed, 113 insertions(+), 15 deletions(-) create mode 100644 .changeset/fix-cli-status-docs.md create mode 100644 openspec/changes/fix-cli-status-docs/.openspec.yaml create mode 100644 openspec/changes/fix-cli-status-docs/design.md create mode 100644 openspec/changes/fix-cli-status-docs/proposal.md create mode 100644 openspec/changes/fix-cli-status-docs/specs/docs-agent-instructions/spec.md create mode 100644 openspec/changes/fix-cli-status-docs/tasks.md diff --git a/.changeset/fix-cli-status-docs.md b/.changeset/fix-cli-status-docs.md new file mode 100644 index 000000000..8473386cf --- /dev/null +++ b/.changeset/fix-cli-status-docs.md @@ -0,0 +1,5 @@ +--- +"@fission-ai/openspec": patch +--- + +docs: fix `openspec status` examples in cli.md to match actual CLI output (field names, indicators, and JSON structure). diff --git a/docs/cli.md b/docs/cli.md index fea903988..ebbb847eb 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -437,29 +437,28 @@ openspec status --change add-dark-mode --json ``` Change: add-dark-mode Schema: spec-driven +Progress: 2/4 artifacts complete -Artifacts: - ✓ proposal proposal.md exists - ✓ specs specs/ exists - ◆ design ready (requires: specs) - ○ tasks blocked (requires: design) - -Next: Create design using /opsx:continue +[x] proposal +[ ] design +[x] specs +[-] tasks (blocked by: design) ``` **Output (JSON):** ```json { - "change": "add-dark-mode", - "schema": "spec-driven", + "changeName": "add-dark-mode", + "schemaName": "spec-driven", + "isComplete": false, + "applyRequires": ["tasks"], "artifacts": [ - {"id": "proposal", "status": "complete", "path": "proposal.md"}, - {"id": "specs", "status": "complete", "path": "specs/"}, - {"id": "design", "status": "ready", "requires": ["specs"]}, - {"id": "tasks", "status": "blocked", "requires": ["design"]} - ], - "next": "design" + {"id": "proposal", "outputPath": "proposal.md", "status": "done"}, + {"id": "design", "outputPath": "design.md", "status": "ready"}, + {"id": "specs", "outputPath": "specs/**/*.md", "status": "done"}, + {"id": "tasks", "outputPath": "tasks.md", "status": "blocked", "missingDeps": ["design"]} + ] } ``` diff --git a/openspec/changes/fix-cli-status-docs/.openspec.yaml b/openspec/changes/fix-cli-status-docs/.openspec.yaml new file mode 100644 index 000000000..e331c975d --- /dev/null +++ b/openspec/changes/fix-cli-status-docs/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-25 diff --git a/openspec/changes/fix-cli-status-docs/design.md b/openspec/changes/fix-cli-status-docs/design.md new file mode 100644 index 000000000..f6883a7b0 --- /dev/null +++ b/openspec/changes/fix-cli-status-docs/design.md @@ -0,0 +1,32 @@ +## Context + +The `docs/cli.md` file contains example output for the `openspec status` command that doesn't match the actual CLI output. The discrepancies exist in both text and JSON format examples. The source of truth is the actual CLI implementation in `src/commands/workflow/status.ts` and `src/commands/workflow/shared.ts`. + +## Goals / Non-Goals + +**Goals:** +- Replace the incorrect text and JSON examples with output that matches the actual CLI behavior +- Ensure examples are verifiable by running the actual commands + +**Non-Goals:** +- Changing the CLI output format itself +- Updating any other documentation sections +- Adding new documentation sections + +## Decisions + +### 1. Derive examples from actual CLI output + +**Decision:** Run `openspec status` against a real change and use the actual output (sanitized with a user-friendly change name) as the documentation examples. + +**Rationale:** This eliminates guesswork and ensures accuracy. The examples should be copy-pasted from real output, not written from memory. + +### 2. Validate after editing + +**Decision:** After updating the documentation, verify correctness by comparing every field name and format in the documented examples against the actual CLI output. + +**Rationale:** The original bug was introduced because examples were written without validation. The fix must not repeat this mistake. + +## Risks / Trade-offs + +- **[Examples go stale if CLI output changes]** → Low risk for a single fix. A systemic solution (generated docs) is out of scope. diff --git a/openspec/changes/fix-cli-status-docs/proposal.md b/openspec/changes/fix-cli-status-docs/proposal.md new file mode 100644 index 000000000..2829f1a3f --- /dev/null +++ b/openspec/changes/fix-cli-status-docs/proposal.md @@ -0,0 +1,23 @@ +## Why + +The `docs/cli.md` documentation for the `openspec status` command shows example output (both text and JSON) that doesn't match the actual CLI output. Anyone reading the docs to understand or parse the output will encounter field names and formats that don't exist, making the documentation misleading for both users and integration developers. + +## What Changes + +- Fix the text output example for `openspec status` to match actual format (`[x]`/`[ ]`/`[-]` indicators, `Progress:` line, `Change:`/`Schema:` headers) +- Fix the JSON output example to use correct field names (`changeName` not `change`, `schemaName` not `schema`, `status: "done"` not `status: "complete"`, `isComplete`, `applyRequires`, `outputPath`, `missingDeps`) +- Remove the non-existent `"next"` field and `"requires"` field from the JSON example + +## Capabilities + +### New Capabilities + +_None._ + +### Modified Capabilities + +_None._ This is a documentation-only fix with no behavioral changes. No spec-level requirements are affected. + +## Impact + +- `docs/cli.md` — status command examples (text and JSON output sections) diff --git a/openspec/changes/fix-cli-status-docs/specs/docs-agent-instructions/spec.md b/openspec/changes/fix-cli-status-docs/specs/docs-agent-instructions/spec.md new file mode 100644 index 000000000..62b322e4f --- /dev/null +++ b/openspec/changes/fix-cli-status-docs/specs/docs-agent-instructions/spec.md @@ -0,0 +1,24 @@ +## ADDED Requirements + +### Requirement: CLI status documentation accuracy + +The `docs/cli.md` status command examples SHALL match the actual output produced by the CLI. + +#### Scenario: Text output example matches actual format + +- **WHEN** comparing the text output example in `docs/cli.md` to the output of `openspec status --change ` +- **THEN** the documented indicators SHALL be `[x]` for done, `[ ]` for ready, and `[-]` for blocked +- **AND** the documented headers SHALL include `Change:`, `Schema:`, and `Progress: N/M artifacts complete` +- **AND** blocked artifacts SHALL show `(blocked by: dep1, dep2)` notation + +#### Scenario: JSON output example matches actual field names + +- **WHEN** comparing the JSON output example in `docs/cli.md` to the output of `openspec status --change --json` +- **THEN** the documented top-level fields SHALL be `changeName`, `schemaName`, `isComplete`, `applyRequires`, and `artifacts` +- **AND** each artifact object SHALL have fields `id`, `outputPath`, `status`, and optionally `missingDeps` +- **AND** the `status` field values SHALL be `done`, `ready`, or `blocked` + +#### Scenario: Validation by running actual CLI + +- **WHEN** the documentation update is complete +- **THEN** the implementer MUST run `openspec status` (both text and `--json` modes) against a real change and verify every field name, value format, and indicator symbol matches the documented examples diff --git a/openspec/changes/fix-cli-status-docs/tasks.md b/openspec/changes/fix-cli-status-docs/tasks.md new file mode 100644 index 000000000..19bfd0565 --- /dev/null +++ b/openspec/changes/fix-cli-status-docs/tasks.md @@ -0,0 +1,13 @@ +## 1. Fix Documentation Examples + +- [x] 1.1 Update the text output example in `docs/cli.md` (lines ~437-448) to match actual `openspec status` format: `[x]`/`[ ]`/`[-]` indicators, `Change:`/`Schema:`/`Progress:` headers, `(blocked by: ...)` notation +- [x] 1.2 Update the JSON output example in `docs/cli.md` (lines ~452-464) to use correct field names: `changeName`, `schemaName`, `isComplete`, `applyRequires`, `artifacts` with `id`/`outputPath`/`status`/`missingDeps` + +## 2. Validation + +- [x] 2.1 Run `openspec status --change ` (text mode) and verify every line in the documented example matches the actual output format +- [x] 2.2 Run `openspec status --change --json` and verify every field name and value format in the documented example matches the actual output + +## 3. Changeset + +- [x] 3.1 Create a changeset file (`.changeset/fix-cli-status-docs.md`) with a patch bump describing the documentation fix