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

Files

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

6.6 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: 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.

6.6 KiB Raw Permalink Blame History