@fission-ai/openspec 0.3.0 → 0.5.0

package/README.md

@@ -15,6 +15,7 @@
   <a href="https://nodejs.org/"><img alt="node version" src="https://img.shields.io/node/v/@fission-ai/openspec?style=flat-square" /></a>
   <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
   <a href="https://conventionalcommits.org"><img alt="Conventional Commits" src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=flat-square" /></a>
+  <a href="https://discord.gg/saTQQGQZ"><img alt="Discord" src="https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?logo=discord&logoColor=white&style=flat-square" /></a>
 </p>
 
 <p align="center">
@@ -22,7 +23,7 @@
 </p>
 
 <p align="center">
-  Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates.
+  Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/saTQQGQZ">OpenSpec Discord</a> for help and questions.
 </p>
 
 # OpenSpec
@@ -82,13 +83,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` |
+| **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
 
 #### AGENTS.md Compatible
 These tools automatically read workflow instructions from `openspec/AGENTS.md`. Ask them to follow the OpenSpec workflow if they need a reminder. Learn more about the [AGENTS.md convention](https://agents.md/).
 
 | Tools |
 |-------|
-| Codex • Amp • Jules • OpenCode • Gemini CLI • GitHub Copilot • Others |
+| Codex • Amp • Jules • Gemini CLI • GitHub Copilot • Others |
 
 ### Install & Initialize
 
@@ -183,13 +185,13 @@ You: Please archive the change
      (Shortcut for tools with slash commands: /openspec:archive add-profile-filters)
 
 AI:  I'll archive the add-profile-filters change.
-     *Runs: openspec archive add-profile-filters*
+    *Runs: openspec archive add-profile-filters --yes*
      ✓ Change archived successfully. Specs updated. Ready for the next feature!
 ```
 
 Or run the command yourself in terminal:
 ```bash
-$ openspec archive add-profile-filters  # Archive the completed change
+$ openspec archive add-profile-filters --yes  # Archive the completed change without prompts
 ```
 
 **Note:** Tools with native slash commands (Claude Code, Cursor) can use the shortcuts shown. All other tools work with natural language requests to "create an OpenSpec proposal", "apply the OpenSpec change", or "archive the change".
@@ -201,7 +203,7 @@ openspec list               # View active change folders
 openspec view               # Interactive dashboard of specs and changes
 openspec show <change>      # Display change details (proposal, tasks, spec updates)
 openspec validate <change>  # Check spec formatting and structure
