Merge branch 'main' into archive-4-completed-changes

Archived:
- enhance-validation-error-messages (updated cli-validate spec)
- improve-agent-instruction-usability (created docs-agent-instructions spec)
- update-cli-init-root-agents (updated cli-init and cli-update specs)
- update-release-automation (no spec updates)

openspec/changes/archive/2025-10-14-enhance-validation-error-messages/tasks.md

@@ -0,0 +1,12 @@
+## 1. Messaging enhancements
+- [x] 1.1 Inventory current validation failures and map each to the desired message improvements.
+- [x] 1.2 Implement structured error builders that include file paths, normalized header names, and example fixes.
+- [x] 1.3 Ensure `openspec validate --help` and troubleshooting docs mention the richer messages and debug tips.
+
+## 2. Tests
+- [x] 2.1 Add unit tests for representative errors (no deltas, missing requirement body, missing scenarios) asserting the new wording.
+- [x] 2.2 Add integration coverage verifying the Next steps footer reflects contextual guidance.
+
+## 3. Documentation
+- [x] 3.1 Update troubleshooting sections and CLI docs with sample output from the enhanced errors.
+- [x] 3.2 Note the change in CHANGELOG or release notes if applicable.

openspec/changes/archive/2025-10-14-improve-agent-instruction-usability/tasks.md

@@ -0,0 +1,11 @@
+## 1. Instruction redesign
+- [x] 1.1 Draft a quick-reference section that surfaces file templates and formatting rules at the top of `openspec/AGENTS.md`.
+- [x] 1.2 Reorganize the workflow narrative with inline examples and progressive disclosure for advanced topics.
+
+## 2. Templates and checklists
+- [x] 2.1 Add copy/paste templates for proposal, tasks, design, and spec delta files.
+- [x] 2.2 Insert a pre-validation checklist capturing common lint failures before running `openspec validate`.
+
+## 3. Documentation updates
+- [x] 3.1 Update supporting docs or README pointers so contributors find the redesigned instructions.
+- [x] 3.2 Confirm examples and references stay in sync with the new scaffold command guidance.

openspec/changes/archive/2025-10-14-update-cli-init-root-agents/tasks.md

@@ -0,0 +1,11 @@
+## 1. Implementation
+- [x] 1.1 Refactor `openspec init` to always generate the root `AGENTS.md` stub (initial run and extend mode) via shared helper logic.
+- [x] 1.2 Rework the AI tool selection wizard to surface "Natively supported" vs "Other tools" groupings and make the stub non-optional.
+- [x] 1.3 Update CLI messaging, templates, and configurators so the new flow stays in sync across init and update commands.
+- [x] 1.4 Refresh unit/integration tests to cover the unconditional stub and the regrouped prompt layout.
+- [x] 1.5 Update documentation, README snippets, and CHANGELOG entries that mention the opt-in `AGENTS.md` experience.
+
+## 2. Validation
+- [x] 2.1 Run `pnpm test` targeting CLI init/update suites.
+- [x] 2.2 Execute `openspec validate update-cli-init-root-agents --strict`.
+- [x] 2.3 Perform a manual smoke test: run `openspec init` in a temp directory, confirm stub + grouped prompts, rerun in extend mode.

openspec/changes/archive/2025-10-14-update-release-automation/tasks.md

@@ -1,12 +1,12 @@
 ## 1. Release workflow automation
-- [ ] 1.1 Add a `.github/workflows/release.yml` that runs on pushes to `main`, sets up pnpm + Node 20, installs dependencies, and invokes `changesets/action@v1` with `publish: pnpm run release`.
-- [ ] 1.2 Configure the action with `createGithubReleases: true` and document required secrets (`NPM_TOKEN`, default `GITHUB_TOKEN`) plus recommended concurrency safeguards.
-- [ ] 1.3 Validate the workflow using `act` or a dry-run push to confirm the action opens release PRs when changesets exist and publishes when the release PR merge lands.
+- [x] 1.1 Add a `.github/workflows/release.yml` that runs on pushes to `main`, sets up pnpm + Node 20, installs dependencies, and invokes `changesets/action@v1` with `publish: pnpm run release`.
+- [x] 1.2 Configure the action with `createGithubReleases: true` and document required secrets (`NPM_TOKEN`, default `GITHUB_TOKEN`) plus recommended concurrency safeguards.
+- [x] 1.3 Validate the workflow using `act` or a dry-run push to confirm the action opens release PRs when changesets exist and publishes when the release PR merge lands.
 
 ## 2. Package release script
