mirror of https://github.com/Fission-AI/OpenSpec.git synced 2026-09-14 20:16:53 +08:00

Files

T

Tabish Bidiwale fb7ff527a6 proposal: add artifact workflow CLI commands (Slice 4) (#415 )

* proposal: add artifact workflow CLI commands (Slice 4)

Add CLI commands for artifact workflow operations:
- `openspec status --change <id>` - Show artifact completion state
- `openspec next --change <id>` - Show ready artifacts
- `openspec instructions <artifact> --change <id>` - Get enriched template
- `openspec templates --change <id>` - Show template paths
- `openspec new change <name>` - Create new change

Commands are top-level for fluid UX and implemented in isolation
for easy removal (experimental feature).

* fix: remove --change from templates command

Templates are schema-level, not change-level. The command now uses
--schema instead of --change for consistency with how templates
are actually resolved.

* rename: cli-workflow -> cli-artifact-workflow

More specific capability name that clarifies which workflow the CLI
commands are for.

* feat: implement artifact workflow CLI commands (Slice 4)

Add experimental CLI commands for artifact-based workflow management:
- `openspec status --change <id>` - display artifact completion status
- `openspec next --change <id>` - show artifacts ready to create
- `openspec instructions <artifact> --change <id>` - output enriched template
- `openspec templates [--schema <name>]` - show resolved template paths
- `openspec new change <name>` - create new change directory

Features:
- JSON output support (--json flag) for all commands
- Color-coded status indicators (green/yellow/red)
- Progress spinners during loading
- --no-color and NO_COLOR env support
- --schema option for custom schema selection
- Comprehensive error handling with helpful messages

All commands are isolated in src/commands/artifact-workflow.ts for easy
removal if the feature doesn't work out. Help text marks them as experimental.

* fix: update specs glob to match nested directory structure

The schema used specs/*.md but specs are stored as specs/<capability>/spec.md.
Updated to specs/**/*.md so openspec status/next correctly detect spec completion.

* test: update test to match new specs glob pattern

* chore: archive add-artifact-workflow-cli change

- Move change to archive/2025-12-28-add-artifact-workflow-cli
- Create cli-artifact-workflow spec

* feat: unify change state model for scaffolded changes

- Update artifact workflow commands to work with scaffolded changes
- Add draft changes section to dashboard view
- Fix completed changes to require tasks.total > 0
- Archive unify-change-state-model change

* fix: validate change name format to prevent path traversal

Add validation in validateChangeExists() to ensure --change parameter
is a valid kebab-case ID before constructing file paths. This prevents
path traversal attacks like --change "../foo" or --change "/etc/passwd".

- Reuses existing validateChangeName() from change-utils.ts
- Adds 3 tests for path traversal, absolute paths, and slashes

2025-12-29 16:55:56 +11:00

7.2 KiB

Raw Permalink Blame History

cli-artifact-workflow Specification

Purpose

TBD - created by archiving change add-artifact-workflow-cli. Update Purpose after archive.

Requirements

Requirement: Status Command

The system SHALL display artifact completion status for a change, including scaffolded (empty) changes.

Fixes bug: Previously required proposal.md to exist via getActiveChangeIds().

Scenario: Show status with all states

WHEN user runs openspec status --change <id>
THEN the system displays each artifact with status indicator:
- [x] for completed artifacts
- [ ] for ready artifacts
- [-] for blocked artifacts (with missing dependencies listed)

Scenario: Status shows completion summary

WHEN user runs openspec status --change <id>
THEN output includes completion percentage and count (e.g., "2/4 artifacts complete")

Scenario: Status JSON output

WHEN user runs openspec status --change <id> --json
THEN the system outputs JSON with changeName, schemaName, isComplete, and artifacts array

Scenario: Status on scaffolded change

WHEN user runs openspec status --change <id> on a change with no artifacts
THEN system displays all artifacts with their status
AND root artifacts (no dependencies) show as ready [ ]
AND dependent artifacts show as blocked [-]

Scenario: Missing change parameter

WHEN user runs openspec status without --change
THEN the system displays an error with list of available changes
AND includes scaffolded changes (directories without proposal.md)

Scenario: Unknown change

WHEN user runs openspec status --change unknown-id
AND directory openspec/changes/unknown-id/ does not exist
THEN the system displays an error listing all available change directories

Requirement: Next Command

The system SHALL show which artifacts are ready to be created, including for scaffolded changes.

Scenario: Show ready artifacts

WHEN user runs openspec next --change <id>
THEN the system lists artifacts whose dependencies are all satisfied

Scenario: No artifacts ready

WHEN all artifacts are either completed or blocked
THEN the system indicates no artifacts are ready (with explanation)

Scenario: All artifacts complete

WHEN all artifacts in the change are completed
THEN the system indicates the change is complete

Scenario: Next JSON output

WHEN user runs openspec next --change <id> --json
THEN the system outputs JSON array of ready artifact IDs

Scenario: Next on scaffolded change

WHEN user runs openspec next --change <id> on a change with no artifacts
THEN system shows root artifacts (e.g., "proposal") as ready to create

Requirement: Instructions Command

The system SHALL output enriched instructions for creating an artifact, including for scaffolded changes.

Scenario: Show enriched instructions

WHEN user runs openspec instructions <artifact> --change <id>
THEN the system outputs:
- Artifact metadata (ID, output path, description)
- Template content
- Dependency status (done/missing)
- Unlocked artifacts (what becomes available after completion)

Scenario: Instructions JSON output

WHEN user runs openspec instructions <artifact> --change <id> --json
THEN the system outputs JSON matching ArtifactInstructions interface

Scenario: Unknown artifact

WHEN user runs openspec instructions unknown-artifact --change <id>
THEN the system displays an error listing valid artifact IDs for the schema

Scenario: Artifact with unmet dependencies

WHEN user requests instructions for a blocked artifact
THEN the system displays instructions with a warning about missing dependencies

Scenario: Instructions on scaffolded change

WHEN user runs openspec instructions proposal --change <id> on a scaffolded change
THEN system outputs template and metadata for creating the proposal
AND does not require any artifacts to already exist

Requirement: Templates Command

The system SHALL show resolved template paths for all artifacts in a schema.

Scenario: List template paths with default schema

WHEN user runs openspec templates
THEN the system displays each artifact with its resolved template path using the default schema

Scenario: List template paths with custom schema

WHEN user runs openspec templates --schema tdd
THEN the system displays template paths for the specified schema

Scenario: Templates JSON output

WHEN user runs openspec templates --json
THEN the system outputs JSON mapping artifact IDs to template paths

Scenario: Template resolution source

WHEN displaying template paths
THEN the system indicates whether each template is from user override or package built-in

Requirement: New Change Command

The system SHALL create new change directories with validation.

Scenario: Create valid change

WHEN user runs openspec new change add-feature
THEN the system creates openspec/changes/add-feature/ directory

Scenario: Invalid change name

WHEN user runs openspec new change "Add Feature" with invalid name
THEN the system displays validation error with guidance

Scenario: Duplicate change name

WHEN user runs openspec new change existing-change for an existing change
THEN the system displays an error indicating the change already exists

Scenario: Create with description

WHEN user runs openspec new change add-feature --description "Add new feature"
THEN the system creates the change directory with description in README.md

Requirement: Schema Selection

The system SHALL support custom schema selection for workflow commands.

Scenario: Default schema

WHEN user runs workflow commands without --schema
THEN the system uses the "spec-driven" schema

Scenario: Custom schema

WHEN user runs openspec status --change <id> --schema tdd
THEN the system uses the specified schema for artifact graph

Scenario: Unknown schema

WHEN user specifies an unknown schema
THEN the system displays an error listing available schemas

Requirement: Output Formatting

The system SHALL provide consistent output formatting.

Scenario: Color output

WHEN terminal supports colors
THEN status indicators use colors: green (done), yellow (ready), red (blocked)

Scenario: No color output

WHEN --no-color flag is used or NO_COLOR environment variable is set
THEN output uses text-only indicators without ANSI colors

Scenario: Progress indication

WHEN loading change state takes time
THEN the system displays a spinner during loading

Requirement: Experimental Isolation

The system SHALL implement artifact workflow commands in isolation for easy removal.

Scenario: Single file implementation

WHEN artifact workflow feature is implemented
THEN all commands are in src/commands/artifact-workflow.ts

Scenario: Help text marking

WHEN user runs --help on any artifact workflow command
THEN help text indicates the command is experimental

7.2 KiB Raw Permalink Blame History