diff --git a/openspec/changes/add-scaffold-command/proposal.md b/openspec/changes/add-scaffold-command/proposal.md deleted file mode 100644 index c97a1d58d..000000000 --- a/openspec/changes/add-scaffold-command/proposal.md +++ /dev/null @@ -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 ` 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/` diff --git a/openspec/changes/add-scaffold-command/specs/cli-scaffold/spec.md b/openspec/changes/add-scaffold-command/specs/cli-scaffold/spec.md deleted file mode 100644 index 572dc2fc4..000000000 --- a/openspec/changes/add-scaffold-command/specs/cli-scaffold/spec.md +++ /dev/null @@ -1,36 +0,0 @@ -## ADDED Requirements -### Requirement: Scaffolding Command Registration -The CLI SHALL expose an `openspec scaffold ` 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 diff --git a/openspec/changes/add-scaffold-command/tasks.md b/openspec/changes/add-scaffold-command/tasks.md deleted file mode 100644 index 0f631a986..000000000 --- a/openspec/changes/add-scaffold-command/tasks.md +++ /dev/null @@ -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//`, creating the directory tree in a single pass. -- [ ] 1.3 Detect when `openspec/changes//` 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. diff --git a/openspec/changes/add-agent-schema-selection/proposal.md b/openspec/changes/archive/2026-01-06-add-agent-schema-selection/proposal.md similarity index 100% rename from openspec/changes/add-agent-schema-selection/proposal.md rename to openspec/changes/archive/2026-01-06-add-agent-schema-selection/proposal.md diff --git a/openspec/changes/add-agent-schema-selection/tasks.md b/openspec/changes/archive/2026-01-06-add-agent-schema-selection/tasks.md similarity index 100% rename from openspec/changes/add-agent-schema-selection/tasks.md rename to openspec/changes/archive/2026-01-06-add-agent-schema-selection/tasks.md diff --git a/openspec/changes/add-per-change-schema-metadata/design.md b/openspec/changes/archive/2026-01-06-add-per-change-schema-metadata/design.md similarity index 100% rename from openspec/changes/add-per-change-schema-metadata/design.md rename to openspec/changes/archive/2026-01-06-add-per-change-schema-metadata/design.md diff --git a/openspec/changes/add-per-change-schema-metadata/proposal.md b/openspec/changes/archive/2026-01-06-add-per-change-schema-metadata/proposal.md similarity index 100% rename from openspec/changes/add-per-change-schema-metadata/proposal.md rename to openspec/changes/archive/2026-01-06-add-per-change-schema-metadata/proposal.md diff --git a/openspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.md b/openspec/changes/archive/2026-01-06-add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.md similarity index 100% rename from openspec/changes/add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.md rename to openspec/changes/archive/2026-01-06-add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.md diff --git a/openspec/changes/add-per-change-schema-metadata/tasks.md b/openspec/changes/archive/2026-01-06-add-per-change-schema-metadata/tasks.md similarity index 100% rename from openspec/changes/add-per-change-schema-metadata/tasks.md rename to openspec/changes/archive/2026-01-06-add-per-change-schema-metadata/tasks.md diff --git a/openspec/changes/add-specs-apply-command/.openspec.yaml b/openspec/changes/archive/2026-01-06-add-specs-apply-command/.openspec.yaml similarity index 100% rename from openspec/changes/add-specs-apply-command/.openspec.yaml rename to openspec/changes/archive/2026-01-06-add-specs-apply-command/.openspec.yaml diff --git a/openspec/changes/add-specs-apply-command/design.md b/openspec/changes/archive/2026-01-06-add-specs-apply-command/design.md similarity index 100% rename from openspec/changes/add-specs-apply-command/design.md rename to openspec/changes/archive/2026-01-06-add-specs-apply-command/design.md diff --git a/openspec/changes/add-specs-apply-command/proposal.md b/openspec/changes/archive/2026-01-06-add-specs-apply-command/proposal.md similarity index 100% rename from openspec/changes/add-specs-apply-command/proposal.md rename to openspec/changes/archive/2026-01-06-add-specs-apply-command/proposal.md diff --git a/openspec/changes/add-specs-apply-command/specs/specs-sync-skill/spec.md b/openspec/changes/archive/2026-01-06-add-specs-apply-command/specs/specs-sync-skill/spec.md similarity index 100% rename from openspec/changes/add-specs-apply-command/specs/specs-sync-skill/spec.md rename to openspec/changes/archive/2026-01-06-add-specs-apply-command/specs/specs-sync-skill/spec.md diff --git a/openspec/changes/add-specs-apply-command/tasks.md b/openspec/changes/archive/2026-01-06-add-specs-apply-command/tasks.md similarity index 100% rename from openspec/changes/add-specs-apply-command/tasks.md rename to openspec/changes/archive/2026-01-06-add-specs-apply-command/tasks.md diff --git a/openspec/changes/make-apply-instructions-schema-aware/proposal.md b/openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/proposal.md similarity index 100% rename from openspec/changes/make-apply-instructions-schema-aware/proposal.md rename to openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/proposal.md diff --git a/openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/specs/cli-artifact-workflow/spec.md b/openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/specs/cli-artifact-workflow/spec.md new file mode 100644 index 000000000..c1ac2472c --- /dev/null +++ b/openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/specs/cli-artifact-workflow/spec.md @@ -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 ` +- **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 ` +- **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 --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 --json` +- **THEN** the system outputs JSON with: + - `changeName`, `schemaName`, `isComplete`, `artifacts` array + - `applyRequires`: array of artifact IDs needed for apply phase diff --git a/openspec/changes/make-apply-instructions-schema-aware/tasks.md b/openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/tasks.md similarity index 100% rename from openspec/changes/make-apply-instructions-schema-aware/tasks.md rename to openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/tasks.md diff --git a/openspec/changes/opsx-archive-command/.openspec.yaml b/openspec/changes/archive/2026-01-06-opsx-archive-command/.openspec.yaml similarity index 100% rename from openspec/changes/opsx-archive-command/.openspec.yaml rename to openspec/changes/archive/2026-01-06-opsx-archive-command/.openspec.yaml diff --git a/openspec/changes/opsx-archive-command/design.md b/openspec/changes/archive/2026-01-06-opsx-archive-command/design.md similarity index 100% rename from openspec/changes/opsx-archive-command/design.md rename to openspec/changes/archive/2026-01-06-opsx-archive-command/design.md diff --git a/openspec/changes/opsx-archive-command/proposal.md b/openspec/changes/archive/2026-01-06-opsx-archive-command/proposal.md similarity index 100% rename from openspec/changes/opsx-archive-command/proposal.md rename to openspec/changes/archive/2026-01-06-opsx-archive-command/proposal.md diff --git a/openspec/changes/opsx-archive-command/specs/opsx-archive-skill/spec.md b/openspec/changes/archive/2026-01-06-opsx-archive-command/specs/opsx-archive-skill/spec.md similarity index 100% rename from openspec/changes/opsx-archive-command/specs/opsx-archive-skill/spec.md rename to openspec/changes/archive/2026-01-06-opsx-archive-command/specs/opsx-archive-skill/spec.md diff --git a/openspec/changes/opsx-archive-command/tasks.md b/openspec/changes/archive/2026-01-06-opsx-archive-command/tasks.md similarity index 100% rename from openspec/changes/opsx-archive-command/tasks.md rename to openspec/changes/archive/2026-01-06-opsx-archive-command/tasks.md diff --git a/openspec/changes/make-validation-scope-aware/proposal.md b/openspec/changes/make-validation-scope-aware/proposal.md deleted file mode 100644 index 391b703cd..000000000 --- a/openspec/changes/make-validation-scope-aware/proposal.md +++ /dev/null @@ -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` - diff --git a/openspec/changes/make-validation-scope-aware/specs/cli-validate/spec.md b/openspec/changes/make-validation-scope-aware/specs/cli-validate/spec.md deleted file mode 100644 index cae28c913..000000000 --- a/openspec/changes/make-validation-scope-aware/specs/cli-validate/spec.md +++ /dev/null @@ -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//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 - diff --git a/openspec/changes/make-validation-scope-aware/tasks.md b/openspec/changes/make-validation-scope-aware/tasks.md deleted file mode 100644 index 9ccf39067..000000000 --- a/openspec/changes/make-validation-scope-aware/tasks.md +++ /dev/null @@ -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 - diff --git a/openspec/specs/cli-artifact-workflow/spec.md b/openspec/specs/cli-artifact-workflow/spec.md index 38cfa3774..7ca8855b9 100644 --- a/openspec/specs/cli-artifact-workflow/spec.md +++ b/openspec/specs/cli-artifact-workflow/spec.md @@ -27,6 +27,13 @@ The system SHALL display artifact completion status for a change, including scaf - **WHEN** user runs `openspec status --change --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 --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 ` 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 ` +- **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 ` +- **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 --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 diff --git a/openspec/specs/opsx-archive-skill/spec.md b/openspec/specs/opsx-archive-skill/spec.md new file mode 100644 index 000000000..ccb4cee95 --- /dev/null +++ b/openspec/specs/opsx-archive-skill/spec.md @@ -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-/` +- **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-` 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