-- [ ] 2.1 Add a `release` script to `package.json` that builds the project and runs `changeset publish` using pnpm.
-- [ ] 2.2 Ensure the script respects the existing `prepare`/`prepublishOnly` hooks to avoid duplicate builds and update documentation or scripts if adjustments are needed.
+- [x] 2.1 Add a `release` script to `package.json` that builds the project and runs `changeset publish` using pnpm.
+- [x] 2.2 Ensure the script respects the existing `prepare`/`prepublishOnly` hooks to avoid duplicate builds and update documentation or scripts if adjustments are needed.
 
 ## 3. Documentation and recovery steps
-- [ ] 3.1 Update maintainer docs (e.g., README or `/docs`) with the end-to-end automated release flow, explicitly removing the manual tag/release steps that are no longer required and explaining how changesets drive the release PR.
-- [ ] 3.2 Document fallback steps for failed publishes (rerun workflow, manual publish) and the hotfix path when a release must be cut without pending changesets.
+- [x] 3.1 Update maintainer docs (e.g., README or `/docs`) with the end-to-end automated release flow, explicitly removing the manual tag/release steps that are no longer required and explaining how changesets drive the release PR.
+- [x] 3.2 Document fallback steps for failed publishes (rerun workflow, manual publish) and the hotfix path when a release must be cut without pending changesets.

openspec/changes/enhance-validation-error-messages/tasks.md

@@ -1,12 +0,0 @@
-## 1. Messaging enhancements
-- [ ] 1.1 Inventory current validation failures and map each to the desired message improvements.
-- [ ] 1.2 Implement structured error builders that include file paths, normalized header names, and example fixes.
-- [ ] 1.3 Ensure `openspec validate --help` and troubleshooting docs mention the richer messages and debug tips.
-
-## 2. Tests
-- [ ] 2.1 Add unit tests for representative errors (no deltas, missing requirement body, missing scenarios) asserting the new wording.
-- [ ] 2.2 Add integration coverage verifying the Next steps footer reflects contextual guidance.
-
-## 3. Documentation
-- [ ] 3.1 Update troubleshooting sections and CLI docs with sample output from the enhanced errors.
-- [ ] 3.2 Note the change in CHANGELOG or release notes if applicable.

openspec/changes/improve-agent-instruction-usability/tasks.md

@@ -1,11 +0,0 @@
-## 1. Instruction redesign
-- [ ] 1.1 Draft a quick-reference section that surfaces file templates and formatting rules at the top of `openspec/AGENTS.md`.
-- [ ] 1.2 Reorganize the workflow narrative with inline examples and progressive disclosure for advanced topics.
-
-## 2. Templates and checklists
-- [ ] 2.1 Add copy/paste templates for proposal, tasks, design, and spec delta files.
-- [ ] 2.2 Insert a pre-validation checklist capturing common lint failures before running `openspec validate`.
-
-## 3. Documentation updates
-- [ ] 3.1 Update supporting docs or README pointers so contributors find the redesigned instructions.
-- [ ] 3.2 Confirm examples and references stay in sync with the new scaffold command guidance.

openspec/changes/update-cli-init-root-agents/tasks.md

@@ -1,11 +0,0 @@
-## 1. Implementation
-- [ ] 1.1 Refactor `openspec init` to always generate the root `AGENTS.md` stub (initial run and extend mode) via shared helper logic.
-- [ ] 1.2 Rework the AI tool selection wizard to surface "Natively supported" vs "Other tools" groupings and make the stub non-optional.
-- [ ] 1.3 Update CLI messaging, templates, and configurators so the new flow stays in sync across init and update commands.
-- [ ] 1.4 Refresh unit/integration tests to cover the unconditional stub and the regrouped prompt layout.
-- [ ] 1.5 Update documentation, README snippets, and CHANGELOG entries that mention the opt-in `AGENTS.md` experience.
-
-## 2. Validation
-- [ ] 2.1 Run `pnpm test` targeting CLI init/update suites.
-- [ ] 2.2 Execute `openspec validate update-cli-init-root-agents --strict`.
-- [ ] 2.3 Perform a manual smoke test: run `openspec init` in a temp directory, confirm stub + grouped prompts, rerun in extend mode.

openspec/specs/cli-init/spec.md

@@ -42,21 +42,17 @@ The command SHALL generate required template files with appropriate content for
 - **AND** generate `project.md` with project context template
 
 ### Requirement: AI Tool Configuration
-The command SHALL configure AI coding assistants with OpenSpec instructions using a marker system.
+The command SHALL configure AI coding assistants with OpenSpec instructions using a grouped selection experience so teams can enable native integrations while always provisioning guidance for other assistants.
+
 #### Scenario: Prompting for AI tool selection
 - **WHEN** run interactively
