mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-10-04 14:38:54 +08:00
Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
b0d46e1bcc |
@@ -1,11 +0,0 @@
|
||||
## Why
|
||||
Manual setup for new changes leads to formatting mistakes in spec deltas and slows agents who must recreate the same file skeletons for every proposal. A built-in scaffold command will generate compliant templates so assistants can focus on the change content instead of structure.
|
||||
|
||||
## What Changes
|
||||
- Add an `openspec scaffold <change-id>` CLI command that creates a change directory (if it does not already exist) with validated `proposal.md`, `tasks.md`, and spec delta templates.
|
||||
- Update CLI documentation and quick-reference guidance so agents discover the scaffold workflow before drafting files manually, including reminders on when to create spec deltas.
|
||||
- Add automated coverage (unit/integ tests) to ensure the command respects naming rules, copies templates correctly, fails for existing directories, and produces output that passes `openspec validate --strict` untouched.
|
||||
|
||||
## Impact
|
||||
- Affected specs: `specs/cli-scaffold`
|
||||
- Affected code: `src/cli/index.ts`, `src/commands`, `docs/`
|
||||
@@ -1,36 +0,0 @@
|
||||
## ADDED Requirements
|
||||
### Requirement: Scaffolding Command Registration
|
||||
The CLI SHALL expose an `openspec scaffold <change-id>` command that validates the change identifier before generating files.
|
||||
|
||||
#### Scenario: Registering scaffold command
|
||||
- **WHEN** a user runs `openspec scaffold add-user-notifications`
|
||||
- **THEN** the CLI SHALL reject invalid identifiers (non kebab-case) before proceeding
|
||||
- **AND** display usage documentation via `openspec scaffold --help`
|
||||
- **AND** exit with code 0 after successful scaffolding
|
||||
|
||||
### Requirement: Change Directory Structure
|
||||
The scaffold command SHALL create the standard change workspace (if it does not already exist) with proposal, tasks, optional design, and `specs/` directories laid out according to OpenSpec conventions.
|
||||
|
||||
#### Scenario: Generating change workspace
|
||||
- **WHEN** scaffolding a new change with id `add-user-notifications`
|
||||
- **THEN** create `openspec/changes/add-user-notifications/` if it does not exist
|
||||
- **AND** copy the default template bundle (proposal, tasks, design placeholders) into that directory in a single operation
|
||||
- **AND** create an empty `openspec/changes/add-user-notifications/specs/` directory ready for capability-specific deltas that will be authored later
|
||||
|
||||
### Requirement: Template Content Guidance
|
||||
The scaffold command SHALL populate generated Markdown files with OpenSpec-compliant templates so authors can copy, edit, and pass validation without reformatting.
|
||||
|
||||
#### Scenario: Populating proposal and tasks templates
|
||||
- **WHEN** the scaffold command writes `proposal.md`
|
||||
- **THEN** include the `## Why`, `## What Changes`, and `## Impact` headings with placeholder guidance text
|
||||
- **AND** ensure `tasks.md` starts with `## 1. Implementation` and numbered checklist items using `- [ ]` syntax
|
||||
- **AND** annotate optional sections (like `design.md`) with inline TODO comments so users understand when to keep or delete them
|
||||
- **AND** include a short reminder inside `specs/README.md` (or similar) instructing authors to add deltas once they know the affected capability
|
||||
|
||||
### Requirement: Idempotent Execution
|
||||
The scaffold command SHALL be safe to rerun, preserving user edits while filling in any missing managed sections.
|
||||
|
||||
#### Scenario: Rerunning scaffold on existing change
|
||||
- **WHEN** the command is executed again for an existing change directory containing user-edited files
|
||||
- **THEN** leave existing content untouched except for managed placeholder regions or missing files that need creation
|
||||
- **AND** update the filesystem summary to highlight which files were skipped, created, or refreshed
|
||||
@@ -1,12 +0,0 @@
|
||||
## 1. CLI scaffolding command
|
||||
- [ ] 1.1 Register an `openspec scaffold` command in the CLI entrypoint with `change-id` argument validation.
|
||||
- [ ] 1.2 Implement generator logic that copies the default change template bundle (`proposal.md`, `tasks.md`, optional `design.md`, `specs/README.md`) into `openspec/changes/<id>/`, creating the directory tree in a single pass.
|
||||
- [ ] 1.3 Detect when `openspec/changes/<id>/` already exists and exit with a clear error instead of overwriting user files.
|
||||
|
||||
## 2. Templates and documentation
|
||||
- [ ] 2.1 Update `openspec/AGENTS.md` quick reference so agents see `openspec scaffold` before drafting files manually.
|
||||
- [ ] 2.2 Refresh CLI docs/README/help text to mention the scaffold workflow, template bundle contents, and when to add spec deltas manually.
|
||||
|
||||
## 3. Test coverage
|
||||
- [ ] 3.1 Add unit tests covering name validation, template copying, and existing-directory failures.
|
||||
- [ ] 3.2 Add integration coverage ensuring a freshly scaffolded change (without deltas) passes `openspec validate --strict` until the author customizes it.
|
||||
+60
@@ -0,0 +1,60 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Schema Apply Block
|
||||
|
||||
The system SHALL support an `apply` block in schema definitions that controls when and how implementation begins.
|
||||
|
||||
#### Scenario: Schema with apply block
|
||||
|
||||
- **WHEN** a schema defines an `apply` block
|
||||
- **THEN** the system uses `apply.requires` to determine which artifacts must exist before apply
|
||||
- **AND** uses `apply.tracks` to identify the file for progress tracking (or null if none)
|
||||
- **AND** uses `apply.instruction` for guidance shown to the agent
|
||||
|
||||
#### Scenario: Schema without apply block
|
||||
|
||||
- **WHEN** a schema has no `apply` block
|
||||
- **THEN** the system requires all artifacts to exist before apply is available
|
||||
- **AND** uses default instruction: "All artifacts complete. Proceed with implementation."
|
||||
|
||||
### Requirement: Apply Instructions Command
|
||||
|
||||
The system SHALL generate schema-aware apply instructions via `openspec instructions apply`.
|
||||
|
||||
#### Scenario: Generate apply instructions
|
||||
|
||||
- **WHEN** user runs `openspec instructions apply --change <id>`
|
||||
- **AND** all required artifacts (per schema's `apply.requires`) exist
|
||||
- **THEN** the system outputs:
|
||||
- Context files from all existing artifacts
|
||||
- Schema-specific instruction text
|
||||
- Progress tracking file path (if `apply.tracks` is set)
|
||||
|
||||
#### Scenario: Apply blocked by missing artifacts
|
||||
|
||||
- **WHEN** user runs `openspec instructions apply --change <id>`
|
||||
- **AND** required artifacts are missing
|
||||
- **THEN** the system indicates apply is blocked
|
||||
- **AND** lists which artifacts must be created first
|
||||
|
||||
#### Scenario: Apply instructions JSON output
|
||||
|
||||
- **WHEN** user runs `openspec instructions apply --change <id> --json`
|
||||
- **THEN** the system outputs JSON with:
|
||||
- `contextFiles`: array of paths to existing artifacts
|
||||
- `instruction`: the apply instruction text
|
||||
- `tracks`: path to progress file or null
|
||||
- `applyRequires`: list of required artifact IDs
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Status Command
|
||||
|
||||
The system SHALL display artifact completion status for a change, including apply readiness.
|
||||
|
||||
#### Scenario: Status JSON includes apply requirements
|
||||
|
||||
- **WHEN** user runs `openspec status --change <id> --json`
|
||||
- **THEN** the system outputs JSON with:
|
||||
- `changeName`, `schemaName`, `isComplete`, `artifacts` array
|
||||
- `applyRequires`: array of artifact IDs needed for apply phase
|
||||
@@ -1,12 +0,0 @@
|
||||
## Why
|
||||
Validation currently errors on changes without spec deltas, even when the change is intentionally proposal-only or tooling-only. This creates false negatives and noisy CI.
|
||||
|
||||
## What Changes
|
||||
- Make change validation scope-aware: validate only artifacts that exist.
|
||||
- Only error on "No deltas found" if spec delta files exist but parse to zero deltas.
|
||||
- Keep archive stricter: if specs exist but parse to zero deltas, fail; allow `--skip-specs` for tooling-only changes.
|
||||
|
||||
## Impact
|
||||
- Affected specs: cli-validate
|
||||
- Affected code: `src/commands/validate.ts`, `src/core/validation/validator.ts`
|
||||
|
||||
@@ -1,25 +0,0 @@
|
||||
## ADDED Requirements
|
||||
### Requirement: Scope-Aware Change Validation
|
||||
The validator SHALL validate only artifacts that exist for a change, avoiding errors for proposal-only or tooling-only changes.
|
||||
|
||||
#### Scenario: Proposal-only change
|
||||
- **WHEN** a change contains `proposal.md` but has no `specs/` directory or contains no `*/spec.md` files
|
||||
- **THEN** validate the proposal (Why/What sections)
|
||||
- **AND** do not require or validate spec deltas
|
||||
|
||||
#### Scenario: Delta validation when specs exist
|
||||
- **WHEN** a change contains one or more `specs/<capability>/spec.md` files
|
||||
- **THEN** validate delta-formatted specs with existing rules (SHALL/MUST, scenarios, duplicates, conflicts)
|
||||
|
||||
## MODIFIED Requirements
|
||||
### Requirement: Validation SHALL provide actionable remediation steps
|
||||
Validation output SHALL include specific guidance to fix each error, including expected structure, example headers, and suggested commands to verify fixes.
|
||||
|
||||
#### Scenario: No deltas found in change
|
||||
- **WHEN** validating a change that contains `specs/` with one or more `*/spec.md` files but the parser finds zero deltas
|
||||
- **THEN** show error "No deltas found" with guidance:
|
||||
- Ensure `openspec/changes/{id}/specs/` has `.md` files that include delta headers
|
||||
- Use delta headers: `## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`, `## RENAMED Requirements`
|
||||
- Each requirement must include at least one `#### Scenario:` block
|
||||
- Try: `openspec change show {id} --json --deltas-only` to inspect parsed deltas
|
||||
|
||||
@@ -1,16 +0,0 @@
|
||||
## 1. Validator changes
|
||||
- [ ] 1.1 Change `validateChangeDeltaSpecs` to only emit "Change must have at least one delta" when `specs/` exists and contains at least one `*/spec.md` but parsed total deltas is 0
|
||||
- [ ] 1.2 Return valid (no error) when `specs/` directory is missing or has no `spec.md` files
|
||||
|
||||
## 2. CLI changes
|
||||
- [ ] 2.1 In bulk validation, keep current behavior (call delta validator). Behavior remains correct after 1.1
|
||||
- [ ] 2.2 Add a short INFO log in human-readable mode when a change has no `specs/` (optional)
|
||||
|
||||
## 3. Documentation
|
||||
- [ ] 3.1 Update README and template: "Validation checks only existing artifacts. Proposal-only changes are valid without spec deltas."
|
||||
|
||||
## 4. Tests
|
||||
- [ ] 4.1 Add test: proposal-only change passes validation without deltas
|
||||
- [ ] 4.2 Add test: specs present but zero parsed deltas → ERROR
|
||||
- [ ] 4.3 Add test: specs present with proper deltas → valid
|
||||
|
||||
@@ -27,6 +27,13 @@ The system SHALL display artifact completion status for a change, including scaf
|
||||
- **WHEN** user runs `openspec status --change <id> --json`
|
||||
- **THEN** the system outputs JSON with changeName, schemaName, isComplete, and artifacts array
|
||||
|
||||
#### Scenario: Status JSON includes apply requirements
|
||||
|
||||
- **WHEN** user runs `openspec status --change <id> --json`
|
||||
- **THEN** the system outputs JSON with:
|
||||
- `changeName`, `schemaName`, `isComplete`, `artifacts` array
|
||||
- `applyRequires`: array of artifact IDs needed for apply phase
|
||||
|
||||
#### Scenario: Status on scaffolded change
|
||||
|
||||
- **WHEN** user runs `openspec status --change <id>` on a change with no artifacts
|
||||
@@ -159,6 +166,52 @@ The system SHALL implement artifact workflow commands in isolation for easy remo
|
||||
- **WHEN** user runs `--help` on any artifact workflow command
|
||||
- **THEN** help text indicates the command is experimental
|
||||
|
||||
### Requirement: Schema Apply Block
|
||||
|
||||
The system SHALL support an `apply` block in schema definitions that controls when and how implementation begins.
|
||||
|
||||
#### Scenario: Schema with apply block
|
||||
|
||||
- **WHEN** a schema defines an `apply` block
|
||||
- **THEN** the system uses `apply.requires` to determine which artifacts must exist before apply
|
||||
- **AND** uses `apply.tracks` to identify the file for progress tracking (or null if none)
|
||||
- **AND** uses `apply.instruction` for guidance shown to the agent
|
||||
|
||||
#### Scenario: Schema without apply block
|
||||
|
||||
- **WHEN** a schema has no `apply` block
|
||||
- **THEN** the system requires all artifacts to exist before apply is available
|
||||
- **AND** uses default instruction: "All artifacts complete. Proceed with implementation."
|
||||
|
||||
### Requirement: Apply Instructions Command
|
||||
|
||||
The system SHALL generate schema-aware apply instructions via `openspec instructions apply`.
|
||||
|
||||
#### Scenario: Generate apply instructions
|
||||
|
||||
- **WHEN** user runs `openspec instructions apply --change <id>`
|
||||
- **AND** all required artifacts (per schema's `apply.requires`) exist
|
||||
- **THEN** the system outputs:
|
||||
- Context files from all existing artifacts
|
||||
- Schema-specific instruction text
|
||||
- Progress tracking file path (if `apply.tracks` is set)
|
||||
|
||||
#### Scenario: Apply blocked by missing artifacts
|
||||
|
||||
- **WHEN** user runs `openspec instructions apply --change <id>`
|
||||
- **AND** required artifacts are missing
|
||||
- **THEN** the system indicates apply is blocked
|
||||
- **AND** lists which artifacts must be created first
|
||||
|
||||
#### Scenario: Apply instructions JSON output
|
||||
|
||||
- **WHEN** user runs `openspec instructions apply --change <id> --json`
|
||||
- **THEN** the system outputs JSON with:
|
||||
- `contextFiles`: array of paths to existing artifacts
|
||||
- `instruction`: the apply instruction text
|
||||
- `tracks`: path to progress file or null
|
||||
- `applyRequires`: list of required artifact IDs
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Next Command
|
||||
|
||||
@@ -0,0 +1,122 @@
|
||||
# OPSX Archive Skill Spec
|
||||
|
||||
### Requirement: OPSX Archive Skill
|
||||
|
||||
The system SHALL provide an `/opsx:archive` skill that archives completed changes in the experimental workflow.
|
||||
|
||||
#### Scenario: Archive a change with all artifacts complete
|
||||
|
||||
- **WHEN** agent executes `/opsx:archive` with a change name
|
||||
- **AND** all artifacts in the schema are complete
|
||||
- **AND** all tasks are complete
|
||||
- **THEN** the agent moves the change to `openspec/changes/archive/YYYY-MM-DD-<name>/`
|
||||
- **AND** displays success message with archived location
|
||||
|
||||
#### Scenario: Change selection prompt
|
||||
|
||||
- **WHEN** agent executes `/opsx:archive` without specifying a change
|
||||
- **THEN** the agent prompts user to select from available changes
|
||||
- **AND** shows only active changes (excludes archive/)
|
||||
|
||||
### Requirement: Artifact Completion Check
|
||||
|
||||
The skill SHALL check artifact completion status using the artifact graph before archiving.
|
||||
|
||||
#### Scenario: Incomplete artifacts warning
|
||||
|
||||
- **WHEN** agent checks artifact status
|
||||
- **AND** one or more artifacts have status other than `done`
|
||||
- **THEN** display warning listing incomplete artifacts
|
||||
- **AND** prompt user for confirmation to continue
|
||||
- **AND** proceed if user confirms
|
||||
|
||||
#### Scenario: All artifacts complete
|
||||
|
||||
- **WHEN** agent checks artifact status
|
||||
- **AND** all artifacts have status `done`
|
||||
- **THEN** proceed without warning
|
||||
|
||||
### Requirement: Task Completion Check
|
||||
|
||||
The skill SHALL check task completion status from tasks.md before archiving.
|
||||
|
||||
#### Scenario: Incomplete tasks found
|
||||
|
||||
- **WHEN** agent reads tasks.md
|
||||
- **AND** incomplete tasks are found (marked with `- [ ]`)
|
||||
- **THEN** display warning showing count of incomplete tasks
|
||||
- **AND** prompt user for confirmation to continue
|
||||
- **AND** proceed if user confirms
|
||||
|
||||
#### Scenario: All tasks complete
|
||||
|
||||
- **WHEN** agent reads tasks.md
|
||||
- **AND** all tasks are complete (marked with `- [x]`)
|
||||
- **THEN** proceed without task-related warning
|
||||
|
||||
#### Scenario: No tasks file
|
||||
|
||||
- **WHEN** tasks.md does not exist
|
||||
- **THEN** proceed without task-related warning
|
||||
|
||||
### Requirement: Spec Sync Prompt
|
||||
|
||||
The skill SHALL prompt to sync delta specs before archiving if specs exist.
|
||||
|
||||
#### Scenario: Delta specs exist
|
||||
|
||||
- **WHEN** agent checks for delta specs
|
||||
- **AND** `specs/` directory exists in the change with spec files
|
||||
- **THEN** prompt user: "This change has delta specs. Would you like to sync them to main specs before archiving?"
|
||||
- **AND** if user confirms, execute `/opsx:sync` logic
|
||||
- **AND** proceed with archive regardless of sync choice
|
||||
|
||||
#### Scenario: No delta specs
|
||||
|
||||
- **WHEN** agent checks for delta specs
|
||||
- **AND** no `specs/` directory or no spec files exist
|
||||
- **THEN** proceed without sync prompt
|
||||
|
||||
### Requirement: Archive Process
|
||||
|
||||
The skill SHALL move the change to the archive folder with date prefix.
|
||||
|
||||
#### Scenario: Successful archive
|
||||
|
||||
- **WHEN** archiving a change
|
||||
- **THEN** create `archive/` directory if it doesn't exist
|
||||
- **AND** generate target name as `YYYY-MM-DD-<change-name>` using current date
|
||||
- **AND** move entire change directory to archive location
|
||||
- **AND** preserve `.openspec.yaml` file in archived change
|
||||
|
||||
#### Scenario: Archive already exists
|
||||
|
||||
- **WHEN** target archive directory already exists
|
||||
- **THEN** fail with error message
|
||||
- **AND** suggest renaming existing archive or using different date
|
||||
|
||||
### Requirement: Skill Output
|
||||
|
||||
The skill SHALL provide clear feedback about the archive operation.
|
||||
|
||||
#### Scenario: Archive complete with sync
|
||||
|
||||
- **WHEN** archive completes after syncing specs
|
||||
- **THEN** display summary:
|
||||
- Specs synced (from `/opsx:sync` output)
|
||||
- Change archived to location
|
||||
- Schema that was used
|
||||
|
||||
#### Scenario: Archive complete without sync
|
||||
|
||||
- **WHEN** archive completes without syncing specs
|
||||
- **THEN** display summary:
|
||||
- Note that specs were not synced (if applicable)
|
||||
- Change archived to location
|
||||
- Schema that was used
|
||||
|
||||
#### Scenario: Archive complete with warnings
|
||||
|
||||
- **WHEN** archive completes with incomplete artifacts or tasks
|
||||
- **THEN** include note about what was incomplete
|
||||
- **AND** suggest reviewing if archive was intentional
|
||||
Reference in New Issue
Block a user