clarify scaffold proposal

Author: TabishB

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 <change-id>` 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 <change-id>` CLI command that validates IDs, copies the default proposal/tasks/design template bundle into a new change directory, and errors out if the target already exists (authors add spec deltas later).
+- 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`

openspec/changes/add-scaffold-command/specs/cli-scaffold/spec.md

@@ -9,13 +9,13 @@ The CLI SHALL expose an `openspec scaffold <change-id>` 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 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
+- **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,20 +25,12 @@ 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
+- **AND** include a short reminder inside `specs/README.md` (or similar) instructing authors to add deltas once they know the affected capability
 
-### 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.
+### Requirement: Directory Collision Handling
+The scaffold command SHALL prevent accidental overwrites by refusing to run when a change directory already exists.
 
-#### 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
-
-### 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
+#### Scenario: Existing change-id
+- **WHEN** the command is executed for a `change-id` whose directory already exists
+- **THEN** emit an error stating the change has already been scaffolded
+- **AND** exit without modifying any files

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/<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 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.