@fission-ai/openspec 0.1.0 → 0.3.0

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

@@ -0,0 +1,37 @@
+import { SlashCommandConfigurator } from './base.js';
+const FILE_PATHS = {
+    proposal: '.claude/commands/openspec/proposal.md',
+    apply: '.claude/commands/openspec/apply.md',
+    archive: '.claude/commands/openspec/archive.md'
+};
+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]
+---`
+};
+export class ClaudeSlashCommandConfigurator extends SlashCommandConfigurator {
+    toolId = 'claude';
+    isAvailable = true;
+    getRelativePath(id) {
+        return FILE_PATHS[id];
+    }
+    getFrontmatter(id) {
+        return FRONTMATTER[id];
+    }
+}
+//# sourceMappingURL=claude.js.map

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

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

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

@@ -0,0 +1,37 @@
+import { SlashCommandConfigurator } from './base.js';
+const FILE_PATHS = {
+    proposal: '.cursor/commands/openspec-proposal.md',
+    apply: '.cursor/commands/openspec-apply.md',
+    archive: '.cursor/commands/openspec-archive.md'
+};
+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.
+---`
+};
+export class CursorSlashCommandConfigurator extends SlashCommandConfigurator {
+    toolId = 'cursor';
+    isAvailable = true;
+    getRelativePath(id) {
+        return FILE_PATHS[id];
+    }
+    getFrontmatter(id) {
+        return FRONTMATTER[id];
+    }
+}
+//# sourceMappingURL=cursor.js.map

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