-openspec archive <change>   # Move a completed change into archive/
+openspec archive <change> [--yes|-y]   # Move a completed change into archive/ (non-interactive with --yes)
 ```
 
 ## Example: How AI Creates OpenSpec Files

package/dist/core/config.js

@@ -6,6 +6,7 @@ export const OPENSPEC_MARKERS = {
 export const AI_TOOLS = [
     { name: 'Claude Code (✅ OpenSpec custom slash commands available)', value: 'claude', available: true, successLabel: 'Claude Code' },
     { name: 'Cursor (✅ OpenSpec custom slash commands available)', value: 'cursor', available: true, successLabel: 'Cursor' },
+    { name: 'OpenCode (✅ OpenSpec custom slash commands available)', value: 'opencode', available: true, successLabel: 'OpenCode' },
     { name: 'AGENTS.md (works with Codex, Amp, Copilot, …)', value: 'agents', available: true, successLabel: 'your AGENTS.md-compatible assistant' }
 ];
 //# sourceMappingURL=config.js.map

package/dist/core/configurators/slash/opencode.d.ts

@@ -0,0 +1,9 @@
+import { SlashCommandConfigurator } from "./base.js";
+import { SlashCommandId } from "../../templates/index.js";
+export declare class OpenCodeSlashCommandConfigurator extends SlashCommandConfigurator {
+    readonly toolId = "opencode";
+    readonly isAvailable = true;
+    protected getRelativePath(id: SlashCommandId): string;
+    protected getFrontmatter(id: SlashCommandId): string | undefined;
+}
+//# sourceMappingURL=opencode.d.ts.map

package/dist/core/configurators/slash/opencode.js

@@ -0,0 +1,36 @@
+import { SlashCommandConfigurator } from "./base.js";
+const FILE_PATHS = {
+    proposal: ".opencode/command/openspec-proposal.md",
+    apply: ".opencode/command/openspec-apply.md",
+    archive: ".opencode/command/openspec-archive.md",
+};
+const FRONTMATTER = {
+    proposal: `---
+agent: build
+description: Scaffold a new OpenSpec change and validate strictly.
+---
+The user has requested the following change proposal. Use the openspec instructions to create their change proposal.
+<UserRequest>
+  $ARGUMENTS
+</UserRequest>
+`,
+    apply: `---
+agent: build
+description: Implement an approved OpenSpec change and keep tasks in sync.
+---`,
+    archive: `---
+agent: build
+description: Archive a deployed OpenSpec change and update specs.
+---`,
+};
+export class OpenCodeSlashCommandConfigurator extends SlashCommandConfigurator {
+    toolId = "opencode";
+    isAvailable = true;
+    getRelativePath(id) {
+        return FILE_PATHS[id];
+    }
+    getFrontmatter(id) {
+        return FRONTMATTER[id];
+    }
+}
+//# sourceMappingURL=opencode.js.map

package/dist/core/configurators/slash/registry.js

@@ -1,12 +1,15 @@
 import { ClaudeSlashCommandConfigurator } from './claude.js';
 import { CursorSlashCommandConfigurator } from './cursor.js';
+import { OpenCodeSlashCommandConfigurator } from './opencode.js';
 export class SlashCommandRegistry {
     static configurators = new Map();
     static {
         const claude = new ClaudeSlashCommandConfigurator();
         const cursor = new CursorSlashCommandConfigurator();
+        const opencode = new OpenCodeSlashCommandConfigurator();
         this.configurators.set(claude.toolId, claude);
         this.configurators.set(cursor.toolId, cursor);
+        this.configurators.set(opencode.toolId, opencode);
     }
     static register(configurator) {
         this.configurators.set(configurator.toolId, configurator);

package/dist/core/converters/json-converter.js

@@ -33,7 +33,8 @@ export class JsonConverter {
         return JSON.stringify(jsonChange, null, 2);
     }
     extractNameFromPath(filePath) {
-        const parts = filePath.split('/');
+        const normalizedPath = filePath.replaceAll('\\', '/');
+        const parts = normalizedPath.split('/');
         for (let i = parts.length - 1; i >= 0; i--) {
             if (parts[i] === 'specs' || parts[i] === 'changes') {
                 if (i < parts.length - 1) {
@@ -41,8 +42,9 @@ export class JsonConverter {
                 }
             }
         }
-        const fileName = parts[parts.length - 1];
-        return fileName.replace('.md', '');
+        const fileName = parts[parts.length - 1] ?? '';
+        const dotIndex = fileName.lastIndexOf('.');
+        return dotIndex > 0 ? fileName.slice(0, dotIndex) : fileName;
     }
 }
 //# sourceMappingURL=json-converter.js.map

package/dist/core/init.js

@@ -1,72 +1,30 @@
 import path from 'path';
-import { createPrompt, isBackspaceKey, isDownKey, isEnterKey, isSpaceKey, isUpKey, useKeypress, usePagination, useState } from '@inquirer/core';
+import { createPrompt, isBackspaceKey, isDownKey, isEnterKey, isSpaceKey, isUpKey, useKeypress, usePagination, useState, } from '@inquirer/core';
 import chalk from 'chalk';
 import ora from 'ora';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { TemplateManager } from './templates/index.js';
 import { ToolRegistry } from './configurators/registry.js';
 import { SlashCommandRegistry } from './configurators/slash/registry.js';
-import { AI_TOOLS, OPENSPEC_DIR_NAME } from './config.js';
+import { AI_TOOLS, OPENSPEC_DIR_NAME, } from './config.js';
 const PROGRESS_SPINNER = {
     interval: 80,
-    frames: ['░░░', '▒░░', '▒▒░', '▒▒▒', '▓▒▒', '▓▓▒', '▓▓▓', '▒▓▓', '░▒▓']
+    frames: ['░░░', '▒░░', '▒▒░', '▒▒▒', '▓▒▒', '▓▓▒', '▓▓▓', '▒▓▓', '░▒▓'],
 };
 const PALETTE = {
     white: chalk.hex('#f4f4f4'),
     lightGray: chalk.hex('#c8c8c8'),
     midGray: chalk.hex('#8a8a8a'),
-    darkGray: chalk.hex('#4a4a4a')
+    darkGray: chalk.hex('#4a4a4a'),
 };
 const LETTER_MAP = {
-    O: [
-        ' ████ ',
-        '██  ██',
-        '██  ██',
-        '██  ██',
-        ' ████ '
-    ],
-    P: [
-        '█████ ',
-        '██  ██',
-        '█████ ',
-        '██    ',
-        '██    '
-    ],
-    E: [
-        '██████',
-        '██    ',
-        '█████ ',
-        '██    ',
-        '██████'
-    ],
-    N: [
-        '██  ██',
-        '███ ██',
-        '██ ███',
-        '██  ██',
-        '██  ██'
-    ],
-    S: [
-        ' █████',
-        '██    ',
-        ' ████ ',
-        '    ██',
-        '█████ '
-    ],
-    C: [
-        ' █████',
-        '██    ',
-        '██    ',
-        '██    ',
-        ' █████'
-    ],
-    ' ': [
-        '  ',
-        '  ',
-        '  ',
-        '  ',
-        '  '
-    ]
+    O: [' ████ ', '██  ██', '██  ██', '██  ██', ' ████ '],
+    P: ['█████ ', '██  ██', '█████ ', '██    ', '██    '],
+    E: ['██████', '██    ', '█████ ', '██    ', '██████'],
+    N: ['██  ██', '███ ██', '██ ███', '██  ██', '██  ██'],
+    S: [' █████', '██    ', ' ████ ', '    ██', '█████ '],
+    C: [' █████', '██    ', '██    ', '██    ', ' █████'],
+    ' ': ['  ', '  ', '  ', '  ', '  '],
 };
 const sanitizeToolLabel = (raw) => raw.replace(/✅/gu, '✔').trim();
 const parseToolLabel = (raw) => {
@@ -77,7 +35,7 @@ const parseToolLabel = (raw) => {
     }
     return {
         primary: match[1].trim(),
-        annotation: match[2].trim()
+        annotation: match[2].trim(),
     };
 };
 const toolSelectionWizard = createPrompt((config, done) => {
@@ -101,12 +59,16 @@ const toolSelectionWizard = createPrompt((config, done) => {
         loop: config.choices.length > 1,
         renderItem: ({ item, isActive }) => {
             const isSelected = selectedSet.has(item.value);
-            const cursorSymbol = isActive ? PALETTE.white('›') : PALETTE.midGray(' ');
-            const indicator = isSelected ? PALETTE.white('◉') : PALETTE.midGray('○');
+            const cursorSymbol = isActive
+                ? PALETTE.white('›')
+                : PALETTE.midGray(' ');
+            const indicator = isSelected
+                ? PALETTE.white('◉')
+                : PALETTE.midGray('○');
             const nameColor = isActive ? PALETTE.white : PALETTE.midGray;
             const label = `${nameColor(item.label.primary)}${item.configured ? PALETTE.midGray(' (already configured)') : ''}`;
             return `${cursorSymbol} ${indicator} ${label}`;
-        }
+        },
     });
     useKeypress((key) => {
         if (step === 'intro') {
@@ -247,13 +209,13 @@ export class InitCommand {
             }
             throw new Error('You must select at least one AI tool to configure.');
         }
-        const availableTools = AI_TOOLS.filter(tool => tool.available);
+        const availableTools = AI_TOOLS.filter((tool) => tool.available);
         const selectedIds = new Set(config.aiTools);
-        const selectedTools = availableTools.filter(tool => selectedIds.has(tool.value));
-        const created = selectedTools.filter(tool => !existingToolStates[tool.value]);
-        const refreshed = selectedTools.filter(tool => existingToolStates[tool.value]);
-        const skippedExisting = availableTools.filter(tool => !selectedIds.has(tool.value) && existingToolStates[tool.value]);
-        const skipped = availableTools.filter(tool => !selectedIds.has(tool.value) && !existingToolStates[tool.value]);
+        const selectedTools = availableTools.filter((tool) => selectedIds.has(tool.value));
+        const created = selectedTools.filter((tool) => !existingToolStates[tool.value]);
+        const refreshed = selectedTools.filter((tool) => existingToolStates[tool.value]);
+        const skippedExisting = availableTools.filter((tool) => !selectedIds.has(tool.value) && existingToolStates[tool.value]);
+        const skipped = availableTools.filter((tool) => !selectedIds.has(tool.value) && !existingToolStates[tool.value]);
         // Step 1: Create directory structure
         if (!extendMode) {
             const structureSpinner = this.startSpinner('Creating OpenSpec structure...');
@@ -261,7 +223,7 @@ export class InitCommand {
             await this.generateFiles(openspecPath, config);
             structureSpinner.stopAndPersist({
                 symbol: PALETTE.white('▌'),
-                text: PALETTE.white('OpenSpec structure created')
+                text: PALETTE.white('OpenSpec structure created'),
             });
         }
         else {
@@ -272,7 +234,7 @@ export class InitCommand {
         await this.configureAITools(projectPath, openspecDir, config.aiTools);
         toolSpinner.stopAndPersist({
             symbol: PALETTE.white('▌'),
-            text: PALETTE.white('AI tools configured')
+            text: PALETTE.white('AI tools configured'),
         });
         // Success message
         this.displaySuccessMessage(selectedTools, created, refreshed, skippedExisting, skipped, extendMode);
@@ -280,7 +242,7 @@ export class InitCommand {
     async validate(projectPath, _openspecPath) {
         const extendMode = await FileSystemUtils.directoryExists(_openspecPath);
         // Check write permissions
-        if (!await FileSystemUtils.ensureWritePermissions(projectPath)) {
+        if (!(await FileSystemUtils.ensureWritePermissions(projectPath))) {
             throw new Error(`Insufficient permissions to write to ${projectPath}`);
         }
         return extendMode;
@@ -290,7 +252,7 @@ export class InitCommand {
         return { aiTools: selectedTools };
     }
     async promptForAITools(existingTools, extendMode) {
-        const availableTools = AI_TOOLS.filter(tool => tool.available);
+        const availableTools = AI_TOOLS.filter((tool) => tool.available);
         if (availableTools.length === 0) {
             return [];
         }
@@ -298,7 +260,9 @@ export class InitCommand {
             ? 'Which AI tools would you like to add or refresh?'
             : 'Which AI tools do you use?';
         const initialSelected = extendMode
-            ? availableTools.filter(tool => existingTools[tool.value]).map(tool => tool.value)
+            ? availableTools
+                .filter((tool) => existingTools[tool.value])
+                .map((tool) => tool.value)
             : [];
         return this.prompt({
             extendMode,
@@ -306,9 +270,9 @@ export class InitCommand {
             choices: availableTools.map((tool) => ({
                 value: tool.value,
                 label: parseToolLabel(tool.name),
-                configured: Boolean(existingTools[tool.value])
+                configured: Boolean(existingTools[tool.value]),
             })),
-            initialSelected
+            initialSelected,
         });
     }
     async getExistingToolStates(projectPath) {
@@ -320,7 +284,8 @@ export class InitCommand {
     }
     async isToolConfigured(projectPath, toolId) {
         const configFile = ToolRegistry.get(toolId)?.configFileName;
-        if (configFile && await FileSystemUtils.fileExists(path.join(projectPath, configFile)))
+        if (configFile &&
+            (await FileSystemUtils.fileExists(path.join(projectPath, configFile))))
             return true;
         const slashConfigurator = SlashCommandRegistry.get(toolId);
         if (!slashConfigurator)
@@ -336,7 +301,7 @@ export class InitCommand {
             openspecPath,
             path.join(openspecPath, 'specs'),
             path.join(openspecPath, 'changes'),
-            path.join(openspecPath, 'changes', 'archive')
+            path.join(openspecPath, 'changes', 'archive'),
         ];
         for (const dir of directories) {
             await FileSystemUtils.createDirectory(dir);
@@ -376,10 +341,18 @@ export class InitCommand {
         console.log();
         console.log(PALETTE.lightGray('Tool summary:'));
         const summaryLines = [
-            created.length ? `${PALETTE.white('▌')} ${PALETTE.white('Created:')} ${this.formatToolNames(created)}` : null,
-            refreshed.length ? `${PALETTE.lightGray('▌')} ${PALETTE.lightGray('Refreshed:')} ${this.formatToolNames(refreshed)}` : null,
-            skippedExisting.length ? `${PALETTE.midGray('▌')} ${PALETTE.midGray('Skipped (already configured):')} ${this.formatToolNames(skippedExisting)}` : null,
-            skipped.length ? `${PALETTE.darkGray('▌')} ${PALETTE.darkGray('Skipped:')} ${this.formatToolNames(skipped)}` : null
+            created.length
+                ? `${PALETTE.white('▌')} ${PALETTE.white('Created:')} ${this.formatToolNames(created)}`
+                : null,
+            refreshed.length
+                ? `${PALETTE.lightGray('▌')} ${PALETTE.lightGray('Refreshed:')} ${this.formatToolNames(refreshed)}`
+                : null,
+            skippedExisting.length
+                ? `${PALETTE.midGray('▌')} ${PALETTE.midGray('Skipped (already configured):')} ${this.formatToolNames(skippedExisting)}`
+                : null,
+            skipped.length
+                ? `${PALETTE.darkGray('▌')} ${PALETTE.darkGray('Skipped:')} ${this.formatToolNames(skipped)}`
+                : null,
         ].filter((line) => Boolean(line));
         for (const line of summaryLines) {
             console.log(line);
@@ -427,7 +400,7 @@ export class InitCommand {
             PALETTE.lightGray,
             PALETTE.midGray,
             PALETTE.lightGray,
-            PALETTE.white
+            PALETTE.white,
         ];
         console.log();
         rows.forEach((row, index) => {
@@ -442,7 +415,7 @@ export class InitCommand {
             text,
             stream: process.stdout,
             color: 'gray',
-            spinner: PROGRESS_SPINNER
+            spinner: PROGRESS_SPINNER,
         }).start();
     }
 }

package/dist/core/parsers/change-parser.js

@@ -124,7 +124,7 @@ export class ChangeParser extends MarkdownParser {
     }
     parseRenames(content) {
         const renames = [];
-        const lines = content.split('\n');
+        const lines = ChangeParser.normalizeContent(content).split('\n');
         let currentRename = {};
         for (const line of lines) {
             const fromMatch = line.match(/^\s*-?\s*FROM:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
@@ -146,7 +146,8 @@ export class ChangeParser extends MarkdownParser {
         return renames;
     }
     parseSectionsFromContent(content) {
-        const lines = content.split('\n');
+        const normalizedContent = ChangeParser.normalizeContent(content);
+        const lines = normalizedContent.split('\n');
         const sections = [];
         const stack = [];
         for (let i = 0; i < lines.length; i++) {

package/dist/core/parsers/markdown-parser.d.ts

@@ -9,6 +9,7 @@ export declare class MarkdownParser {
     private lines;
     private currentLine;
     constructor(content: string);
+    protected static normalizeContent(content: string): string;
     parseSpec(name: string): Spec;
     parseChange(name: string): Change;
     protected parseSections(): Section[];

package/dist/core/parsers/markdown-parser.js

@@ -2,9 +2,13 @@ export class MarkdownParser {
     lines;
     currentLine;
     constructor(content) {
-        this.lines = content.split('\n');
+        const normalized = MarkdownParser.normalizeContent(content);
+        this.lines = normalized.split('\n');
         this.currentLine = 0;
     }
+    static normalizeContent(content) {
+        return content.replace(/\r\n?/g, '\n');
+    }
     parseSpec(name) {
         const sections = this.parseSections();
         const purpose = this.findSection(sections, 'Purpose')?.content || '';

package/dist/core/parsers/requirement-blocks.js

@@ -6,7 +6,8 @@ const REQUIREMENT_HEADER_REGEX = /^###\s*Requirement:\s*(.+)\s*$/;
  * Extracts the Requirements section from a spec file and parses requirement blocks.
  */
 export function extractRequirementsSection(content) {
-    const lines = content.split('\n');
+    const normalized = normalizeLineEndings(content);
+    const lines = normalized.split('\n');
     const reqHeaderIndex = lines.findIndex(l => /^##\s+Requirements\s*$/i.test(l));
     if (reqHeaderIndex === -1) {
         // No requirements section; create an empty one at the end
@@ -70,11 +71,15 @@ export function extractRequirementsSection(content) {
         after: after.startsWith('\n') ? after : '\n' + after,
     };
 }
+function normalizeLineEndings(content) {
+    return content.replace(/\r\n?/g, '\n');
+}
 /**
  * Parse a delta-formatted spec change file content into a DeltaPlan with raw blocks.
  */
 export function parseDeltaSpec(content) {
-    const sections = splitTopLevelSections(content);
+    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'] || '');
@@ -103,7 +108,7 @@ function splitTopLevelSections(content) {
 function parseRequirementBlocksFromSection(sectionBody) {
     if (!sectionBody)
         return [];
-    const lines = sectionBody.split('\n');
+    const lines = normalizeLineEndings(sectionBody).split('\n');
     const blocks = [];
     let i = 0;
     while (i < lines.length) {
@@ -133,7 +138,7 @@ function parseRemovedNames(sectionBody) {
     if (!sectionBody)
         return [];
     const names = [];
-    const lines = sectionBody.split('\n');
+    const lines = normalizeLineEndings(sectionBody).split('\n');
     for (const line of lines) {
         const m = line.match(REQUIREMENT_HEADER_REGEX);
         if (m) {
@@ -152,7 +157,7 @@ function parseRenamedPairs(sectionBody) {
     if (!sectionBody)
         return [];
     const pairs = [];
-    const lines = sectionBody.split('\n');
+    const lines = normalizeLineEndings(sectionBody).split('\n');
     let current = {};
     for (const line of lines) {
         const fromMatch = line.match(/^\s*-?\s*FROM:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);

package/dist/core/templates/agents-template.d.ts

@@ -1,2 +1,2 @@
-export declare const agentsTemplate = "# OpenSpec Instructions\n\nInstructions for AI coding assistants using OpenSpec for spec-driven development.\n\n## TL;DR Quick Checklist\n\n- Search existing work: `openspec spec list --long`, `openspec list` (use `rg` only for full-text search)\n- Decide scope: new capability vs modify existing capability\n- Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`)\n- Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability\n- Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement\n- Validate: `openspec validate [change-id] --strict` and fix issues\n- Request approval: Do not start implementation until proposal is approved\n\n## Three-Stage Workflow\n\n### Stage 1: Creating Changes\nCreate proposal when you need to:\n- Add features or functionality\n- Make breaking changes (API, schema)\n- Change architecture or patterns  \n- Optimize performance (changes behavior)\n- Update security patterns\n\nTriggers (examples):\n- \"Help me create a change proposal\"\n- \"Help me plan a change\"\n- \"Help me create a proposal\"\n- \"I want to create a spec proposal\"\n- \"I want to create a spec\"\n\nLoose matching guidance:\n- Contains one of: `proposal`, `change`, `spec`\n- With one of: `create`, `plan`, `make`, `start`, `help`\n\nSkip proposal for:\n- Bug fixes (restore intended behavior)\n- Typos, formatting, comments\n- Dependency updates (non-breaking)\n- Configuration changes\n- Tests for existing behavior\n\n**Workflow**\n1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context.\n2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes/<id>/`.\n3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement.\n4. Run `openspec validate <id> --strict` and resolve any issues before sharing the proposal.\n\n### Stage 2: Implementing Changes\n1. **Read proposal.md** - Understand what's being built\n2. **Read design.md** (if exists) - Review technical decisions\n3. **Read tasks.md** - Get implementation checklist\n4. **Implement tasks sequentially** - Complete in order\n5. **Mark complete immediately** - Update `- [x]` after each task\n6. **Approval gate** - Do not start implementation until the proposal is reviewed and approved\n\n### Stage 3: Archiving Changes\nAfter deployment, create separate PR to:\n- Move `changes/[name]/` \u2192 `changes/archive/YYYY-MM-DD-[name]/`\n- Update `specs/` if capabilities changed\n- Use `openspec archive [change] --skip-specs` for tooling-only changes\n- Run `openspec validate --strict` to confirm the archived change passes checks\n\n## Before Any Task\n\n**Context Checklist:**\n- [ ] Read relevant specs in `specs/[capability]/spec.md`\n- [ ] Check pending changes in `changes/` for conflicts\n- [ ] Read `openspec/project.md` for conventions\n- [ ] Run `openspec list` to see active changes\n- [ ] Run `openspec list --specs` to see existing capabilities\n\n**Before Creating Specs:**\n- Always check if capability already exists\n- Prefer modifying existing specs over creating duplicates\n- Use `openspec show [spec]` to review current state\n- If request is ambiguous, ask 1\u20132 clarifying questions before scaffolding\n\n### Search Guidance\n- Enumerate specs: `openspec spec list --long` (or `--json` for scripts)\n- Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available)\n- Show details:\n  - Spec: `openspec show <spec-id> --type spec` (use `--json` for filters)\n  - Change: `openspec show <change-id> --json --deltas-only`\n- Full-text search (use ripgrep): `rg -n \"Requirement:|Scenario:\" openspec/specs`\n\n## Quick Start\n\n### CLI Commands\n\n```bash\n# Essential commands\nopenspec list                  # List active changes\nopenspec list --specs          # List specifications\nopenspec show [item]           # Display change or spec\nopenspec diff [change]         # Show spec differences\nopenspec validate [item]       # Validate changes or specs\nopenspec archive [change]      # Archive after deployment\n\n# Project management\nopenspec init [path]           # Initialize OpenSpec\nopenspec update [path]         # Update instruction files\n\n# Interactive mode\nopenspec show                  # Prompts for selection\nopenspec validate              # Bulk validation mode\n\n# Debugging\nopenspec show [change] --json --deltas-only\nopenspec validate [change] --strict\n```\n\n### Command Flags\n\n- `--json` - Machine-readable output\n- `--type change|spec` - Disambiguate items\n- `--strict` - Comprehensive validation\n- `--no-interactive` - Disable prompts\n- `--skip-specs` - Archive without spec updates\n\n## Directory Structure\n\n```\nopenspec/\n\u251C\u2500\u2500 project.md              # Project conventions\n\u251C\u2500\u2500 specs/                  # Current truth - what IS built\n\u2502   \u2514\u2500\u2500 [capability]/       # Single focused capability\n\u2502       \u251C\u2500\u2500 spec.md         # Requirements and scenarios\n\u2502       \u2514\u2500\u2500 design.md       # Technical patterns\n\u251C\u2500\u2500 changes/                # Proposals - what SHOULD change\n\u2502   \u251C\u2500\u2500 [change-name]/\n\u2502   \u2502   \u251C\u2500\u2500 proposal.md     # Why, what, impact\n\u2502   \u2502   \u251C\u2500\u2500 tasks.md        # Implementation checklist\n\u2502   \u2502   \u251C\u2500\u2500 design.md       # Technical decisions (optional; see criteria)\n\u2502   \u2502   \u2514\u2500\u2500 specs/          # Delta changes\n\u2502   \u2502       \u2514\u2500\u2500 [capability]/\n\u2502   \u2502           \u2514\u2500\u2500 spec.md # ADDED/MODIFIED/REMOVED\n\u2502   \u2514\u2500\u2500 archive/            # Completed changes\n```\n\n## Creating Change Proposals\n\n### Decision Tree\n\n```\nNew request?\n\u251C\u2500 Bug fix restoring spec behavior? \u2192 Fix directly\n\u251C\u2500 Typo/format/comment? \u2192 Fix directly  \n\u251C\u2500 New feature/capability? \u2192 Create proposal\n\u251C\u2500 Breaking change? \u2192 Create proposal\n\u251C\u2500 Architecture change? \u2192 Create proposal\n\u2514\u2500 Unclear? \u2192 Create proposal (safer)\n```\n\n### Proposal Structure\n\n1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique)\n\n2. **Write proposal.md:**\n```markdown\n## Why\n[1-2 sentences on problem/opportunity]\n\n## What Changes\n- [Bullet list of changes]\n- [Mark breaking changes with **BREAKING**]\n\n## Impact\n- Affected specs: [list capabilities]\n- Affected code: [key files/systems]\n```\n\n3. **Create spec deltas:** `specs/[capability]/spec.md`\n```markdown\n## ADDED Requirements\n### Requirement: New Feature\nThe system SHALL provide...\n\n#### Scenario: Success case\n- **WHEN** user performs action\n- **THEN** expected result\n\n## MODIFIED Requirements\n### Requirement: Existing Feature\n[Complete modified requirement]\n\n## REMOVED Requirements\n### Requirement: Old Feature\n**Reason**: [Why removing]\n**Migration**: [How to handle]\n```\nIf multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs/<capability>/spec.md`\u2014one per capability.\n\n4. **Create tasks.md:**\n```markdown\n## 1. Implementation\n- [ ] 1.1 Create database schema\n- [ ] 1.2 Implement API endpoint\n- [ ] 1.3 Add frontend component\n- [ ] 1.4 Write tests\n```\n\n5. **Create design.md when needed:**\nCreate `design.md` if any of the following apply; otherwise omit it:\n- Cross-cutting change (multiple services/modules) or a new architectural pattern\n- New external dependency or significant data model changes\n- Security, performance, or migration complexity\n- Ambiguity that benefits from technical decisions before coding\n\nMinimal `design.md` skeleton:\n```markdown\n## Context\n[Background, constraints, stakeholders]\n\n## Goals / Non-Goals\n- Goals: [...]\n- Non-Goals: [...]\n\n## Decisions\n- Decision: [What and why]\n- Alternatives considered: [Options + rationale]\n\n## Risks / Trade-offs\n- [Risk] \u2192 Mitigation\n\n## Migration Plan\n[Steps, rollback]\n\n## Open Questions\n- [...]\n```\n\n## Spec File Format\n\n### Critical: Scenario Formatting\n\n**CORRECT** (use #### headers):\n```markdown\n#### Scenario: User login success\n- **WHEN** valid credentials provided\n- **THEN** return JWT token\n```\n\n**WRONG** (don't use bullets or bold):\n```markdown\n- **Scenario: User login**  \u274C\n**Scenario**: User login     \u274C\n### Scenario: User login      \u274C\n```\n\nEvery requirement MUST have at least one scenario.\n\n### Requirement Wording\n- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative)\n\n### Delta Operations\n\n- `## ADDED Requirements` - New capabilities\n- `## MODIFIED Requirements` - Changed behavior\n- `## REMOVED Requirements` - Deprecated features\n- `## RENAMED Requirements` - Name changes\n\nHeaders matched with `trim(header)` - whitespace ignored.\n\n#### When to use ADDED vs MODIFIED\n- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding \"Slash Command Configuration\") rather than altering the semantics of an existing requirement.\n- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.\n- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.\n\nCommon pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren\u2019t explicitly changing the existing requirement, add a new requirement under ADDED instead.\n\nAuthoring a MODIFIED requirement correctly:\n1) Locate the existing requirement in `openspec/specs/<capability>/spec.md`.\n2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios).\n3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior.\n4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`.\n\nExample for RENAMED:\n```markdown\n## RENAMED Requirements\n- FROM: `### Requirement: Login`\n- TO: `### Requirement: User Authentication`\n```\n\n## Troubleshooting\n\n### Common Errors\n\n**\"Change must have at least one delta\"**\n- Check `changes/[name]/specs/` exists with .md files\n- Verify files have operation prefixes (## ADDED Requirements)\n\n**\"Requirement must have at least one scenario\"**\n- Check scenarios use `#### Scenario:` format (4 hashtags)\n- Don't use bullet points or bold for scenario headers\n\n**Silent scenario parsing failures**\n- Exact format required: `#### Scenario: Name`\n- Debug with: `openspec show [change] --json --deltas-only`\n\n### Validation Tips\n\n```bash\n# Always use strict mode for comprehensive checks\nopenspec validate [change] --strict\n\n# Debug delta parsing\nopenspec show [change] --json | jq '.deltas'\n\n# Check specific requirement\nopenspec show [spec] --json -r 1\n```\n\n## Happy Path Script\n\n```bash\n# 1) Explore current state\nopenspec spec list --long\nopenspec list\n# Optional full-text search:\n# rg -n \"Requirement:|Scenario:\" openspec/specs\n# rg -n \"^#|Requirement:\" openspec/changes\n\n# 2) Choose change id and scaffold\nCHANGE=add-two-factor-auth\nmkdir -p openspec/changes/$CHANGE/{specs/auth}\nprintf \"## Why\\n...\\n\\n## What Changes\\n- ...\\n\\n## Impact\\n- ...\\n\" > openspec/changes/$CHANGE/proposal.md\nprintf \"## 1. Implementation\\n- [ ] 1.1 ...\\n\" > openspec/changes/$CHANGE/tasks.md\n\n# 3) Add deltas (example)\ncat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF'\n## ADDED Requirements\n### Requirement: Two-Factor Authentication\nUsers MUST provide a second factor during login.\n\n#### Scenario: OTP required\n- **WHEN** valid credentials are provided\n- **THEN** an OTP challenge is required\nEOF\n\n# 4) Validate\nopenspec validate $CHANGE --strict\n```\n\n## Multi-Capability Example\n\n```\nopenspec/changes/add-2fa-notify/\n\u251C\u2500\u2500 proposal.md\n\u251C\u2500\u2500 tasks.md\n\u2514\u2500\u2500 specs/\n    \u251C\u2500\u2500 auth/\n    \u2502   \u2514\u2500\u2500 spec.md   # ADDED: Two-Factor Authentication\n    \u2514\u2500\u2500 notifications/\n        \u2514\u2500\u2500 spec.md   # ADDED: OTP email notification\n```\n\nauth/spec.md\n```markdown\n## ADDED Requirements\n### Requirement: Two-Factor Authentication\n...\n```\n\nnotifications/spec.md\n```markdown\n## ADDED Requirements\n### Requirement: OTP Email Notification\n...\n```\n\n## Best Practices\n\n### Simplicity First\n- Default to <100 lines of new code\n- Single-file implementations until proven insufficient\n- Avoid frameworks without clear justification\n- Choose boring, proven patterns\n\n### Complexity Triggers\nOnly add complexity with:\n- Performance data showing current solution too slow\n- Concrete scale requirements (>1000 users, >100MB data)\n- Multiple proven use cases requiring abstraction\n\n### Clear References\n- Use `file.ts:42` format for code locations\n- Reference specs as `specs/auth/spec.md`\n- Link related changes and PRs\n\n### Capability Naming\n- Use verb-noun: `user-auth`, `payment-capture`\n- Single purpose per capability\n- 10-minute understandability rule\n- Split if description needs \"AND\"\n\n### Change ID Naming\n- Use kebab-case, short and descriptive: `add-two-factor-auth`\n- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-`\n- Ensure uniqueness; if taken, append `-2`, `-3`, etc.\n\n## Tool Selection Guide\n\n| Task | Tool | Why |\n|------|------|-----|\n| Find files by pattern | Glob | Fast pattern matching |\n| Search code content | Grep | Optimized regex search |\n| Read specific files | Read | Direct file access |\n| Explore unknown scope | Task | Multi-step investigation |\n\n## Error Recovery\n\n### Change Conflicts\n1. Run `openspec list` to see active changes\n2. Check for overlapping specs\n3. Coordinate with change owners\n4. Consider combining proposals\n\n### Validation Failures\n1. Run with `--strict` flag\n2. Check JSON output for details\n3. Verify spec file format\n4. Ensure scenarios properly formatted\n\n### Missing Context\n1. Read project.md first\n2. Check related specs\n3. Review recent archives\n4. Ask for clarification\n\n## Quick Reference\n\n### Stage Indicators\n- `changes/` - Proposed, not yet built\n- `specs/` - Built and deployed\n- `archive/` - Completed changes\n\n### File Purposes\n- `proposal.md` - Why and what\n- `tasks.md` - Implementation steps\n- `design.md` - Technical decisions\n- `spec.md` - Requirements and behavior\n\n### CLI Essentials\n```bash\nopenspec list              # What's in progress?\nopenspec show [item]       # View details\nopenspec diff [change]     # What's changing?\nopenspec validate --strict # Is it correct?\nopenspec archive [change]  # Mark complete\n```\n\nRemember: Specs are truth. Changes are proposals. Keep them in sync.\n";
+export declare const agentsTemplate = "# OpenSpec Instructions\n\nInstructions for AI coding assistants using OpenSpec for spec-driven development.\n\n## TL;DR Quick Checklist\n\n- Search existing work: `openspec spec list --long`, `openspec list` (use `rg` only for full-text search)\n- Decide scope: new capability vs modify existing capability\n- Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`)\n- Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability\n- Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement\n- Validate: `openspec validate [change-id] --strict` and fix issues\n- Request approval: Do not start implementation until proposal is approved\n\n## Three-Stage Workflow\n\n### Stage 1: Creating Changes\nCreate proposal when you need to:\n- Add features or functionality\n- Make breaking changes (API, schema)\n- Change architecture or patterns  \n- Optimize performance (changes behavior)\n- Update security patterns\n\nTriggers (examples):\n- \"Help me create a change proposal\"\n- \"Help me plan a change\"\n- \"Help me create a proposal\"\n- \"I want to create a spec proposal\"\n- \"I want to create a spec\"\n\nLoose matching guidance:\n- Contains one of: `proposal`, `change`, `spec`\n- With one of: `create`, `plan`, `make`, `start`, `help`\n\nSkip proposal for:\n- Bug fixes (restore intended behavior)\n- Typos, formatting, comments\n- Dependency updates (non-breaking)\n- Configuration changes\n- Tests for existing behavior\n\n**Workflow**\n1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context.\n2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes/<id>/`.\n3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement.\n4. Run `openspec validate <id> --strict` and resolve any issues before sharing the proposal.\n\n### Stage 2: Implementing Changes\nTrack these steps as TODOs and complete them one by one.\n1. **Read proposal.md** - Understand what's being built\n2. **Read design.md** (if exists) - Review technical decisions\n3. **Read tasks.md** - Get implementation checklist\n4. **Implement tasks sequentially** - Complete in order\n5. **Confirm completion** - Ensure every item in `tasks.md` is finished before updating statuses\n6. **Update checklist** - After all work is done, set every task to `- [x]` so the list reflects reality\n7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved\n\n### Stage 3: Archiving Changes\nAfter deployment, create separate PR to:\n- Move `changes/[name]/` \u2192 `changes/archive/YYYY-MM-DD-[name]/`\n- Update `specs/` if capabilities changed\n- Use `openspec archive [change] --skip-specs --yes` for tooling-only changes\n- Run `openspec validate --strict` to confirm the archived change passes checks\n\n## Before Any Task\n\n**Context Checklist:**\n- [ ] Read relevant specs in `specs/[capability]/spec.md`\n- [ ] Check pending changes in `changes/` for conflicts\n- [ ] Read `openspec/project.md` for conventions\n- [ ] Run `openspec list` to see active changes\n- [ ] Run `openspec list --specs` to see existing capabilities\n\n**Before Creating Specs:**\n- Always check if capability already exists\n- Prefer modifying existing specs over creating duplicates\n- Use `openspec show [spec]` to review current state\n- If request is ambiguous, ask 1\u20132 clarifying questions before scaffolding\n\n### Search Guidance\n- Enumerate specs: `openspec spec list --long` (or `--json` for scripts)\n- Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available)\n- Show details:\n  - Spec: `openspec show <spec-id> --type spec` (use `--json` for filters)\n  - Change: `openspec show <change-id> --json --deltas-only`\n- Full-text search (use ripgrep): `rg -n \"Requirement:|Scenario:\" openspec/specs`\n\n## Quick Start\n\n### CLI Commands\n\n```bash\n# Essential commands\nopenspec list                  # List active changes\nopenspec list --specs          # List specifications\nopenspec show [item]           # Display change or spec\nopenspec diff [change]         # Show spec differences\nopenspec validate [item]       # Validate changes or specs\nopenspec archive [change] [--yes|-y]      # Archive after deployment (add --yes for non-interactive runs)\n\n# Project management\nopenspec init [path]           # Initialize OpenSpec\nopenspec update [path]         # Update instruction files\n\n# Interactive mode\nopenspec show                  # Prompts for selection\nopenspec validate              # Bulk validation mode\n\n# Debugging\nopenspec show [change] --json --deltas-only\nopenspec validate [change] --strict\n```\n\n### Command Flags\n\n- `--json` - Machine-readable output\n- `--type change|spec` - Disambiguate items\n- `--strict` - Comprehensive validation\n- `--no-interactive` - Disable prompts\n- `--skip-specs` - Archive without spec updates\n- `--yes`/`-y` - Skip confirmation prompts (non-interactive archive)\n\n## Directory Structure\n\n```\nopenspec/\n\u251C\u2500\u2500 project.md              # Project conventions\n\u251C\u2500\u2500 specs/                  # Current truth - what IS built\n\u2502   \u2514\u2500\u2500 [capability]/       # Single focused capability\n\u2502       \u251C\u2500\u2500 spec.md         # Requirements and scenarios\n\u2502       \u2514\u2500\u2500 design.md       # Technical patterns\n\u251C\u2500\u2500 changes/                # Proposals - what SHOULD change\n\u2502   \u251C\u2500\u2500 [change-name]/\n\u2502   \u2502   \u251C\u2500\u2500 proposal.md     # Why, what, impact\n\u2502   \u2502   \u251C\u2500\u2500 tasks.md        # Implementation checklist\n\u2502   \u2502   \u251C\u2500\u2500 design.md       # Technical decisions (optional; see criteria)\n\u2502   \u2502   \u2514\u2500\u2500 specs/          # Delta changes\n\u2502   \u2502       \u2514\u2500\u2500 [capability]/\n\u2502   \u2502           \u2514\u2500\u2500 spec.md # ADDED/MODIFIED/REMOVED\n\u2502   \u2514\u2500\u2500 archive/            # Completed changes\n```\n\n## Creating Change Proposals\n\n### Decision Tree\n\n```\nNew request?\n\u251C\u2500 Bug fix restoring spec behavior? \u2192 Fix directly\n\u251C\u2500 Typo/format/comment? \u2192 Fix directly  \n\u251C\u2500 New feature/capability? \u2192 Create proposal\n\u251C\u2500 Breaking change? \u2192 Create proposal\n\u251C\u2500 Architecture change? \u2192 Create proposal\n\u2514\u2500 Unclear? \u2192 Create proposal (safer)\n```\n\n### Proposal Structure\n\n1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique)\n\n2. **Write proposal.md:**\n```markdown\n## Why\n[1-2 sentences on problem/opportunity]\n\n## What Changes\n- [Bullet list of changes]\n- [Mark breaking changes with **BREAKING**]\n\n## Impact\n- Affected specs: [list capabilities]\n- Affected code: [key files/systems]\n```\n\n3. **Create spec deltas:** `specs/[capability]/spec.md`\n```markdown\n## ADDED Requirements\n### Requirement: New Feature\nThe system SHALL provide...\n\n#### Scenario: Success case\n- **WHEN** user performs action\n- **THEN** expected result\n\n## MODIFIED Requirements\n### Requirement: Existing Feature\n[Complete modified requirement]\n\n## REMOVED Requirements\n### Requirement: Old Feature\n**Reason**: [Why removing]\n**Migration**: [How to handle]\n```\nIf multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs/<capability>/spec.md`\u2014one per capability.\n\n4. **Create tasks.md:**\n```markdown\n## 1. Implementation\n- [ ] 1.1 Create database schema\n- [ ] 1.2 Implement API endpoint\n- [ ] 1.3 Add frontend component\n- [ ] 1.4 Write tests\n```\n\n5. **Create design.md when needed:**\nCreate `design.md` if any of the following apply; otherwise omit it:\n- Cross-cutting change (multiple services/modules) or a new architectural pattern\n- New external dependency or significant data model changes\n- Security, performance, or migration complexity\n- Ambiguity that benefits from technical decisions before coding\n\nMinimal `design.md` skeleton:\n```markdown\n## Context\n[Background, constraints, stakeholders]\n\n## Goals / Non-Goals\n- Goals: [...]\n- Non-Goals: [...]\n\n## Decisions\n- Decision: [What and why]\n- Alternatives considered: [Options + rationale]\n\n## Risks / Trade-offs\n- [Risk] \u2192 Mitigation\n\n## Migration Plan\n[Steps, rollback]\n\n## Open Questions\n- [...]\n```\n\n## Spec File Format\n\n### Critical: Scenario Formatting\n\n**CORRECT** (use #### headers):\n```markdown\n#### Scenario: User login success\n- **WHEN** valid credentials provided\n- **THEN** return JWT token\n```\n\n**WRONG** (don't use bullets or bold):\n```markdown\n- **Scenario: User login**  \u274C\n**Scenario**: User login     \u274C\n### Scenario: User login      \u274C\n```\n\nEvery requirement MUST have at least one scenario.\n\n### Requirement Wording\n- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative)\n\n### Delta Operations\n\n- `## ADDED Requirements` - New capabilities\n- `## MODIFIED Requirements` - Changed behavior\n- `## REMOVED Requirements` - Deprecated features\n- `## RENAMED Requirements` - Name changes\n\nHeaders matched with `trim(header)` - whitespace ignored.\n\n#### When to use ADDED vs MODIFIED\n- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding \"Slash Command Configuration\") rather than altering the semantics of an existing requirement.\n- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.\n- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.\n\nCommon pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren\u2019t explicitly changing the existing requirement, add a new requirement under ADDED instead.\n\nAuthoring a MODIFIED requirement correctly:\n1) Locate the existing requirement in `openspec/specs/<capability>/spec.md`.\n2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios).\n3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior.\n4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`.\n\nExample for RENAMED:\n```markdown\n## RENAMED Requirements\n- FROM: `### Requirement: Login`\n- TO: `### Requirement: User Authentication`\n```\n\n## Troubleshooting\n\n### Common Errors\n\n**\"Change must have at least one delta\"**\n- Check `changes/[name]/specs/` exists with .md files\n- Verify files have operation prefixes (## ADDED Requirements)\n\n**\"Requirement must have at least one scenario\"**\n- Check scenarios use `#### Scenario:` format (4 hashtags)\n- Don't use bullet points or bold for scenario headers\n\n**Silent scenario parsing failures**\n- Exact format required: `#### Scenario: Name`\n- Debug with: `openspec show [change] --json --deltas-only`\n\n### Validation Tips\n\n```bash\n# Always use strict mode for comprehensive checks\nopenspec validate [change] --strict\n\n# Debug delta parsing\nopenspec show [change] --json | jq '.deltas'\n\n# Check specific requirement\nopenspec show [spec] --json -r 1\n```\n\n## Happy Path Script\n\n```bash\n# 1) Explore current state\nopenspec spec list --long\nopenspec list\n# Optional full-text search:\n# rg -n \"Requirement:|Scenario:\" openspec/specs\n# rg -n \"^#|Requirement:\" openspec/changes\n\n# 2) Choose change id and scaffold\nCHANGE=add-two-factor-auth\nmkdir -p openspec/changes/$CHANGE/{specs/auth}\nprintf \"## Why\\n...\\n\\n## What Changes\\n- ...\\n\\n## Impact\\n- ...\\n\" > openspec/changes/$CHANGE/proposal.md\nprintf \"## 1. Implementation\\n- [ ] 1.1 ...\\n\" > openspec/changes/$CHANGE/tasks.md\n\n# 3) Add deltas (example)\ncat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF'\n## ADDED Requirements\n### Requirement: Two-Factor Authentication\nUsers MUST provide a second factor during login.\n\n#### Scenario: OTP required\n- **WHEN** valid credentials are provided\n- **THEN** an OTP challenge is required\nEOF\n\n# 4) Validate\nopenspec validate $CHANGE --strict\n```\n\n## Multi-Capability Example\n\n```\nopenspec/changes/add-2fa-notify/\n\u251C\u2500\u2500 proposal.md\n\u251C\u2500\u2500 tasks.md\n\u2514\u2500\u2500 specs/\n    \u251C\u2500\u2500 auth/\n    \u2502   \u2514\u2500\u2500 spec.md   # ADDED: Two-Factor Authentication\n    \u2514\u2500\u2500 notifications/\n        \u2514\u2500\u2500 spec.md   # ADDED: OTP email notification\n```\n\nauth/spec.md\n```markdown\n## ADDED Requirements\n### Requirement: Two-Factor Authentication\n...\n```\n\nnotifications/spec.md\n```markdown\n## ADDED Requirements\n### Requirement: OTP Email Notification\n...\n```\n\n## Best Practices\n\n### Simplicity First\n- Default to <100 lines of new code\n- Single-file implementations until proven insufficient\n- Avoid frameworks without clear justification\n- Choose boring, proven patterns\n\n### Complexity Triggers\nOnly add complexity with:\n- Performance data showing current solution too slow\n- Concrete scale requirements (>1000 users, >100MB data)\n- Multiple proven use cases requiring abstraction\n\n### Clear References\n- Use `file.ts:42` format for code locations\n- Reference specs as `specs/auth/spec.md`\n- Link related changes and PRs\n\n### Capability Naming\n- Use verb-noun: `user-auth`, `payment-capture`\n- Single purpose per capability\n- 10-minute understandability rule\n- Split if description needs \"AND\"\n\n### Change ID Naming\n- Use kebab-case, short and descriptive: `add-two-factor-auth`\n- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-`\n- Ensure uniqueness; if taken, append `-2`, `-3`, etc.\n\n## Tool Selection Guide\n\n| Task | Tool | Why |\n|------|------|-----|\n| Find files by pattern | Glob | Fast pattern matching |\n| Search code content | Grep | Optimized regex search |\n| Read specific files | Read | Direct file access |\n| Explore unknown scope | Task | Multi-step investigation |\n\n## Error Recovery\n\n### Change Conflicts\n1. Run `openspec list` to see active changes\n2. Check for overlapping specs\n3. Coordinate with change owners\n4. Consider combining proposals\n\n### Validation Failures\n1. Run with `--strict` flag\n2. Check JSON output for details\n3. Verify spec file format\n4. Ensure scenarios properly formatted\n\n### Missing Context\n1. Read project.md first\n2. Check related specs\n3. Review recent archives\n4. Ask for clarification\n\n## Quick Reference\n\n### Stage Indicators\n- `changes/` - Proposed, not yet built\n- `specs/` - Built and deployed\n- `archive/` - Completed changes\n\n### File Purposes\n- `proposal.md` - Why and what\n- `tasks.md` - Implementation steps\n- `design.md` - Technical decisions\n- `spec.md` - Requirements and behavior\n\n### CLI Essentials\n```bash\nopenspec list              # What's in progress?\nopenspec show [item]       # View details\nopenspec diff [change]     # What's changing?\nopenspec validate --strict # Is it correct?\nopenspec archive [change] [--yes|-y]  # Mark complete (add --yes for automation)\n```\n\nRemember: Specs are truth. Changes are proposals. Keep them in sync.\n";
 //# sourceMappingURL=agents-template.d.ts.map

