@fission-ai/openspec 0.17.2 → 0.18.0

package/dist/core/update.js

@@ -71,7 +71,7 @@ export class UpdateCommand {
         }
         if (updatedSlashFiles.length > 0) {
             // Normalize to forward slashes for cross-platform log consistency
-            const normalized = updatedSlashFiles.map((p) => p.replace(/\\/g, '/'));
+            const normalized = updatedSlashFiles.map((p) => FileSystemUtils.toPosixPath(p));
             summaryParts.push(`Updated slash commands: ${normalized.join(', ')}`);
         }
         const failedItems = [

package/dist/core/validation/validator.js

@@ -5,6 +5,7 @@ import { MarkdownParser } from '../parsers/markdown-parser.js';
 import { ChangeParser } from '../parsers/change-parser.js';
 import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, VALIDATION_MESSAGES } from './constants.js';
 import { parseDeltaSpec, normalizeRequirementName } from '../parsers/requirement-blocks.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
 export class Validator {
     strictMode;
     constructor(strictMode = false) {
@@ -330,7 +331,7 @@ export class Validator {
         return msg;
     }
     extractNameFromPath(filePath) {
-        const normalizedPath = filePath.replaceAll('\\', '/');
+        const normalizedPath = FileSystemUtils.toPosixPath(filePath);
         const parts = normalizedPath.split('/');
         // Look for the directory name after 'specs' or 'changes'
         for (let i = parts.length - 1; i >= 0; i--) {

package/dist/core/view.js

@@ -17,11 +17,19 @@ export class ViewCommand {
         const specsData = await this.getSpecsData(openspecDir);
         // Display summary metrics
         this.displaySummary(changesData, specsData);
+        // Display draft changes
+        if (changesData.draft.length > 0) {
+            console.log(chalk.bold.gray('\nDraft Changes'));
+            console.log('─'.repeat(60));
+            changesData.draft.forEach((change) => {
+                console.log(`  ${chalk.gray('○')} ${change.name}`);
+            });
+        }
         // Display active changes
         if (changesData.active.length > 0) {
             console.log(chalk.bold.cyan('\nActive Changes'));
             console.log('─'.repeat(60));
-            changesData.active.forEach(change => {
+            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)
@@ -33,7 +41,7 @@ export class ViewCommand {
         if (changesData.completed.length > 0) {
             console.log(chalk.bold.green('\nCompleted Changes'));
             console.log('─'.repeat(60));
-            changesData.completed.forEach(change => {
+            changesData.completed.forEach((change) => {
                 console.log(`  ${chalk.green('✓')} ${change.name}`);
             });
         }
@@ -54,23 +62,32 @@ export class ViewCommand {
     async getChangesData(openspecDir) {
         const changesDir = path.join(openspecDir, 'changes');
         if (!fs.existsSync(changesDir)) {
-            return { active: [], completed: [] };
+            return { draft: [], active: [], completed: [] };
         }
+        const draft = [];
         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) {
+                if (progress.total === 0) {
+                    // No tasks defined yet - still in planning/draft phase
+                    draft.push({ name: entry.name });
+                }
+                else if (progress.completed === progress.total) {
+                    // All tasks complete
                     completed.push({ name: entry.name });
                 }
                 else {
+                    // Has tasks but not all complete
                     active.push({ name: entry.name, progress });
                 }
             }
         }
-        // Sort active changes by completion percentage (ascending) and then by name for deterministic ordering
+        // Sort all categories by name for deterministic ordering
+        draft.sort((a, b) => a.name.localeCompare(b.name));
+        // Sort active changes by completion percentage (ascending) and then by name
         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;
@@ -81,7 +98,7 @@ export class ViewCommand {
             return a.name.localeCompare(b.name);
         });
         completed.sort((a, b) => a.name.localeCompare(b.name));
-        return { active, completed };
+        return { draft, active, completed };
     }
     async getSpecsData(openspecDir) {
         const specsDir = path.join(openspecDir, 'specs');
@@ -111,13 +128,13 @@ export class ViewCommand {
         return specs;
     }
     displaySummary(changesData, specsData) {
-        const totalChanges = changesData.active.length + changesData.completed.length;
+        const totalChanges = changesData.draft.length + 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 => {
+        changesData.active.forEach((change) => {
             totalTasks += change.progress.total;
             completedTasks += change.progress.completed;
         });
@@ -127,6 +144,9 @@ export class ViewCommand {
         });
         console.log(chalk.bold('Summary:'));
         console.log(`  ${chalk.cyan('●')} Specifications: ${chalk.bold(totalSpecs)} specs, ${chalk.bold(totalRequirements)} requirements`);
+        if (changesData.draft.length > 0) {
+            console.log(`  ${chalk.gray('●')} Draft Changes: ${chalk.bold(changesData.draft.length)}`);
+        }
         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) {

package/dist/utils/change-metadata.d.ts

@@ -0,0 +1,47 @@
+import { type ChangeMetadata } from '../core/artifact-graph/types.js';
+/**
+ * Error thrown when change metadata validation fails.
+ */
+export declare class ChangeMetadataError extends Error {
+    readonly metadataPath: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, metadataPath: string, cause?: Error | undefined);
+}
+/**
+ * Validates that a schema name is valid (exists in available schemas).
+ *
+ * @param schemaName - The schema name to validate
+ * @returns The validated schema name
+ * @throws Error if schema is not found
+ */
+export declare function validateSchemaName(schemaName: string): string;
+/**
+ * Writes change metadata to .openspec.yaml in the change directory.
+ *
+ * @param changeDir - The path to the change directory
+ * @param metadata - The metadata to write
+ * @throws ChangeMetadataError if validation fails or write fails
+ */
+export declare function writeChangeMetadata(changeDir: string, metadata: ChangeMetadata): void;
+/**
+ * Reads change metadata from .openspec.yaml in the change directory.
+ *
+ * @param changeDir - The path to the change directory
+ * @returns The validated metadata, or null if no metadata file exists
+ * @throws ChangeMetadataError if the file exists but is invalid
+ */
+export declare function readChangeMetadata(changeDir: string): ChangeMetadata | null;
+/**
+ * Resolves the schema for a change, with explicit override taking precedence.
+ *
+ * Resolution order:
+ * 1. Explicit schema (if provided)
+ * 2. Schema from .openspec.yaml metadata (if exists)
+ * 3. Default 'spec-driven'
+ *
+ * @param changeDir - The path to the change directory
+ * @param explicitSchema - Optional explicit schema override
+ * @returns The resolved schema name
+ */
+export declare function resolveSchemaForChange(changeDir: string, explicitSchema?: string): string;
+//# sourceMappingURL=change-metadata.d.ts.map

package/dist/utils/change-metadata.js

@@ -0,0 +1,130 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'yaml';
+import { ChangeMetadataSchema } from '../core/artifact-graph/types.js';
+import { listSchemas } from '../core/artifact-graph/resolver.js';
+const METADATA_FILENAME = '.openspec.yaml';
+/**
+ * Error thrown when change metadata validation fails.
+ */
+export class ChangeMetadataError extends Error {
+    metadataPath;
+    cause;
+    constructor(message, metadataPath, cause) {
+        super(message);
+        this.metadataPath = metadataPath;
+        this.cause = cause;
+        this.name = 'ChangeMetadataError';
+    }
+}
+/**
+ * Validates that a schema name is valid (exists in available schemas).
+ *
+ * @param schemaName - The schema name to validate
+ * @returns The validated schema name
+ * @throws Error if schema is not found
+ */
+export function validateSchemaName(schemaName) {
+    const availableSchemas = listSchemas();
+    if (!availableSchemas.includes(schemaName)) {
+        throw new Error(`Unknown schema '${schemaName}'. Available: ${availableSchemas.join(', ')}`);
+    }
+    return schemaName;
+}
+/**
+ * Writes change metadata to .openspec.yaml in the change directory.
+ *
+ * @param changeDir - The path to the change directory
+ * @param metadata - The metadata to write
+ * @throws ChangeMetadataError if validation fails or write fails
+ */
+export function writeChangeMetadata(changeDir, metadata) {
+    const metaPath = path.join(changeDir, METADATA_FILENAME);
+    // Validate schema exists
+    validateSchemaName(metadata.schema);
+    // Validate with Zod
+    const parseResult = ChangeMetadataSchema.safeParse(metadata);
+    if (!parseResult.success) {
+        throw new ChangeMetadataError(`Invalid metadata: ${parseResult.error.message}`, metaPath);
+    }
+    // Write YAML file
+    const content = yaml.stringify(parseResult.data);
+    try {
+        fs.writeFileSync(metaPath, content, 'utf-8');
+    }
+    catch (err) {
+        const ioError = err instanceof Error ? err : new Error(String(err));
+        throw new ChangeMetadataError(`Failed to write metadata: ${ioError.message}`, metaPath, ioError);
+    }
+}
+/**
+ * Reads change metadata from .openspec.yaml in the change directory.
+ *
+ * @param changeDir - The path to the change directory
+ * @returns The validated metadata, or null if no metadata file exists
+ * @throws ChangeMetadataError if the file exists but is invalid
+ */
+export function readChangeMetadata(changeDir) {
+    const metaPath = path.join(changeDir, METADATA_FILENAME);
+    if (!fs.existsSync(metaPath)) {
+        return null;
+    }
+    let content;
+    try {
+        content = fs.readFileSync(metaPath, 'utf-8');
+    }
+    catch (err) {
+        const ioError = err instanceof Error ? err : new Error(String(err));
+        throw new ChangeMetadataError(`Failed to read metadata: ${ioError.message}`, metaPath, ioError);
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(content);
+    }
+    catch (err) {
+        const parseError = err instanceof Error ? err : new Error(String(err));
+        throw new ChangeMetadataError(`Invalid YAML in metadata file: ${parseError.message}`, metaPath, parseError);
+    }
+    // Validate with Zod
+    const parseResult = ChangeMetadataSchema.safeParse(parsed);
+    if (!parseResult.success) {
+        throw new ChangeMetadataError(`Invalid metadata: ${parseResult.error.message}`, metaPath);
+    }
+    // Validate that the schema exists
+    const availableSchemas = listSchemas();
+    if (!availableSchemas.includes(parseResult.data.schema)) {
+        throw new ChangeMetadataError(`Unknown schema '${parseResult.data.schema}'. Available: ${availableSchemas.join(', ')}`, metaPath);
+    }
+    return parseResult.data;
+}
+/**
+ * Resolves the schema for a change, with explicit override taking precedence.
+ *
+ * Resolution order:
+ * 1. Explicit schema (if provided)
+ * 2. Schema from .openspec.yaml metadata (if exists)
+ * 3. Default 'spec-driven'
+ *
+ * @param changeDir - The path to the change directory
+ * @param explicitSchema - Optional explicit schema override
+ * @returns The resolved schema name
+ */
+export function resolveSchemaForChange(changeDir, explicitSchema) {
+    // 1. Explicit override wins
+    if (explicitSchema) {
+        return explicitSchema;
+    }
+    // 2. Try reading from metadata
+    try {
+        const metadata = readChangeMetadata(changeDir);
+        if (metadata?.schema) {
+            return metadata.schema;
+        }
+    }
+    catch {
+        // If metadata read fails, fall back to default
+    }
+    // 3. Default
+    return 'spec-driven';
+}
+//# sourceMappingURL=change-metadata.js.map

package/dist/utils/change-utils.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Options for creating a change.
+ */
+export interface CreateChangeOptions {
+    /** The workflow schema to use (default: 'spec-driven') */
+    schema?: string;
+}
+/**
+ * Result of validating a change name.
+ */
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validates that a change name follows kebab-case conventions.
+ *
+ * Valid names:
+ * - Start with a lowercase letter
+ * - Contain only lowercase letters, numbers, and hyphens
+ * - Do not start or end with a hyphen
+ * - Do not contain consecutive hyphens
+ *
+ * @param name - The change name to validate
+ * @returns Validation result with `valid: true` or `valid: false` with an error message
+ *
+ * @example
+ * validateChangeName('add-auth') // { valid: true }
+ * validateChangeName('Add-Auth') // { valid: false, error: '...' }
+ */
+export declare function validateChangeName(name: string): ValidationResult;
+/**
+ * Creates a new change directory with metadata file.
+ *
+ * @param projectRoot - The root directory of the project (where `openspec/` lives)
+ * @param name - The change name (must be valid kebab-case)
+ * @param options - Optional settings for the change
+ * @throws Error if the change name is invalid
+ * @throws Error if the schema name is invalid
+ * @throws Error if the change directory already exists
+ *
+ * @example
+ * // Creates openspec/changes/add-auth/ with default schema
+ * await createChange('/path/to/project', 'add-auth')
+ *
+ * @example
+ * // Creates openspec/changes/add-auth/ with TDD schema
+ * await createChange('/path/to/project', 'add-auth', { schema: 'tdd' })
+ */
+export declare function createChange(projectRoot: string, name: string, options?: CreateChangeOptions): Promise<void>;
+//# sourceMappingURL=change-utils.d.ts.map

package/dist/utils/change-utils.js

@@ -0,0 +1,100 @@
+import path from 'path';
+import { FileSystemUtils } from './file-system.js';
+import { writeChangeMetadata, validateSchemaName } from './change-metadata.js';
+const DEFAULT_SCHEMA = 'spec-driven';
+/**
+ * Validates that a change name follows kebab-case conventions.
+ *
+ * Valid names:
+ * - Start with a lowercase letter
+ * - Contain only lowercase letters, numbers, and hyphens
+ * - Do not start or end with a hyphen
+ * - Do not contain consecutive hyphens
+ *
+ * @param name - The change name to validate
+ * @returns Validation result with `valid: true` or `valid: false` with an error message
+ *
+ * @example
+ * validateChangeName('add-auth') // { valid: true }
+ * validateChangeName('Add-Auth') // { valid: false, error: '...' }
+ */
+export function validateChangeName(name) {
+    // Pattern: starts with lowercase letter, followed by lowercase letters/numbers,
+    // optionally followed by hyphen + lowercase letters/numbers (repeatable)
+    const kebabCasePattern = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+    if (!name) {
+        return { valid: false, error: 'Change name cannot be empty' };
+    }
+    if (!kebabCasePattern.test(name)) {
+        // Provide specific error messages for common mistakes
+        if (/[A-Z]/.test(name)) {
+            return { valid: false, error: 'Change name must be lowercase (use kebab-case)' };
+        }
+        if (/\s/.test(name)) {
+            return { valid: false, error: 'Change name cannot contain spaces (use hyphens instead)' };
+        }
+        if (/_/.test(name)) {
+            return { valid: false, error: 'Change name cannot contain underscores (use hyphens instead)' };
+        }
+        if (name.startsWith('-')) {
+            return { valid: false, error: 'Change name cannot start with a hyphen' };
+        }
+        if (name.endsWith('-')) {
+            return { valid: false, error: 'Change name cannot end with a hyphen' };
+        }
+        if (/--/.test(name)) {
+            return { valid: false, error: 'Change name cannot contain consecutive hyphens' };
+        }
+        if (/[^a-z0-9-]/.test(name)) {
+            return { valid: false, error: 'Change name can only contain lowercase letters, numbers, and hyphens' };
+        }
+        if (/^[0-9]/.test(name)) {
+            return { valid: false, error: 'Change name must start with a letter' };
+        }
+        return { valid: false, error: 'Change name must follow kebab-case convention (e.g., add-auth, refactor-db)' };
+    }
+    return { valid: true };
+}
+/**
+ * Creates a new change directory with metadata file.
+ *
+ * @param projectRoot - The root directory of the project (where `openspec/` lives)
+ * @param name - The change name (must be valid kebab-case)
+ * @param options - Optional settings for the change
+ * @throws Error if the change name is invalid
+ * @throws Error if the schema name is invalid
+ * @throws Error if the change directory already exists
+ *
+ * @example
+ * // Creates openspec/changes/add-auth/ with default schema
+ * await createChange('/path/to/project', 'add-auth')
+ *
+ * @example
+ * // Creates openspec/changes/add-auth/ with TDD schema
+ * await createChange('/path/to/project', 'add-auth', { schema: 'tdd' })
+ */
+export async function createChange(projectRoot, name, options = {}) {
+    // Validate the name first
+    const validation = validateChangeName(name);
+    if (!validation.valid) {
+        throw new Error(validation.error);
+    }
+    // Determine schema (validate if provided)
+    const schemaName = options.schema ?? DEFAULT_SCHEMA;
+    validateSchemaName(schemaName);
+    // Build the change directory path
+    const changeDir = path.join(projectRoot, 'openspec', 'changes', name);
+    // Check if change already exists
+    if (await FileSystemUtils.directoryExists(changeDir)) {
+        throw new Error(`Change '${name}' already exists at ${changeDir}`);
+    }
+    // Create the directory (including parent directories if needed)
+    await FileSystemUtils.createDirectory(changeDir);
+    // Write metadata file with schema and creation date
+    const today = new Date().toISOString().split('T')[0];
+    writeChangeMetadata(changeDir, {
+        schema: schemaName,
+        created: today,
+    });
+}
+//# sourceMappingURL=change-utils.js.map

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

@@ -1,4 +1,9 @@
 export declare class FileSystemUtils {
+    /**
+     * Converts a path to use forward slashes (POSIX style).
+     * Essential for cross-platform compatibility with glob libraries like fast-glob.
+     */
+    static toPosixPath(p: string): string;
     private static isWindowsBasePath;
     private static normalizeSegments;
     static joinPath(basePath: string, ...segments: string[]): string;

package/dist/utils/file-system.js

@@ -30,6 +30,13 @@ function findMarkerIndex(content, marker, fromIndex = 0) {
     return -1;
 }
 export class FileSystemUtils {
+    /**
+     * Converts a path to use forward slashes (POSIX style).
+     * Essential for cross-platform compatibility with glob libraries like fast-glob.
+     */
+    static toPosixPath(p) {
+        return p.replace(/\\/g, '/');
+    }
     static isWindowsBasePath(basePath) {
         return /^[A-Za-z]:[\\/]/.test(basePath) || basePath.startsWith('\\');
     }

package/dist/utils/index.d.ts

@@ -1,2 +1,4 @@
-export {};
+export { validateChangeName, createChange } from './change-utils.js';
+export type { ValidationResult, CreateChangeOptions } from './change-utils.js';
+export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, validateSchemaName, ChangeMetadataError, } from './change-metadata.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -1,2 +1,5 @@
-export {};
+// Shared utilities
+export { validateChangeName, createChange } from './change-utils.js';
+// Change metadata utilities
+export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, validateSchemaName, ChangeMetadataError, } from './change-metadata.js';
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -32,6 +32,7 @@
   "files": [
     "dist",
     "bin",
+    "schemas",
     "scripts/postinstall.js",
     "!dist/**/*.test.js",
     "!dist/**/__tests__",
@@ -54,7 +55,9 @@
     "@inquirer/prompts": "^7.8.0",
     "chalk": "^5.5.0",
     "commander": "^14.0.0",
+    "fast-glob": "^3.3.3",
     "ora": "^8.2.0",
+    "yaml": "^2.8.2",
     "zod": "^4.0.17"
   },
   "scripts": {

package/schemas/spec-driven/schema.yaml

@@ -0,0 +1,148 @@
+name: spec-driven
+version: 1
+description: Default OpenSpec workflow - proposal → specs → design → tasks
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Initial proposal document outlining the change
+    template: proposal.md
+    instruction: |
+      Create the proposal document that establishes WHY this change is needed.
+
+      Sections:
+      - **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
+      - **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
+      - **Capabilities**: Identify which specs will be created or modified:
+        - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<name>/spec.md`. Use kebab-case names (e.g., `user-auth`, `data-export`).
+        - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Check `openspec/specs/` for existing spec names. Leave empty if no requirement changes.
+      - **Impact**: Affected code, APIs, dependencies, or systems.
+
+      IMPORTANT: The Capabilities section is critical. It creates the contract between
+      proposal and specs phases. Research existing specs before filling this in.
+      Each capability listed here will need a corresponding spec file.
+
+      Keep it concise (1-2 pages). Focus on the "why" not the "how" -
+      implementation details belong in design.md.
+
+      This is the foundation - specs, design, and tasks all build on this.
+    requires: []
+
+  - id: specs
+    generates: "specs/**/*.md"
+    description: Detailed specifications for the change
+    template: spec.md
+    instruction: |
+      Create specification files that define WHAT the system should do.
+
+      Create one spec file per capability/feature area in specs/<name>/spec.md.
+
+      Delta operations (use ## headers):
+      - **ADDED Requirements**: New capabilities
+      - **MODIFIED Requirements**: Changed behavior - MUST include full updated content
+      - **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration**
+      - **RENAMED Requirements**: Name changes only - use FROM:/TO: format
+
+      Format requirements:
+      - Each requirement: `### Requirement: <name>` followed by description
+      - Use SHALL/MUST for normative requirements (avoid should/may)
+      - Each scenario: `#### Scenario: <name>` with WHEN/THEN format
+      - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
+      - Every requirement MUST have at least one scenario.
+
+      MODIFIED requirements workflow:
+      1. Locate the existing requirement in openspec/specs/<capability>/spec.md
+      2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
+      3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
+      4. Ensure header text matches exactly (whitespace-insensitive)
+
+      Common pitfall: Using MODIFIED with partial content loses detail at archive time.
+      If adding new concerns without changing existing behavior, use ADDED instead.
+
+      Example:
+      ```
+      ## ADDED Requirements
+
+      ### Requirement: User can export data
+      The system SHALL allow users to export their data in CSV format.
+
+      #### Scenario: Successful export
+      - **WHEN** user clicks "Export" button
+      - **THEN** system downloads a CSV file with all user data
+
+      ## REMOVED Requirements
+
+      ### Requirement: Legacy export
+      **Reason**: Replaced by new export system
+      **Migration**: Use new export endpoint at /api/v2/export
+      ```
+
+      Specs should be testable - each scenario is a potential test case.
+    requires:
+      - proposal
+
+  - id: design
+    generates: design.md
+    description: Technical design document with implementation details
+    template: design.md
+    instruction: |
+      Create the design document that explains HOW to implement the change.
+
+      When to include design.md (create only if any apply):
+      - Cross-cutting change (multiple services/modules) or new architectural pattern
+      - New external dependency or significant data model changes
+      - Security, performance, or migration complexity
+      - Ambiguity that benefits from technical decisions before coding
+
+      Sections:
+      - **Context**: Background, current state, constraints, stakeholders
+      - **Goals / Non-Goals**: What this design achieves and explicitly excludes
+      - **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision.
+      - **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation
+      - **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
+      - **Open Questions**: Outstanding decisions or unknowns to resolve
+
+      Focus on architecture and approach, not line-by-line implementation.
+      Reference the proposal for motivation and specs for requirements.
+
+      Good design docs explain the "why" behind technical decisions.
+    requires:
+      - proposal
+
+  - id: tasks
+    generates: tasks.md
+    description: Implementation tasks derived from specs and design
+    template: tasks.md
+    instruction: |
+      Create the task list that breaks down the implementation work.
+
+      Guidelines:
+      - Group related tasks under ## numbered headings
+      - Each task is a checkbox: - [ ] X.Y Task description
+      - Tasks should be small enough to complete in one session
+      - Order tasks by dependency (what must be done first?)
+
+      Example:
+      ```
+      ## 1. Setup
+
+      - [ ] 1.1 Create new module structure
+      - [ ] 1.2 Add dependencies to package.json
+
+      ## 2. Core Implementation
+
+      - [ ] 2.1 Implement data export function
+      - [ ] 2.2 Add CSV formatting utilities
+      ```
+
+      Reference specs for what needs to be built, design for how to build it.
+      Each task should be verifiable - you know when it's done.
+    requires:
+      - specs
+      - design
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    Read context files, work through pending tasks, mark complete as you go.
+    Pause if you hit blockers or need clarification.