@fission-ai/openspec 0.12.0 → 0.14.0

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

@@ -1,4 +1,6 @@
 import { SlashCommandConfigurator } from "./base.js";
+import { FileSystemUtils } from "../../../utils/file-system.js";
+import { OPENSPEC_MARKERS } from "../../config.js";
 const FILE_PATHS = {
     proposal: ".opencode/command/openspec-proposal.md",
     apply: ".opencode/command/openspec-apply.md",
@@ -17,11 +19,20 @@ The user has requested the following change proposal. Use the openspec instructi
     apply: `---
 agent: build
 description: Implement an approved OpenSpec change and keep tasks in sync.
----`,
+---
+The user has requested to implement the following change proposal. Find the change proposal and follow the instructions below. If you're not sure or if ambiguous, ask for clarification from the user.
+<UserRequest>
+  $ARGUMENTS
+</UserRequest>
+`,
     archive: `---
 agent: build
 description: Archive a deployed OpenSpec change and update specs.
----`,
+---
+<ChangeId>
+  $ARGUMENTS
+</ChangeId>
+`,
 };
 export class OpenCodeSlashCommandConfigurator extends SlashCommandConfigurator {
     toolId = "opencode";
@@ -32,5 +43,33 @@ export class OpenCodeSlashCommandConfigurator extends SlashCommandConfigurator {
     getFrontmatter(id) {
         return FRONTMATTER[id];
     }
+    async generateAll(projectPath, _openspecDir) {
+        const createdOrUpdated = await super.generateAll(projectPath, _openspecDir);
+        await this.rewriteArchiveFile(projectPath);
+        return createdOrUpdated;
+    }
+    async updateExisting(projectPath, _openspecDir) {
+        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;
+    }
+    async rewriteArchiveFile(projectPath) {
+        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 = [];
+        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;
+    }
 }
 //# sourceMappingURL=opencode.js.map

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

@@ -0,0 +1,35 @@
+import { SlashCommandConfigurator } from './base.js';
+import { SlashCommandId } from '../../templates/index.js';
+/**
+ * Qoder Slash Command Configurator
+ *
+ * Manages OpenSpec slash commands for Qoder AI assistant.
+ * Creates three workflow commands: proposal, apply, and archive.
+ * Uses colon-separated command format (/openspec:proposal).
+ *
+ * @extends {SlashCommandConfigurator}
+ */
+export declare class QoderSlashCommandConfigurator extends SlashCommandConfigurator {
+    /** Unique identifier for Qoder tool */
+    readonly toolId = "qoder";
+    /** Indicates slash commands are available for this tool */
+    readonly isAvailable = true;
+    /**
+     * Get relative file path for a slash command
+     *
+     * @param {SlashCommandId} id - Command identifier (proposal, apply, or archive)
+     * @returns {string} Relative path from project root to command file
+     */
+    protected getRelativePath(id: SlashCommandId): string;
+    /**
+     * Get YAML frontmatter for a slash command
+     *
+     * Frontmatter defines how the command appears in Qoder's UI,
+     * including display name, description, and categorization.
+     *
+     * @param {SlashCommandId} id - Command identifier (proposal, apply, or archive)
+     * @returns {string} YAML frontmatter block with command metadata
+     */
+    protected getFrontmatter(id: SlashCommandId): string;
+}
+//# sourceMappingURL=qoder.d.ts.map

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

@@ -0,0 +1,76 @@
+import { SlashCommandConfigurator } from './base.js';
+/**
+ * File paths for Qoder slash commands
+ * Maps each OpenSpec workflow stage to its command file location
+ * Commands are stored in .qoder/commands/openspec/ directory
+ */
+const FILE_PATHS = {
+    // Create and validate new change proposals
+    proposal: '.qoder/commands/openspec/proposal.md',
+    // Implement approved changes with task tracking
+    apply: '.qoder/commands/openspec/apply.md',
+    // Archive completed changes and update specs
+    archive: '.qoder/commands/openspec/archive.md'
+};
+/**
+ * YAML frontmatter for Qoder slash commands
+ * Defines metadata displayed in Qoder's command palette
+ * Each command is categorized and tagged for easy discovery
+ */
+const FRONTMATTER = {
+    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]
+---`
+};
+/**
+ * Qoder Slash Command Configurator
+ *
+ * Manages OpenSpec slash commands for Qoder AI assistant.
+ * Creates three workflow commands: proposal, apply, and archive.
+ * Uses colon-separated command format (/openspec:proposal).
+ *
+ * @extends {SlashCommandConfigurator}
+ */
+export class QoderSlashCommandConfigurator extends SlashCommandConfigurator {
+    /** Unique identifier for Qoder tool */
+    toolId = 'qoder';
+    /** Indicates slash commands are available for this tool */
+    isAvailable = true;
+    /**
+     * Get relative file path for a slash command
+     *
+     * @param {SlashCommandId} id - Command identifier (proposal, apply, or archive)
+     * @returns {string} Relative path from project root to command file
+     */
+    getRelativePath(id) {
+        return FILE_PATHS[id];
+    }
+    /**
+     * Get YAML frontmatter for a slash command
+     *
+     * Frontmatter defines how the command appears in Qoder's UI,
+     * including display name, description, and categorization.
+     *
+     * @param {SlashCommandId} id - Command identifier (proposal, apply, or archive)
+     * @returns {string} YAML frontmatter block with command metadata
+     */
+    getFrontmatter(id) {
+        return FRONTMATTER[id];
+    }
+}
+//# sourceMappingURL=qoder.js.map

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

@@ -0,0 +1,37 @@
+/**
+ * Qwen slash command configurator for OpenSpec integration.
+ * This class handles the generation of Qwen-specific slash command files
+ * in the .qwen/commands directory structure.
+ *
+ * @implements {SlashCommandConfigurator}
+ */
+import { SlashCommandConfigurator } from './base.js';
+import { SlashCommandId } from '../../templates/index.js';
+/**
+ * QwenSlashCommandConfigurator class provides integration with Qwen Code
+ * by creating the necessary slash command files in the .qwen/commands directory.
+ *
+ * The slash commands include:
+ * - /openspec-proposal: Create an OpenSpec change proposal
+ * - /openspec-apply: Apply an approved OpenSpec change
+ * - /openspec-archive: Archive a deployed OpenSpec change
+ */
+export declare class QwenSlashCommandConfigurator extends SlashCommandConfigurator {
+    /** Unique identifier for the Qwen tool */
+    readonly toolId = "qwen";
+    /** Availability status for the Qwen tool */
+    readonly isAvailable = true;
+    /**
+     * Returns the relative file path for a given slash command ID.
+     * @param {SlashCommandId} id - The slash command identifier
+     * @returns {string} The relative path to the command file
+     */
+    protected getRelativePath(id: SlashCommandId): string;
+    /**
+     * Returns the YAML frontmatter for a given slash command ID.
+     * @param {SlashCommandId} id - The slash command identifier
+     * @returns {string} The YAML frontmatter string
+     */
+    protected getFrontmatter(id: SlashCommandId): string;
+}
+//# sourceMappingURL=qwen.d.ts.map

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

@@ -0,0 +1,74 @@
+/**
+ * Qwen slash command configurator for OpenSpec integration.
+ * This class handles the generation of Qwen-specific slash command files
+ * in the .qwen/commands directory structure.
+ *
+ * @implements {SlashCommandConfigurator}
+ */
+import { SlashCommandConfigurator } from './base.js';
+/**
+ * Mapping of slash command IDs to their corresponding file paths in .qwen/commands directory.
+ * @type {Record<SlashCommandId, string>}
+ */
+const FILE_PATHS = {
+    proposal: '.qwen/commands/openspec-proposal.md',
+    apply: '.qwen/commands/openspec-apply.md',
+    archive: '.qwen/commands/openspec-archive.md'
+};
+/**
+ * YAML frontmatter definitions for Qwen command files.
+ * These provide metadata for each slash command to ensure proper recognition by Qwen Code.
+ * @type {Record<SlashCommandId, string>}
+ */
+const FRONTMATTER = {
+    proposal: `---
+name: /openspec-proposal
+id: openspec-proposal
+category: OpenSpec
+description: Scaffold a new OpenSpec change and validate strictly.
+---`,
+    apply: `---
+name: /openspec-apply
+id: openspec-apply
+category: OpenSpec
+description: Implement an approved OpenSpec change and keep tasks in sync.
+---`,
+    archive: `---
+name: /openspec-archive
+id: openspec-archive
+category: OpenSpec
+description: Archive a deployed OpenSpec change and update specs.
+---`
+};
+/**
+ * QwenSlashCommandConfigurator class provides integration with Qwen Code
+ * by creating the necessary slash command files in the .qwen/commands directory.
+ *
+ * The slash commands include:
+ * - /openspec-proposal: Create an OpenSpec change proposal
+ * - /openspec-apply: Apply an approved OpenSpec change
+ * - /openspec-archive: Archive a deployed OpenSpec change
+ */
+export class QwenSlashCommandConfigurator extends SlashCommandConfigurator {
+    /** Unique identifier for the Qwen tool */
+    toolId = 'qwen';
+    /** Availability status for the Qwen tool */
+    isAvailable = true;
+    /**
+     * Returns the relative file path for a given slash command ID.
+     * @param {SlashCommandId} id - The slash command identifier
+     * @returns {string} The relative path to the command file
+     */
+    getRelativePath(id) {
+        return FILE_PATHS[id];
+    }
+    /**
+     * Returns the YAML frontmatter for a given slash command ID.
+     * @param {SlashCommandId} id - The slash command identifier
+     * @returns {string} The YAML frontmatter string
+     */
+    getFrontmatter(id) {
+        return FRONTMATTER[id];
+    }
+}
+//# sourceMappingURL=qwen.js.map

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

@@ -1,4 +1,6 @@
 import { ClaudeSlashCommandConfigurator } from './claude.js';
+import { CodeBuddySlashCommandConfigurator } from './codebuddy.js';
+import { QoderSlashCommandConfigurator } from './qoder.js';
 import { CursorSlashCommandConfigurator } from './cursor.js';
 import { WindsurfSlashCommandConfigurator } from './windsurf.js';
 import { KiloCodeSlashCommandConfigurator } from './kilocode.js';
@@ -7,10 +9,17 @@ 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 { ClineSlashCommandConfigurator } from './cline.js';
+import { CrushSlashCommandConfigurator } from './crush.js';
+import { CostrictSlashCommandConfigurator } from './costrict.js';
+import { QwenSlashCommandConfigurator } from './qwen.js';
 export class SlashCommandRegistry {
     static configurators = new Map();
     static {
         const claude = new ClaudeSlashCommandConfigurator();
+        const codeBuddy = new CodeBuddySlashCommandConfigurator();
+        const qoder = new QoderSlashCommandConfigurator();
         const cursor = new CursorSlashCommandConfigurator();
         const windsurf = new WindsurfSlashCommandConfigurator();
         const kilocode = new KiloCodeSlashCommandConfigurator();
@@ -19,7 +28,14 @@ export class SlashCommandRegistry {
         const githubCopilot = new GitHubCopilotSlashCommandConfigurator();
         const amazonQ = new AmazonQSlashCommandConfigurator();
         const factory = new FactorySlashCommandConfigurator();
+        const auggie = new AuggieSlashCommandConfigurator();
+        const cline = new ClineSlashCommandConfigurator();
+        const crush = new CrushSlashCommandConfigurator();
+        const costrict = new CostrictSlashCommandConfigurator();
+        const qwen = new QwenSlashCommandConfigurator();
         this.configurators.set(claude.toolId, claude);
+        this.configurators.set(codeBuddy.toolId, codeBuddy);
+        this.configurators.set(qoder.toolId, qoder);
         this.configurators.set(cursor.toolId, cursor);
         this.configurators.set(windsurf.toolId, windsurf);
         this.configurators.set(kilocode.toolId, kilocode);
@@ -28,6 +44,11 @@ export class SlashCommandRegistry {
         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(cline.toolId, cline);
+        this.configurators.set(crush.toolId, crush);
+        this.configurators.set(costrict.toolId, costrict);
+        this.configurators.set(qwen.toolId, qwen);
     }
     static register(configurator) {
         this.configurators.set(configurator.toolId, configurator);

package/dist/core/init.d.ts

@@ -39,6 +39,8 @@ export declare class InitCommand {
     private isToolConfigured;
     private createDirectoryStructure;
     private generateFiles;
+    private ensureTemplateFiles;
+    private writeTemplateFiles;
     private configureAITools;
     private configureRootAgentsStub;
     private displaySuccessMessage;

package/dist/core/init.js

@@ -6,7 +6,7 @@ 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, OPENSPEC_MARKERS, } from './config.js';
 import { PALETTE } from './styles/palette.js';
 const PROGRESS_SPINNER = {
     interval: 80,
@@ -254,7 +254,7 @@ export class InitCommand {
         const openspecPath = path.join(projectPath, openspecDir);
         // Validation happens silently in the background
         const extendMode = await this.validate(projectPath, openspecPath);
-        const existingToolStates = await this.getExistingToolStates(projectPath);
+        const existingToolStates = await this.getExistingToolStates(projectPath, extendMode);
         this.renderBanner(extendMode);
         // Get configuration (after validation to avoid prompts if validation fails)
         const config = await this.getConfiguration(existingToolStates, extendMode);
@@ -276,7 +276,9 @@ export class InitCommand {
             });
         }
         else {
-            ora({ stream: process.stdout }).info(PALETTE.midGray('ℹ OpenSpec already initialized. Skipping base scaffolding.'));
+            ora({ stream: process.stdout }).info(PALETTE.midGray('ℹ OpenSpec already initialized. Checking for missing files...'));
+            await this.createDirectoryStructure(openspecPath);
+            await this.ensureTemplateFiles(openspecPath, config);
         }
         // Step 2: Configure AI tools
         const toolSpinner = this.startSpinner('Configuring AI tools...');
@@ -413,25 +415,64 @@ export class InitCommand {
             initialSelected,
         });
     }
-    async getExistingToolStates(projectPath) {
-        const states = {};
-        for (const tool of AI_TOOLS) {
-            states[tool.value] = await this.isToolConfigured(projectPath, tool.value);
+    async getExistingToolStates(projectPath, extendMode) {
+        // Fresh initialization - no tools configured yet
+        if (!extendMode) {
+            return Object.fromEntries(AI_TOOLS.map(t => [t.value, false]));
         }
-        return states;
+        // Extend mode - check all tools in parallel for better performance
+        const entries = await Promise.all(AI_TOOLS.map(async (t) => [t.value, await this.isToolConfigured(projectPath, t.value)]));
+        return Object.fromEntries(entries);
     }
     async isToolConfigured(projectPath, toolId) {
+        // A tool is only considered "configured by OpenSpec" if its files contain OpenSpec markers.
+        // For tools with both config files and slash commands, BOTH must have markers.
+        // For slash commands, at least one file with markers is sufficient (not all required).
+        // Helper to check if a file exists and contains OpenSpec markers
+        const fileHasMarkers = async (absolutePath) => {
+            try {
+                const content = await FileSystemUtils.readFile(absolutePath);
+                return content.includes(OPENSPEC_MARKERS.start) && content.includes(OPENSPEC_MARKERS.end);
+            }
+            catch {
+                return false;
+            }
+        };
+        let hasConfigFile = false;
+        let hasSlashCommands = false;
+        // Check if the tool has a config file with OpenSpec markers
         const configFile = ToolRegistry.get(toolId)?.configFileName;
-        if (configFile &&
-            (await FileSystemUtils.fileExists(path.join(projectPath, configFile))))
-            return true;
+        if (configFile) {
+            const configPath = path.join(projectPath, configFile);
+            hasConfigFile = (await FileSystemUtils.fileExists(configPath)) && (await fileHasMarkers(configPath));
+        }
+        // Check if any slash command file exists with OpenSpec markers
         const slashConfigurator = SlashCommandRegistry.get(toolId);
-        if (!slashConfigurator)
-            return false;
-        for (const target of slashConfigurator.getTargets()) {
-            const absolute = slashConfigurator.resolveAbsolutePath(projectPath, target.id);
-            if (await FileSystemUtils.fileExists(absolute))
-                return true;
+        if (slashConfigurator) {
+            for (const target of slashConfigurator.getTargets()) {
+                const absolute = slashConfigurator.resolveAbsolutePath(projectPath, target.id);
+                if ((await FileSystemUtils.fileExists(absolute)) && (await fileHasMarkers(absolute))) {
+                    hasSlashCommands = true;
+                    break; // At least one file with markers is sufficient
+                }
+            }
+        }
+        // Tool is only configured if BOTH exist with markers
+        // OR if the tool has no config file requirement (slash commands only)
+        // OR if the tool has no slash commands requirement (config file only)
+        const hasConfigFileRequirement = configFile !== undefined;
+        const hasSlashCommandRequirement = slashConfigurator !== undefined;
+        if (hasConfigFileRequirement && hasSlashCommandRequirement) {
+            // Both are required - both must be present with markers
+            return hasConfigFile && hasSlashCommands;
+        }
+        else if (hasConfigFileRequirement) {
+            // Only config file required
+            return hasConfigFile;
+        }
+        else if (hasSlashCommandRequirement) {
+            // Only slash commands required
+            return hasSlashCommands;
         }
         return false;
     }
@@ -447,12 +488,22 @@ export class InitCommand {
         }
     }
     async generateFiles(openspecPath, config) {
+        await this.writeTemplateFiles(openspecPath, config, false);
+    }
+    async ensureTemplateFiles(openspecPath, config) {
+        await this.writeTemplateFiles(openspecPath, config, true);
+    }
+    async writeTemplateFiles(openspecPath, config, skipExisting) {
         const context = {
         // Could be enhanced with prompts for project details
         };
         const templates = TemplateManager.getTemplates(context);
         for (const template of templates) {
             const filePath = path.join(openspecPath, template.path);
+            // Skip if file exists and we're in skipExisting mode
+            if (skipExisting && (await FileSystemUtils.fileExists(filePath))) {
+                continue;
+            }
             const content = typeof template.content === 'function'
                 ? template.content(context)
                 : template.content;

package/dist/core/parsers/requirement-blocks.d.ts

@@ -23,6 +23,12 @@ export interface DeltaPlan {
         from: string;
         to: string;
     }>;
+    sectionPresence: {
+        added: boolean;
+        modified: boolean;
+        removed: boolean;
+        renamed: boolean;
+    };
 }
 /**
  * Parse a delta-formatted spec change file content into a DeltaPlan with raw blocks.

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

@@ -80,11 +80,26 @@ function normalizeLineEndings(content) {
 export function parseDeltaSpec(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'] || '');
-    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) {
     const lines = content.split('\n');
@@ -105,6 +120,14 @@ function splitTopLevelSections(content) {
     }
     return result;
 }
+function getSectionCaseInsensitive(sections, desired) {
+    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) {
     if (!sectionBody)
         return [];

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\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";
+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-id> --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly)\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 validate [item]       # Validate changes or specs\nopenspec archive <change-id> [--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# Change: [Brief description of change]\n\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 validate --strict # Is it correct?\nopenspec archive <change-id> [--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