@hivehub/rulebook 5.5.2 → 5.7.0

package/dist/core/generators/generator.js

@@ -0,0 +1,1041 @@
+import path from 'path';
+import { readFile, fileExists, writeFile, ensureDir } from '../../utils/file-system.js';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { DecisionManager } from '../tasks/decision-manager.js';
+import { KnowledgeManager } from '../tasks/knowledge-manager.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Resolve templates directory (handles both dev and production)
+export function getTemplatesDir() {
+    // In production (dist/), templates are at package root
+    // In development (src/), templates are at package root
+    // Both resolve to same location
+    return path.join(__dirname, '..', '..', '..', 'templates');
+}
+// Helper to read core template files (AGENT_AUTOMATION, DOCUMENTATION_RULES, QUALITY_ENFORCEMENT, RULEBOOK)
+async function generateCoreRules(name) {
+    const templatesDir = path.join(getTemplatesDir(), 'core');
+    const templatePath = path.join(templatesDir, `${name.toUpperCase()}.md`);
+    if (await fileExists(templatePath)) {
+        return await readFile(templatePath);
+    }
+    return `<!-- ${name.toUpperCase()}:START -->\n# ${name.charAt(0).toUpperCase() + name.slice(1)} Rules\n\nCore rules for ${name}.\n<!-- ${name.toUpperCase()}:END -->\n`;
+}
+export async function generateAgentsContent(config) {
+    const sections = [];
+    // Header comment
+    sections.push('<!-- RULEBOOK:START -->');
+    sections.push('# Project Rules');
+    sections.push('');
+    sections.push('Generated by @hivellm/rulebook');
+    sections.push(`Generated at: ${new Date().toISOString()}`);
+    sections.push('');
+    const rulebookDir = config.rulebookDir || '.rulebook';
+    // RULEBOOK.md has HIGHEST PRECEDENCE - must be first and most prominent
+    sections.push('## ⚠️ CRITICAL: Task Management Rules (HIGHEST PRECEDENCE)');
+    sections.push('');
+    sections.push('**MANDATORY**: All task creation MUST follow Rulebook task management system.');
+    sections.push('');
+    sections.push(`**📋 ALWAYS reference \`/${rulebookDir}/specs/RULEBOOK.md\` FIRST before creating any tasks.**`);
+    sections.push('');
+    sections.push('**Rules from RULEBOOK.md take precedence over all other rules in this file.**');
+    sections.push('');
+    sections.push('**Key Requirements:**');
+    sections.push('- ✅ Context7 MCP is REQUIRED for task creation');
+    sections.push('- ✅ All tasks MUST follow Rulebook task format');
+    sections.push('- ✅ Use `rulebook task create` to create tasks');
+    sections.push('- ✅ Always validate task format before committing');
+    sections.push('- ❌ NEVER create tasks without checking RULEBOOK.md format requirements');
+    sections.push('');
+    sections.push('### ⚠️ CRITICAL: Task File Structure Rules');
+    sections.push('');
+    sections.push('**MANDATORY**: When creating or updating tasks, you MUST follow the correct file structure:');
+    sections.push('');
+    sections.push('**✅ CORRECT File Structure:**');
+    sections.push('- `proposal.md` - **Why** and **What Changes** (detailed explanations go here)');
+    sections.push('- `tasks.md` - **ONLY checklist items** (simple `- [ ]` or `- [x]` format)');
+    sections.push('- `specs/<module>/spec.md` - **Technical specifications** (SHALL/MUST requirements)');
+    sections.push('- `design.md` - **Technical design decisions** (optional, for complex features)');
+    sections.push('');
+    sections.push('**❌ FORBIDDEN Practices:**');
+    sections.push('- ❌ **NEVER** add long explanations or specifications in `tasks.md`');
+    sections.push('- ❌ **NEVER** put technical details in `tasks.md` (use `specs/` instead)');
+    sections.push('- ❌ **NEVER** create `README.md` or `README` files in task directories');
+    sections.push('- ❌ **NEVER** create `PROCESS.md` or `PROCESS` files in task directories');
+    sections.push('- ❌ **NEVER** create any file not listed in the correct structure above');
+    sections.push('');
+    sections.push('**What Goes Where:**');
+    sections.push('');
+    sections.push('1. **`proposal.md`** - Use for:');
+    sections.push('   - Detailed "Why" explanations (minimum 20 characters)');
+    sections.push('   - "What Changes" descriptions');
+    sections.push('   - Impact analysis');
+    sections.push('   - Business/technical rationale');
+    sections.push('');
+    sections.push('2. **`tasks.md`** - Use ONLY for:');
+    sections.push('   - Simple checklist items: `- [ ] Task description`');
+    sections.push('   - Status updates: `- [x] Completed task`');
+    sections.push('   - Brief comments: `<!-- tested, coverage: 95% -->`');
+    sections.push('   - **DO NOT** add long explanations, specifications, or technical details here');
+    sections.push('');
+    sections.push('3. **`specs/<module>/spec.md`** - Use for:');
+    sections.push('   - Technical specifications with SHALL/MUST requirements');
+    sections.push('   - Scenario definitions (Given/When/Then)');
+    sections.push('   - Delta operations (ADDED/MODIFIED/REMOVED)');
+    sections.push('   - All detailed technical requirements');
+    sections.push('');
+    sections.push('4. **`design.md`** - Use for (optional):');
+    sections.push('   - Architecture decisions');
+    sections.push('   - Technical design rationale');
+    sections.push('   - Complex implementation details');
+    sections.push('');
+    sections.push('**Example of WRONG usage:**');
+    sections.push('```markdown');
+    sections.push('# tasks.md (WRONG - too much detail)');
+    sections.push('');
+    sections.push('## Implementation');
+    sections.push('- [ ] Create authentication system');
+    sections.push('  The system SHALL implement JWT-based authentication...');
+    sections.push('  Users MUST be able to login with email and password...');
+    sections.push('  The system MUST validate tokens...');
+    sections.push('```');
+    sections.push('');
+    sections.push('**Example of CORRECT usage:**');
+    sections.push('```markdown');
+    sections.push('# tasks.md (CORRECT - simple checklist)');
+    sections.push('');
+    sections.push('## 1. Implementation Phase');
+    sections.push('- [ ] 1.1 Create authentication module');
+    sections.push('- [ ] 1.2 Add JWT token generation');
+    sections.push('- [ ] 1.3 Implement password validation');
+    sections.push('');
+    sections.push('# specs/auth/spec.md (CORRECT - specifications here)');
+    sections.push('');
+    sections.push('## ADDED Requirements');
+    sections.push('');
+    sections.push('### Requirement: Authentication System');
+    sections.push('The system SHALL implement JWT-based authentication.');
+    sections.push('');
+    sections.push('#### Scenario: User Login');
+    sections.push('Given a user with valid credentials');
+    sections.push('When the user submits login form');
+    sections.push('Then the system MUST return a JWT token');
+    sections.push('```');
+    sections.push('');
+    sections.push('**Remember:**');
+    sections.push('- ✅ `tasks.md` = Simple checklist only');
+    sections.push('- ✅ `proposal.md` = Why and what changes');
+    sections.push('- ✅ `specs/` = Technical specifications');
+    sections.push('- ❌ No README, PROCESS, or other files');
+    sections.push('');
+    sections.push(`**For complete task management guidelines, see: \`/${rulebookDir}/specs/RULEBOOK.md\`**`);
+    sections.push('');
+    sections.push('---');
+    sections.push('');
+    // Core rules summary (detailed rules in /rulebook/)
+    sections.push('## Core Rules');
+    sections.push('');
+    sections.push('This project uses @hivellm/rulebook standards.');
+    sections.push('');
+    sections.push('**CRITICAL RULES:**');
+    sections.push('1. **ALWAYS check `RULEBOOK.md` first** when creating tasks');
+    sections.push(`2. Write tests first (${config.coverageThreshold}%+ coverage required)`);
+    sections.push('3. Run quality checks before committing:');
+    sections.push('   - Type check / Compiler check');
+    sections.push('   - Linter (no warnings allowed)');
+    sections.push('   - All tests (100% pass rate)');
+    sections.push('   - Coverage check');
+    sections.push('4. Update docs/ when implementing features');
+    sections.push('5. Follow strict documentation structure');
+    sections.push('6. **NEVER run destructive deletions (`rm -rf`) in this repository; when adding submodules always use `git submodule add`.**');
+    sections.push('7. **Temporary files and scripts**:');
+    sections.push('   - ✅ ALL scripts MUST be created in `/scripts` directory');
+    sections.push('   - ✅ ALL temporary files (test, log, debug) MUST be in `/scripts`');
+    sections.push('   - ✅ ALL temporary files MUST be removed immediately after use (MANDATORY)');
+    sections.push('   - ❌ NEVER create temporary files in project root or outside `/scripts`');
+    sections.push('   - ❌ NEVER leave temporary files after use - clean up before committing');
+    sections.push('');
+    sections.push('## Detailed Rules');
+    sections.push('');
+    sections.push(`For comprehensive rules, see the corresponding files in \`/${rulebookDir}/specs/\`:`);
+    sections.push('');
+    // TIER1_PROHIBITIONS is ALWAYS first (absolute highest precedence)
+    sections.push(`- \`/${rulebookDir}/specs/TIER1_PROHIBITIONS.md\` - **Absolute prohibitions (HIGHEST PRECEDENCE — read first)**`);
+    // RULEBOOK.md is second (task management)
+    sections.push(`- \`/${rulebookDir}/specs/RULEBOOK.md\` - **Task management rules**`);
+    // Only reference QUALITY_ENFORCEMENT if not in light mode
+    if (!config.lightMode) {
+        sections.push(`- \`/${rulebookDir}/specs/QUALITY_ENFORCEMENT.md\` - Quality enforcement rules`);
+    }
+    // Only reference GIT if enabled
+    if (config.includeGitWorkflow) {
+        sections.push(`- \`/${rulebookDir}/specs/GIT.md\` - Git workflow rules`);
+    }
+    // Token optimization reference
+    if (!config.lightMode) {
+        sections.push(`- \`/${rulebookDir}/specs/TOKEN_OPTIMIZATION.md\` - Model tier assignment and output verbosity rules`);
+    }
+    // Reference PLANS.md for session continuity
+    sections.push(`- \`/${rulebookDir}/PLANS.md\` - **Session scratchpad** (read at session start for current task context)`);
+    sections.push('');
+    sections.push(`Language-specific rules are in \`/${rulebookDir}/specs/\`.`);
+    sections.push(`Module-specific patterns are in \`/${rulebookDir}/specs/\`.`);
+    sections.push('');
+    sections.push('## Persistent Memory System');
+    sections.push('');
+    sections.push('This project uses a **persistent memory system** with hybrid BM25+vector search.');
+    sections.push('Memory is **enabled by default** and persists across sessions for maintaining context and preserving learnings.');
+    sections.push('');
+    sections.push('**MANDATORY: You MUST actively use memory to preserve context and learnings.**');
+    sections.push('');
+    sections.push('**Status**: ✅ Enabled by default in `.rulebook` configuration');
+    sections.push('');
+    sections.push('### Key Features');
+    sections.push('');
+    sections.push('- **Rich Contextual Summaries**: Memories auto-extract summaries with key concepts, decisions, patterns, gotchas');
+    sections.push('- **Hybrid Search**: BM25 keyword search + HNSW vector semantic search for relevant results');
+    sections.push('- **3-Layer Search Pattern**: Compact results → Timeline context → Full details (token-efficient)');
+    sections.push('- **Auto-Capture**: Implementation outputs from AI agents automatically captured');
+    sections.push('- **Zero Native Dependencies**: Pure WASM + TypeScript, works on all platforms');
+    sections.push('');
+    sections.push('### When to Save to Memory');
+    sections.push('');
+    sections.push('Save to memory whenever you:');
+    sections.push('- **Make an architectural decision** — why you chose one approach over another');
+    sections.push('- **Fix a bug** — root cause and how it was resolved');
+    sections.push('- **Discover something important** — codebase patterns, gotchas, constraints');
+    sections.push('- **Implement a feature** — design approach, patterns discovered, edge cases handled');
+    sections.push('- **Encounter an error** — root cause and solution for future reference');
+    sections.push('- **Receive user preferences** — coding style, conventions, workflow preferences');
+    sections.push('- **Complete a task or session** — summarize what was accomplished and learnings');
+    sections.push('');
+    sections.push('### How to Save Memory');
+    sections.push('');
+    sections.push('Save memories with rich context for better future searches:');
+    sections.push('');
+    sections.push('**Via MCP:**');
+    sections.push('```');
+    sections.push('rulebook_memory_save({');
+    sections.push('  type: "feature|decision|bugfix|discovery|refactor|change|observation",');
+    sections.push('  title: "Short title (≤80 chars)",');
+    sections.push('  content: "Detailed explanation: what was done, why, key decisions, patterns, gotchas...",');
+    sections.push('  tags: ["relevant", "tags"]');
+    sections.push('})');
+    sections.push('```');
+    sections.push('');
+    sections.push('**Via CLI:**');
+    sections.push('```bash');
+    sections.push('rulebook memory save "Detailed content here" --type feature --title "Brief Title" --tags tag1,tag2');
+    sections.push('```');
+    sections.push('');
+    sections.push('**Summary Auto-Extraction**: Summaries are automatically extracted from content, capturing:');
+    sections.push('- Key concepts and decisions');
+    sections.push('- Design patterns discovered');
+    sections.push('- Gotchas and edge cases');
+    sections.push('- Problem/solution context');
+    sections.push('');
+    sections.push('### When and How to Search Memory');
+    sections.push('');
+    sections.push('**At the START of every session**, search memory for relevant context:');
+    sections.push('');
+    sections.push('**Via MCP (3-Layer Search - token efficient):**');
+    sections.push('```');
+    sections.push('Layer 1 - Compact search: rulebook_memory_search({ query: "your topic", mode: "hybrid", limit: 10 })');
+    sections.push('  → Returns: id, title, type, score, summary (compact results)');
+    sections.push('Layer 2 - Timeline: rulebook_memory_timeline({ memoryId: "abc-123", window: 5 })');
+    sections.push('  → Returns: 5 before/after chronologically');
+    sections.push('Layer 3 - Full details: rulebook_memory_get({ ids: ["abc-123"] })');
+    sections.push('  → Returns: complete memory objects');
+    sections.push('```');
+    sections.push('');
+    sections.push('**Via CLI:**');
+    sections.push('```bash');
+    sections.push('rulebook memory search "authentication" --mode hybrid          # Keyword + semantic');
+    sections.push('rulebook memory search "oauth" --type feature                  # Filter by memory type');
+    sections.push('rulebook memory list --limit 10                               # Recent memories');
+    sections.push('```');
+    sections.push('');
+    sections.push('Also search when:');
+    sections.push("- Working on code you've touched before");
+    sections.push('- The user references a past discussion or decision');
+    sections.push('- You need context about why something was done a certain way');
+    sections.push('- **Before implementing similar features** — find past patterns and gotchas');
+    sections.push('');
+    sections.push('### Session Workflow');
+    sections.push('');
+    sections.push('**Complete memory-enhanced workflow:**');
+    sections.push('1. **Start of session**: Search memory for relevant past context');
+    sections.push('2. **During work**: Save discoveries, patterns, decisions as they happen');
+    sections.push('3. **After feature**: Save complete implementation with summaries');
+    sections.push('4. **End of session**: Save session summary for future sessions');
+    sections.push('');
+    sections.push('### Session Summary');
+    sections.push('');
+    sections.push('Before ending a session or when context is getting long, save a summary:');
+    sections.push('```');
+    sections.push('type: observation');
+    sections.push('title: "Session summary: <date or topic>"');
+    sections.push('content: "Accomplished: ... | Pending: ... | Key decisions: ..."');
+    sections.push('```');
+    sections.push('');
+    sections.push('When in doubt, ask to review @AGENTS.md first.');
+    sections.push('');
+    // Decision Records section — inject active ADRs if any exist
+    try {
+        const projectRoot = config.rulebookDir ? process.cwd() : process.cwd();
+        const dm = new DecisionManager(projectRoot, config.rulebookDir || '.rulebook');
+        const decisionContent = await dm.getForGenerator();
+        if (decisionContent) {
+            sections.push(decisionContent);
+        }
+    }
+    catch {
+        // No decisions directory yet — skip silently
+    }
+    // Project Knowledge section — inject patterns/anti-patterns if any exist
+    try {
+        const projectRoot = config.rulebookDir ? process.cwd() : process.cwd();
+        const km = new KnowledgeManager(projectRoot, config.rulebookDir || '.rulebook');
+        const knowledgeContent = await km.getForGenerator();
+        if (knowledgeContent) {
+            sections.push(knowledgeContent);
+        }
+    }
+    catch {
+        // No knowledge directory yet — skip silently
+    }
+    sections.push('<!-- RULEBOOK:END -->');
+    return sections.join('\n');
+}
+export async function generateLanguageRules(language) {
+    const templatesDir = path.join(getTemplatesDir(), 'languages');
+    const templatePath = path.join(templatesDir, `${language.toUpperCase()}.md`);
+    if (await fileExists(templatePath)) {
+        return await readFile(templatePath);
+    }
+    return `<!-- ${language.toUpperCase()}:START -->\n# ${language.charAt(0).toUpperCase() + language.slice(1)} Rules\n\nLanguage-specific rules for ${language}.\n<!-- ${language.toUpperCase()}:END -->\n`;
+}
+export async function generateModuleRules(module) {
+    const templatesDir = path.join(getTemplatesDir(), 'modules');
+    // Try UPPERCASE.md first, then kebab-case.md (e.g. sequential_thinking → sequential-thinking.md)
+    const candidates = [
+        path.join(templatesDir, `${module.toUpperCase()}.md`),
+        path.join(templatesDir, `${module.toLowerCase().replace(/_/g, '-')}.md`),
+    ];
+    for (const templatePath of candidates) {
+        if (await fileExists(templatePath)) {
+            return await readFile(templatePath);
+        }
+    }
+    return `<!-- ${module.toUpperCase()}:START -->\n# ${module.charAt(0).toUpperCase() + module.slice(1)} Instructions\n\nModule-specific instructions for ${module}.\n<!-- ${module.toUpperCase()}:END -->\n`;
+}
+export async function generateGitRules(pushMode) {
+    const templatesDir = path.join(getTemplatesDir(), 'git');
+    const templatePath = path.join(templatesDir, 'GIT_WORKFLOW.md');
+    let gitRules = '';
+    if (await fileExists(templatePath)) {
+        gitRules = await readFile(templatePath);
+    }
+    else {
+        gitRules = `<!-- GIT:START -->\n# Git Workflow Rules\n\nGit workflow guidelines for this project.\n<!-- GIT:END -->\n`;
+    }
+    // Add push mode configuration
+    const pushModeConfig = `\n**AI Assistant Git Push Mode**: ${pushMode.toUpperCase()}\n\n`;
+    const pushModeInstructions = {
+        manual: `**CRITICAL**: Never execute \`git push\` commands automatically.
+Always provide push commands for manual execution by the user.
+
+Example:
+\`\`\`
+✋ MANUAL ACTION REQUIRED:
+Run these commands manually (SSH password may be required):
+  git push origin main
+  git push origin v1.0.0
+\`\`\``,
+        prompt: `**CRITICAL**: Always ask user permission before pushing.
+
+Example:
+\`\`\`
+Ready to push changes. Execute these commands?
+  git push origin main
+
+[Y/n]:
+\`\`\``,
+        auto: `**INFO**: Automatic push enabled.
+AI assistants may execute push commands automatically.
+
+⚠️ Only use this mode if:
+- SSH key has no password
+- GitHub CLI is authenticated
+- You trust the AI assistant completely`,
+    };
+    // Insert push mode config after <!-- GIT:START -->
+    gitRules = gitRules.replace('<!-- GIT:START -->', `<!-- GIT:START -->\n${pushModeConfig}${pushModeInstructions[pushMode]}\n`);
+    return gitRules;
+}
+/**
+ * Write modular directive file to /rulebook/ directory
+ * Adds header and footer comments for consistency
+ */
+async function writeModularFile(projectRoot, fileName, content, rulebookDir = '.rulebook') {
+    const specsPath = path.join(projectRoot, rulebookDir, 'specs');
+    await ensureDir(specsPath);
+    const filePath = path.join(specsPath, `${fileName}.md`);
+    // Add header comment if not already present
+    const headerComment = `<!-- ${fileName}:START -->\n`;
+    const footerComment = `\n<!-- ${fileName}:END -->`;
+    let finalContent = content.trim();
+    // Add header if not present
+    if (!finalContent.startsWith(headerComment.trim())) {
+        finalContent = headerComment + finalContent;
+    }
+    // Add footer if not present
+    if (!finalContent.endsWith(footerComment.trim())) {
+        finalContent = finalContent + footerComment;
+    }
+    await writeFile(filePath, finalContent);
+}
+/**
+ * Generate reference section for AGENTS.md
+ */
+function generateReferenceSection(name, fileName, description, quickRef, rulebookDir = '.rulebook') {
+    const sections = [];
+    sections.push(`### ${name}`);
+    sections.push('');
+    sections.push(`For comprehensive ${description}, see \`/${rulebookDir}/specs/${fileName}.md\``);
+    sections.push('');
+    sections.push('Quick reference:');
+    for (const item of quickRef) {
+        sections.push(`- ${item}`);
+    }
+    sections.push('');
+    return sections.join('\n');
+}
+/**
+ * Generate language reference for AGENTS.md
+ */
+function generateLanguageReference(language, rulebookDir = '.rulebook') {
+    const languageName = language.charAt(0).toUpperCase() + language.slice(1);
+    const quickRef = [
+        'Type safety and strict mode',
+        'Code quality standards',
+        'Testing requirements (95%+ coverage)',
+        'Package management',
+        'Error handling patterns',
+    ];
+    return generateReferenceSection(`${languageName} Development Rules`, language.toUpperCase(), `${languageName}-specific guidelines`, quickRef, rulebookDir);
+}
+/**
+ * Generate module reference for AGENTS.md
+ */
+function generateModuleReference(module, rulebookDir = '.rulebook') {
+    const moduleName = module.charAt(0).toUpperCase() + module.slice(1).replace(/_/g, ' ');
+    const quickRef = ['Module-specific instructions', 'Usage guidelines', 'Integration patterns'];
+    return generateReferenceSection(`${moduleName} Instructions`, module.toUpperCase(), `${moduleName}-specific instructions`, quickRef, rulebookDir);
+}
+/**
+ * Load project configuration from .rulebook file
+ */
+async function loadProjectConfigFromRulebook(projectRoot = process.cwd()) {
+    const { createConfigManager } = await import('../state/config-manager.js');
+    const configManager = createConfigManager(projectRoot);
+    try {
+        const rulebookConfig = await configManager.loadConfig();
+        // Map RulebookConfig to ProjectConfig
+        const projectConfig = {
+            languages: rulebookConfig.languages || [],
+            modules: rulebookConfig.modules || [],
+            modular: rulebookConfig.modular !== false, // Default to true
+            rulebookDir: rulebookConfig.rulebookDir || '.rulebook',
+        };
+        return projectConfig;
+    }
+    catch {
+        // If .rulebook doesn't exist or can't be read, return empty config
+        return {};
+    }
+}
+const AGENT_REGISTRY = [
+    // Core agents
+    {
+        task: 'Implementation',
+        agent: 'implementer',
+        model: 'sonnet',
+        when: 'Writing new code or modifying existing',
+    },
+    {
+        task: 'Research',
+        agent: 'researcher',
+        model: 'haiku',
+        when: 'Exploring codebase, finding patterns',
+    },
+    {
+        task: 'Testing',
+        agent: 'tester',
+        model: 'sonnet',
+        when: 'Writing and running tests',
+    },
+    {
+        task: 'Documentation',
+        agent: 'docs-writer',
+        model: 'haiku',
+        when: 'README, docs, changelogs',
+    },
+    {
+        task: 'Code Review',
+        agent: 'code-reviewer',
+        model: 'sonnet',
+        when: 'Reviewing implementations for quality',
+    },
+    {
+        task: 'Build/CI',
+        agent: 'build-engineer',
+        model: 'sonnet',
+        when: 'Build failures, CI, dependencies',
+    },
+    {
+        task: 'Security',
+        agent: 'security-reviewer',
+        model: 'haiku',
+        when: 'Dependency audit, vulnerability review',
+    },
+    // Specialist agents
+    {
+        task: 'Architecture',
+        agent: 'architect',
+        model: 'opus',
+        when: 'System design, ADRs, scalability decisions',
+    },
+    {
+        task: 'API Design',
+        agent: 'api-designer',
+        model: 'sonnet',
+        when: 'REST/GraphQL endpoints, OpenAPI specs',
+    },
+    {
+        task: 'Database',
+        agent: 'database-architect',
+        model: 'sonnet',
+        when: 'Schema design, migrations, query optimization',
+    },
+    {
+        task: 'DevOps',
+        agent: 'devops-engineer',
+        model: 'sonnet',
+        when: 'CI/CD, Docker, Kubernetes, infrastructure',
+    },
+    {
+        task: 'Performance',
+        agent: 'performance-engineer',
+        model: 'sonnet',
+        when: 'Profiling, benchmarks, optimization',
+    },
+    {
+        task: 'Refactoring',
+        agent: 'refactoring-agent',
+        model: 'sonnet',
+        when: 'Code smells, complexity reduction, cleanup',
+    },
+    {
+        task: 'Migration',
+        agent: 'migration-engineer',
+        model: 'sonnet',
+        when: 'DB migrations, API migrations, upgrades',
+    },
+    {
+        task: 'Accessibility',
+        agent: 'accessibility-reviewer',
+        model: 'haiku',
+        when: 'WCAG compliance, ARIA, screen readers',
+    },
+    {
+        task: 'i18n',
+        agent: 'i18n-engineer',
+        model: 'haiku',
+        when: 'Internationalization, localization, RTL',
+    },
+    {
+        task: 'UX Review',
+        agent: 'ux-reviewer',
+        model: 'haiku',
+        when: 'Usability, interaction patterns, error states',
+    },
+    // Orchestration
+    {
+        task: 'Orchestration',
+        agent: 'team-lead',
+        model: 'opus',
+        when: 'Multi-agent coordination for complex tasks',
+    },
+];
+/**
+ * Generate the agent delegation section for AGENTS.md.
+ * Adapts table based on detected languages.
+ */
+export function generateDelegationSection(config) {
+    const lines = [];
+    const primaryLang = config.languages?.[0] || 'the project language';
+    lines.push('## Agent Delegation');
+    lines.push('');
+    lines.push('Delegate work to specialist agents instead of doing everything in the main conversation. Each agent uses a cost-appropriate model.');
+    lines.push('');
+    lines.push('| Task | Agent | Model | When to use |');
+    lines.push('|------|-------|-------|-------------|');
+    for (const entry of AGENT_REGISTRY) {
+        lines.push(`| ${entry.task} | ${entry.agent} | ${entry.model} | ${entry.when} |`);
+    }
+    lines.push('');
+    lines.push('### Delegation Rules');
+    lines.push('');
+    lines.push('1. **Never write code directly in the main conversation** — delegate to the appropriate agent');
+    lines.push('2. **After implementing code**, launch tester + docs-writer in parallel to update tests and documentation');
+    lines.push('3. **The main conversation** serves for planning, coordination, and user communication only');
+    lines.push('4. **Use haiku agents** (researcher, docs-writer, security-reviewer) for read-only tasks — they are significantly cheaper');
+    lines.push('5. **Launch independent agents in parallel** when possible to maximize throughput');
+    lines.push('');
+    lines.push(`> **Project context**: Primary language is **${primaryLang}**. Agents are pre-configured with this context.`);
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Resolve placeholder values from project config.
+ */
+export function resolveAgentPlaceholders(config) {
+    const primaryLang = config.languages?.[0] || 'TypeScript';
+    // Map language to common test framework
+    const testFrameworkMap = {
+        typescript: 'vitest',
+        javascript: 'jest',
+        python: 'pytest',
+        rust: 'cargo test',
+        go: 'go test',
+        java: 'JUnit',
+        csharp: 'xUnit',
+        ruby: 'RSpec',
+        php: 'PHPUnit',
+        swift: 'XCTest',
+        kotlin: 'JUnit',
+        dart: 'flutter test',
+        elixir: 'ExUnit',
+        scala: 'ScalaTest',
+    };
+    // Map language to file naming convention
+    const fileNamingMap = {
+        typescript: 'kebab-case',
+        javascript: 'kebab-case',
+        python: 'snake_case',
+        rust: 'snake_case',
+        go: 'snake_case',
+        java: 'PascalCase',
+        csharp: 'PascalCase',
+        ruby: 'snake_case',
+        php: 'PascalCase',
+        swift: 'PascalCase',
+        kotlin: 'PascalCase',
+        dart: 'snake_case',
+        elixir: 'snake_case',
+        scala: 'PascalCase',
+    };
+    const langKey = primaryLang.toLowerCase();
+    return {
+        '{{language}}': primaryLang,
+        '{{framework}}': 'none',
+        '{{test_framework}}': testFrameworkMap[langKey] || 'the project test framework',
+        '{{file_naming}}': fileNamingMap[langKey] || 'kebab-case',
+    };
+}
+/**
+ * Substitute placeholders in agent template content.
+ */
+export function substituteAgentPlaceholders(content, placeholders) {
+    let result = content;
+    for (const [key, value] of Object.entries(placeholders)) {
+        result = result.replaceAll(key, value);
+    }
+    return result;
+}
+/**
+ * Install agent definitions to .claude/agents/ with placeholder substitution.
+ */
+async function installAgentsWithPlaceholders(projectRoot, config) {
+    const agentsDir = path.join(getTemplatesDir(), 'agents');
+    const targetDir = path.join(projectRoot, '.claude', 'agents');
+    if (!(await fileExists(agentsDir)))
+        return;
+    await ensureDir(targetDir);
+    const placeholders = resolveAgentPlaceholders(config);
+    const { readdirSync } = await import('fs');
+    const files = readdirSync(agentsDir).filter((f) => f.endsWith('.md'));
+    for (const file of files) {
+        const content = await readFile(path.join(agentsDir, file));
+        const substituted = substituteAgentPlaceholders(content, placeholders);
+        await writeFile(path.join(targetDir, file), substituted);
+    }
+}
+/**
+ * Names of `core/` skills that are user-invocable (slash-command or
+ * natural-language trigger), so their SKILL.md files must land in
+ * `.claude/skills/` alongside the `dev/` skills. Non-invocable core
+ * skills (agent-automation, dag, documentation-rules, quality-enforcement,
+ * rulebook) stay referenced via AGENTS.md only.
+ */
+export const INVOCABLE_CORE_SKILLS = [
+    'rulebook-terse',
+    'rulebook-terse-commit',
+    'rulebook-terse-review',
+    'karpathy-guidelines',
+];
+/**
+ * Copy every SKILL.md under a source directory into .claude/skills/.
+ * Used for both the full `dev/` category and a curated subset of `core/`
+ * skills (see INVOCABLE_CORE_SKILLS).
+ *
+ * Exported for test coverage of the install pipeline.
+ */
+export async function installSkillsFromSource(sourceDir, targetSkillsDir, filter) {
+    const { readdirSync, statSync } = await import('fs');
+    if (!(await fileExists(sourceDir)))
+        return;
+    await ensureDir(targetSkillsDir);
+    const entries = readdirSync(sourceDir);
+    for (const entry of entries) {
+        if (filter && !filter.includes(entry))
+            continue;
+        const entryPath = path.join(sourceDir, entry);
+        if (!statSync(entryPath).isDirectory())
+            continue;
+        const skillFile = path.join(entryPath, 'SKILL.md');
+        if (!(await fileExists(skillFile)))
+            continue;
+        const targetSkillDir = path.join(targetSkillsDir, entry);
+        await ensureDir(targetSkillDir);
+        const content = await readFile(skillFile);
+        await writeFile(path.join(targetSkillDir, 'SKILL.md'), content);
+    }
+}
+/**
+ * Install dev skills + invocable core skills to .claude/skills/ (modern
+ * Claude Code skills format). Each skill is a directory with a SKILL.md
+ * file. Always installed on init/update — useful for any project.
+ */
+async function installDevSkillsFromTemplates(projectRoot) {
+    const skillsTargetDir = path.join(projectRoot, '.claude', 'skills');
+    const templatesRoot = getTemplatesDir();
+    await installSkillsFromSource(path.join(templatesRoot, 'skills', 'dev'), skillsTargetDir);
+    await installSkillsFromSource(path.join(templatesRoot, 'skills', 'core'), skillsTargetDir, INVOCABLE_CORE_SKILLS);
+}
+/**
+ * Generate modular AGENTS.md with references
+ */
+export async function generateModularAgents(config, projectRoot = process.cwd()) {
+    // Load saved configuration from .rulebook and merge with provided config
+    const savedConfig = await loadProjectConfigFromRulebook(projectRoot);
+    // Merge: saved config takes precedence for languages/modules
+    // provided config takes precedence for other settings (like rulebookDir when explicitly set)
+    const mergedConfig = {
+        ...config,
+        languages: savedConfig.languages?.length ? savedConfig.languages : config.languages,
+        modules: savedConfig.modules?.length ? savedConfig.modules : config.modules,
+        modular: savedConfig.modular !== undefined ? savedConfig.modular : config.modular !== false,
+        // rulebookDir: provided config takes precedence if explicitly set, otherwise use saved or default
+        rulebookDir: config.rulebookDir || savedConfig.rulebookDir || '.rulebook',
+    };
+    const rulebookDir = mergedConfig.rulebookDir || '.rulebook';
+    const sections = [];
+    // Add Rulebook section (core rules stay embedded - simplified)
+    sections.push(await generateAgentsContent(mergedConfig));
+    sections.push('');
+    // Write RULEBOOK.md to /rulebook/ (ALWAYS included - highest precedence)
+    const rulebookContent = await generateCoreRules('RULEBOOK');
+    await writeModularFile(projectRoot, 'RULEBOOK', rulebookContent.trim(), rulebookDir);
+    // Write QUALITY_ENFORCEMENT to /rulebook/ (always included unless light mode)
+    if (!mergedConfig.lightMode) {
+        const enforcementContent = await generateCoreRules('QUALITY_ENFORCEMENT');
+        await writeModularFile(projectRoot, 'QUALITY_ENFORCEMENT', enforcementContent.trim(), rulebookDir);
+    }
+    // Write TIER1_PROHIBITIONS to /rulebook/ (always included — highest precedence directives)
+    const tier1Content = await generateCoreRules('TIER1_PROHIBITIONS');
+    if (tier1Content.trim()) {
+        await writeModularFile(projectRoot, 'TIER1_PROHIBITIONS', tier1Content.trim(), rulebookDir);
+    }
+    // Write TOKEN_OPTIMIZATION to /rulebook/ (always included unless light mode)
+    if (!mergedConfig.lightMode) {
+        const tokenOptContent = await generateCoreRules('TOKEN_OPTIMIZATION');
+        if (tokenOptContent.trim()) {
+            await writeModularFile(projectRoot, 'TOKEN_OPTIMIZATION', tokenOptContent.trim(), rulebookDir);
+        }
+    }
+    // Write Git workflow rules to /.rulebook/specs/GIT.md
+    if (mergedConfig.includeGitWorkflow) {
+        const gitRules = await generateGitRules(mergedConfig.gitPushMode || 'manual');
+        await writeModularFile(projectRoot, 'GIT', gitRules.trim(), rulebookDir);
+    }
+    // If WORKSPACE.md spec exists, add reference in AGENTS.md
+    {
+        const { existsSync } = await import('fs');
+        const wsSpecPath = path.join(projectRoot, rulebookDir, 'specs', 'WORKSPACE.md');
+        if (existsSync(wsSpecPath)) {
+            sections.push('## Workspace Mode');
+            sections.push('');
+            sections.push(`**This project is part of a multi-project workspace.** All MCP tool calls MUST include the correct \`projectId\` parameter.`);
+            sections.push('');
+            sections.push(`**📋 ALWAYS read \`/${rulebookDir}/specs/WORKSPACE.md\` to understand project routing before using any Rulebook MCP tools.**`);
+            sections.push('');
+        }
+    }
+    // Write language files and add references
+    if (mergedConfig.languages.length > 0) {
+        sections.push('## Language-Specific Rules');
+        sections.push('');
+        sections.push(`The following languages are configured for this project. For detailed rules, see the corresponding files in \`/${rulebookDir}/specs/\`:`);
+        sections.push('');
+        // Write all language files first
+        for (const language of mergedConfig.languages) {
+            const langRules = await generateLanguageRules(language);
+            await writeModularFile(projectRoot, language.toUpperCase(), langRules, rulebookDir);
+        }
+        // Then add all references together
+        for (const language of mergedConfig.languages) {
+            sections.push(generateLanguageReference(language, rulebookDir));
+        }
+        sections.push(`**Usage**: When working with language-specific code, reference the corresponding \`/${rulebookDir}/specs/[LANGUAGE].md\` file for detailed guidelines.`);
+        sections.push('');
+    }
+    // Write module files and add references
+    // First, write AGENT_AUTOMATION if not minimal (core file, not module)
+    if (!mergedConfig.minimal) {
+        const agentAutomation = await generateCoreRules('AGENT_AUTOMATION');
+        await writeModularFile(projectRoot, 'AGENT_AUTOMATION', agentAutomation, rulebookDir);
+    }
+    // Write MULTI_AGENT directives (after AGENT_AUTOMATION)
+    if (!mergedConfig.minimal) {
+        const multiAgentContent = await generateCoreRules('MULTI_AGENT');
+        await writeModularFile(projectRoot, 'MULTI_AGENT', multiAgentContent, rulebookDir);
+    }
+    // Then handle all modules together
+    const allModules = [];
+    if (!mergedConfig.minimal) {
+        allModules.push('agent_automation');
+        allModules.push('multi_agent');
+    }
+    allModules.push(...mergedConfig.modules);
+    if (allModules.length > 0) {
+        sections.push('## Module-Specific Instructions');
+        sections.push('');
+        sections.push(`The following modules are configured for this project. For detailed instructions, see the corresponding files in \`/${rulebookDir}/specs/\`:`);
+        sections.push('');
+        // Write all module files first (except AGENT_AUTOMATION which is already written)
+        for (const module of mergedConfig.modules) {
+            const moduleRules = await generateModuleRules(module);
+            await writeModularFile(projectRoot, module.toUpperCase(), moduleRules, rulebookDir);
+        }
+        // Then add all references together
+        if (!mergedConfig.minimal) {
+            sections.push(generateModuleReference('agent_automation', rulebookDir));
+            sections.push(generateModuleReference('multi_agent', rulebookDir));
+        }
+        for (const module of mergedConfig.modules) {
+            sections.push(generateModuleReference(module, rulebookDir));
+        }
+        sections.push(`**Usage**: When working with module-specific features, reference the corresponding \`/${rulebookDir}/specs/[MODULE].md\` file for detailed instructions.`);
+        sections.push('');
+    }
+    // Add enabled skills section (v2.0)
+    try {
+        const { SkillsManager, getDefaultTemplatesPath } = await import('../skills/skills-manager.js');
+        const { createConfigManager } = await import('../state/config-manager.js');
+        const configManager = createConfigManager(projectRoot);
+        const rulebookConfig = await configManager.loadConfig();
+        if (rulebookConfig.skills?.enabled && rulebookConfig.skills.enabled.length > 0) {
+            const skillsManager = new SkillsManager(getDefaultTemplatesPath(), projectRoot);
+            const enabledSkills = await skillsManager.getEnabledSkills(rulebookConfig);
+            // Add capabilities summary
+            if (enabledSkills.length > 0) {
+                sections.push('## Project Capabilities');
+                sections.push('');
+                sections.push('This project has the following AI-assisted capabilities enabled:');
+                sections.push('');
+                // Group skills by category for summary
+                const categorySummary = new Map();
+                for (const skill of enabledSkills) {
+                    const category = skill.category;
+                    if (!categorySummary.has(category)) {
+                        categorySummary.set(category, []);
+                    }
+                    categorySummary.get(category)?.push(skill.metadata.name);
+                }
+                for (const [category, skills] of categorySummary.entries()) {
+                    const categoryLabel = category.charAt(0).toUpperCase() + category.slice(1);
+                    sections.push(`- **${categoryLabel}**: ${skills.join(', ')}`);
+                }
+                sections.push('');
+                sections.push('Use `rulebook skill list` to see all available skills.');
+                sections.push('Use `rulebook skill add <skill-id>` to enable additional skills.');
+                sections.push('');
+            }
+            // Add skills content (includes index and detailed rules)
+            const skillsContent = await skillsManager.mergeSkillsContent(rulebookConfig);
+            if (skillsContent) {
+                sections.push(skillsContent);
+            }
+        }
+    }
+    catch {
+        // Skills not configured or error loading - skip silently
+    }
+    // Add monorepo package index and generate per-package AGENTS.md if monorepo detected
+    try {
+        const { detectMonorepo } = await import('../detect/detector.js');
+        const monorepo = await detectMonorepo(projectRoot);
+        if (monorepo.detected && monorepo.packages.length > 0) {
+            sections.push('## Monorepo Package Index');
+            sections.push('');
+            sections.push(`Monorepo tool: **${monorepo.tool}**`);
+            sections.push('');
+            sections.push('Packages:');
+            for (const pkg of monorepo.packages) {
+                sections.push(`- \`${pkg}/\` — see \`${pkg}/AGENTS.md\` for package-specific rules`);
+            }
+            sections.push('');
+            // Generate per-package AGENTS.md files
+            for (const pkg of monorepo.packages) {
+                await generatePackageAgentsMd(path.join(projectRoot, pkg), mergedConfig, projectRoot).catch(() => {
+                    /* skip on error */
+                });
+            }
+        }
+    }
+    catch {
+        // Monorepo detection failed — skip silently
+    }
+    // Generate multi-tool IDE config files (GEMINI.md, .windsurfrules, etc.)
+    try {
+        const { detectGeminiCli, detectContinueDev, detectWindsurf, detectGithubCopilot } = await import('../detect/detector.js');
+        const { generateMultiToolConfigs } = await import('../ide/multi-tool-generator.js');
+        const [geminiCli, continueDev, windsurf, githubCopilot] = await Promise.all([
+            detectGeminiCli(projectRoot),
+            detectContinueDev(projectRoot),
+            detectWindsurf(projectRoot),
+            detectGithubCopilot(projectRoot),
+        ]);
+        await generateMultiToolConfigs(projectRoot, {
+            languages: [],
+            modules: [],
+            existingAgents: null,
+            geminiCli,
+            continueDev,
+            windsurf,
+            githubCopilot,
+        });
+    }
+    catch {
+        // Multi-tool generation failed - skip silently
+    }
+    // Generate agent delegation section
+    sections.push(generateDelegationSection(mergedConfig));
+    // Install agent definitions and dev skills to .claude/
+    try {
+        await installAgentsWithPlaceholders(projectRoot, mergedConfig);
+        await installDevSkillsFromTemplates(projectRoot);
+    }
+    catch {
+        // Agent/skill installation failed — skip silently
+    }
+    // Append AGENTS.override.md content if present and non-empty
+    try {
+        const { readOverrideContent } = await import('../state/override-manager.js');
+        const overrideContent = await readOverrideContent(projectRoot);
+        if (overrideContent) {
+            sections.push('');
+            sections.push('## Project-Specific Overrides');
+            sections.push('');
+            sections.push(overrideContent);
+        }
+    }
+    catch {
+        // Override reading failed — skip silently
+    }
+    return sections.join('\n').trim() + '\n';
+}
+/**
+ * Generate a minimal AGENTS.md for an individual package inside a monorepo.
+ * Inherits language detection from the package root and links back to the root AGENTS.md.
+ */
+export async function generatePackageAgentsMd(packageRoot, rootConfig, monorepoRoot) {
+    const { existsSync } = await import('fs');
+    const { detectProject } = await import('../detect/detector.js');
+    const agentsPath = path.join(packageRoot, 'AGENTS.md');
+    // Don't overwrite if already customized (has RULEBOOK markers)
+    if (existsSync(agentsPath)) {
+        const existing = await readFile(agentsPath).catch(() => '');
+        if (existing.includes('<!-- RULEBOOK:START -->'))
+            return;
+    }
+    // Detect languages specific to this package
+    const pkgDetection = await detectProject(packageRoot).catch(() => null);
+    const langList = pkgDetection
+        ? pkgDetection.languages.map((l) => l.language)
+        : rootConfig.languages;
+    const relRoot = path.relative(packageRoot, monorepoRoot) || '..';
+    const content = [
+        '<!-- RULEBOOK:START -->',
+        `# Package Agent Directives`,
+        '',
+        `> Part of a monorepo. Root rules: [\`${relRoot}/AGENTS.md\`](${relRoot}/AGENTS.md)`,
+        '',
+        '## Languages',
+        '',
+        langList.length > 0
+            ? langList.map((l) => `- ${l.toUpperCase()}`).join('\n')
+            : '- (inherits from root)',
+        '',
+        '## Rules',
+        '',
+        `- Follow root AGENTS.md for task management and quality gates`,
+        `- Package-specific overrides go in \`AGENTS.override.md\` (if present)`,
+        '<!-- RULEBOOK:END -->',
+        '',
+    ].join('\n');
+    await writeFile(agentsPath, content);
+}
+/**
+ * Generate lean AGENTS.md — a lightweight index (< 3KB) referencing spec files.
+ * All spec files are still written to .rulebook/specs/ by generateModularAgents.
+ */
+export async function generateLeanAgents(config, projectRoot = process.cwd()) {
+    // First run modular generation to ensure all spec files are up to date
+    await generateModularAgents(config, projectRoot);
+    const rulebookDir = config.rulebookDir || '.rulebook';
+    // Load lean template
+    const templatesDir = path.join(getTemplatesDir(), 'core');
+    const leanTemplatePath = path.join(templatesDir, 'AGENTS_LEAN.md');
+    let template = '';
+    if (await fileExists(leanTemplatePath)) {
+        template = await readFile(leanTemplatePath);
+    }
+    else {
+        template = `<!-- RULEBOOK:START -->\n# Project Agent Directives\n\nSee \`/${rulebookDir}/specs/\` for all rules.\n\n- **Task Management**: \`/${rulebookDir}/specs/RULEBOOK.md\`\n- **Quality Gates**: \`/${rulebookDir}/specs/QUALITY_ENFORCEMENT.md\`\n- **Git Workflow**: \`/${rulebookDir}/specs/GIT.md\`\n<!-- RULEBOOK:END -->\n`;
+    }
+    // Build language refs
+    const langRefs = config.languages
+        .map((lang) => `- **${lang.toUpperCase()}**: \`/${rulebookDir}/specs/${lang.toUpperCase()}.md\``)
+        .join('\n');
+    template = template.replace('LANGUAGE_REFS', langRefs || '_None configured_');
+    // Build module refs (core + user modules)
+    const coreModules = config.minimal ? [] : ['agent_automation', 'multi_agent'];
+    const allModules = [...coreModules, ...(config.modules || [])];
+    const moduleRefs = allModules
+        .map((mod) => `- **${mod.toUpperCase()}**: \`/${rulebookDir}/specs/${mod.toUpperCase()}.md\``)
+        .join('\n');
+    template = template.replace('MODULE_REFS', moduleRefs || '_None configured_');
+    return template;
+}
+/**
+ * Generate full AGENTS.md (modular by default, legacy mode available)
+ */
+export async function generateFullAgents(config, projectRoot = process.cwd()) {
+    // Always use lean template — the procedural 6k-line output is deprecated.
+    return await generateLeanAgents(config, projectRoot);
+}
+//# sourceMappingURL=generator.js.map