@@ -0,0 +1,8 @@
+import { SlashCommandConfigurator } from './base.js';
+export declare class SlashCommandRegistry {
+    private static configurators;
+    static register(configurator: SlashCommandConfigurator): void;
+    static get(toolId: string): SlashCommandConfigurator | undefined;
+    static getAll(): SlashCommandConfigurator[];
+}
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1,21 @@
+import { ClaudeSlashCommandConfigurator } from './claude.js';
+import { CursorSlashCommandConfigurator } from './cursor.js';
+export class SlashCommandRegistry {
+    static configurators = new Map();
+    static {
+        const claude = new ClaudeSlashCommandConfigurator();
+        const cursor = new CursorSlashCommandConfigurator();
+        this.configurators.set(claude.toolId, claude);
+        this.configurators.set(cursor.toolId, cursor);
+    }
+    static register(configurator) {
+        this.configurators.set(configurator.toolId, configurator);
+    }
+    static get(toolId) {
+        return this.configurators.get(toolId);
+    }
+    static getAll() {
+        return Array.from(this.configurators.values());
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/init.d.ts

@@ -1,10 +1,38 @@
+type ToolLabel = {
+    primary: string;
+    annotation?: string;
+};
+type ToolWizardChoice = {
+    value: string;
+    label: ToolLabel;
+    configured: boolean;
+};
+type ToolWizardConfig = {
+    extendMode: boolean;
+    baseMessage: string;
+    choices: ToolWizardChoice[];
+    initialSelected?: string[];
+};
+type ToolSelectionPrompt = (config: ToolWizardConfig) => Promise<string[]>;
+type InitCommandOptions = {
+    prompt?: ToolSelectionPrompt;
+};
 export declare class InitCommand {
+    private readonly prompt;
+    constructor(options?: InitCommandOptions);
     execute(targetPath: string): Promise<void>;
     private validate;
     private getConfiguration;
+    private promptForAITools;
+    private getExistingToolStates;
+    private isToolConfigured;
     private createDirectoryStructure;
     private generateFiles;
     private configureAITools;
     private displaySuccessMessage;
+    private formatToolNames;
+    private renderBanner;
+    private startSpinner;
 }
+export {};
 //# sourceMappingURL=init.d.ts.map

package/dist/core/init.js

@@ -1,57 +1,335 @@
 import path from 'path';
-import { select } from '@inquirer/prompts';
+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';
+const PROGRESS_SPINNER = {
+    interval: 80,
+    frames: ['░░░', '▒░░', '▒▒░', '▒▒▒', '▓▒▒', '▓▓▒', '▓▓▓', '▒▓▓', '░▒▓']
+};
+const PALETTE = {
+    white: chalk.hex('#f4f4f4'),
+    lightGray: chalk.hex('#c8c8c8'),
+    midGray: chalk.hex('#8a8a8a'),
+    darkGray: chalk.hex('#4a4a4a')
+};
+const LETTER_MAP = {
+    O: [
+        ' ████ ',
+        '██  ██',
+        '██  ██',
+        '██  ██',
+        ' ████ '
+    ],
+    P: [
+        '█████ ',
+        '██  ██',
+        '█████ ',
+        '██    ',
+        '██    '
+    ],
+    E: [
+        '██████',
+        '██    ',
+        '█████ ',
+        '██    ',
+        '██████'
+    ],
+    N: [
+        '██  ██',
+        '███ ██',
+        '██ ███',
+        '██  ██',
+        '██  ██'
+    ],
+    S: [
+        ' █████',
+        '██    ',
+        ' ████ ',
+        '    ██',
+        '█████ '
+    ],
+    C: [
+        ' █████',
+        '██    ',
+        '██    ',
+        '██    ',
+        ' █████'
+    ],
+    ' ': [
+        '  ',
+        '  ',
+        '  ',
+        '  ',
+        '  '
+    ]
+};
+const sanitizeToolLabel = (raw) => raw.replace(/✅/gu, '✔').trim();
+const parseToolLabel = (raw) => {
+    const sanitized = sanitizeToolLabel(raw);
+    const match = sanitized.match(/^(.*?)\s*\((.+)\)$/u);
+    if (!match) {
+        return { primary: sanitized };
+    }
+    return {
+        primary: match[1].trim(),
+        annotation: match[2].trim()
+    };
+};
+const toolSelectionWizard = createPrompt((config, done) => {
+    const totalSteps = 3;
+    const [step, setStep] = useState('intro');
+    const [cursor, setCursor] = useState(0);
+    const [selected, setSelected] = useState(() => config.initialSelected ?? []);
+    const [error, setError] = useState(null);
+    const selectedSet = new Set(selected);
+    const pageSize = Math.max(Math.min(config.choices.length, 7), 1);
+    const updateSelected = (next) => {
+        const ordered = config.choices
+            .map((choice) => choice.value)
+            .filter((value) => next.has(value));
+        setSelected(ordered);
+    };
+    const page = usePagination({
+        items: config.choices,
+        active: cursor,
+        pageSize,
+        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 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') {
+            if (isEnterKey(key)) {
+                setStep('select');
+            }
+            return;
+        }
+        if (step === 'select') {
+            if (isUpKey(key)) {
+                const previousIndex = cursor <= 0 ? config.choices.length - 1 : cursor - 1;
+                setCursor(previousIndex);
+                setError(null);
+                return;
+            }
+            if (isDownKey(key)) {
+                const nextIndex = cursor >= config.choices.length - 1 ? 0 : cursor + 1;
+                setCursor(nextIndex);
+                setError(null);
+                return;
+            }
+            if (isSpaceKey(key)) {
+                const current = config.choices[cursor];
+                if (!current)
+                    return;
+                const next = new Set(selected);
+                if (next.has(current.value)) {
+                    next.delete(current.value);
+                }
+                else {
+                    next.add(current.value);
+                }
+                updateSelected(next);
+                setError(null);
+                return;
+            }
+            if (isEnterKey(key)) {
+                if (selected.length === 0) {
+                    setError('Select at least one AI tool to continue.');
+                    return;
+                }
+                setStep('review');
+                setError(null);
+                return;
+            }
+            if (key.name === 'escape') {
+                setSelected([]);
+                setError(null);
+            }
+            return;
+        }
+        if (step === 'review') {
+            if (isEnterKey(key)) {
+                const finalSelection = config.choices
+                    .map((choice) => choice.value)
+                    .filter((value) => selectedSet.has(value));
+                done(finalSelection);
+                return;
+            }
+            if (isBackspaceKey(key) || key.name === 'escape') {
+                setStep('select');
+                setError(null);
+            }
+        }
+    });
+    const selectedNames = config.choices
+        .filter((choice) => selectedSet.has(choice.value))
+        .map((choice) => choice.label.primary);
+    const stepIndex = step === 'intro' ? 1 : step === 'select' ? 2 : 3;
+    const lines = [];
+    lines.push(PALETTE.midGray(`Step ${stepIndex}/${totalSteps}`));
+    lines.push('');
+    if (step === 'intro') {
+        const introHeadline = config.extendMode
+            ? 'Extend your OpenSpec tooling'
+            : 'Configure your OpenSpec tooling';
+        const introBody = config.extendMode
+            ? 'We detected an existing setup. We will help you refresh or add integrations.'
+            : "Let's get your AI assistants connected so they understand OpenSpec.";
+        lines.push(PALETTE.white(introHeadline));
+        lines.push(PALETTE.midGray(introBody));
+        lines.push('');
+        lines.push(PALETTE.midGray('Press Enter to continue.'));
+    }
+    else if (step === 'select') {
+        lines.push(PALETTE.white(config.baseMessage));
+        lines.push(PALETTE.midGray('Use ↑/↓ to move · Space to toggle · Enter to review selections.'));
+        lines.push('');
+        lines.push(page);
+        lines.push('');
+        if (selectedNames.length === 0) {
+            lines.push(`${PALETTE.midGray('Selected')}: ${PALETTE.midGray('None selected yet')}`);
+        }
+        else {
+            lines.push(PALETTE.midGray('Selected:'));
+            selectedNames.forEach((name) => {
+                lines.push(`  ${PALETTE.white('-')} ${PALETTE.white(name)}`);
+            });
+        }
+    }
+    else {
+        lines.push(PALETTE.white('Review selections'));
+        lines.push(PALETTE.midGray('Press Enter to confirm or Backspace to adjust.'));
+        lines.push('');
+        if (selectedNames.length === 0) {
+            lines.push(PALETTE.midGray('No tools selected. Press Backspace to return.'));
+        }
+        else {
+            selectedNames.forEach((name) => {
+                lines.push(`${PALETTE.white('▌')} ${PALETTE.white(name)}`);
+            });
+        }
+    }
+    if (error) {
+        return [lines.join('\n'), chalk.red(error)];
+    }
+    return lines.join('\n');
+});
 export class InitCommand {
+    prompt;
+    constructor(options = {}) {
+        this.prompt = options.prompt ?? ((config) => toolSelectionWizard(config));
+    }
     async execute(targetPath) {
         const projectPath = path.resolve(targetPath);
         const openspecDir = OPENSPEC_DIR_NAME;
         const openspecPath = path.join(projectPath, openspecDir);
         // Validation happens silently in the background
-        await this.validate(projectPath, openspecPath);
+        const extendMode = await this.validate(projectPath, openspecPath);
+        const existingToolStates = await this.getExistingToolStates(projectPath);
+        this.renderBanner(extendMode);
         // Get configuration (after validation to avoid prompts if validation fails)
-        const config = await this.getConfiguration();
+        const config = await this.getConfiguration(existingToolStates, extendMode);
+        if (config.aiTools.length === 0) {
+            if (extendMode) {
+                throw new Error(`OpenSpec seems to already be initialized at ${openspecPath}.\n` +
+                    `Use 'openspec update' to update the structure.`);
+            }
+            throw new Error('You must select at least one AI tool to configure.');
+        }
+        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]);
         // Step 1: Create directory structure
-        const structureSpinner = ora({ text: 'Creating OpenSpec structure...', stream: process.stdout }).start();
-        await this.createDirectoryStructure(openspecPath);
-        await this.generateFiles(openspecPath, config);
-        structureSpinner.succeed('OpenSpec structure created');
+        if (!extendMode) {
+            const structureSpinner = this.startSpinner('Creating OpenSpec structure...');
+            await this.createDirectoryStructure(openspecPath);
+            await this.generateFiles(openspecPath, config);
+            structureSpinner.stopAndPersist({
+                symbol: PALETTE.white('▌'),
+                text: PALETTE.white('OpenSpec structure created')
+            });
+        }
+        else {
+            ora({ stream: process.stdout }).info(PALETTE.midGray('ℹ OpenSpec already initialized. Skipping base scaffolding.'));
+        }
         // Step 2: Configure AI tools
-        const toolSpinner = ora({ text: 'Configuring AI tools...', stream: process.stdout }).start();
+        const toolSpinner = this.startSpinner('Configuring AI tools...');
         await this.configureAITools(projectPath, openspecDir, config.aiTools);
-        toolSpinner.succeed('AI tools configured');
+        toolSpinner.stopAndPersist({
+            symbol: PALETTE.white('▌'),
+            text: PALETTE.white('AI tools configured')
+        });
         // Success message
-        this.displaySuccessMessage(openspecDir, config);
+        this.displaySuccessMessage(selectedTools, created, refreshed, skippedExisting, skipped, extendMode);
     }
