Merge branch 'main' into fix-validation

chore(dev): add VS Code dev container configuration (#209 )
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>
2026-10-11 04:49:52 +08:00 · 2025-10-19 23:47:07 +11:00 · 2025-10-19 21:50:50 +11:00 · 2025-10-19 11:55:36 +11:00 · 2025-10-17 14:01:28 +11:00 · 2025-10-16 18:07:51 +11:00
54 changed files with 1427 additions and 111 deletions
@@ -0,0 +1,92 @@
+# Dev Container Setup
+
+This directory contains the VS Code dev container configuration for OpenSpec development.
+
+## What's Included
+
+- **Node.js 20 LTS** (>=20.19.0) - TypeScript/JavaScript runtime
+- **pnpm** - Fast, disk space efficient package manager
+- **Git + GitHub CLI** - Version control tools
+- **VS Code Extensions**:
+  - ESLint & Prettier for code quality
+  - Vitest Explorer for running tests
+  - GitLens for enhanced git integration
+  - Error Lens for inline error highlighting
+  - Code Spell Checker
+  - Path IntelliSense
+
+## How to Use
+
+### First Time Setup
+
+1. **Install Prerequisites** (on your local machine):
+   - [VS Code](https://code.visualstudio.com/)
+   - [Docker Desktop](https://www.docker.com/products/docker-desktop)
+   - [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+2. **Open in Container**:
+   - Open this project in VS Code
+   - You'll see a notification: "Folder contains a Dev Container configuration file"
+   - Click "Reopen in Container"
+
+   OR
+
+   - Open Command Palette (`Cmd/Ctrl+Shift+P`)
+   - Type "Dev Containers: Reopen in Container"
+   - Press Enter
+
+3. **Wait for Setup**:
+   - The container will build (first time takes a few minutes)
+   - `pnpm install` runs automatically via `postCreateCommand`
+   - All extensions install automatically
+
+### Daily Development
+
+Once set up, the container preserves your development environment:
+
+```bash
+# Run development build
+pnpm run dev
+
+# Run CLI in development
+pnpm run dev:cli
+
+# Run tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Build the project
+pnpm run build
+```
+
+### SSH Keys
+
+Your SSH keys are mounted read-only from `~/.ssh`, so git operations work seamlessly with GitHub/GitLab.
+
+### Rebuilding the Container
+
+If you modify `.devcontainer/devcontainer.json`:
+- Command Palette → "Dev Containers: Rebuild Container"
+
+## Benefits
+
+- No need to install Node.js or pnpm on your local machine
+- Consistent development environment across team members
+- Isolated from other Node.js projects on your machine
+- All dependencies and tools containerized
+- Easy onboarding for new developers
+
+## Troubleshooting
+
+**Container won't build:**
+- Ensure Docker Desktop is running
+- Check Docker has enough memory allocated (recommend 4GB+)
+
+**Extensions not appearing:**
+- Rebuild the container: "Dev Containers: Rebuild Container"
+
+**Permission issues:**
+- The container runs as the `node` user (non-root)
+- Files created in the container are owned by this user
@@ -0,0 +1,68 @@
+{
+  "name": "OpenSpec Development",
+  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20-bookworm",
+
+  // Additional tools and features
+  "features": {
+    "ghcr.io/devcontainers/features/git:1": {
+      "version": "latest",
+      "ppa": true
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {
+      "version": "latest"
+    }
+  },
+
+  // Configure tool-specific properties
+  "customizations": {
+    "vscode": {
+      // Set default container specific settings
+      "settings": {
+        "typescript.tsdk": "node_modules/typescript/lib",
+        "typescript.enablePromptUseWorkspaceTsdk": true,
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "esbenp.prettier-vscode",
+        "editor.codeActionsOnSave": {
+          "source.fixAll": "explicit"
+        },
+        "files.eol": "\n",
+        "terminal.integrated.defaultProfile.linux": "bash"
+      },
+
+      // Add extensions you want installed when the container is created
+      "extensions": [
+        // TypeScript/JavaScript essentials
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+
+        // Testing
+        "vitest.explorer",
+
+        // Git
+        "eamodio.gitlens",
+
+        // Utilities
+        "streetsidesoftware.code-spell-checker",
+        "usernamehw.errorlens",
+        "christian-kohler.path-intellisense"
+      ]
+    }
+  },
+
+  // Use 'forwardPorts' to make a list of ports inside the container available locally
+  // "forwardPorts": [],
+
+  // Use 'postCreateCommand' to run commands after the container is created
+  "postCreateCommand": "corepack enable && corepack prepare pnpm@latest --activate && pnpm install",
+
+  // Configure mounts to preserve SSH keys for git operations
+  "mounts": [
+    "source=${localEnv:HOME}${localEnv:USERPROFILE}/.ssh,target=/home/node/.ssh,readonly,type=bind,consistency=cached"
+  ],
+
+  // Set the default user to 'node' (non-root user)
+  "remoteUser": "node",
+
+  // Ensure git is properly configured
+  "initializeCommand": "echo 'Initializing dev container...'"
+}
@@ -147,3 +147,6 @@ docs/
 .claude/
 CLAUDE.md
 .DS_Store
+
+# Pnpm
+.pnpm-store/
@@ -1,5 +1,16 @@
 # @fission-ai/openspec

+## 0.12.0
+
+### Minor Changes
+
+- 082abb4: Add factory function support for slash commands and non-interactive init options
+
+  This release includes two new features:
+
+  - **Factory function support for slash commands**: Slash commands can now be defined as functions that return command objects, enabling dynamic command configuration
+  - **Non-interactive init options**: Added `--tools`, `--all-tools`, and `--skip-tools` CLI flags to `openspec init` for automated initialization in CI/CD pipelines while maintaining backward compatibility with interactive mode
+
 ## 0.11.0

 ### Minor Changes
@@ -92,12 +92,14 @@ These tools have built-in OpenSpec commands. Select the OpenSpec integration whe
 |------|----------|
 | **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |
 | **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
+| **Factory Droid** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.factory/commands/`) |
 | **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
 | **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
 | **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) |
 | **Codex** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (global: `~/.codex/prompts`, auto-installed) |
 | **GitHub Copilot** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.github/prompts/`) |
 | **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` (`.amazonq/prompts/`) |
+| **Auggie (Augment CLI)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.augment/commands/`) |

 Kilo Code discovers team workflows automatically. Save the generated files under `.kilocode/workflows/` and trigger them from the command palette with `/openspec-proposal.md`, `/openspec-apply.md`, or `/openspec-archive.md`.

@@ -144,6 +146,8 @@ openspec init
 **After setup:**
 - Primary AI tools can trigger `/openspec` workflows without additional configuration
 - Run `openspec list` to verify the setup and view any active changes
+- If your coding assistant doesn't surface the new slash commands right away, restart it. Slash commands are loaded at startup,
+  so a fresh launch ensures they appear.

 ### Create Your First Change

@@ -60,7 +60,7 @@ Track these steps as TODOs and complete them one by one.
 After deployment, create separate PR to:
 - Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/`
 - Update `specs/` if capabilities changed
- Use `openspec archive [change] --skip-specs --yes` for tooling-only changes
+- Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly)
 - Run `openspec validate --strict` to confirm the archived change passes checks

 ## Before Any Task
@@ -97,7 +97,7 @@ openspec list --specs          # List specifications
 openspec show [item]           # Display change or spec
 openspec diff [change]         # Show spec differences
 openspec validate [item]       # Validate changes or specs
-openspec archive [change] [--yes|-y]      # Archive after deployment (add --yes for non-interactive runs)
+openspec archive <change-id> [--yes|-y]   # Archive after deployment (add --yes for non-interactive runs)

 # Project management
 openspec init [path]           # Initialize OpenSpec
@@ -450,7 +450,7 @@ openspec list              # What's in progress?
 openspec show [item]       # View details
 openspec diff [change]     # What's changing?
 openspec validate --strict # Is it correct?
-openspec archive [change] [--yes|-y]  # Mark complete (add --yes for automation)
+openspec archive <change-id> [--yes|-y]  # Mark complete (add --yes for automation)
 ```

 Remember: Specs are truth. Changes are proposals. Keep them in sync.
@@ -0,0 +1,17 @@
+# Add Archive Command Arguments
+
+## Why
+The `/openspec:archive` slash command currently lacks argument support, forcing the AI to infer which change to archive from conversation context or by listing all changes. This creates a safety risk where the wrong proposal could be archived if the context is ambiguous or multiple changes exist. Users expect to specify the change ID explicitly, matching the behavior of the CLI command `openspec archive <id>`.
+
+## What Changes
+- Add `$ARGUMENTS` placeholder to the OpenCode archive slash command frontmatter (matching existing pattern for proposal command)
+- Update archive command template steps to validate the specific change ID argument when provided
+- Note: Codex, GitHub Copilot, and Amazon Q already have `$ARGUMENTS` for archive; Claude/Cursor/Windsurf/Kilocode don't support arguments
+
+## Impact
+- Affected specs: `cli-update` (slash command generation logic)
+- Affected code:
+  - `src/core/configurators/slash/opencode.ts` (add `$ARGUMENTS` to archive frontmatter)
+  - `src/core/templates/slash-command-templates.ts` (archive template steps for argument validation)
+- Breaking: No - this is additive functionality that makes the command safer
+- User-facing: Yes - OpenCode users will be able to pass the change ID as an argument: `/openspec:archive <change-id>`
@@ -0,0 +1,34 @@
+# CLI Update Specification Delta
+
+## MODIFIED Requirements
+
+### Requirement: Slash Command Updates
+The update command SHALL refresh existing slash command files for configured tools without creating new ones, and ensure the OpenCode archive command accepts change ID arguments.
+
+#### Scenario: Updating slash commands for OpenCode
+- **WHEN** `.opencode/command/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+- **AND** ensure the archive command includes `$ARGUMENTS` placeholder in frontmatter for accepting change ID arguments
+
+## ADDED Requirements
+
+### Requirement: Archive Command Argument Support
+The archive slash command template SHALL support optional change ID arguments for tools that support `$ARGUMENTS` placeholder.
+
+#### Scenario: Archive command with change ID argument
+- **WHEN** a user invokes `/openspec:archive <change-id>` with a change ID
+- **THEN** the template SHALL instruct the AI to validate the provided change ID against `openspec list`
+- **AND** use the provided change ID for archiving if valid
+- **AND** fail fast if the provided change ID doesn't match an archivable change
+
+#### Scenario: Archive command without argument (backward compatibility)
+- **WHEN** a user invokes `/openspec:archive` without providing a change ID
+- **THEN** the template SHALL instruct the AI to identify the change ID from context or by running `openspec list`
+- **AND** proceed with the existing behavior (maintaining backward compatibility)
+
+#### Scenario: OpenCode archive template generation
+- **WHEN** generating the OpenCode archive slash command file
+- **THEN** include the `$ARGUMENTS` placeholder in the frontmatter
+- **AND** wrap it in a clear structure like `<ChangeId>\n  $ARGUMENTS\n</ChangeId>` to indicate the expected argument
+- **AND** include validation steps in the template body to check if the change ID is valid
@@ -0,0 +1,21 @@
+# Implementation Tasks
+
+## 1. Update OpenCode Configurator
+- [x] 1.1 Add `$ARGUMENTS` placeholder to OpenCode archive frontmatter (matching the proposal pattern)
+- [x] 1.2 Format it as `<ChangeId>\n  $ARGUMENTS\n</ChangeId>` or similar structure for clarity
+- [x] 1.3 Ensure `updateExisting` rewrites the archive frontmatter/body so `$ARGUMENTS` persists after `openspec update`
+
+## 2. Update Slash Command Templates
+- [x] 2.1 Modify archive steps to validate change ID argument when provided via `$ARGUMENTS`
+- [x] 2.2 Keep backward compatibility - allow inferring from context if no argument provided
+- [x] 2.3 Add step to validate the change ID exists using `openspec list` before archiving
+
+## 3. Update Documentation
+- [x] 3.1 Update AGENTS.md archive examples to show argument usage
+- [x] 3.2 Document that OpenCode now supports `/openspec:archive <change-id>`
+
+## 4. Validation and Testing
+- [ ] 4.1 Run `openspec update` to regenerate OpenCode slash commands
+- [ ] 4.2 Manually test with OpenCode using `/openspec:archive <change-id>`
+- [ ] 4.3 Test backward compatibility (archive command without arguments)
+- [ ] 4.4 Run `openspec validate --strict` to ensure no issues
@@ -0,0 +1,13 @@
+## Why
+Add support for Crush AI assistant in OpenSpec to enable developers to use Crush's enhanced capabilities for spec-driven development workflows.
+
+## What Changes
+- Add Crush slash command configurator for proposal, apply, and archive operations
+- Add Crush-specific AGENTS.md configuration template 
+- Update tool registry to include Crush configurator
+- **BREAKING**: None - this is additive functionality
+
+## Impact
+- Affected specs: cli-init (new tool option)
+- Affected code: src/core/configurators/slash/crush.ts, registry.ts
+- New files: .crush/commands/openspec/ (proposal.md, apply.md, archive.md)
@@ -0,0 +1,21 @@
+## ADDED Requirements
+### Requirement: Crush Tool Support
+The system SHALL provide Crush AI assistant as a supported tool option during OpenSpec initialization.
+
+#### Scenario: Initialize project with Crush support
+- **WHEN** user runs `openspec init --tool crush`
+- **THEN** Crush-specific slash commands are configured in `.crush/commands/openspec/`
+- **AND** Crush AGENTS.md includes OpenSpec workflow instructions
+- **AND** Crush is registered as available configurator
+
+#### Scenario: Crush proposal command generation
+- **WHEN** Crush slash commands are configured
+- **THEN** `.crush/commands/openspec/proposal.md` contains proposal workflow with guardrails
+- **AND** Includes Crush-specific frontmatter with OpenSpec category and tags
+- **AND** Follows established slash command template pattern
+
+#### Scenario: Crush apply and archive commands
+- **WHEN** Crush slash commands are configured
+- **THEN** `.crush/commands/openspec/apply.md` contains implementation workflow
+- **AND** `.crush/commands/openspec/archive.md` contains archiving workflow
+- **AND** Both commands include appropriate frontmatter and references
@@ -0,0 +1,7 @@
+## 1. Implementation
+- [x] 1.1 Create CrushSlashCommandConfigurator class in src/core/configurators/slash/crush.ts
+- [x] 1.2 Define file paths for Crush commands (.crush/commands/openspec/)
+- [x] 1.3 Create Crush-specific frontmatter for proposal, apply, archive commands
+- [x] 1.4 Register Crush configurator in slash/registry.ts
+- [x] 1.5 Add Crush to available tools in cli-init command
+- [x] 1.6 Test integration with openspec init --tool crush
@@ -0,0 +1,12 @@
+## Why
+Factory's Droid CLI recently shipped custom slash commands that mirror other native assistant integrations. Teams using OpenSpec want the same managed workflows they already get for Cursor, Windsurf, and others so init/update can provision and refresh Factory commands without manual setup.
+
+## What Changes
+- Extend the native tool registry so Factory/Droid appears alongside other slash-command integrations during `openspec init`.
+- Add shared templates that generate the three Factory custom commands (proposal, apply, archive) and wrap them in OpenSpec markers for safe refreshes.
+- Update the init and update command flows so they create or refresh Factory command files when the tool is selected or already present.
+- Refresh CLI specs to document the Factory support and align validation expectations.
+
+## Impact
+- Affected specs: `specs/cli-init`, `specs/cli-update`
+- Affected code (expected): tool registry, slash-command template manager, init/update command helpers, documentation snippets
@@ -0,0 +1,54 @@
+## MODIFIED Requirements
+### Requirement: Slash Command Configuration
+The init command SHALL generate slash command files for supported editors using shared templates.
+
+#### Scenario: Generating slash commands for Claude Code
+- **WHEN** the user selects Claude Code during initialization
+- **THEN** create `.claude/commands/openspec/proposal.md`, `.claude/commands/openspec/apply.md`, and `.claude/commands/openspec/archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Cursor
+- **WHEN** the user selects Cursor during initialization
+- **THEN** create `.cursor/commands/openspec-proposal.md`, `.cursor/commands/openspec-apply.md`, and `.cursor/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Factory Droid
+- **WHEN** the user selects Factory Droid during initialization
+- **THEN** create `.factory/commands/openspec-proposal.md`, `.factory/commands/openspec-apply.md`, and `.factory/commands/openspec-archive.md`
+- **AND** populate each file from shared templates that include Factory-compatible YAML frontmatter for the `description` and `argument-hint` fields
+- **AND** include the `$ARGUMENTS` placeholder in the template body so droid receives any user-supplied input
+- **AND** wrap the generated content in OpenSpec managed markers so `openspec update` can safely refresh the commands
+
+#### Scenario: Generating slash commands for OpenCode
+- **WHEN** the user selects OpenCode during initialization
+- **THEN** create `.opencode/commands/openspec-proposal.md`, `.opencode/commands/openspec-apply.md`, and `.opencode/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Windsurf
+- **WHEN** the user selects Windsurf during initialization
+- **THEN** create `.windsurf/workflows/openspec-proposal.md`, `.windsurf/workflows/openspec-apply.md`, and `.windsurf/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Kilo Code
+- **WHEN** the user selects Kilo Code during initialization
+- **THEN** create `.kilocode/workflows/openspec-proposal.md`, `.kilocode/workflows/openspec-apply.md`, and `.kilocode/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Codex
+- **WHEN** the user selects Codex during initialization
+- **THEN** create global prompt files at `~/.codex/prompts/openspec-proposal.md`, `~/.codex/prompts/openspec-apply.md`, and `~/.codex/prompts/openspec-archive.md` (or under `$CODEX_HOME/prompts` if set)
+- **AND** populate each file from shared templates that map the first numbered placeholder (`$1`) to the primary user input (e.g., change identifier or question text)
+- **AND** wrap the generated content in OpenSpec markers so `openspec update` can refresh the prompts without touching surrounding custom notes
+
+#### Scenario: Generating slash commands for GitHub Copilot
+- **WHEN** the user selects GitHub Copilot during initialization
+- **THEN** create `.github/prompts/openspec-proposal.prompt.md`, `.github/prompts/openspec-apply.prompt.md`, and `.github/prompts/openspec-archive.prompt.md`
+- **AND** populate each file with YAML frontmatter containing a `description` field that summarizes the workflow stage
+- **AND** include `$ARGUMENTS` placeholder to capture user input
+- **AND** wrap the shared template body with OpenSpec markers so `openspec update` can refresh the content
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
@@ -0,0 +1,54 @@
+## MODIFIED Requirements
+### Requirement: Slash Command Updates
+The update command SHALL refresh existing slash command files for configured tools without creating new ones.
+
+#### Scenario: Updating slash commands for Claude Code
+- **WHEN** `.claude/commands/openspec/` contains `proposal.md`, `apply.md`, and `archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Cursor
+- **WHEN** `.cursor/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Factory Droid
+- **WHEN** `.factory/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using the shared Factory templates that include YAML frontmatter for the `description` and `argument-hint` fields
+- **AND** ensure the template body retains the `$ARGUMENTS` placeholder so user input keeps flowing into droid
+- **AND** update only the content inside the OpenSpec managed markers, leaving any unmanaged notes untouched
+- **AND** skip creating missing files during update
+
+#### Scenario: Updating slash commands for OpenCode
+- **WHEN** `.opencode/command/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Windsurf
+- **WHEN** `.windsurf/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates wrapped in OpenSpec markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+- **AND** skip creating missing files (the update command only refreshes what already exists)
+
+#### Scenario: Updating slash commands for Kilo Code
+- **WHEN** `.kilocode/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates wrapped in OpenSpec markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+- **AND** skip creating missing files (the update command only refreshes what already exists)
+
+#### Scenario: Updating slash commands for Codex
+- **GIVEN** the global Codex prompt directory contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **WHEN** a user runs `openspec update`
+- **THEN** refresh each file using the shared slash-command templates (including placeholder guidance)
+- **AND** preserve any unmanaged content outside the OpenSpec marker block
+- **AND** skip creation when a Codex prompt file is missing
+
+#### Scenario: Updating slash commands for GitHub Copilot
+- **WHEN** `.github/prompts/` contains `openspec-proposal.prompt.md`, `openspec-apply.prompt.md`, and `openspec-archive.prompt.md`
+- **THEN** refresh each file using shared templates while preserving the YAML frontmatter
+- **AND** update only the OpenSpec-managed block between markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Missing slash command file
+- **WHEN** a tool lacks a slash command file
+- **THEN** do not create a new file during update
@@ -0,0 +1,11 @@
+## 1. Factory tool registration
+- [x] 1.1 Add Factory/Droid metadata to the native tool registry used by init/update (ID, display name, command paths, availability flags).
+- [x] 1.2 Surface Factory in interactive prompts and non-interactive `--tools` parsing alongside existing slash-command integrations.
+
+## 2. Slash command templates
+- [x] 2.1 Create shared templates for Factory's `openspec-proposal`, `openspec-apply`, and `openspec-archive` custom commands following Factory's CLI format.
+- [x] 2.2 Wire the templates into init/update so generation happens on create and refresh respects OpenSpec markers.
+
+## 3. Verification
+- [x] 3.1 Update or add automated coverage that ensures Factory command files are scaffolded and refreshed correctly.
+- [x] 3.2 Document the new option in any user-facing copy (help text, README snippets) if required by spec.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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:
@@ -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.
@@ -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:`.
@@ -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
+
@@ -1,6 +1,6 @@
 {
  "name": "@fission-ai/openspec",
-  "version": "0.11.0",
+  "version": "0.12.0",
  "description": "AI-native system for spec-driven development",
  "keywords": [
    "openspec",
@@ -187,7 +187,7 @@ program
  .option('-y, --yes', 'Skip confirmation prompts')
  .option('--skip-specs', 'Skip spec update operations (useful for infrastructure, tooling, or doc-only changes)')
  .option('--no-validate', 'Skip validation (not recommended, requires confirmation)')
-  .action(async (changeName?: string, options?: { yes?: boolean; skipSpecs?: boolean; noValidate?: boolean }) => {
+  .action(async (changeName?: string, options?: { yes?: boolean; skipSpecs?: boolean; noValidate?: boolean; validate?: boolean }) => {
    try {
      const archiveCommand = new ArchiveCommand();
      await archiveCommand.execute(changeName, options);
@@ -19,7 +19,10 @@ interface SpecUpdate {
 }

 export class ArchiveCommand {
-  async execute(changeName?: string, options: { yes?: boolean; skipSpecs?: boolean; noValidate?: boolean } = {}): Promise<void> {
+  async execute(
+    changeName?: string,
+    options: { yes?: boolean; skipSpecs?: boolean; noValidate?: boolean; validate?: boolean } = {}
+  ): Promise<void> {
    const targetPath = '.';
    const changesDir = path.join(targetPath, 'openspec', 'changes');
    const archiveDir = path.join(changesDir, 'archive');
@@ -54,8 +57,10 @@ export class ArchiveCommand {
      throw new Error(`Change '${changeName}' not found.`);
    }

+    const skipValidation = options.validate === false || options.noValidate === true;
+
    // Validate specs and change before archiving
-    if (!options.noValidate) {
+    if (!skipValidation) {
      const validator = new Validator();
      let hasValidationErrors = false;

@@ -201,7 +206,7 @@ export class ArchiveCommand {
          let totals = { added: 0, modified: 0, removed: 0, renamed: 0 };
          for (const p of prepared) {
            const specName = path.basename(path.dirname(p.update.target));
-            if (!options.noValidate) {
+            if (!skipValidation) {
              const report = await new Validator().validateSpecContent(specName, p.rebuilt);
              if (!report.valid) {
                console.log(chalk.red(`\nValidation errors in rebuilt spec for ${specName} (will not write changes):`));
@@ -598,4 +603,4 @@ export class ArchiveCommand {
    // Returns date in YYYY-MM-DD format
    return new Date().toISOString().split('T')[0];
  }
-}
+}
@@ -17,8 +17,11 @@ export interface AIToolOption {
 }

 export const AI_TOOLS: AIToolOption[] = [
+  { name: 'Auggie (Augment CLI)', value: 'auggie', available: true, successLabel: 'Auggie' },
  { name: 'Claude Code', value: 'claude', available: true, successLabel: 'Claude Code' },
+  { name: 'Crush', value: 'crush', available: true, successLabel: 'Crush' },
  { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor' },
+  { name: 'Factory Droid', value: 'factory', available: true, successLabel: 'Factory Droid' },
  { name: 'OpenCode', value: 'opencode', available: true, successLabel: 'OpenCode' },
  { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code' },
  { name: 'Windsurf', value: 'windsurf', available: true, successLabel: 'Windsurf' },
@@ -0,0 +1,37 @@
+import { SlashCommandConfigurator } from './base.js';
+import { SlashCommandId } from '../../templates/index.js';
+
+const FILE_PATHS: Record<SlashCommandId, string> = {
+  proposal: '.augment/commands/openspec-proposal.md',
+  apply: '.augment/commands/openspec-apply.md',
+  archive: '.augment/commands/openspec-archive.md'
+};
+
+const FRONTMATTER: Record<SlashCommandId, string> = {
+  proposal: `---
+description: Scaffold a new OpenSpec change and validate strictly.
+argument-hint: feature description or request
+---`,
+  apply: `---
+description: Implement an approved OpenSpec change and keep tasks in sync.
+argument-hint: change-id
+---`,
+  archive: `---
+description: Archive a deployed OpenSpec change and update specs.
+argument-hint: change-id
+---`
+};
+
+export class AuggieSlashCommandConfigurator extends SlashCommandConfigurator {
+  readonly toolId = 'auggie';
+  readonly isAvailable = true;
+
+  protected getRelativePath(id: SlashCommandId): string {
+    return FILE_PATHS[id];
+  }
+
+  protected getFrontmatter(id: SlashCommandId): string {
+    return FRONTMATTER[id];
+  }
+}
+
@@ -26,7 +26,7 @@ export abstract class SlashCommandConfigurator {
    const createdOrUpdated: string[] = [];

    for (const target of this.getTargets()) {
-      const body = TemplateManager.getSlashCommandBody(target.id).trim();
+      const body = this.getBody(target.id);
      const filePath = FileSystemUtils.joinPath(projectPath, target.path);

      if (await FileSystemUtils.fileExists(filePath)) {
@@ -54,7 +54,7 @@ export abstract class SlashCommandConfigurator {
    for (const target of this.getTargets()) {
      const filePath = FileSystemUtils.joinPath(projectPath, target.path);
      if (await FileSystemUtils.fileExists(filePath)) {
-        const body = TemplateManager.getSlashCommandBody(target.id).trim();
+        const body = this.getBody(target.id);
        await this.updateBody(filePath, body);
        updated.push(target.path);
      }
@@ -66,6 +66,10 @@ export abstract class SlashCommandConfigurator {
  protected abstract getRelativePath(id: SlashCommandId): string;
  protected abstract getFrontmatter(id: SlashCommandId): string | undefined;

+  protected getBody(id: SlashCommandId): string {
+    return TemplateManager.getSlashCommandBody(id).trim();
+  }
+
  // Resolve absolute path for a given slash command target. Subclasses may override
  // to redirect to tool-specific locations (e.g., global directories).
  resolveAbsolutePath(projectPath: string, id: SlashCommandId): string {
@@ -0,0 +1,42 @@
+import { SlashCommandConfigurator } from './base.js';
+import { SlashCommandId } from '../../templates/index.js';
+
+const FILE_PATHS: Record<SlashCommandId, string> = {
+  proposal: '.crush/commands/openspec/proposal.md',
+  apply: '.crush/commands/openspec/apply.md',
+  archive: '.crush/commands/openspec/archive.md'
+};
+
+const FRONTMATTER: Record<SlashCommandId, string> = {
+  proposal: `---
+name: OpenSpec: Proposal
+description: Scaffold a new OpenSpec change and validate strictly.
+category: OpenSpec
+tags: [openspec, change]
+---`,
+  apply: `---
+name: OpenSpec: Apply
+description: Implement an approved OpenSpec change and keep tasks in sync.
+category: OpenSpec
+tags: [openspec, apply]
+---`,
+  archive: `---
+name: OpenSpec: Archive
+description: Archive a deployed OpenSpec change and update specs.
+category: OpenSpec
+tags: [openspec, archive]
+---`
+};
+
+export class CrushSlashCommandConfigurator extends SlashCommandConfigurator {
+  readonly toolId = 'crush';
+  readonly isAvailable = true;
+
+  protected getRelativePath(id: SlashCommandId): string {
+    return FILE_PATHS[id];
+  }
+
+  protected getFrontmatter(id: SlashCommandId): string {
+    return FRONTMATTER[id];
+  }
+}
@@ -0,0 +1,41 @@
+import { SlashCommandConfigurator } from './base.js';
+import { SlashCommandId } from '../../templates/index.js';
+
+const FILE_PATHS: Record<SlashCommandId, string> = {
+  proposal: '.factory/commands/openspec-proposal.md',
+  apply: '.factory/commands/openspec-apply.md',
+  archive: '.factory/commands/openspec-archive.md'
+};
+
+const FRONTMATTER: Record<SlashCommandId, string> = {
+  proposal: `---
+description: Scaffold a new OpenSpec change and validate strictly.
+argument-hint: request or feature description
+---`,
+  apply: `---
+description: Implement an approved OpenSpec change and keep tasks in sync.
+argument-hint: change-id
+---`,
+  archive: `---
+description: Archive a deployed OpenSpec change and update specs.
+argument-hint: change-id
+---`
+};
+
+export class FactorySlashCommandConfigurator extends SlashCommandConfigurator {
+  readonly toolId = 'factory';
+  readonly isAvailable = true;
+
+  protected getRelativePath(id: SlashCommandId): string {
+    return FILE_PATHS[id];
+  }
+
+  protected getFrontmatter(id: SlashCommandId): string {
+    return FRONTMATTER[id];
+  }
+
+  protected getBody(id: SlashCommandId): string {
+    const baseBody = super.getBody(id);
+    return `${baseBody}\n\n$ARGUMENTS`;
+  }
+}
@@ -1,5 +1,7 @@
 import { SlashCommandConfigurator } from "./base.js";
 import { SlashCommandId } from "../../templates/index.js";
+import { FileSystemUtils } from "../../../utils/file-system.js";
+import { OPENSPEC_MARKERS } from "../../config.js";

 const FILE_PATHS: Record<SlashCommandId, string> = {
  proposal: ".opencode/command/openspec-proposal.md",
@@ -24,7 +26,11 @@ description: Implement an approved OpenSpec change and keep tasks in sync.
  archive: `---
 agent: build
 description: Archive a deployed OpenSpec change and update specs.
---`,
+---
+<ChangeId>
+  $ARGUMENTS
+</ChangeId>
+`,
 };

 export class OpenCodeSlashCommandConfigurator extends SlashCommandConfigurator {
@@ -38,4 +44,38 @@ export class OpenCodeSlashCommandConfigurator extends SlashCommandConfigurator {
  protected getFrontmatter(id: SlashCommandId): string | undefined {
    return FRONTMATTER[id];
  }
+
+  async generateAll(projectPath: string, _openspecDir: string): Promise<string[]> {
+    const createdOrUpdated = await super.generateAll(projectPath, _openspecDir);
+    await this.rewriteArchiveFile(projectPath);
+    return createdOrUpdated;
+  }
+
+  async updateExisting(projectPath: string, _openspecDir: string): Promise<string[]> {
+    const updated = await super.updateExisting(projectPath, _openspecDir);
+    const rewroteArchive = await this.rewriteArchiveFile(projectPath);
+    if (rewroteArchive && !updated.includes(FILE_PATHS.archive)) {
+      updated.push(FILE_PATHS.archive);
+    }
+    return updated;
+  }
+
+  private async rewriteArchiveFile(projectPath: string): Promise<boolean> {
+    const archivePath = FileSystemUtils.joinPath(projectPath, FILE_PATHS.archive);
+    if (!await FileSystemUtils.fileExists(archivePath)) {
+      return false;
+    }
+
+    const body = this.getBody("archive");
+    const frontmatter = this.getFrontmatter("archive");
+    const sections: string[] = [];
+
+    if (frontmatter) {
+      sections.push(frontmatter.trim());
+    }
+
+    sections.push(`${OPENSPEC_MARKERS.start}\n${body}\n${OPENSPEC_MARKERS.end}`);
+    await FileSystemUtils.writeFile(archivePath, sections.join("\n") + "\n");
+    return true;
+  }
 }
@@ -7,6 +7,9 @@ import { OpenCodeSlashCommandConfigurator } from './opencode.js';
 import { CodexSlashCommandConfigurator } from './codex.js';
 import { GitHubCopilotSlashCommandConfigurator } from './github-copilot.js';
 import { AmazonQSlashCommandConfigurator } from './amazon-q.js';
+import { FactorySlashCommandConfigurator } from './factory.js';
+import { AuggieSlashCommandConfigurator } from './auggie.js';
+import { CrushSlashCommandConfigurator } from './crush.js';

 export class SlashCommandRegistry {
  private static configurators: Map<string, SlashCommandConfigurator> = new Map();
@@ -20,6 +23,9 @@ export class SlashCommandRegistry {
    const codex = new CodexSlashCommandConfigurator();
    const githubCopilot = new GitHubCopilotSlashCommandConfigurator();
    const amazonQ = new AmazonQSlashCommandConfigurator();
+    const factory = new FactorySlashCommandConfigurator();
+    const auggie = new AuggieSlashCommandConfigurator();
+    const crush = new CrushSlashCommandConfigurator();

    this.configurators.set(claude.toolId, claude);
    this.configurators.set(cursor.toolId, cursor);
@@ -29,6 +35,9 @@ export class SlashCommandRegistry {
    this.configurators.set(codex.toolId, codex);
    this.configurators.set(githubCopilot.toolId, githubCopilot);
    this.configurators.set(amazonQ.toolId, amazonQ);
+    this.configurators.set(factory.toolId, factory);
+    this.configurators.set(auggie.toolId, auggie);
+    this.configurators.set(crush.toolId, crush);
  }

  static register(configurator: SlashCommandConfigurator): void {
@@ -101,6 +101,12 @@ export interface DeltaPlan {
  modified: RequirementBlock[];
  removed: string[]; // requirement names
  renamed: Array<{ from: string; to: string }>;
+  sectionPresence: {
+    added: boolean;
+    modified: boolean;
+    removed: boolean;
+    renamed: boolean;
+  };
 }

 function normalizeLineEndings(content: string): string {
@@ -113,11 +119,26 @@ function normalizeLineEndings(content: string): string {
 export function parseDeltaSpec(content: string): DeltaPlan {
  const normalized = normalizeLineEndings(content);
  const sections = splitTopLevelSections(normalized);
-  const added = parseRequirementBlocksFromSection(sections['ADDED Requirements'] || '');
-  const modified = parseRequirementBlocksFromSection(sections['MODIFIED Requirements'] || '');
-  const removedNames = parseRemovedNames(sections['REMOVED Requirements'] || '');
-  const renamedPairs = parseRenamedPairs(sections['RENAMED Requirements'] || '');
-  return { added, modified, removed: removedNames, renamed: renamedPairs };
+  const addedLookup = getSectionCaseInsensitive(sections, 'ADDED Requirements');
+  const modifiedLookup = getSectionCaseInsensitive(sections, 'MODIFIED Requirements');
+  const removedLookup = getSectionCaseInsensitive(sections, 'REMOVED Requirements');
+  const renamedLookup = getSectionCaseInsensitive(sections, 'RENAMED Requirements');
+  const added = parseRequirementBlocksFromSection(addedLookup.body);
+  const modified = parseRequirementBlocksFromSection(modifiedLookup.body);
+  const removedNames = parseRemovedNames(removedLookup.body);
+  const renamedPairs = parseRenamedPairs(renamedLookup.body);
+  return {
+    added,
+    modified,
+    removed: removedNames,
+    renamed: renamedPairs,
+    sectionPresence: {
+      added: addedLookup.found,
+      modified: modifiedLookup.found,
+      removed: removedLookup.found,
+      renamed: renamedLookup.found,
+    },
+  };
 }

 function splitTopLevelSections(content: string): Record<string, string> {
@@ -140,6 +161,14 @@ function splitTopLevelSections(content: string): Record<string, string> {
  return result;
 }

+function getSectionCaseInsensitive(sections: Record<string, string>, desired: string): { body: string; found: boolean } {
+  const target = desired.toLowerCase();
+  for (const [title, body] of Object.entries(sections)) {
+    if (title.toLowerCase() === target) return { body, found: true };
+  }
+  return { body: '', found: false };
+}
+
 function parseRequirementBlocksFromSection(sectionBody: string): RequirementBlock[] {
  if (!sectionBody) return [];
  const lines = normalizeLineEndings(sectionBody).split('\n');
@@ -203,5 +232,3 @@ function parseRenamedPairs(sectionBody: string): Array<{ from: string; to: strin
  }
  return pairs;
 }
-
-
@@ -60,7 +60,7 @@ Track these steps as TODOs and complete them one by one.
 After deployment, create separate PR to:
 - Move \`changes/[name]/\` → \`changes/archive/YYYY-MM-DD-[name]/\`
 - Update \`specs/\` if capabilities changed
- Use \`openspec archive [change] --skip-specs --yes\` for tooling-only changes
+- Use \`openspec archive <change-id> --skip-specs --yes\` for tooling-only changes (always pass the change ID explicitly)
 - Run \`openspec validate --strict\` to confirm the archived change passes checks

 ## Before Any Task
@@ -97,7 +97,7 @@ openspec list --specs          # List specifications
 openspec show [item]           # Display change or spec
 openspec diff [change]         # Show spec differences
 openspec validate [item]       # Validate changes or specs
-openspec archive [change] [--yes|-y]      # Archive after deployment (add --yes for non-interactive runs)
+openspec archive <change-id> [--yes|-y]   # Archive after deployment (add --yes for non-interactive runs)

 # Project management
 openspec init [path]           # Initialize OpenSpec
@@ -450,7 +450,7 @@ openspec list              # What's in progress?
 openspec show [item]       # View details
 openspec diff [change]     # What's changing?
 openspec validate --strict # Is it correct?
-openspec archive [change] [--yes|-y]  # Mark complete (add --yes for automation)
+openspec archive <change-id> [--yes|-y]  # Mark complete (add --yes for automation)
 \`\`\`

 Remember: Specs are truth. Changes are proposals. Keep them in sync.
@@ -33,12 +33,18 @@ const applyReferences = `**Reference**
 - Use \`openspec show <id> --json --deltas-only\` if you need additional context from the proposal while implementing.`;

 const archiveSteps = `**Steps**
-1. Identify the requested change ID (via the prompt or \`openspec list\`).
-2. Run \`openspec archive <id> --yes\` to let the CLI move the change and apply spec updates without prompts (use \`--skip-specs\` only for tooling-only work).
-3. Review the command output to confirm the target specs were updated and the change landed in \`changes/archive/\`.
-4. Validate with \`openspec validate --strict\` and inspect with \`openspec show <id>\` if anything looks off.`;
+1. Determine the change ID to archive:
+   - If this prompt already includes a specific change ID (for example inside a \`<ChangeId>\` block populated by slash-command arguments), use that value after trimming whitespace.
+   - If the conversation references a change loosely (for example by title or summary), run \`openspec list\` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
+   - Otherwise, review the conversation, run \`openspec list\`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
+   - If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
+2. Validate the change ID by running \`openspec list\` (or \`openspec show <id>\`) and stop if the change is missing, already archived, or otherwise not ready to archive.
+3. Run \`openspec archive <id> --yes\` so the CLI moves the change and applies spec updates without prompts (use \`--skip-specs\` only for tooling-only work).
+4. Review the command output to confirm the target specs were updated and the change landed in \`changes/archive/\`.
+5. Validate with \`openspec validate --strict\` and inspect with \`openspec show <id>\` if anything looks off.`;

 const archiveReferences = `**Reference**
+- Use \`openspec list\` to confirm change IDs before archiving.
 - Inspect refreshed specs with \`openspec list --specs\` and address any validation issues before handing off.`;

 export const slashCommandBodies: Record<SlashCommandId, string> = {
@@ -114,6 +114,8 @@ export class Validator {
    const issues: ValidationIssue[] = [];
    const specsDir = path.join(changeDir, 'specs');
    let totalDeltas = 0;
+    const missingHeaderSpecs: string[] = [];
+    const emptySectionSpecs: Array<{ path: string; sections: string[] }> = [];

    try {
      const entries = await fs.readdir(specsDir, { withFileTypes: true });
@@ -130,6 +132,17 @@ export class Validator {

        const plan = parseDeltaSpec(content);
        const entryPath = `${specName}/spec.md`;
+        const sectionNames: string[] = [];
+        if (plan.sectionPresence.added) sectionNames.push('## ADDED Requirements');
+        if (plan.sectionPresence.modified) sectionNames.push('## MODIFIED Requirements');
+        if (plan.sectionPresence.removed) sectionNames.push('## REMOVED Requirements');
+        if (plan.sectionPresence.renamed) sectionNames.push('## RENAMED Requirements');
+        const hasSections = sectionNames.length > 0;
+        const hasEntries = plan.added.length + plan.modified.length + plan.removed.length + plan.renamed.length > 0;
+        if (!hasEntries) {
+          if (hasSections) emptySectionSpecs.push({ path: entryPath, sections: sectionNames });
+          else missingHeaderSpecs.push(entryPath);
+        }

        const addedNames = new Set<string>();
        const modifiedNames = new Set<string>();
@@ -236,6 +249,21 @@ export class Validator {
      // If no specs dir, treat as no deltas
    }

+    for (const { path: specPath, sections } of emptySectionSpecs) {
+      issues.push({
+        level: 'ERROR',
+        path: specPath,
+        message: `Delta sections ${this.formatSectionList(sections)} were found, but no requirement entries parsed. Ensure each section includes at least one "### Requirement:" block (REMOVED may use bullet list syntax).`,
+      });
+    }
+    for (const path of missingHeaderSpecs) {
+      issues.push({
+        level: 'ERROR',
+        path,
+        message: 'No delta sections found. Add headers such as "## ADDED Requirements" or move non-delta notes outside specs/.',
+      });
+    }
+
    if (totalDeltas === 0) {
      issues.push({ level: 'ERROR', path: 'file', message: this.enrichTopLevelError('change', VALIDATION_MESSAGES.CHANGE_NO_DELTAS) });
    }
@@ -375,16 +403,30 @@ export class Validator {

  private extractRequirementText(blockRaw: string): string | undefined {
    const lines = blockRaw.split('\n');
-    // Skip header
+    // Skip header line (index 0)
    let i = 1;
-    const bodyLines: string[] = [];
+
+    // Find the first substantial text line, skipping metadata and blank lines
    for (; i < lines.length; i++) {
      const line = lines[i];
-      if (/^####\s+/.test(line)) break; // scenarios start
-      bodyLines.push(line);
+
+      // Stop at scenario headers
+      if (/^####\s+/.test(line)) break;
+
+      const trimmed = line.trim();
+
+      // Skip blank lines
+      if (trimmed.length === 0) continue;
+
+      // Skip metadata lines (lines starting with ** like **ID**, **Priority**, etc.)
+      if (/^\*\*[^*]+\*\*:/.test(trimmed)) continue;
+
+      // Found first non-metadata, non-blank line - this is the requirement text
+      return trimmed;
    }
-    const text = bodyLines.join('\n').split('\n').map(l => l.trim()).find(l => l.length > 0);
-    return text;
+
+    // No requirement text found
+    return undefined;
  }

  private containsShallOrMust(text: string): boolean {
@@ -395,4 +437,12 @@ export class Validator {
    const matches = blockRaw.match(/^####\s+/gm);
    return matches ? matches.length : 0;
  }
+
+  private formatSectionList(sections: string[]): string {
+    if (sections.length === 0) return '';
+    if (sections.length === 1) return sections[0];
+    const head = sections.slice(0, -1);
+    const last = sections[sections.length - 1];
+    return `${head.join(', ')} and ${last}`;
+  }
 }
@@ -84,7 +84,11 @@ describe('openspec CLI e2e basics', () => {
      const emptyProjectDir = path.join(projectDir, '..', 'empty-project');
      await fs.mkdir(emptyProjectDir, { recursive: true });

-      const result = await runCLI(['init', '--tools', 'all'], { cwd: emptyProjectDir });
+      const codexHome = path.join(emptyProjectDir, '.codex');
+      const result = await runCLI(['init', '--tools', 'all'], {
+        cwd: emptyProjectDir,
+        env: { CODEX_HOME: codexHome },
+      });
      expect(result.exitCode).toBe(0);
      expect(result.stdout).toContain('Tool summary:');

@@ -1,5 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { ArchiveCommand } from '../../src/core/archive.js';
+import { Validator } from '../../src/core/validation/validator.js';
 import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
@@ -215,6 +216,46 @@ Then expected result happens`;
      expect(archives[0]).toMatch(new RegExp(`\\d{4}-\\d{2}-\\d{2}-${changeName}`));
    });

+    it('should skip validation when commander sets validate to false (--no-validate)', async () => {
+      const changeName = 'skip-validation-flag';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      const changeSpecDir = path.join(changeDir, 'specs', 'unstable-capability');
+      await fs.mkdir(changeSpecDir, { recursive: true });
+
+      const deltaSpec = `# Unstable Capability
+
+## ADDED Requirements
+
+### Requirement: Logging Feature
+**ID**: REQ-LOG-001
+
+The system will log all events.
+
+#### Scenario: Event recorded
+- **WHEN** an event occurs
+- **THEN** it is captured`;
+      await fs.writeFile(path.join(changeSpecDir, 'spec.md'), deltaSpec);
+      await fs.writeFile(path.join(changeDir, 'tasks.md'), '- [x] Task 1\n');
+
+      const deltaSpy = vi.spyOn(Validator.prototype, 'validateChangeDeltaSpecs');
+      const specContentSpy = vi.spyOn(Validator.prototype, 'validateSpecContent');
+
+      try {
+        await archiveCommand.execute(changeName, { yes: true, skipSpecs: true, validate: false });
+
+        expect(deltaSpy).not.toHaveBeenCalled();
+        expect(specContentSpy).not.toHaveBeenCalled();
+
+        const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+        const archives = await fs.readdir(archiveDir);
+        expect(archives.length).toBe(1);
+        expect(archives[0]).toMatch(new RegExp(`\\d{4}-\\d{2}-\\d{2}-${changeName}`));
+      } finally {
+        deltaSpy.mockRestore();
+        specContentSpy.mockRestore();
+      }
+    });
+
    it('should proceed with archive when user declines spec updates', async () => {
      const { confirm } = await import('@inquirer/prompts');
      const mockConfirm = confirm as unknown as ReturnType<typeof vi.fn>;
@@ -636,4 +677,4 @@ E1 updated`);
      await expect(fs.access(changeDir)).resolves.not.toThrow();
    });
  });
-});
+});
@@ -316,6 +316,59 @@ describe('InitCommand', () => {
      expect(archiveContent).toContain('openspec list --specs');
    });

+    it('should create Factory slash command files with templates', async () => {
+      queueSelections('factory', DONE);
+
+      await initCommand.execute(testDir);
+
+      const factoryProposal = path.join(
+        testDir,
+        '.factory/commands/openspec-proposal.md'
+      );
+      const factoryApply = path.join(
+        testDir,
+        '.factory/commands/openspec-apply.md'
+      );
+      const factoryArchive = path.join(
+        testDir,
+        '.factory/commands/openspec-archive.md'
+      );
+
+      expect(await fileExists(factoryProposal)).toBe(true);
+      expect(await fileExists(factoryApply)).toBe(true);
+      expect(await fileExists(factoryArchive)).toBe(true);
+
+      const proposalContent = await fs.readFile(factoryProposal, 'utf-8');
+      expect(proposalContent).toContain('description: Scaffold a new OpenSpec change and validate strictly.');
+      expect(proposalContent).toContain('argument-hint: request or feature description');
+      expect(proposalContent).toContain('<!-- OPENSPEC:START -->');
+      expect(
+        /<!-- OPENSPEC:START -->([\s\S]*?)<!-- OPENSPEC:END -->/u.exec(
+          proposalContent
+        )?.[1]
+      ).toContain('$ARGUMENTS');
+
+      const applyContent = await fs.readFile(factoryApply, 'utf-8');
+      expect(applyContent).toContain('description: Implement an approved OpenSpec change and keep tasks in sync.');
+      expect(applyContent).toContain('argument-hint: change-id');
+      expect(applyContent).toContain('Work through tasks sequentially');
+      expect(
+        /<!-- OPENSPEC:START -->([\s\S]*?)<!-- OPENSPEC:END -->/u.exec(
+          applyContent
+        )?.[1]
+      ).toContain('$ARGUMENTS');
+
+      const archiveContent = await fs.readFile(factoryArchive, 'utf-8');
+      expect(archiveContent).toContain('description: Archive a deployed OpenSpec change and update specs.');
+      expect(archiveContent).toContain('argument-hint: change-id');
+      expect(archiveContent).toContain('openspec archive <id> --yes');
+      expect(
+        /<!-- OPENSPEC:START -->([\s\S]*?)<!-- OPENSPEC:END -->/u.exec(
+          archiveContent
+        )?.[1]
+      ).toContain('$ARGUMENTS');
+    });
+
    it('should create Codex prompts with templates and placeholders', async () => {
      queueSelections('codex', DONE);

@@ -559,6 +612,18 @@ describe('InitCommand', () => {
      expect(codexChoice.configured).toBe(true);
    });

+    it('should mark Factory Droid as already configured during extend mode', async () => {
+      queueSelections('factory', DONE, 'factory', DONE);
+      await initCommand.execute(testDir);
+      await initCommand.execute(testDir);
+
+      const secondRunArgs = mockPrompt.mock.calls[1][0];
+      const factoryChoice = secondRunArgs.choices.find(
+        (choice: any) => choice.value === 'factory'
+      );
+      expect(factoryChoice.configured).toBe(true);
+    });
+
    it('should mark GitHub Copilot as already configured during extend mode', async () => {
      queueSelections('github-copilot', DONE, 'github-copilot', DONE);
      await initCommand.execute(testDir);
@@ -618,6 +683,120 @@ describe('InitCommand', () => {
      );
      expect(amazonQChoice.configured).toBe(true);
    });
+
+    it('should create Auggie slash command files with templates', async () => {
+      queueSelections('auggie', DONE);
+
+      await initCommand.execute(testDir);
+
+      const auggieProposal = path.join(
+        testDir,
+        '.augment/commands/openspec-proposal.md'
+      );
+      const auggieApply = path.join(
+        testDir,
+        '.augment/commands/openspec-apply.md'
+      );
+      const auggieArchive = path.join(
+        testDir,
+        '.augment/commands/openspec-archive.md'
+      );
+
+      expect(await fileExists(auggieProposal)).toBe(true);
+      expect(await fileExists(auggieApply)).toBe(true);
+      expect(await fileExists(auggieArchive)).toBe(true);
+
+      const proposalContent = await fs.readFile(auggieProposal, 'utf-8');
+      expect(proposalContent).toContain('---');
+      expect(proposalContent).toContain('description: Scaffold a new OpenSpec change and validate strictly.');
+      expect(proposalContent).toContain('argument-hint: feature description or request');
+      expect(proposalContent).toContain('<!-- OPENSPEC:START -->');
+      expect(proposalContent).toContain('**Guardrails**');
+
+      const applyContent = await fs.readFile(auggieApply, 'utf-8');
+      expect(applyContent).toContain('---');
+      expect(applyContent).toContain('description: Implement an approved OpenSpec change and keep tasks in sync.');
+      expect(applyContent).toContain('argument-hint: change-id');
+      expect(applyContent).toContain('Work through tasks sequentially');
+
+      const archiveContent = await fs.readFile(auggieArchive, 'utf-8');
+      expect(archiveContent).toContain('---');
+      expect(archiveContent).toContain('description: Archive a deployed OpenSpec change and update specs.');
+      expect(archiveContent).toContain('argument-hint: change-id');
+      expect(archiveContent).toContain('openspec archive <id> --yes');
+    });
+
+    it('should mark Auggie as already configured during extend mode', async () => {
+      queueSelections('auggie', DONE, 'auggie', DONE);
+      await initCommand.execute(testDir);
+      await initCommand.execute(testDir);
+
+      const secondRunArgs = mockPrompt.mock.calls[1][0];
+      const auggieChoice = secondRunArgs.choices.find(
+        (choice: any) => choice.value === 'auggie'
+      );
+      expect(auggieChoice.configured).toBe(true);
+    });
+
+    it('should create Crush slash command files with templates', async () => {
+      queueSelections('crush', DONE);
+
+      await initCommand.execute(testDir);
+
+      const crushProposal = path.join(
+        testDir,
+        '.crush/commands/openspec/proposal.md'
+      );
+      const crushApply = path.join(
+        testDir,
+        '.crush/commands/openspec/apply.md'
+      );
+      const crushArchive = path.join(
+        testDir,
+        '.crush/commands/openspec/archive.md'
+      );
+
+      expect(await fileExists(crushProposal)).toBe(true);
+      expect(await fileExists(crushApply)).toBe(true);
+      expect(await fileExists(crushArchive)).toBe(true);
+
+      const proposalContent = await fs.readFile(crushProposal, 'utf-8');
+      expect(proposalContent).toContain('---');
+      expect(proposalContent).toContain('name: OpenSpec: Proposal');
+      expect(proposalContent).toContain('description: Scaffold a new OpenSpec change and validate strictly.');
+      expect(proposalContent).toContain('category: OpenSpec');
+      expect(proposalContent).toContain('tags: [openspec, change]');
+      expect(proposalContent).toContain('<!-- OPENSPEC:START -->');
+      expect(proposalContent).toContain('**Guardrails**');
+
+      const applyContent = await fs.readFile(crushApply, 'utf-8');
+      expect(applyContent).toContain('---');
+      expect(applyContent).toContain('name: OpenSpec: Apply');
+      expect(applyContent).toContain('description: Implement an approved OpenSpec change and keep tasks in sync.');
+      expect(applyContent).toContain('category: OpenSpec');
+      expect(applyContent).toContain('tags: [openspec, apply]');
+      expect(applyContent).toContain('Work through tasks sequentially');
+
+      const archiveContent = await fs.readFile(crushArchive, 'utf-8');
+      expect(archiveContent).toContain('---');
+      expect(archiveContent).toContain('name: OpenSpec: Archive');
+      expect(archiveContent).toContain('description: Archive a deployed OpenSpec change and update specs.');
+      expect(archiveContent).toContain('category: OpenSpec');
+      expect(archiveContent).toContain('tags: [openspec, archive]');
+      expect(archiveContent).toContain('openspec archive <id> --yes');
+    });
+
+    it('should mark Crush as already configured during extend mode', async () => {
+      queueSelections('crush', DONE, 'crush', DONE);
+      await initCommand.execute(testDir);
+      await initCommand.execute(testDir);
+
+      const secondRunArgs = mockPrompt.mock.calls[1][0];
+      const crushChoice = secondRunArgs.choices.find(
+        (choice: any) => choice.value === 'crush'
+      );
+      expect(crushChoice.configured).toBe(true);
+    });
  });

  describe('non-interactive mode', () => {
@@ -377,6 +377,76 @@ Old body
    await expect(FileSystemUtils.fileExists(ghArchive)).resolves.toBe(false);
  });

+  it('should refresh existing Factory slash commands', async () => {
+    const factoryPath = path.join(
+      testDir,
+      '.factory/commands/openspec-proposal.md'
+    );
+    await fs.mkdir(path.dirname(factoryPath), { recursive: true });
+    const initialContent = `---
+description: Scaffold a new OpenSpec change and validate strictly.
+argument-hint: request or feature description
+---
+
+<!-- OPENSPEC:START -->
+Old body
+<!-- OPENSPEC:END -->`;
+    await fs.writeFile(factoryPath, initialContent);
+
+    const consoleSpy = vi.spyOn(console, 'log');
+
+    await updateCommand.execute(testDir);
+
+    const updated = await fs.readFile(factoryPath, 'utf-8');
+    expect(updated).toContain('description: Scaffold a new OpenSpec change and validate strictly.');
+    expect(updated).toContain('argument-hint: request or feature description');
+    expect(
+      /<!-- OPENSPEC:START -->([\s\S]*?)<!-- OPENSPEC:END -->/u.exec(updated)?.[1]
+    ).toContain('$ARGUMENTS');
+    expect(updated).toContain('**Guardrails**');
+    expect(updated).not.toContain('Old body');
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('.factory/commands/openspec-proposal.md')
+    );
+
+    consoleSpy.mockRestore();
+  });
+
+  it('should not create missing Factory slash command files on update', async () => {
+    const factoryApply = path.join(
+      testDir,
+      '.factory/commands/openspec-apply.md'
+    );
+
+    await fs.mkdir(path.dirname(factoryApply), { recursive: true });
+    await fs.writeFile(
+      factoryApply,
+      `---
+description: Old
+argument-hint: old
+---
+
+<!-- OPENSPEC:START -->
+Old body
+<!-- OPENSPEC:END -->`
+    );
+
+    await updateCommand.execute(testDir);
+
+    const factoryProposal = path.join(
+      testDir,
+      '.factory/commands/openspec-proposal.md'
+    );
+    const factoryArchive = path.join(
+      testDir,
+      '.factory/commands/openspec-archive.md'
+    );
+
+    await expect(FileSystemUtils.fileExists(factoryProposal)).resolves.toBe(false);
+    await expect(FileSystemUtils.fileExists(factoryArchive)).resolves.toBe(false);
+  });
+
  it('should refresh existing Amazon Q Developer prompts', async () => {
    const aqPath = path.join(
      testDir,
@@ -443,6 +513,145 @@ Old body
    await expect(FileSystemUtils.fileExists(aqArchive)).resolves.toBe(false);
  });

+  it('should refresh existing Auggie slash command files', async () => {
+    const auggiePath = path.join(
+      testDir,
+      '.augment/commands/openspec-apply.md'
+    );
+    await fs.mkdir(path.dirname(auggiePath), { recursive: true });
+    const initialContent = `---
+description: Implement an approved OpenSpec change and keep tasks in sync.
+argument-hint: change-id
+---
+<!-- OPENSPEC:START -->
+Old body
+<!-- OPENSPEC:END -->`;
+    await fs.writeFile(auggiePath, initialContent);
+
+    const consoleSpy = vi.spyOn(console, 'log');
+
+    await updateCommand.execute(testDir);
+
+    const updatedContent = await fs.readFile(auggiePath, 'utf-8');
+    expect(updatedContent).toContain('**Guardrails**');
+    expect(updatedContent).toContain('<!-- OPENSPEC:START -->');
+    expect(updatedContent).toContain('<!-- OPENSPEC:END -->');
+    expect(updatedContent).not.toContain('Old body');
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('.augment/commands/openspec-apply.md')
+    );
+
+    consoleSpy.mockRestore();
+  });
+
+  it('should not create missing Auggie slash command files on update', async () => {
+    const auggieApply = path.join(
+      testDir,
+      '.augment/commands/openspec-apply.md'
+    );
+
+    // Only create apply; leave proposal and archive missing
+    await fs.mkdir(path.dirname(auggieApply), { recursive: true });
+    await fs.writeFile(
+      auggieApply,
+      '---\ndescription: Old\nargument-hint: old\n---\n<!-- OPENSPEC:START -->\nOld\n<!-- OPENSPEC:END -->'
+    );
+
+    await updateCommand.execute(testDir);
+
+    const auggieProposal = path.join(
+      testDir,
+      '.augment/commands/openspec-proposal.md'
+    );
+    const auggieArchive = path.join(
+      testDir,
+      '.augment/commands/openspec-archive.md'
+    );
+
+    // Confirm they weren't created by update
+    await expect(FileSystemUtils.fileExists(auggieProposal)).resolves.toBe(false);
+    await expect(FileSystemUtils.fileExists(auggieArchive)).resolves.toBe(false);
+  });
+
+  it('should refresh existing Crush slash command files', async () => {
+    const crushPath = path.join(
+      testDir,
+      '.crush/commands/openspec/proposal.md'
+    );
+    await fs.mkdir(path.dirname(crushPath), { recursive: true });
+    const initialContent = `---
+name: OpenSpec: Proposal
+description: Old description
+category: OpenSpec
+tags: [openspec, change]
+---
+<!-- OPENSPEC:START -->
+Old slash content
+<!-- OPENSPEC:END -->`;
+    await fs.writeFile(crushPath, initialContent);
+
+    const consoleSpy = vi.spyOn(console, 'log');
+
+    await updateCommand.execute(testDir);
+
+    const updated = await fs.readFile(crushPath, 'utf-8');
+    expect(updated).toContain('name: OpenSpec: Proposal');
+    expect(updated).toContain('**Guardrails**');
+    expect(updated).toContain(
+      'Validate with `openspec validate <id> --strict`'
+    );
+    expect(updated).not.toContain('Old slash content');
+
+    const [logMessage] = consoleSpy.mock.calls[0];
+    expect(logMessage).toContain(
+      'Updated OpenSpec instructions (openspec/AGENTS.md'
+    );
+    expect(logMessage).toContain('AGENTS.md (created)');
+    expect(logMessage).toContain(
+      'Updated slash commands: .crush/commands/openspec/proposal.md'
+    );
+
+    consoleSpy.mockRestore();
+  });
+
+  it('should not create missing Crush slash command files on update', async () => {
+    const crushApply = path.join(
+      testDir,
+      '.crush/commands/openspec-apply.md'
+    );
+
+    // Only create apply; leave proposal and archive missing
+    await fs.mkdir(path.dirname(crushApply), { recursive: true });
+    await fs.writeFile(
+      crushApply,
+      `---
+name: OpenSpec: Apply
+description: Old description
+category: OpenSpec
+tags: [openspec, apply]
+---
+<!-- OPENSPEC:START -->
+Old body
+<!-- OPENSPEC:END -->`
+    );
+
+    await updateCommand.execute(testDir);
+
+    const crushProposal = path.join(
+      testDir,
+      '.crush/commands/openspec-proposal.md'
+    );
+    const crushArchive = path.join(
+      testDir,
+      '.crush/commands/openspec-archive.md'
+    );
+
+    // Confirm they weren't created by update
+    await expect(FileSystemUtils.fileExists(crushProposal)).resolves.toBe(false);
+    await expect(FileSystemUtils.fileExists(crushArchive)).resolves.toBe(false);
+  });
+
  it('should preserve Windsurf content outside markers during update', async () => {
    const wsPath = path.join(
      testDir,
@@ -306,10 +306,10 @@ Then result`;

      const specPath = path.join(testDir, 'spec.md');
      await fs.writeFile(specPath, specContent);
-      
+
      const validator = new Validator(true); // strict mode
      const report = await validator.validateSpec(specPath);
-      
+
      expect(report.valid).toBe(false); // Should fail due to brief overview warning
    });

@@ -330,12 +330,160 @@ Then result`;

      const specPath = path.join(testDir, 'spec.md');
      await fs.writeFile(specPath, specContent);
-      
+
      const validator = new Validator(false); // non-strict mode
      const report = await validator.validateSpec(specPath);
-      
+
      expect(report.valid).toBe(true); // Should pass despite warnings
      expect(report.summary.warnings).toBeGreaterThan(0);
    });
  });
-});
+
+  describe('validateChangeDeltaSpecs with metadata', () => {
+    it('should validate requirement with metadata before SHALL/MUST text', async () => {
+      const changeDir = path.join(testDir, 'test-change');
+      const specsDir = path.join(changeDir, 'specs', 'test-spec');
+      await fs.mkdir(specsDir, { recursive: true });
+
+      const deltaSpec = `# Test Spec
+
+## ADDED Requirements
+
+### Requirement: Circuit Breaker State Management SHALL be implemented
+**ID**: REQ-CB-001
+**Priority**: P1 (High)
+
+The system MUST implement a circuit breaker with three states.
+
+#### Scenario: Normal operation
+**Given** the circuit breaker is in CLOSED state
+**When** a request is made
+**Then** the request is executed normally`;
+
+      const specPath = path.join(specsDir, 'spec.md');
+      await fs.writeFile(specPath, deltaSpec);
+
+      const validator = new Validator(true);
+      const report = await validator.validateChangeDeltaSpecs(changeDir);
+
+      expect(report.valid).toBe(true);
+      expect(report.summary.errors).toBe(0);
+    });
+
+    it('should validate requirement with SHALL in text but not in header', async () => {
+      const changeDir = path.join(testDir, 'test-change-2');
+      const specsDir = path.join(changeDir, 'specs', 'test-spec');
+      await fs.mkdir(specsDir, { recursive: true });
+
+      const deltaSpec = `# Test Spec
+
+## ADDED Requirements
+
+### Requirement: Error Handling
+**ID**: REQ-ERR-001
+**Priority**: P2
+
+The system SHALL handle all errors gracefully.
+
+#### Scenario: Error occurs
+**Given** an error condition
+**When** an error occurs
+**Then** the error is logged and user is notified`;
+
+      const specPath = path.join(specsDir, 'spec.md');
+      await fs.writeFile(specPath, deltaSpec);
+
+      const validator = new Validator(true);
+      const report = await validator.validateChangeDeltaSpecs(changeDir);
+
+      expect(report.valid).toBe(true);
+      expect(report.summary.errors).toBe(0);
+    });
+
+    it('should fail when requirement text lacks SHALL/MUST', async () => {
+      const changeDir = path.join(testDir, 'test-change-3');
+      const specsDir = path.join(changeDir, 'specs', 'test-spec');
+      await fs.mkdir(specsDir, { recursive: true });
+
+      const deltaSpec = `# Test Spec
+
+## ADDED Requirements
+
+### Requirement: Logging Feature
+**ID**: REQ-LOG-001
+
+The system will log all events.
+
+#### Scenario: Event occurs
+**Given** an event
+**When** it occurs
+**Then** it is logged`;
+
+      const specPath = path.join(specsDir, 'spec.md');
+      await fs.writeFile(specPath, deltaSpec);
+
+      const validator = new Validator(true);
+      const report = await validator.validateChangeDeltaSpecs(changeDir);
+
+      expect(report.valid).toBe(false);
+      expect(report.summary.errors).toBeGreaterThan(0);
+      expect(report.issues.some(i => i.message.includes('must contain SHALL or MUST'))).toBe(true);
+    });
+
+    it('should handle requirements without metadata fields', async () => {
+      const changeDir = path.join(testDir, 'test-change-4');
+      const specsDir = path.join(changeDir, 'specs', 'test-spec');
+      await fs.mkdir(specsDir, { recursive: true });
+
+      const deltaSpec = `# Test Spec
+
+## ADDED Requirements
+
+### Requirement: Simple Feature
+The system SHALL implement this feature.
+
+#### Scenario: Basic usage
+**Given** a condition
+**When** an action occurs
+**Then** a result happens`;
+
+      const specPath = path.join(specsDir, 'spec.md');
+      await fs.writeFile(specPath, deltaSpec);
+
+      const validator = new Validator(true);
+      const report = await validator.validateChangeDeltaSpecs(changeDir);
+
+      expect(report.valid).toBe(true);
+      expect(report.summary.errors).toBe(0);
+    });
+
+    it('should treat delta headers case-insensitively', async () => {
+      const changeDir = path.join(testDir, 'test-change-mixed-case');
+      const specsDir = path.join(changeDir, 'specs', 'test-spec');
+      await fs.mkdir(specsDir, { recursive: true });
+
+      const deltaSpec = `# Test Spec
+
+## Added Requirements
+
+### Requirement: Mixed Case Handling
+The system MUST support mixed case delta headers.
+
+#### Scenario: Case insensitive parsing
+**Given** a delta file with mixed case headers
+**When** validation runs
+**Then** the delta is detected`;
+
+      const specPath = path.join(specsDir, 'spec.md');
+      await fs.writeFile(specPath, deltaSpec);
+
+      const validator = new Validator(true);
+      const report = await validator.validateChangeDeltaSpecs(changeDir);
+
+      expect(report.valid).toBe(true);
+      expect(report.summary.errors).toBe(0);
+      expect(report.summary.warnings).toBe(0);
+      expect(report.summary.info).toBe(0);
+    });
+  });
+});
Author	SHA1	Message	Date
Tabish Bidiwale	76f4f4c9dc	Merge branch 'main' into fix-validation	2025-10-19 23:47:07 +11:00
HariKrishnanandClaude	822464ec44	chore(dev): add VS Code dev container configuration (#209 ) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>	2025-10-19 21:50:50 +11:00
Gianluca BoianoandCrush	67ab683105	feat: add Crush AI assistant support (#206 ) Add comprehensive OpenSpec integration for Crush AI assistant including: - CrushSlashCommandConfigurator for proposal, apply, and archive commands - Integration with slash command registry and CLI tools - Generates .crush/commands/openspec/ with proper frontmatter and workflows - Available via `openspec init --tools crush` 💘 Generated with Crush Co-authored-by: Crush <crush@charm.land>	2025-10-19 11:55:36 +11:00
Vimpas	f82e243551	feat: add Auggie (Augment CLI) support to configuration and documenta… (#196 ) * feat: add Auggie (Augment CLI) support to configuration and documentation - Added Auggie (Augment CLI) to the AI tools configuration in `config.ts`. - Updated the slash command registry to include Auggie's configurator. - Documented Auggie's commands in the README.md for better visibility. This enhances the integration of Auggie within the existing toolset. * test: add tests for Auggie command file creation and updates - Implemented tests to verify the creation of Auggie slash command files with appropriate templates. - Added checks to ensure existing Auggie command files are refreshed correctly during updates. - Confirmed that missing command files are not created during the update process. These changes enhance the test coverage for Auggie's integration and ensure proper functionality of command file management.	2025-10-17 14:01:28 +11:00
Tabish Bidiwale	2fec61e69c	fix: improve delta spec validation with case-insensitive headers and empty section detection This commit enhances the validation logic for delta specs: - Delta section headers are now parsed case-insensitively (e.g., "Added Requirements" and "ADDED Requirements" both work) - Empty delta sections now produce clear error messages guiding users to add requirement entries - Specs with no delta headers at all now receive specific error messages - Added test coverage for case-insensitive delta header parsing	2025-10-16 18:07:51 +11:00
Tabish Bidiwale	88b260d51f	fix: honor --no-validate and ignore metadata during archive validation (#190 ) * fix: skip metadata when validating requirement SHALL/MUST keywords Fixes validation incorrectly checking metadata lines instead of requirement text. The extractRequirementText() function was returning the first non-empty line after the requirement header, which was often metadata like ID: REQ-001 instead of the actual requirement statement. Changes: - Updated extractRequirementText() to skip lines matching Key: Value pattern - Skip blank lines between header and requirement text - Return first substantive text line for SHALL/MUST validation Added comprehensive tests for: - Requirements with metadata before SHALL/MUST text - Requirements with SHALL in text but not header - Requirements correctly failing without SHALL/MUST - Requirements without metadata fields All 20 validation tests pass. Fixes #159 * Respect --no-validate flag while archiving	2025-10-16 17:34:33 +11:00
Tabish Bidiwale	ce7422209f	docs: sync AGENTS.md and agents-template with explicit change-id notation (#189 ) Standardize archive command documentation to use `<change-id>` instead of `[change]` to clarify that the change ID must be explicitly passed. Remove OpenCode-specific slash command reference from AGENTS.md to keep it tool-agnostic.	2025-10-16 14:48:12 +11:00
Tabish Bidiwale	63b8a3e9f9	feat: add argument support to archive slash command (#183 ) * feat: add argument support to archive slash command Add $ARGUMENTS placeholder to the /openspec:archive slash command to allow explicit change ID specification, improving safety and matching CLI behavior. Changes: - Add $ARGUMENTS to archive command frontmatter in OpenCode configurator - Update archive command template with argument validation steps - Add rewriteArchiveFile method to handle managed section updates - Update AGENTS.md documentation for archive command usage This change makes it possible for users to run `/openspec:archive <change-id>` instead of relying on context inference, reducing the risk of archiving the wrong change. * refactor: improve archive slash command argument handling instructions Update the archive slash command template to provide clearer guidance on how to handle change IDs from arguments versus conversation context. The new instructions better distinguish between explicit argument-provided IDs and contextual references, and provide more explicit failure modes.	2025-10-16 14:05:29 +11:00
Tabish Bidiwale	4cf7bf863d	docs: note restart for slash commands (#182 )	2025-10-15 14:37:38 +11:00
github-actions[bot]andTabish Bidiwale	b30882b579	chore(release): version packages (#180 ) * Version Packages * chore: trigger CI --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Tabish Bidiwale <tabishbidiwale@gmail.com>	2025-10-14 21:36:52 +11:00
Tabish Bidiwale	082abb4795	Add changeset for factory functions and init options (#179 )	2025-10-14 21:29:59 +11:00
Tabish Bidiwale	b81fa1e6cc	feat: add factory function support for slash commands (#178 ) This change adds support for factory functions in slash command configuration, allowing slash commands to be defined as functions that return command objects.	2025-10-14 21:19:58 +11:00
Tabish Bidiwale	4a863285b0	chore: archive 4 completed changes and update specs (#172 ) 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)	2025-10-14 15:42:49 +11:00