Compare commits

...
Author SHA1 Message Date
Tabish Bidiwale b0d46e1bcc chore: archive completed changes and clean up stale ones
Archive 5 completed changes:
- opsx-archive-command (synced specs)
- add-specs-apply-command
- add-per-change-schema-metadata
- make-apply-instructions-schema-aware (synced specs)
- add-agent-schema-selection

Delete 5 stale/abandoned changes:
- add-fingerprinting (no tasks, 7 weeks old)
- add-scaffold-command (0/7 tasks, 7 weeks old)
- add-proposal-frontmatter (no tasks, 8 weeks old)
- add-interactive-proposal-command (no tasks, 8 weeks old)
- make-validation-scope-aware (0/8 tasks, 4 months old)

Sync delta specs to main:
- Add opsx-archive-skill spec (new capability)
- Update cli-artifact-workflow spec with Schema Apply Block and
  Apply Instructions Command requirements
2026-01-06 23:25:25 -08:00
27 changed files with 235 additions and 112 deletions
@@ -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.
@@ -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
+122
View File
@@ -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