-- **THEN** prompt the user with "Which AI tools do you use?" using a multi-select menu
-- **AND** list every available tool with a checkbox:
-  - Claude Code (creates or refreshes CLAUDE.md and slash commands)
-  - Cursor (creates or refreshes `.cursor/commands/*` slash commands)
-  - OpenCode (creates or refreshes `.opencode/command/openspec-*.md` slash commands)
-  - Windsurf (creates or refreshes `.windsurf/workflows/openspec-*.md` workflows)
-  - Kilo Code (creates or refreshes `.kilocode/workflows/openspec-*.md` workflows)
-  - Codex (creates or refreshes global prompts at `~/.codex/prompts/openspec-*.md`)
-  - AGENTS.md standard (creates or refreshes AGENTS.md with OpenSpec markers)
-- **AND** show "(already configured)" beside tools whose managed files exist so users understand selections will refresh content
-- **AND** treat disabled tools as "coming soon" and keep them unselectable
-- **AND** allow confirming with Enter after selecting one or more tools
+- **THEN** present a multi-select wizard that separates options into two headings:
+  - **Natively supported providers** shows each available first-party integration (Claude Code, Cursor, OpenCode, …) with checkboxes
+  - **Other tools** explains that the root-level `AGENTS.md` stub is always generated for AGENTS-compatible assistants and cannot be deselected
+- **AND** mark already configured native tools with "(already configured)" to signal that choosing them will refresh managed content
+- **AND** keep disabled or unavailable providers labelled as "coming soon" so users know they cannot opt in yet
+- **AND** allow confirming the selection even when no native provider is chosen because the root stub remains enabled by default
+- **AND** change the base prompt copy in extend mode to "Which natively supported AI tools would you like to add or refresh?"
 
 ### Requirement: AI Tool Configuration Details
 
@@ -142,11 +138,12 @@ The command SHALL use consistent exit codes to indicate different failure modes.
 - **AND** personalize the "Next steps" header using the names of the selected tools, defaulting to a generic label when none remain
 
 ### Requirement: Exit Code Adjustments
-`openspec init` SHALL treat extend mode with no selected tools as a guarded error.
+`openspec init` SHALL treat extend mode without new native tool selections as a successful refresh.
 
-#### Scenario: Preventing empty extend runs
-- **WHEN** OpenSpec is already initialized and the user selects no additional tools
-- **THEN** exit with code 1 after showing the existing-initialization guidance message
+#### Scenario: Allowing empty extend runs
+- **WHEN** OpenSpec is already initialized and the user selects no additional natively supported tools
+- **THEN** complete successfully while refreshing the root `AGENTS.md` stub
+- **AND** exit with code 0
 
 ### Requirement: Slash Command Configuration
 The init command SHALL generate slash command files for supported editors using shared templates.
@@ -221,6 +218,16 @@ The command SHALL support non-interactive operation through command-line options
 - **WHEN** displaying CLI help for `openspec init`
 - **THEN** show the `--tools` option description with the valid values derived from the AI tool registry
 
+### Requirement: Root instruction stub
+`openspec init` SHALL always scaffold the root-level `AGENTS.md` hand-off so every teammate finds the primary OpenSpec instructions.
+
+#### Scenario: Creating root `AGENTS.md`
+- **GIVEN** the project may or may not already contain an `AGENTS.md` file
+- **WHEN** initialization completes in fresh or extend mode
+- **THEN** create or refresh `AGENTS.md` at the repository root using the managed marker block from `TemplateManager.getAgentsStandardTemplate()`
+- **AND** preserve any existing content outside the managed markers while replacing the stub text inside them
+- **AND** create the stub regardless of which native AI tools are selected
+
 ## Why
 
 Manual creation of OpenSpec structure is error-prone and creates adoption friction. A standardized init command ensures:

openspec/specs/cli-update/spec.md

@@ -32,18 +32,14 @@ The update command SHALL handle file updates in a predictable and safe manner.
 - **AND** if a root-level stub exists, update the managed block content so it keeps directing teammates to `@/openspec/AGENTS.md`
 
 ### Requirement: Tool-Agnostic Updates
-The update command SHALL handle file updates in a predictable and safe manner while respecting team tool choices.
+The update command SHALL refresh OpenSpec-managed files in a predictable manner while respecting each team's chosen tooling.
 
 #### Scenario: Updating files
-
 - **WHEN** updating files
 - **THEN** completely replace `openspec/AGENTS.md` with the latest template
-- **AND** update the root-level `AGENTS.md` using the OpenSpec markers only when that file already exists, keeping the stub content that links to `@/openspec/AGENTS.md`
-- **AND** update only the OpenSpec-managed blocks in **existing** AI tool files using markers
-- **AND** use the default directory name `openspec`
-- **AND** be idempotent (repeated runs have no additional effect)
-- **AND** respect team members' AI tool choices by not creating additional tool files beyond the root `AGENTS.md`
-- **AND** do not create new root-level stub files when none are present
+- **AND** create or refresh the root-level `AGENTS.md` stub using the managed marker block, even if the file was previously absent
+- **AND** update only the OpenSpec-managed sections inside existing AI tool files, leaving user-authored content untouched
+- **AND** avoid creating new native-tool configuration files (slash commands, CLAUDE.md, etc.) unless they already exist
 
 ### Requirement: Core Files Always Updated
 The update command SHALL always update the core OpenSpec files and display an ASCII-safe success message.

