diff --git a/openspec/changes/add-scaffold-command/proposal.md b/openspec/changes/add-scaffold-command/proposal.md index c0fb0342..c97a1d58 100644 --- a/openspec/changes/add-scaffold-command/proposal.md +++ b/openspec/changes/add-scaffold-command/proposal.md @@ -2,9 +2,9 @@ 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 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. -- Add automated coverage (unit/integ tests) to ensure the command respects existing naming rules and generated Markdown passes validation. +- 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` diff --git a/openspec/changes/add-scaffold-command/specs/cli-scaffold/spec.md b/openspec/changes/add-scaffold-command/specs/cli-scaffold/spec.md index 7b896ec8..572dc2fc 100644 --- a/openspec/changes/add-scaffold-command/specs/cli-scaffold/spec.md +++ b/openspec/changes/add-scaffold-command/specs/cli-scaffold/spec.md @@ -9,13 +9,13 @@ The CLI SHALL expose an `openspec scaffold ` command that validates t - **AND** exit with code 0 after successful scaffolding ### Requirement: Change Directory Structure -The scaffold command SHALL create the standard change workspace with proposal, tasks, optional design, and delta directories laid out according to OpenSpec conventions. +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/` -- **AND** generate `proposal.md`, `tasks.md`, and `design.md` (commented placeholder content) in that directory when missing -- **AND** create `openspec/changes/add-user-notifications/specs/` ready for capability-specific deltas +- **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. @@ -25,15 +25,7 @@ The scaffold command SHALL populate generated Markdown files with OpenSpec-compl - **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 - -### Requirement: Delta Spec Creation -The scaffold command SHALL create at least one capability delta file with correctly formatted requirement and scenario placeholders that guide authors to enter the actual behavior. - -#### Scenario: Creating spec delta skeleton -- **WHEN** scaffolding a change and the capability `cli-scaffold` is provided interactively or via flags -- **THEN** generate `openspec/changes/add-user-notifications/specs/cli-scaffold/spec.md` -- **AND** include `## ADDED Requirements` with at least one `### Requirement:` block and matching `#### Scenario:` entries that remind the author to replace placeholder text -- **AND** ensure the generated delta passes `openspec validate add-user-notifications --strict` until the author edits it +- **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. diff --git a/openspec/changes/add-scaffold-command/tasks.md b/openspec/changes/add-scaffold-command/tasks.md index 5dc859df..0f631a98 100644 --- a/openspec/changes/add-scaffold-command/tasks.md +++ b/openspec/changes/add-scaffold-command/tasks.md @@ -1,11 +1,12 @@ ## 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 creates the change directory structure plus default `proposal.md`, `tasks.md`, and delta spec skeletons without overwriting existing populated files. +- [ ] 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 Surface copy/paste templates and scaffold usage in the top-level quick reference for `openspec/AGENTS.md`. -- [ ] 2.2 Refresh other CLI docs (`docs/`, README) to mention the scaffold workflow and link to instructions. +- [ ] 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, file generation, and idempotent reruns. -- [ ] 3.2 Add integration coverage ensuring generated files pass `openspec validate --strict` without manual edits. +- [ ] 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.