-    async validate(projectPath, openspecPath) {
-        // Check if OpenSpec already exists
-        if (await FileSystemUtils.directoryExists(openspecPath)) {
-            throw new Error(`OpenSpec seems to already be initialized at ${openspecPath}.\n` +
-                `Use 'openspec update' to update the structure.`);
-        }
+    async validate(projectPath, _openspecPath) {
+        const extendMode = await FileSystemUtils.directoryExists(_openspecPath);
         // Check write permissions
         if (!await FileSystemUtils.ensureWritePermissions(projectPath)) {
             throw new Error(`Insufficient permissions to write to ${projectPath}`);
         }
+        return extendMode;
     }
-    async getConfiguration() {
-        const config = {
-            aiTools: []
-        };
-        // Single-select for better UX
-        const selectedTool = await select({
-            message: 'Which AI tool do you use?',
-            choices: AI_TOOLS.map(tool => ({
-                name: tool.available ? tool.name : `${tool.name} (coming soon)`,
+    async getConfiguration(existingTools, extendMode) {
+        const selectedTools = await this.promptForAITools(existingTools, extendMode);
+        return { aiTools: selectedTools };
+    }
+    async promptForAITools(existingTools, extendMode) {
+        const availableTools = AI_TOOLS.filter(tool => tool.available);
+        if (availableTools.length === 0) {
+            return [];
+        }
+        const baseMessage = extendMode
+            ? '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)
+            : [];
+        return this.prompt({
+            extendMode,
+            baseMessage,
+            choices: availableTools.map((tool) => ({
                 value: tool.value,
-                disabled: !tool.available
-            }))
+                label: parseToolLabel(tool.name),
+                configured: Boolean(existingTools[tool.value])
+            })),
+            initialSelected
         });
-        config.aiTools = [selectedTool];
-        return config;
+    }
+    async getExistingToolStates(projectPath) {
+        const states = {};
+        for (const tool of AI_TOOLS) {
+            states[tool.value] = await this.isToolConfigured(projectPath, tool.value);
+        }
+        return states;
+    }
+    async isToolConfigured(projectPath, toolId) {
+        const configFile = ToolRegistry.get(toolId)?.configFileName;
+        if (configFile && await FileSystemUtils.fileExists(path.join(projectPath, configFile)))
+            return true;
+        const slashConfigurator = SlashCommandRegistry.get(toolId);
+        if (!slashConfigurator)
+            return false;
+        for (const target of slashConfigurator.getTargets()) {
+            if (await FileSystemUtils.fileExists(path.join(projectPath, target.path)))
+                return true;
+        }
+        return false;
     }
     async createDirectoryStructure(openspecPath) {
         const directories = [
@@ -83,27 +361,89 @@ export class InitCommand {
             if (configurator && configurator.isAvailable) {
                 await configurator.configure(projectPath, openspecDir);
             }
+            const slashConfigurator = SlashCommandRegistry.get(toolId);
+            if (slashConfigurator && slashConfigurator.isAvailable) {
+                await slashConfigurator.generateAll(projectPath, openspecDir);
+            }
         }
     }
-    displaySuccessMessage(openspecDir, config) {
+    displaySuccessMessage(selectedTools, created, refreshed, skippedExisting, skipped, extendMode) {
         console.log(); // Empty line for spacing
-        ora().succeed('OpenSpec initialized successfully!');
-        // Get the selected tool name for display
-        const selectedToolId = config.aiTools[0];
-        const selectedTool = AI_TOOLS.find(t => t.value === selectedToolId);
-        const toolName = selectedTool ? selectedTool.name : 'your AI assistant';
-        console.log(`\nNext steps - Copy these prompts to ${toolName}:\n`);
-        console.log('────────────────────────────────────────────────────────────');
-        console.log('1. Populate your project context:');
-        console.log('   "Please read openspec/project.md and help me fill it out');
-        console.log('    with details about my project, tech stack, and conventions"\n');
-        console.log('2. Create your first change proposal:');
-        console.log('   "I want to add [YOUR FEATURE HERE]. Please create an');
-        console.log('    OpenSpec change proposal for this feature"\n');
-        console.log('3. Learn the OpenSpec workflow:');
-        console.log('   "Please explain the OpenSpec workflow from openspec/README.md');
-        console.log('    and how I should work with you on this project"');
-        console.log('────────────────────────────────────────────────────────────\n');
+        const successHeadline = extendMode
+            ? 'OpenSpec tool configuration updated!'
+            : 'OpenSpec initialized successfully!';
+        ora().succeed(PALETTE.white(successHeadline));
+        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
+        ].filter((line) => Boolean(line));
+        for (const line of summaryLines) {
+            console.log(line);
+        }
+        console.log();
+        console.log(PALETTE.midGray('Use `openspec update` to refresh shared OpenSpec instructions in the future.'));
+        // Get the selected tool name(s) for display
+        const toolName = this.formatToolNames(selectedTools);
+        console.log();
+        console.log(`Next steps - Copy these prompts to ${toolName}:`);
+        console.log(chalk.gray('────────────────────────────────────────────────────────────'));
+        console.log(PALETTE.white('1. Populate your project context:'));
+        console.log(PALETTE.lightGray('   "Please read openspec/project.md and help me fill it out'));
+        console.log(PALETTE.lightGray('    with details about my project, tech stack, and conventions"\n'));
+        console.log(PALETTE.white('2. Create your first change proposal:'));
+        console.log(PALETTE.lightGray('   "I want to add [YOUR FEATURE HERE]. Please create an'));
+        console.log(PALETTE.lightGray('    OpenSpec change proposal for this feature"\n'));
+        console.log(PALETTE.white('3. Learn the OpenSpec workflow:'));
+        console.log(PALETTE.lightGray('   "Please explain the OpenSpec workflow from openspec/AGENTS.md'));
+        console.log(PALETTE.lightGray('    and how I should work with you on this project"'));
+        console.log(PALETTE.darkGray('────────────────────────────────────────────────────────────\n'));
+    }
+    formatToolNames(tools) {
+        const names = tools
+            .map((tool) => tool.successLabel ?? tool.name)
+            .filter((name) => Boolean(name));
+        if (names.length === 0)
+            return PALETTE.lightGray('your AI assistant');
+        if (names.length === 1)
+            return PALETTE.white(names[0]);
+        const base = names.slice(0, -1).map((name) => PALETTE.white(name));
+        const last = PALETTE.white(names[names.length - 1]);
+        return `${base.join(PALETTE.midGray(', '))}${base.length ? PALETTE.midGray(', and ') : ''}${last}`;
+    }
+    renderBanner(_extendMode) {
+        const rows = ['', '', '', '', ''];
+        for (const char of 'OPENSPEC') {
+            const glyph = LETTER_MAP[char] ?? LETTER_MAP[' '];
+            for (let i = 0; i < rows.length; i += 1) {
+                rows[i] += `${glyph[i]}  `;
+            }
+        }
+        const rowStyles = [
+            PALETTE.white,
+            PALETTE.lightGray,
+            PALETTE.midGray,
+            PALETTE.lightGray,
+            PALETTE.white
+        ];
+        console.log();
+        rows.forEach((row, index) => {
+            console.log(rowStyles[index](row.replace(/\s+$/u, '')));
+        });
+        console.log();
+        console.log(PALETTE.white('Welcome to OpenSpec!'));
+        console.log();
+    }
+    startSpinner(text) {
+        return ora({
+            text,
+            stream: process.stdout,
+            color: 'gray',
+            spinner: PROGRESS_SPINNER
+        }).start();
     }
 }
 //# sourceMappingURL=init.js.map

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

@@ -0,0 +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";
+//# sourceMappingURL=agents-template.d.ts.map