@fission-ai/openspec 0.1.0 → 0.3.0

package/dist/core/update.js

@@ -1,8 +1,10 @@
 import path from 'path';
 import { FileSystemUtils } from '../utils/file-system.js';
-import { OPENSPEC_DIR_NAME } from './config.js';
-import { readmeTemplate } from './templates/readme-template.js';
+import { OPENSPEC_DIR_NAME, OPENSPEC_MARKERS } from './config.js';
+import { agentsTemplate } from './templates/agents-template.js';
+import { TemplateManager } from './templates/index.js';
 import { ToolRegistry } from './configurators/registry.js';
+import { SlashCommandRegistry } from './configurators/slash/registry.js';
 export class UpdateCommand {
     async execute(projectPath) {
         const resolvedProjectPath = path.resolve(projectPath);
@@ -12,18 +14,28 @@ export class UpdateCommand {
         if (!await FileSystemUtils.directoryExists(openspecPath)) {
             throw new Error(`No OpenSpec directory found. Run 'openspec init' first.`);
         }
-        // 2. Update README.md (full replacement)
-        const readmePath = path.join(openspecPath, 'README.md');
-        await FileSystemUtils.writeFile(readmePath, readmeTemplate);
+        // 2. Update AGENTS.md (full replacement)
+        const agentsPath = path.join(openspecPath, 'AGENTS.md');
+        const rootAgentsPath = path.join(resolvedProjectPath, 'AGENTS.md');
+        const rootAgentsExisted = await FileSystemUtils.fileExists(rootAgentsPath);
+        await FileSystemUtils.writeFile(agentsPath, agentsTemplate);
+        const agentsStandardContent = TemplateManager.getAgentsStandardTemplate();
+        await FileSystemUtils.updateFileWithMarkers(rootAgentsPath, agentsStandardContent, OPENSPEC_MARKERS.start, OPENSPEC_MARKERS.end);
         // 3. Update existing AI tool configuration files only
         const configurators = ToolRegistry.getAll();
+        const slashConfigurators = SlashCommandRegistry.getAll();
         let updatedFiles = [];
         let failedFiles = [];
+        let updatedSlashFiles = [];
+        let failedSlashTools = [];
         for (const configurator of configurators) {
             const configFilePath = path.join(resolvedProjectPath, configurator.configFileName);
             // Only update if the file already exists
             if (await FileSystemUtils.fileExists(configFilePath)) {
                 try {
+                    if (!await FileSystemUtils.canWriteFile(configFilePath)) {
+                        throw new Error(`Insufficient permissions to modify ${configurator.configFileName}`);
+                    }
                     await configurator.configure(resolvedProjectPath, openspecPath);
                     updatedFiles.push(configurator.configFileName);
                 }
@@ -33,14 +45,35 @@ export class UpdateCommand {
                 }
             }
         }
+        for (const slashConfigurator of slashConfigurators) {
+            if (!slashConfigurator.isAvailable) {
+                continue;
+            }
+            try {
+                const updated = await slashConfigurator.updateExisting(resolvedProjectPath, openspecPath);
+                updatedSlashFiles = updatedSlashFiles.concat(updated);
+            }
+            catch (error) {
+                failedSlashTools.push(slashConfigurator.toolId);
+                console.error(`Failed to update slash commands for ${slashConfigurator.toolId}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         // 4. Success message (ASCII-safe)
-        const messages = ['Updated OpenSpec instructions (README.md)'];
+        const instructionUpdates = ['openspec/AGENTS.md'];
+        instructionUpdates.push(`AGENTS.md${rootAgentsExisted ? '' : ' (created)'}`);
+        const messages = [`Updated OpenSpec instructions (${instructionUpdates.join(', ')})`];
         if (updatedFiles.length > 0) {
             messages.push(`Updated AI tool files: ${updatedFiles.join(', ')}`);
         }
+        if (updatedSlashFiles.length > 0) {
+            messages.push(`Updated slash commands: ${updatedSlashFiles.join(', ')}`);
+        }
         if (failedFiles.length > 0) {
             messages.push(`Failed to update: ${failedFiles.join(', ')}`);
         }
+        if (failedSlashTools.length > 0) {
+            messages.push(`Failed slash command updates: ${failedSlashTools.join(', ')}`);
+        }
         console.log(messages.join('\n'));
     }
 }

package/dist/core/view.d.ts

@@ -0,0 +1,8 @@
+export declare class ViewCommand {
+    execute(targetPath?: string): Promise<void>;
+    private getChangesData;
+    private getSpecsData;
+    private displaySummary;
+    private createProgressBar;
+}
+//# sourceMappingURL=view.d.ts.map

package/dist/core/view.js

@@ -0,0 +1,148 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import chalk from 'chalk';
+import { getTaskProgressForChange } from '../utils/task-progress.js';
+import { MarkdownParser } from './parsers/markdown-parser.js';
+export class ViewCommand {
+    async execute(targetPath = '.') {
+        const openspecDir = path.join(targetPath, 'openspec');
+        if (!fs.existsSync(openspecDir)) {
+            console.error(chalk.red('No openspec directory found'));
+            process.exit(1);
+        }
+        console.log(chalk.bold('\nOpenSpec Dashboard\n'));
+        console.log('═'.repeat(60));
+        // Get changes and specs data
+        const changesData = await this.getChangesData(openspecDir);
+        const specsData = await this.getSpecsData(openspecDir);
+        // Display summary metrics
+        this.displaySummary(changesData, specsData);
+        // Display active changes
+        if (changesData.active.length > 0) {
+            console.log(chalk.bold.cyan('\nActive Changes'));
+            console.log('─'.repeat(60));
+            changesData.active.forEach(change => {
+                const progressBar = this.createProgressBar(change.progress.completed, change.progress.total);
+                const percentage = change.progress.total > 0
+                    ? Math.round((change.progress.completed / change.progress.total) * 100)
+                    : 0;
+                console.log(`  ${chalk.yellow('◉')} ${chalk.bold(change.name.padEnd(30))} ${progressBar} ${chalk.dim(`${percentage}%`)}`);
+            });
+        }
+        // Display completed changes
+        if (changesData.completed.length > 0) {
+            console.log(chalk.bold.green('\nCompleted Changes'));
+            console.log('─'.repeat(60));
+            changesData.completed.forEach(change => {
+                console.log(`  ${chalk.green('✓')} ${change.name}`);
+            });
+        }
+        // Display specifications
+        if (specsData.length > 0) {
+            console.log(chalk.bold.blue('\nSpecifications'));
+            console.log('─'.repeat(60));
+            // Sort specs by requirement count (descending)
+            specsData.sort((a, b) => b.requirementCount - a.requirementCount);
+            specsData.forEach(spec => {
+                const reqLabel = spec.requirementCount === 1 ? 'requirement' : 'requirements';
+                console.log(`  ${chalk.blue('▪')} ${chalk.bold(spec.name.padEnd(30))} ${chalk.dim(`${spec.requirementCount} ${reqLabel}`)}`);
+            });
+        }
+        console.log('\n' + '═'.repeat(60));
+        console.log(chalk.dim(`\nUse ${chalk.white('openspec list --changes')} or ${chalk.white('openspec list --specs')} for detailed views`));
+    }
+    async getChangesData(openspecDir) {
+        const changesDir = path.join(openspecDir, 'changes');
+        if (!fs.existsSync(changesDir)) {
+            return { active: [], completed: [] };
+        }
+        const active = [];
+        const completed = [];
+        const entries = fs.readdirSync(changesDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory() && entry.name !== 'archive') {
+                const progress = await getTaskProgressForChange(changesDir, entry.name);
+                if (progress.total === 0 || progress.completed === progress.total) {
+                    completed.push({ name: entry.name });
+                }
+                else {
+                    active.push({ name: entry.name, progress });
+                }
+            }
+        }
+        // Sort active changes by completion percentage (ascending) and then by name for deterministic ordering
+        active.sort((a, b) => {
+            const percentageA = a.progress.total > 0 ? a.progress.completed / a.progress.total : 0;
+            const percentageB = b.progress.total > 0 ? b.progress.completed / b.progress.total : 0;
+            if (percentageA < percentageB)
+                return -1;
+            if (percentageA > percentageB)
+                return 1;
+            return a.name.localeCompare(b.name);
+        });
+        completed.sort((a, b) => a.name.localeCompare(b.name));
+        return { active, completed };
+    }
+    async getSpecsData(openspecDir) {
+        const specsDir = path.join(openspecDir, 'specs');
+        if (!fs.existsSync(specsDir)) {
+            return [];
+        }
+        const specs = [];
+        const entries = fs.readdirSync(specsDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const specFile = path.join(specsDir, entry.name, 'spec.md');
+                if (fs.existsSync(specFile)) {
+                    try {
+                        const content = fs.readFileSync(specFile, 'utf-8');
+                        const parser = new MarkdownParser(content);
+                        const spec = parser.parseSpec(entry.name);
+                        const requirementCount = spec.requirements.length;
+                        specs.push({ name: entry.name, requirementCount });
+                    }
+                    catch (error) {
+                        // If spec cannot be parsed, include with 0 count
+                        specs.push({ name: entry.name, requirementCount: 0 });
+                    }
+                }
+            }
+        }
+        return specs;
+    }
+    displaySummary(changesData, specsData) {
+        const totalChanges = changesData.active.length + changesData.completed.length;
+        const totalSpecs = specsData.length;
+        const totalRequirements = specsData.reduce((sum, spec) => sum + spec.requirementCount, 0);
+        // Calculate total task progress
+        let totalTasks = 0;
+        let completedTasks = 0;
+        changesData.active.forEach(change => {
+            totalTasks += change.progress.total;
+            completedTasks += change.progress.completed;
+        });
+        changesData.completed.forEach(() => {
+            // Completed changes count as 100% done (we don't know exact task count)
+            // This is a simplification
+        });
+        console.log(chalk.bold('Summary:'));
+        console.log(`  ${chalk.cyan('●')} Specifications: ${chalk.bold(totalSpecs)} specs, ${chalk.bold(totalRequirements)} requirements`);
+        console.log(`  ${chalk.yellow('●')} Active Changes: ${chalk.bold(changesData.active.length)} in progress`);
+        console.log(`  ${chalk.green('●')} Completed Changes: ${chalk.bold(changesData.completed.length)}`);
+        if (totalTasks > 0) {
+            const overallProgress = Math.round((completedTasks / totalTasks) * 100);
+            console.log(`  ${chalk.magenta('●')} Task Progress: ${chalk.bold(`${completedTasks}/${totalTasks}`)} (${overallProgress}% complete)`);
+        }
+    }
+    createProgressBar(completed, total, width = 20) {
+        if (total === 0)
+            return chalk.dim('─'.repeat(width));
+        const percentage = completed / total;
+        const filled = Math.round(percentage * width);
+        const empty = width - filled;
+        const filledBar = chalk.green('█'.repeat(filled));
+        const emptyBar = chalk.dim('░'.repeat(empty));
+        return `[${filledBar}${emptyBar}]`;
+    }
+}
+//# sourceMappingURL=view.js.map

package/dist/utils/file-system.d.ts

@@ -1,6 +1,7 @@
 export declare class FileSystemUtils {
     static createDirectory(dirPath: string): Promise<void>;
     static fileExists(filePath: string): Promise<boolean>;
+    static canWriteFile(filePath: string): Promise<boolean>;
     static directoryExists(dirPath: string): Promise<boolean>;
     static writeFile(filePath: string, content: string): Promise<void>;
     static readFile(filePath: string): Promise<string>;

package/dist/utils/file-system.js

@@ -16,6 +16,22 @@ export class FileSystemUtils {
             return false;
         }
     }
+    static async canWriteFile(filePath) {
+        try {
+            const stats = await fs.stat(filePath);
+            if (!stats.isFile()) {
+                return true;
+            }
+            return (stats.mode & 0o222) !== 0;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return true;
+            }
+            console.debug(`Unable to determine write permissions for ${filePath}: ${error.message}`);
+            return false;
+        }
+    }
     static async directoryExists(dirPath) {
         try {
             const stats = await fs.stat(dirPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -48,10 +48,10 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
+    "@inquirer/core": "^10.2.2",
     "@inquirer/prompts": "^7.8.0",
     "chalk": "^5.5.0",
     "commander": "^14.0.0",
-    "jest-diff": "^30.0.5",
     "ora": "^8.2.0",
     "zod": "^4.0.17"
   },

package/dist/core/diff.d.ts

@@ -1,11 +0,0 @@
-export declare class DiffCommand {
-    private filesChanged;
-    private linesAdded;
-    private linesRemoved;
-    execute(changeName?: string): Promise<void>;
-    private selectChange;
-    private showDiffs;
-    private walkAndDiff;
-    private diffFile;
-}
-//# sourceMappingURL=diff.d.ts.map

package/dist/core/diff.js

@@ -1,193 +0,0 @@
-import { promises as fs } from 'fs';
-import path from 'path';
-import chalk from 'chalk';
-import { diffStringsUnified } from 'jest-diff';
-import { select } from '@inquirer/prompts';
-import { Validator } from './validation/validator.js';
-// Constants
-const ARCHIVE_DIR = 'archive';
-const MARKDOWN_EXT = '.md';
-const OPENSPEC_DIR = 'openspec';
-const CHANGES_DIR = 'changes';
-const SPECS_DIR = 'specs';
-export class DiffCommand {
-    filesChanged = 0;
-    linesAdded = 0;
-    linesRemoved = 0;
-    async execute(changeName) {
-        const changesDir = path.join(process.cwd(), OPENSPEC_DIR, CHANGES_DIR);
-        try {
-            await fs.access(changesDir);
-        }
-        catch {
-            throw new Error('No OpenSpec changes directory found');
-        }
-        if (!changeName) {
-            changeName = await this.selectChange(changesDir);
-            if (!changeName)
-                return;
-        }
-        const changeDir = path.join(changesDir, changeName);
-        try {
-            await fs.access(changeDir);
-        }
-        catch {
-            throw new Error(`Change '${changeName}' not found`);
-        }
-        const changeSpecsDir = path.join(changeDir, SPECS_DIR);
-        try {
-            await fs.access(changeSpecsDir);
-        }
-        catch {
-            console.log(`No spec changes found for '${changeName}'`);
-            return;
-        }
-        // Validate specs and show warnings (non-blocking)
-        const validator = new Validator();
-        let hasWarnings = false;
-        try {
-            const entries = await fs.readdir(changeSpecsDir, { withFileTypes: true });
-            for (const entry of entries) {
-                if (entry.isDirectory()) {
-                    const specFile = path.join(changeSpecsDir, entry.name, 'spec.md');
-                    try {
-                        await fs.access(specFile);
-                        const report = await validator.validateSpec(specFile);
-                        if (report.issues.length > 0) {
-                            const warnings = report.issues.filter(i => i.level === 'WARNING');
-                            const errors = report.issues.filter(i => i.level === 'ERROR');
-                            if (errors.length > 0 || warnings.length > 0) {
-                                if (!hasWarnings) {
-                                    console.log(chalk.yellow('\n⚠️  Validation warnings found:'));
-                                    hasWarnings = true;
-                                }
-                                console.log(chalk.yellow(`\n  ${entry.name}/spec.md:`));
-                                for (const issue of errors) {
-                                    console.log(chalk.red(`    ✗ ${issue.message}`));
-                                }
-                                for (const issue of warnings) {
-                                    console.log(chalk.yellow(`    ⚠ ${issue.message}`));
-                                }
-                            }
-                        }
-                    }
-                    catch {
-                        // Spec file doesn't exist, skip validation
-                    }
-                }
-            }
-            if (hasWarnings) {
-                console.log(chalk.yellow('\nConsider fixing these issues before archiving.\n'));
-            }
-        }
-        catch {
-            // No specs directory, skip validation
-        }
-        // Reset counters
-        this.filesChanged = 0;
-        this.linesAdded = 0;
-        this.linesRemoved = 0;
-        await this.showDiffs(changeSpecsDir);
-        // Show summary
-        if (this.filesChanged > 0) {
-            console.log(chalk.bold(`\n📊 Summary: ${this.filesChanged} file(s) changed, ${chalk.green(`+${this.linesAdded}`)} ${chalk.red(`-${this.linesRemoved}`)}`));
-        }
-    }
-    async selectChange(changesDir) {
-        const entries = await fs.readdir(changesDir, { withFileTypes: true });
-        const changes = entries
-            .filter(entry => entry.isDirectory() && entry.name !== ARCHIVE_DIR)
-            .map(entry => entry.name);
-        if (changes.length === 0) {
-            console.log('No changes found');
-            return undefined;
-        }
-        console.log('Available changes:');
-        const choices = changes.map((name) => ({
-            name: name,
-            value: name
-        }));
-        const answer = await select({
-            message: 'Select a change',
-            choices
-        });
-        return answer;
-    }
-    async showDiffs(changeSpecsDir) {
-        const currentSpecsDir = path.join(process.cwd(), OPENSPEC_DIR, SPECS_DIR);
-        await this.walkAndDiff(changeSpecsDir, currentSpecsDir, '');
-    }
-    async walkAndDiff(changeDir, currentDir, relativePath) {
-        const entries = await fs.readdir(path.join(changeDir, relativePath), { withFileTypes: true });
-        for (const entry of entries) {
-            const entryPath = path.join(relativePath, entry.name);
-            if (entry.isDirectory()) {
-                await this.walkAndDiff(changeDir, currentDir, entryPath);
-            }
-            else if (entry.isFile() && entry.name.endsWith(MARKDOWN_EXT)) {
-                await this.diffFile(path.join(changeDir, entryPath), path.join(currentDir, entryPath), entryPath);
-            }
-        }
-    }
-    async diffFile(changePath, currentPath, displayPath) {
-        let changeContent = '';
-        let currentContent = '';
-        let isNewFile = false;
-        let isDeleted = false;
-        try {
-            changeContent = await fs.readFile(changePath, 'utf-8');
-        }
-        catch {
-            changeContent = '';
-        }
-        try {
-            currentContent = await fs.readFile(currentPath, 'utf-8');
-        }
-        catch {
-            currentContent = '';
-            isNewFile = true;
-        }
-        if (changeContent === currentContent) {
-            return;
-        }
-        if (changeContent === '' && currentContent !== '') {
-            isDeleted = true;
-        }
-        // Enhanced header with file status
-        console.log(chalk.bold.cyan(`\n${'═'.repeat(60)}`));
-        console.log(chalk.bold.cyan(`📄 ${displayPath}`));
-        if (isNewFile) {
-            console.log(chalk.green(`   Status: NEW FILE`));
-        }
-        else if (isDeleted) {
-            console.log(chalk.red(`   Status: DELETED`));
-        }
-        else {
-            console.log(chalk.yellow(`   Status: MODIFIED`));
-        }
-        // Use jest-diff for the actual diff with custom options
-        const diffOptions = {
-            aAnnotation: 'Current',
-            bAnnotation: 'Proposed',
-            aColor: chalk.red,
-            bColor: chalk.green,
-            commonColor: chalk.gray,
-            contextLines: 3,
-            expand: false,
-            includeChangeCounts: true,
-        };
-        const diff = diffStringsUnified(currentContent, changeContent, diffOptions);
-        // Count lines for statistics (approximate)
-        const addedLines = (diff.match(/^\+[^+]/gm) || []).length;
-        const removedLines = (diff.match(/^-[^-]/gm) || []).length;
-        console.log(chalk.gray(`   Lines: ${chalk.green(`+${addedLines}`)} ${chalk.red(`-${removedLines}`)}`));
-        console.log(chalk.bold.cyan(`${'─'.repeat(60)}\n`));
-        // Display the diff
-        console.log(diff);
-        // Update counters
-        this.filesChanged++;
-        this.linesAdded += addedLines;
-        this.linesRemoved += removedLines;
-    }
-}
-//# sourceMappingURL=diff.js.map

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

@@ -1,2 +0,0 @@
-export declare const readmeTemplate = "# OpenSpec Instructions\n\nThis document provides instructions for AI coding assistants on how to use OpenSpec conventions for spec-driven development. Follow these rules precisely when working on OpenSpec-enabled projects.\n\n## Core Principle\n\nOpenSpec is an AI-native system for change-driven development where:\n- **Specs** (`specs/`) reflect what IS currently built and deployed\n- **Changes** (`changes/`) contain proposals for what SHOULD be changed\n- **AI drives the process** - You generate proposals, humans review and approve\n- **Specs are living documentation** - Always kept in sync with deployed code\n\n## Start Simple\n\n**Default to minimal implementations:**\n- New features should be <100 lines of code initially\n- Use the simplest solution that works\n- Avoid premature optimization (no caching, parallelization, or complex patterns without proven need)\n- Choose boring technology over cutting-edge solutions\n\n**Complexity triggers** - Only add complexity when you have:\n- **Performance data** showing current solution is too slow\n- **Scale requirements** with specific numbers (>1000 users, >100MB data)\n- **Multiple use cases** requiring the same abstraction\n- **Regulatory compliance** mandating specific patterns\n- **Security threats** that simple solutions cannot address\n\nWhen triggered, document the specific justification in your change proposal.\n\n## Directory Structure\n\n```\nopenspec/\n\u251C\u2500\u2500 project.md              # Project-specific context (tech stack, conventions)\n\u251C\u2500\u2500 README.md               # This file - OpenSpec instructions\n\u251C\u2500\u2500 specs/                  # Current truth - what IS built\n\u2502   \u251C\u2500\u2500 [capability]/       # Single, focused capability\n\u2502   \u2502   \u251C\u2500\u2500 spec.md         # WHAT the capability does and WHY\n\u2502   \u2502   \u2514\u2500\u2500 design.md       # HOW it's built (established patterns)\n\u2502   \u2514\u2500\u2500 ...\n\u251C\u2500\u2500 changes/                # Proposed changes - what we're CHANGING\n\u2502   \u251C\u2500\u2500 [change-name]/\n\u2502   \u2502   \u251C\u2500\u2500 proposal.md     # Why, what, impact (consolidated)\n\u2502   \u2502   \u251C\u2500\u2500 tasks.md        # Implementation checklist\n\u2502   \u2502   \u251C\u2500\u2500 design.md       # Technical decisions (optional, for complex changes)\n\u2502   \u2502   \u2514\u2500\u2500 specs/          # Delta changes to specs\n\u2502   \u2502       \u2514\u2500\u2500 [capability]/\n\u2502   \u2502           \u2514\u2500\u2500 spec.md # Delta format (ADDED/MODIFIED/REMOVED/RENAMED)\n\u2502   \u2514\u2500\u2500 archive/            # Completed changes (dated)\n```\n\n### Capability Organization\n\n**Use capabilities, not features** - Each directory under `specs/` represents a single, focused responsibility:\n- **Verb-noun naming**: `user-auth`, `payment-capture`, `order-checkout`\n- **10-minute rule**: Each capability should be understandable in <10 minutes\n- **Single purpose**: If it needs \"AND\" to describe it, split it\n\nExamples:\n```\n\u2705 GOOD: user-auth, user-sessions, payment-capture, payment-refunds\n\u274C BAD: users, payments, core, misc\n```\n\n## Key Behavioral Rules\n\n### 1. Always Start by Reading\n\nBefore any task:\n1. **Read relevant specs** in `specs/[capability]/spec.md` to understand current state\n2. **Check pending changes** in `changes/` directory for potential conflicts\n3. **Read project.md** for project-specific conventions\n\n### 2. When to Create Change Proposals\n\n**ALWAYS create a change proposal for:**\n- New features or functionality\n- Breaking changes (API changes, schema updates)\n- Architecture changes or new patterns\n- Performance optimizations that change behavior\n- Security updates affecting auth/access patterns\n- Any change requiring multiple steps or affecting multiple systems\n\n**SKIP proposals for:**\n- Bug fixes that restore intended behavior\n- Typos, formatting, or comment updates\n- Dependency updates (unless breaking)\n- Configuration or environment variable changes\n- Adding tests for existing behavior\n- Documentation fixes\n\n**Complexity assessment:**\n- If your solution requires >100 lines of new code, justify the complexity\n- If adding dependencies, frameworks, or architectural patterns, document why simpler alternatives won't work\n- Default to single-file implementations until proven insufficient\n\n### 3. Delta-Based Change Format\n\nChanges use a delta format with clear sections:\n\n```markdown\n## ADDED Requirements\n### Requirement: New Feature\n[Complete requirement content in structured format]\n\n## MODIFIED Requirements  \n### Requirement: Existing Feature\n[Complete modified requirement (header must match current spec)]\n\n## REMOVED Requirements\n### Requirement: Old Feature\n**Reason for removal**: [Why removing]\n**Migration path**: [How to handle existing usage]\n\n## RENAMED Requirements\n- FROM: `### Requirement: Old Name`\n- TO: `### Requirement: New Name`\n```\n\nKey rules:\n- Headers are matched using `normalize(header) = trim(header)`\n- Include complete requirements (not diffs)\n- Use standard symbols in CLI output: + (added), ~ (modified), - (removed), \u2192 (renamed)\n\n### 4. Creating a Change Proposal\n\nWhen a user requests a significant change:\n\n```bash\n# 1. Create the change directory\nopenspec/changes/[descriptive-name]/\n\n# 2. Generate proposal.md with all context\n## Why\n[1-2 sentences on the problem/opportunity]\n\n## What Changes  \n[Bullet list of changes, including breaking changes]\n\n## Impact\n- Affected specs: [list capabilities that will change]\n- Affected code: [list key files/systems]\n\n# 3. Create delta specs for ALL affected capabilities\n# - Store only the changes (not complete future state)\n# - Use sections: ## ADDED, ## MODIFIED, ## REMOVED, ## RENAMED\n# - Include complete requirements in their final form\n# Example spec.md content:\n#   ## ADDED Requirements\n#   ### Requirement: Password Reset\n#   Users SHALL be able to reset passwords via email...\n#   \n#   ## MODIFIED Requirements\n#   ### Requirement: User Authentication\n#   [Complete modified requirement with new password reset hook]\nspecs/\n\u2514\u2500\u2500 [capability]/\n    \u2514\u2500\u2500 spec.md  # Contains delta sections\n\n# 4. Create tasks.md with implementation steps\n## 1. [Task Group]\n- [ ] 1.1 [Specific task]\n- [ ] 1.2 [Specific task]\n\n# 5. For complex changes, add design.md\n[Technical decisions and trade-offs]\n```\n\n### 5. The Change Lifecycle\n\n1. **Propose** \u2192 Create change directory with delta-based documentation\n2. **Review** \u2192 User reviews and approves the proposal\n3. **Implement** \u2192 Follow the approved tasks.md (can be multiple PRs)\n4. **Deploy** \u2192 User confirms deployment\n5. **Update Specs** \u2192 Apply deltas to sync specs/ with new reality (IF the change affects system capabilities)\n6. **Archive** \u2192 Move to `changes/archive/YYYY-MM-DD-[name]/`\n\n### 6. Implementing Changes\n\nWhen implementing an approved change:\n1. Follow the tasks.md checklist exactly\n2. **Mark completed tasks** in tasks.md as you finish them (e.g., `- [x] 1.1 Task completed`)\n3. Ensure code matches the proposed behavior\n4. Update any affected tests\n5. **Keep change in `changes/` directory** - do NOT archive in implementation PR\n\n**Multiple Implementation PRs:**\n- Changes can be implemented across multiple PRs\n- Each PR should update tasks.md to mark what was completed\n- Different developers can work on different task groups\n- Example: PR #1 completes tasks 1.1-1.3, PR #2 completes tasks 2.1-2.4\n\n### 7. Updating Specs and Archiving After Deployment\n\n**Create a separate PR after deployment** that:\n1. Moves change to `changes/archive/YYYY-MM-DD-[name]/`\n2. Updates relevant files in `specs/` to reflect new reality (if needed)\n3. If design.md exists, incorporates proven patterns into `specs/[capability]/design.md`\n\nThis ensures changes are only archived when truly complete and deployed.\n\n### 8. Types of Changes That Don't Require Specs\n\nSome changes only affect development infrastructure and don't need specs:\n- Initial project setup (package.json, tsconfig.json, etc.)\n- Development tooling changes (linters, formatters, build tools)\n- CI/CD configuration\n- Development dependencies\n\nFor these changes:\n1. Implement \u2192 Deploy \u2192 Mark tasks complete \u2192 Archive\n2. Skip the \"Update Specs\" step entirely\n\n### What Deserves a Spec?\n\nAsk yourself:\n- Is this a system capability that users or other systems interact with?\n- Does it have ongoing behavior that needs documentation?\n- Would a new developer need to understand this to work with the system?\n\nIf NO to all \u2192 No spec needed (likely just tooling/infrastructure)\n\n## Understanding Specs vs Code\n\n### Specs Document WHAT and WHY\n```markdown\n# Authentication Spec\n\nUsers SHALL authenticate with email and password.\n\nWHEN credentials are valid THEN issue JWT token.\nWHEN credentials are invalid THEN return generic error.\n\nWHY: Prevent user enumeration attacks.\n```\n\n### Code Documents HOW\n```javascript\n// Implementation details\nconst user = await db.users.findOne({ email });\nconst valid = await bcrypt.compare(password, user.hashedPassword);\n```\n\n**Key Distinction**: Specs capture intent, constraints, and decisions that aren't obvious from code.\n\n## Common Scenarios\n\n### New Feature Request\n```\nUser: \"Add password reset functionality\"\n\nYou should:\n1. Read specs/user-auth/spec.md\n2. Check changes/ for pending auth changes\n3. Create changes/add-password-reset/ with:\n   - proposal.md describing the change\n   - specs/user-auth/spec.md with:\n     ## ADDED Requirements\n     ### Requirement: Password Reset\n     [Complete requirement for password reset]\n     \n     ## MODIFIED Requirements\n     ### Requirement: User Authentication\n     [Updated to integrate with password reset]\n4. Wait for approval before implementing\n```\n\n### Bug Fix\n```\nUser: \"Getting null pointer error when bio is empty\"\n\nYou should:\n1. Check if spec says bios are optional\n2. If yes \u2192 Fix directly (it's a bug)\n3. If no \u2192 Create change proposal (it's a behavior change)\n```\n\n### Infrastructure Setup\n```\nUser: \"Initialize TypeScript project\"\n\nYou should:\n1. Create change proposal for TypeScript setup\n2. Implement configuration files (PR #1)\n3. Mark tasks complete in tasks.md\n4. After deployment, create separate PR to archive\n   (no specs update needed - this is tooling, not a capability)\n```\n\n## Summary Workflow\n\n1. **Receive request** \u2192 Determine if it needs a change proposal\n2. **Read current state** \u2192 Check specs and pending changes\n3. **Create proposal** \u2192 Generate complete change documentation\n4. **Get approval** \u2192 User reviews the proposal\n5. **Implement** \u2192 Follow approved tasks, mark completed items in tasks.md\n6. **Deploy** \u2192 User deploys the implementation\n7. **Archive PR** \u2192 Create separate PR to:\n   - Move change to archive\n   - Update specs if needed\n   - Mark change as complete\n\n## PR Workflow Examples\n\n### Single Developer, Simple Change\n```\nPR #1: Implementation\n- Implement all tasks\n- Update tasks.md marking items complete\n- Get merged and deployed\n\nPR #2: Archive (after deployment)\n- Move changes/feature-x/ \u2192 changes/archive/2025-01-15-feature-x/\n- Update specs if needed\n```\n\n### Multiple Developers, Complex Change\n```\nPR #1: Alice implements auth components\n- Complete tasks 1.1, 1.2, 1.3\n- Update tasks.md marking these complete\n\nPR #2: Bob implements UI components  \n- Complete tasks 2.1, 2.2\n- Update tasks.md marking these complete\n\nPR #3: Alice fixes integration issues\n- Complete remaining task 1.4\n- Update tasks.md\n\n[Deploy all changes]\n\nPR #4: Archive\n- Move to archive with deployment date\n- Update specs to reflect new auth flow\n```\n\n### Key Rules\n- **Never archive in implementation PRs** - changes aren't done until deployed\n- **Always update tasks.md** - shows accurate progress\n- **One archive PR per change** - clear completion boundary\n- **Archive PR includes spec updates** - keeps specs current\n\n## Capability Organization Best Practices\n\n### Naming Capabilities\n- Use **verb-noun** patterns: `user-auth`, `payment-capture`, `order-checkout`\n- Be specific: `payment-capture` not just `payments`\n- Keep flat: Avoid nesting capabilities within capabilities\n- Singular focus: If you need \"AND\" to describe it, split it\n\n### When to Split Capabilities\nSplit when you have:\n- Multiple unrelated API endpoints\n- Different user personas or actors\n- Separate deployment considerations\n- Independent evolution paths\n\n#### Capability Boundary Guidelines\n- Would you import these separately? \u2192 Separate capabilities\n- Different deployment cadence? \u2192 Separate capabilities\n- Different teams own them? \u2192 Separate capabilities\n- Shared data models are OK, shared business logic means combine\n\nExamples:\n- user-auth (login/logout) vs user-sessions (token management) \u2192 SEPARATE\n- payment-capture vs payment-refunds \u2192 SEPARATE (different workflows)\n- user-profile vs user-settings \u2192 COMBINE (same data model, same owner)\n\n### Cross-Cutting Concerns\nFor system-wide policies (rate limiting, error handling, security), document them in:\n- `project.md` for project-wide conventions\n- Within relevant capability specs where they apply\n- Or create a dedicated capability if complex enough (e.g., `api-rate-limiting/`)\n\n### Examples of Well-Organized Capabilities\n```\nspecs/\n\u251C\u2500\u2500 user-auth/              # Login, logout, password reset\n\u251C\u2500\u2500 user-sessions/          # Token management, refresh\n\u251C\u2500\u2500 user-profile/           # Profile CRUD operations\n\u251C\u2500\u2500 payment-capture/        # Processing payments\n\u251C\u2500\u2500 payment-refunds/        # Handling refunds\n\u2514\u2500\u2500 order-checkout/         # Checkout workflow\n```\n\nFor detailed guidance, see the [Capability Organization Guide](../docs/capability-organization.md).\n\n## Common Scenarios and Clarifications\n\n### Decision Ambiguity: Bug vs Behavior Change\n\nWhen specs are missing or ambiguous:\n- If NO spec exists \u2192 Treat current code behavior as implicit spec, require proposal\n- If spec is VAGUE \u2192 Require proposal to clarify spec alongside fix\n- If code and spec DISAGREE \u2192 Spec is truth, code is buggy (fix without proposal)\n- If unsure \u2192 Default to creating a proposal (safer option)\n\nExample:\n```\nUser: \"The API returns 404 for missing users but should return 400\"\nAI: Is this a bug (spec says 400) or behavior change (spec says 404)?\n```\n\n### When You Don't Know the Scope\nIt's OK to explore first! Tell the user you need to investigate, then create an informed proposal.\n\n### Exploration Phase (When Needed)\n\nBEFORE creating proposal, you may need exploration when:\n- User request is vague or high-level\n- Multiple implementation approaches exist\n- Scope is unclear without seeing code\n\nExploration checklist:\n1. Tell user you need to explore first\n2. Use Grep/Read to understand current state\n3. Create initial proposal based on findings\n4. Refine with user feedback\n\nExample:\n```\nUser: \"Add caching to improve performance\"\nAI: \"Let me explore the codebase to understand the current architecture and identify caching opportunities.\"\n[After exploration]\nAI: \"Based on my analysis, I've identified three areas where caching would help. Here's my proposal...\"\n```\n\n### When No Specs Exist\nTreat current code as implicit spec. Your proposal should document current state AND proposed changes.\n\n### When in Doubt\nDefault to creating a proposal. It's easier to skip an unnecessary proposal than fix an undocumented change.\n\n### AI Workflow Adaptations\n\nTask tracking with OpenSpec:\n- Track exploration tasks separately from implementation\n- Document proposal creation steps as you go\n- Keep implementation tasks separate until proposal approved\n\nParallel operations encouraged:\n- Read multiple specs simultaneously\n- Check multiple pending changes at once\n- Batch related searches for efficiency\n\nProgress communication:\n- \"Exploring codebase to understand scope...\"\n- \"Creating proposal based on findings...\"\n- \"Implementing approved changes...\"\n\n### For AI Assistants\n- **Bias toward simplicity** - Propose the minimal solution that works\n- Use your exploration tools liberally before proposing\n- Batch operations for efficiency\n- Communicate your progress\n- It's OK to revise proposals based on discoveries\n- **Question complexity** - If your solution feels complex, simplify first\n\n## Edge Case Handling\n\n### Multi-Capability Changes\nCreate ONE proposal that:\n- Lists all affected capabilities\n- Shows changes per capability\n- Has unified task list\n- Gets approved as a whole\n\n### Outdated Specs\nIf specs clearly outdated:\n1. Create proposal to update specs to match reality\n2. Implement new feature in separate proposal\n3. OR combine both in one proposal with clear sections\n\n### Emergency Hotfixes\nFor critical production issues:\n1. Announce: \"This is an emergency fix\"\n2. Implement fix immediately\n3. Create retroactive proposal\n4. Update specs after deployment\n5. Tag with [EMERGENCY] in archive\n\n### Pure Refactoring\nNo proposal needed for:\n- Code formatting/style\n- Internal refactoring (same API)\n- Performance optimization (same behavior)\n- Adding types to untyped code\n\nProposal REQUIRED for:\n- API changes (even if compatible)\n- Database schema changes\n- Architecture changes\n- New dependencies\n\n### Observability Additions\nNo proposal needed for:\n- Adding log statements\n- New metrics/traces\n- Debugging additions\n- Error tracking\n\nProposal REQUIRED if:\n- Changes log format/structure\n- Adds new monitoring service\n- Changes what's logged (privacy)\n\n## Remember\n\n- You are the process driver - automate documentation burden\n- Specs must always reflect deployed reality\n- Changes are proposed, not imposed\n- Impact analysis prevents surprises\n- Simplicity is the power - just markdown files, minimal solutions\n- Start simple, add complexity only when justified\n\nBy following these conventions, you enable true spec-driven development where documentation stays current, changes are traceable, and evolution is intentional.\n";
-//# sourceMappingURL=readme-template.d.ts.map