forge-dev-framework 1.0.1 → 1.2.0

package/dist/generators/gsd-converter.js

@@ -0,0 +1,335 @@
+/**
+ * GSD to FORGE Project Converter
+ *
+ * Converts existing GSD projects to FORGE format by:
+ * 1. Reading GSD artifacts (PROJECT.md, ROADMAP.md, phase plans)
+ * 2. Creating FORGE equivalents (CLAUDE.md, STATE.json)
+ * 3. Preserving roadmap and phase structure
+ *
+ * @private - Not published to NPM
+ */
+import { readFile, writeFile, mkdir, access, readdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { existsSync } from 'fs';
+/**
+ * Detect if current directory is a GSD project
+ */
+export async function detectGSDProject(projectPath) {
+    const projectMdPath = join(projectPath, 'PROJECT.md');
+    const roadmapMdPath = join(projectPath, 'ROADMAP.md');
+    const planningDir = join(projectPath, '.planning');
+    const info = {
+        name: '',
+        hasProjectMd: false,
+        hasRoadmapMd: false,
+        hasPlanningDir: false,
+        phases: [],
+    };
+    // Check for PROJECT.md
+    try {
+        await access(projectMdPath);
+        info.hasProjectMd = true;
+        const content = await readFile(projectMdPath, 'utf-8');
+        // Extract project name from first line or title
+        const nameMatch = content.match(/^#\s+(.+)$/m) || content.match(/^# Project: (.+)$/m);
+        if (nameMatch) {
+            info.name = nameMatch[1].trim();
+        }
+    }
+    catch {
+        // PROJECT.md doesn't exist
+    }
+    // Check for ROADMAP.md
+    try {
+        await access(roadmapMdPath);
+        info.hasRoadmapMd = true;
+    }
+    catch {
+        // ROADMAP.md doesn't exist
+    }
+    // Check for .planning directory and phases
+    try {
+        await access(planningDir);
+        info.hasPlanningDir = true;
+        // List phases
+        const phasesDir = join(planningDir, 'phases');
+        try {
+            await access(phasesDir);
+            const entries = await readdir(phasesDir, { withFileTypes: true });
+            info.phases = entries
+                .filter((e) => e.name.endsWith('.md') || e.isDirectory())
+                .map((e) => e.name)
+                .sort();
+        }
+        catch {
+            // phases directory doesn't exist
+        }
+    }
+    catch {
+        // .planning directory doesn't exist
+    }
+    return info;
+}
+/**
+ * Extract project metadata from PROJECT.md
+ */
+export async function extractProjectMetadata(projectPath) {
+    const projectMdPath = join(projectPath, 'PROJECT.md');
+    const metadata = {
+        name: '',
+        description: '',
+        techStack: [],
+        team: [],
+    };
+    try {
+        const content = await readFile(projectMdPath, 'utf-8');
+        // Extract name from title
+        const nameMatch = content.match(/^#\s+(.+)$/m);
+        if (nameMatch) {
+            metadata.name = nameMatch[1].trim();
+        }
+        // Extract description (usually after title)
+        const descMatch = content.match(/^#\s+.+\n+(.+)$/m);
+        if (descMatch) {
+            metadata.description = descMatch[1].trim();
+        }
+        // Extract tech stack (looks for "Tech Stack" or similar section)
+        const techStackMatch = content.match(/##?\s*(?:Tech Stack|Technology Stack|Stack)\n+([\s\S]+?)(?=\n##|\n*$)/i);
+        if (techStackMatch) {
+            const techLines = techStackMatch[1]
+                .split('\n')
+                .map((line) => line.replace(/^[\s\-\*]+/, '').trim())
+                .filter((line) => line.length > 0);
+            metadata.techStack = techLines;
+        }
+    }
+    catch (error) {
+        // PROJECT.md doesn't exist or couldn't be read
+    }
+    return metadata;
+}
+/**
+ * Generate CLAUDE.md from PROJECT.md content
+ */
+export async function generateClaudeMd(projectPath) {
+    const projectMdPath = join(projectPath, 'PROJECT.md');
+    let projectMdContent = '';
+    try {
+        projectMdContent = await readFile(projectMdPath, 'utf-8');
+    }
+    catch {
+        // PROJECT.md doesn't exist, use template
+    }
+    const metadata = await extractProjectMetadata(projectPath);
+    // Build CLAUDE.md content
+    let claudeMd = `# ${metadata.name || 'FORGE Project'}\n\n`;
+    claudeMd += `> **Converted from GSD.** This project was migrated from GSD to FORGE.\n`;
+    claudeMd += `> Conversion date: ${new Date().toISOString()}\n\n`;
+    // Add tech stack if available
+    if (metadata.techStack && metadata.techStack.length > 0) {
+        claudeMd += `## Tech Stack\n\n`;
+        metadata.techStack.forEach((tech) => {
+            claudeMd += `- ${tech}\n`;
+        });
+        claudeMd += `\n`;
+    }
+    // Add FORGE-specific sections
+    claudeMd += `## Core Architecture\n\n`;
+    claudeMd += `### Event-Sourced State\n\n`;
+    claudeMd += `FORGE uses an **append-only event log** with **single-writer state derivation**:\n\n`;
+    claudeMd += `1. All agents write events to \`state/events/\`\n`;
+    claudeMd += `2. State Steward (ARCHITECT) merges events → canonical \`STATE.json\`\n`;
+    claudeMd += `3. Events are **never modified**, only appended\n`;
+    claudeMd += `4. State is **deterministically replayable** from event log\n\n`;
+    claudeMd += `### Command System\n\n`;
+    claudeMd += `FORGE provides slash commands for Claude Code:\n\n`;
+    claudeMd += `\`\`\`\n`;
+    claudeMd += `/forge:new-project    # Initialize new FORGE project\n`;
+    claudeMd += `/forge:init          # Initialize FORGE in current directory\n`;
+    claudeMd += `/forge:status        # Show project progress\n`;
+    claudeMd += `/forge:config        # View/edit configuration\n`;
+    claudeMd += `/forge:discuss       # Capture phase context\n`;
+    claudeMd += `/forge:plan          # Generate task breakdown\n`;
+    claudeMd += `/forge:verify        # Verify plan against requirements\n`;
+    claudeMd += `/forge:execute       # Execute phase with agent teams\n`;
+    claudeMd += `/forge:generate      # Generate artifact from template\n`;
+    claudeMd += `/forge:help          # Show command reference\n`;
+    claudeMd += `\`\`\`\n\n`;
+    claudeMd += `### The Wipe Protocol\n\n`;
+    claudeMd += `Agent context is **ephemeral**, git is **persistent**:\n\n`;
+    claudeMd += `1. **Hydrate** — Agent reads CLAUDE.md + STATE.json + task + contracts\n`;
+    claudeMd += `2. **Execute** — Agent writes code, runs tests\n`;
+    claudeMd += `3. **Commit** — Atomic git commit (one task = one commit)\n`;
+    claudeMd += `4. **Terminate** — Session ends, context wiped\n`;
+    claudeMd += `5. **Reincarnate** — Next task starts with fresh context\n\n`;
+    claudeMd += `## Hard Rules\n\n`;
+    claudeMd += `### 5-6 Task Limit\n\n`;
+    claudeMd += `Each teammate gets **maximum 6 atomic tasks per phase**.\n\n`;
+    claudeMd += `### Atomic Commits\n\n`;
+    claudeMd += `**Every task = one git commit.** No exceptions.\n\n`;
+    claudeMd += `Commit format: \`type(scope): description\`\n\n`;
+    // Include original PROJECT.md content as appendix
+    if (projectMdContent) {
+        claudeMd += `\n---\n\n## Original GSD Content\n\n`;
+        claudeMd += `The following content was preserved from the original GSD PROJECT.md:\n\n`;
+        claudeMd += projectMdContent;
+    }
+    return claudeMd;
+}
+/**
+ * Extract tasks from GSD phase plans and convert to FORGE tasks
+ */
+export async function extractTasksFromPhases(projectPath) {
+    const phasesDir = join(projectPath, '.planning', 'phases');
+    const tasks = [];
+    let currentMilestone = 'v1.0-M1';
+    let taskId = 1;
+    try {
+        await access(phasesDir);
+        const entries = await readdir(phasesDir, { withFileTypes: true });
+        for (const entry of entries.filter((e) => e.isFile())) {
+            const phasePath = join(phasesDir, entry.name);
+            const phaseContent = await readFile(phasePath, 'utf-8');
+            // Extract tasks from phase plan
+            // GSD phase plans typically have tasks as list items or under "Tasks" section
+            const taskMatches = phaseContent.matchAll(/^[\s]*(?:[-*+]|\d+\.)\s+\[?\[?(?:task|Task)?\]?\]?\s*(.+?)(?:\s+\[([^\]]+)\])?$/gm);
+            for (const match of taskMatches) {
+                const taskTitle = match[1]?.trim() || '';
+                const taskOwner = match[2]?.trim() || 'unassigned';
+                if (taskTitle.length > 0 && !taskTitle.toLowerCase().includes('optional')) {
+                    tasks.push({
+                        id: `task-${String(taskId).padStart(3, '0')}`,
+                        title: taskTitle,
+                        ownerRole: taskOwner,
+                        status: 'pending',
+                        deps: [],
+                        allowedPaths: [],
+                        acceptance: [],
+                        verify: [],
+                        commit: null,
+                        requests: [],
+                        priority: 5,
+                        blockedBy: [],
+                        blocks: [],
+                        assignedTo: null,
+                        createdAt: new Date().toISOString(),
+                        startedAt: null,
+                        completedAt: null,
+                    });
+                    taskId++;
+                }
+            }
+        }
+    }
+    catch {
+        // No phases directory or couldn't read
+    }
+    return { currentMilestone, tasks };
+}
+/**
+ * Create initial STATE.json for FORGE project
+ */
+export async function createForgeState(projectName, tasks) {
+    const projectState = {
+        name: projectName,
+        status: 'in_progress',
+        currentMilestone: 'v1.0-M1',
+        currentPhase: 1,
+        updatedAt: new Date().toISOString(),
+    };
+    return {
+        project: projectState,
+        tasks,
+        contracts: [],
+        eventsPointer: 'state/events/',
+    };
+}
+/**
+ * Main conversion function
+ */
+export async function convertGSDToForge(projectPath, options = {}) {
+    const result = {
+        success: false,
+        message: '',
+        filesCreated: [],
+        warnings: [],
+    };
+    const log = (msg) => {
+        if (options.verbose) {
+            console.log(`[convert] ${msg}`);
+        }
+    };
+    // Detect GSD project
+    log('Detecting GSD project...');
+    const gsdInfo = await detectGSDProject(projectPath);
+    if (!gsdInfo.hasProjectMd && !gsdInfo.hasPlanningDir) {
+        result.message = 'Not a GSD project: No PROJECT.md or .planning/ directory found.';
+        return result;
+    }
+    log(`Found GSD project: ${gsdInfo.name || projectPath}`);
+    log(`  - PROJECT.md: ${gsdInfo.hasProjectMd}`);
+    log(`  - ROADMAP.md: ${gsdInfo.hasRoadmapMd}`);
+    log(`  - Phases: ${gsdInfo.phases.length}`);
+    if (options.dryRun) {
+        result.success = true;
+        result.message = 'Dry run completed. No files modified.';
+        return result;
+    }
+    // Create FORGE directory structure
+    const stateDir = join(projectPath, 'state');
+    const eventsDir = join(stateDir, 'events');
+    const contractsDir = join(projectPath, 'contracts');
+    const claudeRulesDir = join(projectPath, '.claude', 'rules');
+    for (const dir of [stateDir, eventsDir, contractsDir, claudeRulesDir]) {
+        if (!existsSync(dir)) {
+            await mkdir(dir, { recursive: true });
+            result.filesCreated.push(dir);
+            log(`Created directory: ${dir}`);
+        }
+    }
+    // Generate CLAUDE.md
+    log('Generating CLAUDE.md...');
+    const claudeMd = await generateClaudeMd(projectPath);
+    const claudeMdPath = join(projectPath, 'CLAUDE.md');
+    await writeFile(claudeMdPath, claudeMd, 'utf-8');
+    result.filesCreated.push(claudeMdPath);
+    log(`Created: ${claudeMdPath}`);
+    // Extract tasks and create STATE.json
+    log('Extracting tasks from phase plans...');
+    const { currentMilestone, tasks } = await extractTasksFromPhases(projectPath);
+    const projectName = gsdInfo.name || 'Forge Project';
+    log(`Extracted ${tasks.length} tasks from ${gsdInfo.phases.length} phase plans`);
+    const forgeState = await createForgeState(projectName, tasks);
+    const stateJsonPath = join(stateDir, 'STATE.json');
+    await writeFile(stateJsonPath, JSON.stringify(forgeState, null, 2), 'utf-8');
+    result.filesCreated.push(stateJsonPath);
+    log(`Created: ${stateJsonPath}`);
+    // Create forge.config.json
+    log('Creating forge.config.json...');
+    const config = {
+        mode: 'interactive',
+        depth: 'standard',
+        maxTeammates: 5,
+        taskLimit: 6,
+        conventionalCommits: true,
+        worktreeIsolation: true,
+        convertedFrom: 'GSD',
+        convertedAt: new Date().toISOString(),
+    };
+    const configPath = join(projectPath, '.planning', 'forge.config.json');
+    await mkdir(dirname(configPath), { recursive: true });
+    await writeFile(configPath, JSON.stringify(config, null, 2), 'utf-8');
+    result.filesCreated.push(configPath);
+    log(`Created: ${configPath}`);
+    // Warnings
+    if (!gsdInfo.hasRoadmapMd) {
+        result.warnings.push('No ROADMAP.md found. You may need to create one manually.');
+    }
+    if (tasks.length === 0) {
+        result.warnings.push('No tasks found in phase plans. You may need to run `forge plan <phase>` to create tasks.');
+    }
+    result.success = true;
+    result.message = `Successfully converted GSD project to FORGE. Created ${result.filesCreated.length} files.`;
+    return result;
+}
+//# sourceMappingURL=gsd-converter.js.map

package/dist/generators/gsd-converter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gsd-converter.js","sourceRoot":"","sources":["../../src/generators/gsd-converter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AA6DhC;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,WAAmB;IACxD,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IACtD,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IACtD,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IAEnD,MAAM,IAAI,GAAmB;QAC3B,IAAI,EAAE,EAAE;QACR,YAAY,EAAE,KAAK;QACnB,YAAY,EAAE,KAAK;QACnB,cAAc,EAAE,KAAK;QACrB,MAAM,EAAE,EAAE;KACX,CAAC;IAEF,uBAAuB;IACvB,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QAC5B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QACvD,gDAAgD;QAChD,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;QACtF,IAAI,SAAS,EAAE,CAAC;YACd,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAClC,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,2BAA2B;IAC7B,CAAC;IAED,uBAAuB;IACvB,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QAC5B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,2BAA2B;IAC7B,CAAC;IAED,2CAA2C;IAC3C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;QAC1B,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAE3B,cAAc;QACd,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QAC9C,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;YACxB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;YAClE,IAAI,CAAC,MAAM,GAAG,OAAO;iBAClB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;iBACxD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;iBAClB,IAAI,EAAE,CAAC;QACZ,CAAC;QAAC,MAAM,CAAC;YACP,iCAAiC;QACnC,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,oCAAoC;IACtC,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,WAAmB;IAM9D,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG;QACf,IAAI,EAAE,EAAE;QACR,WAAW,EAAE,EAAE;QACf,SAAS,EAAE,EAAc;QACzB,IAAI,EAAE,EAAc;KACrB,CAAC;IAEF,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QAEvD,0BAA0B;QAC1B,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAC/C,IAAI,SAAS,EAAE,CAAC;YACd,QAAQ,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACtC,CAAC;QAED,4CAA4C;QAC5C,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;QACpD,IAAI,SAAS,EAAE,CAAC;YACd,QAAQ,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC7C,CAAC;QAED,iEAAiE;QACjE,MAAM,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC,wEAAwE,CAAC,CAAC;QAC/G,IAAI,cAAc,EAAE,CAAC;YACnB,MAAM,SAAS,GAAG,cAAc,CAAC,CAAC,CAAC;iBAChC,KAAK,CAAC,IAAI,CAAC;iBACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;iBACpD,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACrC,QAAQ,CAAC,SAAS,GAAG,SAAS,CAAC;QACjC,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,+CAA+C;IACjD,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,WAAmB;IACxD,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IACtD,IAAI,gBAAgB,GAAG,EAAE,CAAC;IAE1B,IAAI,CAAC;QACH,gBAAgB,GAAG,MAAM,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,yCAAyC;IAC3C,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,sBAAsB,CAAC,WAAW,CAAC,CAAC;IAE3D,0BAA0B;IAC1B,IAAI,QAAQ,GAAG,KAAK,QAAQ,CAAC,IAAI,IAAI,eAAe,MAAM,CAAC;IAE3D,QAAQ,IAAI,0EAA0E,CAAC;IACvF,QAAQ,IAAI,sBAAsB,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC;IAEjE,8BAA8B;IAC9B,IAAI,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxD,QAAQ,IAAI,mBAAmB,CAAC;QAChC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;YAClC,QAAQ,IAAI,KAAK,IAAI,IAAI,CAAC;QAC5B,CAAC,CAAC,CAAC;QACH,QAAQ,IAAI,IAAI,CAAC;IACnB,CAAC;IAED,8BAA8B;IAC9B,QAAQ,IAAI,0BAA0B,CAAC;IAEvC,QAAQ,IAAI,6BAA6B,CAAC;IAC1C,QAAQ,IAAI,sFAAsF,CAAC;IACnG,QAAQ,IAAI,mDAAmD,CAAC;IAChE,QAAQ,IAAI,yEAAyE,CAAC;IACtF,QAAQ,IAAI,mDAAmD,CAAC;IAChE,QAAQ,IAAI,iEAAiE,CAAC;IAE9E,QAAQ,IAAI,wBAAwB,CAAC;IACrC,QAAQ,IAAI,oDAAoD,CAAC;IACjE,QAAQ,IAAI,UAAU,CAAC;IACvB,QAAQ,IAAI,wDAAwD,CAAC;IACrE,QAAQ,IAAI,gEAAgE,CAAC;IAC7E,QAAQ,IAAI,gDAAgD,CAAC;IAC7D,QAAQ,IAAI,kDAAkD,CAAC;IAC/D,QAAQ,IAAI,gDAAgD,CAAC;IAC7D,QAAQ,IAAI,kDAAkD,CAAC;IAC/D,QAAQ,IAAI,2DAA2D,CAAC;IACxE,QAAQ,IAAI,yDAAyD,CAAC;IACtE,QAAQ,IAAI,0DAA0D,CAAC;IACvE,QAAQ,IAAI,iDAAiD,CAAC;IAC9D,QAAQ,IAAI,YAAY,CAAC;IAEzB,QAAQ,IAAI,2BAA2B,CAAC;IACxC,QAAQ,IAAI,4DAA4D,CAAC;IACzE,QAAQ,IAAI,0EAA0E,CAAC;IACvF,QAAQ,IAAI,kDAAkD,CAAC;IAC/D,QAAQ,IAAI,6DAA6D,CAAC;IAC1E,QAAQ,IAAI,kDAAkD,CAAC;IAC/D,QAAQ,IAAI,8DAA8D,CAAC;IAE3E,QAAQ,IAAI,mBAAmB,CAAC;IAChC,QAAQ,IAAI,wBAAwB,CAAC;IACrC,QAAQ,IAAI,8DAA8D,CAAC;IAC3E,QAAQ,IAAI,wBAAwB,CAAC;IACrC,QAAQ,IAAI,qDAAqD,CAAC;IAClE,QAAQ,IAAI,iDAAiD,CAAC;IAE9D,kDAAkD;IAClD,IAAI,gBAAgB,EAAE,CAAC;QACrB,QAAQ,IAAI,sCAAsC,CAAC;QACnD,QAAQ,IAAI,2EAA2E,CAAC;QACxF,QAAQ,IAAI,gBAAgB,CAAC;IAC/B,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,WAAmB;IAEnB,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;IAC3D,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,IAAI,gBAAgB,GAAG,SAAS,CAAC;IACjC,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;QACxB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAElE,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;YACtD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAC9C,MAAM,YAAY,GAAG,MAAM,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YAExD,gCAAgC;YAChC,8EAA8E;YAC9E,MAAM,WAAW,GAAG,YAAY,CAAC,QAAQ,CACvC,mFAAmF,CACpF,CAAC;YAEF,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;gBAChC,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;gBACzC,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,YAAY,CAAC;gBAEnD,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;oBAC1E,KAAK,CAAC,IAAI,CAAC;wBACT,EAAE,EAAE,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE;wBAC7C,KAAK,EAAE,SAAS;wBAChB,SAAS,EAAE,SAAS;wBACpB,MAAM,EAAE,SAAS;wBACjB,IAAI,EAAE,EAAE;wBACR,YAAY,EAAE,EAAE;wBAChB,UAAU,EAAE,EAAE;wBACd,MAAM,EAAE,EAAE;wBACV,MAAM,EAAE,IAAI;wBACZ,QAAQ,EAAE,EAAE;wBACZ,QAAQ,EAAE,CAAC;wBACX,SAAS,EAAE,EAAE;wBACb,MAAM,EAAE,EAAE;wBACV,UAAU,EAAE,IAAI;wBAChB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;wBACnC,SAAS,EAAE,IAAI;wBACf,WAAW,EAAE,IAAI;qBAClB,CAAC,CAAC;oBACH,MAAM,EAAE,CAAC;gBACX,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,uCAAuC;IACzC,CAAC;IAED,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,WAAmB,EACnB,KAAkB;IAElB,MAAM,YAAY,GAAsB;QACtC,IAAI,EAAE,WAAW;QACjB,MAAM,EAAE,aAAa;QACrB,gBAAgB,EAAE,SAAS;QAC3B,YAAY,EAAE,CAAC;QACf,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IAEF,OAAO;QACL,OAAO,EAAE,YAAY;QACrB,KAAK;QACL,SAAS,EAAE,EAAE;QACb,aAAa,EAAE,eAAe;KAC/B,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,WAAmB,EACnB,UAAmD,EAAE;IAErD,MAAM,MAAM,GAAqB;QAC/B,OAAO,EAAE,KAAK;QACd,OAAO,EAAE,EAAE;QACX,YAAY,EAAE,EAAE;QAChB,QAAQ,EAAE,EAAE;KACb,CAAC;IAEF,MAAM,GAAG,GAAG,CAAC,GAAW,EAAE,EAAE;QAC1B,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,CAAC,GAAG,CAAC,aAAa,GAAG,EAAE,CAAC,CAAC;QAClC,CAAC;IACH,CAAC,CAAC;IAEF,qBAAqB;IACrB,GAAG,CAAC,0BAA0B,CAAC,CAAC;IAChC,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAC,WAAW,CAAC,CAAC;IAEpD,IAAI,CAAC,OAAO,CAAC,YAAY,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;QACrD,MAAM,CAAC,OAAO,GAAG,iEAAiE,CAAC;QACnF,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,GAAG,CAAC,sBAAsB,OAAO,CAAC,IAAI,IAAI,WAAW,EAAE,CAAC,CAAC;IACzD,GAAG,CAAC,mBAAmB,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC/C,GAAG,CAAC,mBAAmB,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC/C,GAAG,CAAC,eAAe,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAE5C,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;QACtB,MAAM,CAAC,OAAO,GAAG,uCAAuC,CAAC;QACzD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,mCAAmC;IACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC3C,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACpD,MAAM,cAAc,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IAE7D,KAAK,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,cAAc,CAAC,EAAE,CAAC;QACtE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACtC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC9B,GAAG,CAAC,sBAAsB,GAAG,EAAE,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED,qBAAqB;IACrB,GAAG,CAAC,yBAAyB,CAAC,CAAC;IAC/B,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACrD,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACpD,MAAM,SAAS,CAAC,YAAY,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IACjD,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACvC,GAAG,CAAC,YAAY,YAAY,EAAE,CAAC,CAAC;IAEhC,sCAAsC;IACtC,GAAG,CAAC,sCAAsC,CAAC,CAAC;IAC5C,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,GAAG,MAAM,sBAAsB,CAAC,WAAW,CAAC,CAAC;IAC9E,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,IAAI,eAAe,CAAC;IAEpD,GAAG,CAAC,aAAa,KAAK,CAAC,MAAM,eAAe,OAAO,CAAC,MAAM,CAAC,MAAM,cAAc,CAAC,CAAC;IAEjF,MAAM,UAAU,GAAG,MAAM,gBAAgB,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IAC9D,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IACnD,MAAM,SAAS,CAAC,aAAa,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC7E,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACxC,GAAG,CAAC,YAAY,aAAa,EAAE,CAAC,CAAC;IAEjC,2BAA2B;IAC3B,GAAG,CAAC,+BAA+B,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG;QACb,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,UAAU;QACjB,YAAY,EAAE,CAAC;QACf,SAAS,EAAE,CAAC;QACZ,mBAAmB,EAAE,IAAI;QACzB,iBAAiB,EAAE,IAAI;QACvB,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACtC,CAAC;IACF,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,mBAAmB,CAAC,CAAC;IACvE,MAAM,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,SAAS,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACtE,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACrC,GAAG,CAAC,YAAY,UAAU,EAAE,CAAC,CAAC;IAE9B,WAAW;IACX,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;QAC1B,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,2DAA2D,CAAC,CAAC;IACpF,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,CAAC,QAAQ,CAAC,IAAI,CAClB,0FAA0F,CAC3F,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,OAAO,GAAG,wDAAwD,MAAM,CAAC,YAAY,CAAC,MAAM,SAAS,CAAC;IAE7G,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/templates/.claude/rules/api-patterns.md.template

@@ -0,0 +1,212 @@
+# API Design Patterns — {{projectName}}
+
+> **Scope:** Backend API development | **Loaded On-Demand**
+
+---
+
+## RESTful Conventions
+
+### URL Structure
+{{#if apiUrlStructure}}
+{{apiUrlStructure}}
+{{else}}
+- Use kebab-case for resource names: `/api/v1/user-profiles`
+- Use plural for collections: `/api/v1/users` (not `/api/v1/user`)
+- Nest resources logically: `/api/v1/users/{userId}/posts`
+{{/if}}
+
+### HTTP Methods
+{{#if httpMethods}}
+{{#each httpMethods}}
+- **{{this.method}}** {{this.usage}}
+{{/each}}
+{{else}}
+- **GET** — Retrieve resources (no side effects)
+- **POST** — Create new resources
+- **PATCH** — Partial updates (preferred over PUT)
+- **PUT** — Full replacement (rarely used)
+- **DELETE** — Resource deletion
+{{/if}}
+
+### Response Format
+{{#if responseFormat}}
+{{responseFormat}}
+{{else}}
+Always return consistent JSON structure:
+
+```json
+{
+  "data": { ... },
+  "meta": {
+    "page": 1,
+    "perPage": 20,
+    "total": 100
+  },
+  "errors": null
+}
+```
+{{/if}}
+
+---
+
+## Error Handling
+
+### Error Response Structure
+```json
+{
+  "error": {
+    "code": "VALIDATION_FAILED",
+    "message": "User-friendly message",
+    "details": [
+      {
+        "field": "email",
+        "message": "Invalid email format"
+      }
+    ],
+    "requestId": "req_abc123"
+  }
+}
+```
+
+### HTTP Status Codes
+{{#if errorCodes}}
+{{#each errorCodes}}
+- **{{this.code}}** — {{this.description}}
+{{/each}}
+{{else}}
+- **200** — Success
+- **201** — Created
+- **204** — No Content
+- **400** — Bad Request (validation errors)
+- **401** — Unauthorized (not logged in)
+- **403** — Forbidden (logged in, no permission)
+- **404** — Not Found
+- **409** — Conflict (duplicate, state mismatch)
+- **422** — Unprocessable Entity
+- **429** — Too Many Requests (rate limit)
+- **500** — Internal Server Error
+- **503** — Service Unavailable
+{{/if}}
+
+### Error Codes Naming
+{{#if errorNaming}}
+Use {{errorNaming}}
+{{else}}
+Use SCREAMING_SNAKE_CASE for error codes:
+- `VALIDATION_FAILED`
+- `AUTHENTICATION_REQUIRED`
+- `RATE_LIMIT_EXCEEDED`
+- `RESOURCE_NOT_FOUND`
+{{/if}}
+
+---
+
+## Authentication & Authorization
+
+{{#if authPatterns}}
+{{authPatterns}}
+{{else}}
+### Authentication
+- Use JWT tokens with httpOnly cookies
+- Include `expiresIn` claim
+- Refresh token endpoint: `POST /api/v1/auth/refresh`
+
+### Authorization
+- Check permissions at route level
+- Use role-based access control (RBAC)
+- Return 403 for permission errors (not 401)
+{{/if}}
+
+---
+
+## Pagination
+
+### Standard Pagination
+{{#if pagination}}
+{{pagination}}
+{{else}}
+Default: page-based pagination
+```
+GET /api/v1/users?page=1&perPage=20
+```
+
+Response:
+```json
+{
+  "data": [...],
+  "meta": {
+    "page": 1,
+    "perPage": 20,
+    "totalPages": 5,
+    "total": 100
+  }
+}
+```
+{{/if}}
+
+---
+
+## Rate Limiting
+
+{{#if rateLimiting}}
+{{rateLimiting}}
+{{else}}
+- Standard: 100 requests/minute per IP
+- Authenticated: 1000 requests/minute per user
+- Headers returned:
+  - `X-RateLimit-Limit`
+  - `X-RateLimit-Remaining`
+  - `X-RateLimit-Reset`
+{{/if}}
+
+---
+
+## Versioning
+
+{{#if apiVersioning}}
+{{apiVersioning}}
+{{else}}
+- URL-based versioning: `/api/v1/`, `/api/v2/`
+- Maintain backward compatibility for at least one major version
+- Document deprecation timeline
+{{/if}}
+
+---
+
+## Validation
+
+{{#if validationRules}}
+{{validationRules}}
+{{else}}
+### Request Validation
+- Validate all inputs at handler boundary
+- Return detailed field-level errors
+- Use Zod or similar schema validation
+
+### Response Validation
+- Validate contracts against OpenAPI schema
+- Type-safe client generation from OpenAPI
+{{/if}}
+
+---
+
+## OpenAPI Contract Requirements
+
+{{#if openApiRequirements}}
+{{openApiRequirements}}
+{{else}}
+Every API must have:
+1. OpenAPI 3.1 spec in `/contracts/`
+2. All endpoints documented with:
+   - Summary and description
+   - Request/response schemas
+   - Error responses
+   - Authentication requirements
+3. Auto-generated TypeScript types
+4. Example requests/responses
+{{/if}}
+
+---
+
+> **Token Budget:** ~1000 tokens max
+> **Loaded On-Demand** — Only when working on API code