skills/fission-ai__openspec
1
0
Fork 0
mirror of https://github.com/Fission-AI/OpenSpec.git synced 2026-09-14 20:16:53 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
feat/opsx-ff-command
fission-ai__openspec/openspec/specs/cli-artifact-workflow/spec.md
T
Tabish Bidiwale cac54042ce feat: add Agent Skills for experimental artifact workflow (#424) 
* feat: add Agent Skills for experimental artifact workflow

Implements Task #3 from the experimental release plan:
- Create skill templates for openspec-new-change and openspec-continue-change
- Add artifact-experimental-setup CLI command
- Generate Agent Skills in .claude/skills/ directory
- Support cross-editor compatibility (Claude Code, Cursor, Windsurf)

Skills follow the Agent Skills specification and provide:
- Natural language invocation by AI assistants
- Step-by-step artifact creation workflow
- Dependency-driven change management

* fix: update GitHub issues URL to correct repository

Replace placeholder `https://github.com/your-org/openspec/issues`
with correct URL `https://github.com/Fission-AI/OpenSpec/issues` in:
- docs/experimental-release-plan.md
- src/commands/artifact-workflow.ts

Verified against package.json repository.url field.

* feat: add openspec-apply-change skill for task implementation

Add the apply skill to guide agents through implementing tasks from an
OpenSpec change:

- Add `openspec instructions apply` CLI command that parses tasks.md and
  returns context files, progress tracking, and dynamic instructions
- Add `getApplyChangeSkillTemplate()` to skill-templates.ts with full
  workflow guidance for implementing tasks
- Update artifact-experimental-setup to generate all three skills:
  openspec-new-change, openspec-continue-change, openspec-apply-change

The apply skill supports the fluid "actions on a change" model:
- Can be invoked anytime (if tasks.md exists)
- Handles blocked/ready/all_done states
- Guides agents to pause on issues and suggest artifact updates
- Tracks progress via task checkboxes

* docs: mark apply skill implementation steps as complete

* feat: add Capabilities section to proposal template

Enrich the proposal template to explicitly capture capability discovery:

- Add "Capabilities" section with "New Capabilities" and "Modified
  Capabilities" subsections to proposal template
- Update proposal instruction in schema.yaml to guide agents on
  researching existing specs and listing capabilities
- Update skill instructions with detailed guidance for the Capabilities
  section

This creates a clear contract between proposal and specs phases - each
capability listed in the proposal will need a corresponding spec file.

* feat: remove redundant `openspec next` command

The `next` command was redundant with `status` - both show which artifacts
are ready to create. The status command provides more context (done/ready/blocked)
and is the single source of truth for artifact state.

Changes:
- Remove nextCommand function and CLI registration from artifact-workflow.ts
- Update skill templates to use status instead of next
- Update docs and specs to reflect removal
- Add REMOVED Requirements section to cli-artifact-workflow spec
- Remove 7 tests for the next command

Migration: Use `openspec status --change <id> --json` and filter artifacts
with `status: "ready"` to find artifacts that can be created next.

* docs: clarify kebab-case naming in proposal template

Update HTML comments in the Capabilities section to explicitly instruct
using kebab-case identifiers with examples (user-auth, data-export,
api-rate-limiting).

* feat: add change proposals for per-change schema metadata

Add two related change proposals for enabling schema selection in the
experimental artifact workflow:

1. add-per-change-schema-metadata: Store schema choice in .openspec.yaml
   per change, enabling auto-detection in workflow commands. Includes
   Zod schema design and delta specs for cli-artifact-workflow.

2. add-agent-schema-selection: Follow-up to update agent skills to
   support dynamic schema selection (depends on metadata change).

Also includes:
- Example .openspec.yaml in add-frontmatter-to-openspec-artifact-files
- Clarify "Modified Capabilities" guidance in proposal template

* remove test change

* feat: fix design.md as optional, update docs, add schema-aware apply proposal

Changes:
- Fix generateApplyInstructions to treat design.md as optional (not required)
- Update experimental-release-plan.md CLI output to match implementation
- Add openspec-apply-change skill to docs (was missing)
- Fix test flow numbering after adding apply skill verification step
- Add change proposal for making apply instructions schema-aware

The schema-aware proposal introduces an `implementation` block in schema.yaml
to define when a change becomes implementable and how to track progress.
2026-01-05 16:42:17 -08:00

170 lines
6.6 KiB
Markdown
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: 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
## REMOVED Requirements
### Requirement: Next Command
**Reason**: Redundant with Status Command - `openspec status` already shows which artifacts are ready (status: "ready") vs blocked vs done.
**Migration**: Use `openspec status --change <id> --json` and filter artifacts with `status: "ready"` to find artifacts that can be created next.
Reference in New Issue View Git Blame Copy Permalink