package/dist/core/templates/agents-template.js

@@ -47,18 +47,20 @@ Skip proposal for:
 4. Run \`openspec validate <id> --strict\` and resolve any issues before sharing the proposal.
 
 ### Stage 2: Implementing Changes
+Track these steps as TODOs and complete them one by one.
 1. **Read proposal.md** - Understand what's being built
 2. **Read design.md** (if exists) - Review technical decisions
 3. **Read tasks.md** - Get implementation checklist
 4. **Implement tasks sequentially** - Complete in order
-5. **Mark complete immediately** - Update \`- [x]\` after each task
-6. **Approval gate** - Do not start implementation until the proposal is reviewed and approved
+5. **Confirm completion** - Ensure every item in \`tasks.md\` is finished before updating statuses
+6. **Update checklist** - After all work is done, set every task to \`- [x]\` so the list reflects reality
+7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved
 
 ### Stage 3: Archiving Changes
 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\` for tooling-only changes
+- Use \`openspec archive [change] --skip-specs --yes\` for tooling-only changes
 - Run \`openspec validate --strict\` to confirm the archived change passes checks
 
 ## Before Any Task
@@ -95,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]      # Archive after deployment
+openspec archive [change] [--yes|-y]      # Archive after deployment (add --yes for non-interactive runs)
 
 # Project management
 openspec init [path]           # Initialize OpenSpec
@@ -117,6 +119,7 @@ openspec validate [change] --strict
 - \`--strict\` - Comprehensive validation
 - \`--no-interactive\` - Disable prompts
 - \`--skip-specs\` - Archive without spec updates
+- \`--yes\`/\`-y\` - Skip confirmation prompts (non-interactive archive)
 
 ## Directory Structure
 
@@ -447,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]  # Mark complete
+openspec archive [change] [--yes|-y]  # Mark complete (add --yes for automation)
 \`\`\`
 
 Remember: Specs are truth. Changes are proposals. Keep them in sync.

package/dist/core/templates/slash-command-templates.js

@@ -16,15 +16,17 @@ const proposalReferences = `**Reference**
 - Search existing requirements with \`rg -n "Requirement:|Scenario:" openspec/specs\` before writing new ones.
 - Explore the codebase with \`rg <keyword>\`, \`ls\`, or direct file reads so proposals align with current implementation realities.`;
 const applySteps = `**Steps**
+Track these steps as TODOs and complete them one by one.
 1. Read \`changes/<id>/proposal.md\`, \`design.md\` (if present), and \`tasks.md\` to confirm scope and acceptance criteria.
 2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
-3. Mark each task \`- [x]\` immediately after completing it to keep the checklist in sync.
-4. Reference \`openspec list\` or \`openspec show <item>\` when additional context is required.`;
+3. Confirm completion before updating statuses—make sure every item in \`tasks.md\` is finished.
+4. Update the checklist after all work is done so each task is marked \`- [x]\` and reflects reality.
+5. Reference \`openspec list\` or \`openspec show <item>\` when additional context is required.`;
 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>\` to let the CLI move the change and apply spec updates (use \`--skip-specs\` only for tooling-only work).
+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.`;
 const archiveReferences = `**Reference**

package/dist/core/validation/validator.js

@@ -297,7 +297,8 @@ export class Validator {
         return msg;
     }
     extractNameFromPath(filePath) {
-        const parts = filePath.split('/');
+        const normalizedPath = filePath.replaceAll('\\', '/');
+        const parts = normalizedPath.split('/');
         // Look for the directory name after 'specs' or 'changes'
         for (let i = parts.length - 1; i >= 0; i--) {
             if (parts[i] === 'specs' || parts[i] === 'changes') {
@@ -307,8 +308,9 @@ export class Validator {
             }
         }
         // Fallback to filename without extension if not in expected structure
-        const fileName = parts[parts.length - 1];
-        return fileName.replace('.md', '');
+        const fileName = parts[parts.length - 1] ?? '';
+        const dotIndex = fileName.lastIndexOf('.');
+        return dotIndex > 0 ? fileName.slice(0, dotIndex) : fileName;
     }
     createReport(issues) {
         const errors = issues.filter(i => i.level === 'ERROR').length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -18,8 +18,7 @@
   "author": "OpenSpec Contributors",
   "type": "module",
   "publishConfig": {
-    "access": "public",
-    "tag": "next"
+    "access": "public"
   },
   "exports": {
     ".": {