openspec/specs/cli-validate/spec.md

@@ -9,17 +9,25 @@ Validation output SHALL include specific guidance to fix each error, including e
 #### Scenario: No deltas found in change
 - **WHEN** validating a change with zero parsed deltas
 - **THEN** show error "No deltas found" with guidance:
-  - Ensure `openspec/changes/{id}/specs/` exists with `.md` files
-  - 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 what was parsed
+  - Explain that change specs must include `## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`, or `## RENAMED Requirements`
+  - Remind authors that files must live under `openspec/changes/{id}/specs/<capability>/spec.md`
+  - Include an explicit note: "Spec delta files cannot start with titles before the operation headers"
+  - Suggest running `openspec change show {id} --json --deltas-only` for debugging
 
 #### Scenario: Missing required sections
 - **WHEN** a required section is missing
-- **THEN** the validator SHALL include expected header names and a minimal skeleton:
+- **THEN** include expected header names and a minimal skeleton:
   - For Spec: `## Purpose`, `## Requirements`
   - For Change: `## Why`, `## What Changes`
-  - Show an example snippet of the missing section
+  - Provide an example snippet of the missing section with placeholder prose ready to copy
+  - Mention the quick-reference section in `openspec/AGENTS.md` as the authoritative template
+
+#### Scenario: Missing requirement descriptive text
+- **WHEN** a requirement header lacks descriptive text before scenarios
+- **THEN** emit an error explaining that `### Requirement:` lines must be followed by narrative text before any `#### Scenario:` headers
+  - Show compliant example: "### Requirement: Foo" followed by "The system SHALL ..."
+  - Suggest adding 1-2 sentences describing the normative behavior prior to listing scenarios
+  - Reference the pre-validation checklist in `openspec/AGENTS.md`
 
 ### Requirement: Validator SHALL detect likely misformatted scenarios and warn with a fix
 The validator SHALL recognize bulleted lines that look like scenarios (e.g., lines beginning with WHEN/THEN/AND) and emit a targeted warning with a conversion example to `#### Scenario:`.

openspec/specs/docs-agent-instructions/spec.md

@@ -0,0 +1,38 @@
+# docs-agent-instructions Specification
+
+## Purpose
+TBD - created by archiving change improve-agent-instruction-usability. Update Purpose after archive.
+## Requirements
+### Requirement: Quick Reference Placement
+The AI instructions SHALL begin with a quick-reference section that surfaces required file structures, templates, and formatting rules before any narrative guidance.
+
+#### Scenario: Loading templates at the top
+- **WHEN** `openspec/AGENTS.md` is regenerated or updated
+- **THEN** the first substantive section after the title SHALL provide copy-ready headings for `proposal.md`, `tasks.md`, spec deltas, and scenario formatting
+- **AND** link each template to the corresponding workflow step for deeper reading
+
+### Requirement: Embedded Templates and Examples
+`openspec/AGENTS.md` SHALL include complete copy/paste templates and inline examples exactly where agents make corresponding edits.
+
+#### Scenario: Providing file templates
+- **WHEN** authors reach the workflow guidance for drafting proposals and deltas
+- **THEN** provide fenced Markdown templates that match the required structure (`## Why`, `## ADDED Requirements`, `#### Scenario:` etc.)
+- **AND** accompany each template with a brief example showing correct header usage and scenario bullets
+
+### Requirement: Pre-validation Checklist
+`openspec/AGENTS.md` SHALL offer a concise pre-validation checklist that highlights common formatting mistakes before running `openspec validate`.
+
+#### Scenario: Highlighting common validation failures
+- **WHEN** a reader reaches the validation guidance
+- **THEN** present a checklist reminding them to verify requirement headers, scenario formatting, and delta sections
+- **AND** include reminders about at least `#### Scenario:` usage and descriptive requirement text before scenarios
+
+### Requirement: Progressive Disclosure of Workflow Guidance
+The documentation SHALL separate beginner essentials from advanced topics so newcomers can focus on core steps without losing access to advanced workflows.
+
+#### Scenario: Organizing beginner and advanced sections
+- **WHEN** reorganizing `openspec/AGENTS.md`
+- **THEN** keep an introductory section limited to the minimum steps (scaffold, draft, validate, request review)
+- **AND** move advanced topics (multi-capability changes, archiving details, tooling deep dives) into clearly labeled later sections
+- **AND** provide anchor links from the quick-reference to those advanced sections
+