@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/commands-v2/handlers/project.js

@@ -0,0 +1,1035 @@
+/**
+ * Project Commands for REPL V2
+ *
+ * Commands for project management: init, backlog, workflow, anchors, design, sketch, refine
+ */
+import { executeCommand } from '../registry.js';
+import { BacklogOverlayV2, WorkflowOverlayV2, DocsOverlayV2, DocumentDetailOverlayV2, AnchorsOverlayV2, ProjectsOverlayV2, NewProjectOverlayV2, OnboardingWizardOverlayV2, KeysOverlayV2, ArchTypeOverlayV2, ModelWarningOverlayV2 } from '../../ui/overlay/index.js';
+import { projectRepository, workItemRepository } from '../../db/repositories/index.js';
+import { setCurrentProject, getCurrentProject } from '../../tools/project-db.js';
+import { getSkillPrompt } from '../../repl-helpers.js';
+import { getModelTier, modelMeetsTier } from '../../utils/model-tiers.js';
+import { getCurrentProjectIdForTracking, handleProjectSwitch } from './session.js';
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Sync the footer project name with the current project.
+ * Call after any overlay that might change the current project.
+ */
+function syncFooterWithCurrentProject(ctx) {
+    const current = getCurrentProject();
+    ctx.ui.setProjectName(current?.displayName ?? null);
+}
+// =============================================================================
+// New Command
+// =============================================================================
+export const newCommand = {
+    name: 'new',
+    description: 'Create a new project',
+    details: 'Interactive wizard to scaffold a new project. Asks about project name, type, tech stack, and documentation preferences. Creates project structure with COMPILR.md, backlog, and optional separate docs repo.',
+    examples: [{ code: '/new' }],
+    interactions: [
+        '8-step wizard (0-7)',
+        '↑/↓ for selection steps, type for input steps',
+        'Enter to confirm, Esc to go back',
+    ],
+    async execute(_args, ctx) {
+        // Track project ID before overlay (for session/team switch handling)
+        const oldProjectId = getCurrentProjectIdForTracking();
+        const newProjectOverlay = new NewProjectOverlayV2();
+        const result = await ctx.ui.showOverlay(newProjectOverlay);
+        // User cancelled
+        if (!result?.created) {
+            return true;
+        }
+        // Check if this was an import or new project
+        const isImport = result.imported === true;
+        // Show success message
+        if (isImport) {
+            ctx.ui.print({ type: 'success', message: `Project imported: ${result.projectPath ?? ''}` });
+        }
+        else {
+            ctx.ui.print({ type: 'success', message: `Project created: ${result.projectPath ?? ''}` });
+            if (result.docsPath) {
+                ctx.ui.print({ type: 'success', message: `Docs repo created: ${result.docsPath}` });
+            }
+        }
+        // Register project in database if tracking is enabled
+        if (result.trackInDatabase && result.projectName && result.projectPath) {
+            try {
+                // Determine display name - for imports, use detected name; for new projects, prettify
+                const displayName = result.detectedProject?.displayName
+                    ?? result.projectName.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+                const project = projectRepository.create({
+                    name: result.projectName,
+                    display_name: displayName,
+                    description: result.description,
+                    path: result.projectPath,
+                    type: 'general',
+                    workflow_mode: result.workflowMode ?? 'flexible',
+                    git_remote: result.gitRemote,
+                    // For imports, include detected language and framework
+                    language: result.detectedProject?.language ?? undefined,
+                    framework: result.detectedProject?.framework ?? undefined,
+                    package_manager: result.detectedProject?.packageManager ?? undefined,
+                });
+                // For imports, set lifecycle to 'active' immediately
+                if (isImport) {
+                    projectRepository.update(project.id, { lifecycle_state: 'active' });
+                }
+                setCurrentProject({ id: project.id, name: project.name, displayName: project.displayName, path: project.path });
+                ctx.ui.setProjectName(project.displayName);
+                ctx.ui.print({ type: 'success', message: `Project tracked in database (${result.workflowMode ?? 'flexible'} mode)` });
+                ctx.ui.print({ type: 'success', message: `"${project.displayName}" is now the current project` });
+                // Handle project switch - saves old session/team and creates fresh team for new project
+                const switchResult = await handleProjectSwitch(oldProjectId, ctx.agent ?? null, ctx.team && ctx.agentFactory ? {
+                    team: ctx.team,
+                    agentFactory: ctx.agentFactory,
+                } : undefined);
+                if (switchResult?.switched) {
+                    // Update the team if a new one was created
+                    if (switchResult.newTeam && ctx.setTeam) {
+                        ctx.setTeam(switchResult.newTeam);
+                        // Update footer with new active agent
+                        const active = switchResult.newTeam.getActive();
+                        ctx.ui.setActiveTeamAgent({
+                            id: active.id,
+                            displayName: active.displayName,
+                            mascot: active.mascot,
+                        });
+                    }
+                    ctx.ui.print({ type: 'info', message: 'Fresh team and session started for project.' });
+                }
+            }
+            catch (dbError) {
+                ctx.ui.print({ type: 'warning', message: `Could not register in database: ${dbError.message}` });
+            }
+        }
+        // Show next steps
+        ctx.ui.print({ type: 'info', message: '' });
+        if (isImport) {
+            // Import-specific next steps
+            ctx.ui.print({ type: 'info', message: 'Next steps:' });
+            ctx.ui.print({ type: 'info', message: '  Review the generated COMPILR.md' });
+            ctx.ui.print({ type: 'info', message: '  Add existing work items with /backlog' });
+            ctx.ui.print({ type: 'info', message: '  Or ask the agent to explore the codebase' });
+        }
+        else {
+            // New project next steps
+            ctx.ui.print({ type: 'info', message: 'Next steps:' });
+            ctx.ui.print({ type: 'info', message: `  cd ${result.projectPath?.split('/').pop() ?? 'project'}` });
+            ctx.ui.print({ type: 'info', message: '  npm install' });
+            ctx.ui.print({ type: 'info', message: '  npm run dev' });
+        }
+        ctx.ui.print({ type: 'info', message: '' });
+        // Hint for agent interaction
+        const compilrMdPath = result.docsPath
+            ? `${result.docsPath}/COMPILR.md`
+            : `${result.projectPath ?? '.'}/COMPILR.md`;
+        ctx.ui.print({ type: 'info', message: `Tip: Ask the agent to read ${compilrMdPath} to get started!` });
+        if (!isImport) {
+            ctx.ui.print({ type: 'info', message: 'When ready to define requirements, type /design' });
+        }
+        return true;
+    },
+};
+// =============================================================================
+// Init Command (Setup Status Placeholder)
+// =============================================================================
+export const initCommand = {
+    name: 'init',
+    description: 'Run the CLI setup wizard',
+    details: 'Opens the onboarding wizard to configure API keys, git settings, and CLI preferences. Re-runnable anytime to update settings.',
+    examples: [{ code: '/init' }],
+    interactions: [
+        '↑/↓ to navigate wizard steps',
+        'Enter to confirm, Esc to go back',
+        'Type to enter values in input steps',
+    ],
+    async execute(_args, ctx) {
+        // Show onboarding wizard (same as first-run experience)
+        // Loop if user chooses to configure keys
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        while (true) {
+            const wizard = new OnboardingWizardOverlayV2();
+            const result = await ctx.ui.showOverlay(wizard);
+            if (result?.openKeys) {
+                // User chose to configure keys - show keys overlay then loop back
+                const keysOverlay = new KeysOverlayV2();
+                await ctx.ui.showOverlay(keysOverlay);
+                continue;
+            }
+            // Done (completed or cancelled)
+            break;
+        }
+        return true;
+    },
+};
+// =============================================================================
+// Backlog Command
+// =============================================================================
+export const backlogCommand = {
+    name: 'backlog',
+    description: 'View and manage project backlog',
+    details: 'Opens an interactive overlay to browse, filter, and manage backlog items. You can add new items, change status/priority, search, and view details.',
+    examples: [{ code: '/backlog' }],
+    interactions: [
+        'Tab cycles: All → Feature → Bug → Tech-Debt → Chore → Active',
+        '↑/↓ to navigate, ←/→ for pages',
+        'Enter for details, Space to toggle status',
+        '/ to search, n for new item',
+        'Esc to close',
+    ],
+    async execute(_args, ctx) {
+        // Get team agent IDs for owner selection in detail screen
+        const teamAgentIds = ctx.team?.getAgentIds() ?? [];
+        const backlogOverlay = new BacklogOverlayV2(undefined, teamAgentIds);
+        const result = await ctx.ui.showOverlay(backlogOverlay);
+        if (result?.modified) {
+            ctx.ui.print({ type: 'success', message: 'Backlog updated.' });
+        }
+        return true;
+    },
+};
+// =============================================================================
+// Workflow Command
+// =============================================================================
+export const workflowCommand = {
+    name: 'workflow',
+    description: 'View project workflow dashboard',
+    details: 'Displays the current project workflow status, progress through phases (init → design → backlog → scaffold → build), and recommended next actions. Helps you understand where you are in the development process.',
+    examples: [{ code: '/workflow' }],
+    interactions: [
+        '↑/↓ to navigate actions',
+        'Enter to run selected action',
+        'Esc to close',
+    ],
+    async execute(_args, ctx) {
+        // Track project ID before overlay (for session switch handling)
+        const oldProjectId = getCurrentProjectIdForTracking();
+        const workflowOverlay = new WorkflowOverlayV2();
+        const result = await ctx.ui.showOverlay(workflowOverlay);
+        // Handle project switch if it occurred (includes team switching)
+        const switchResult = await handleProjectSwitch(oldProjectId, ctx.agent ?? null, ctx.team && ctx.agentFactory ? {
+            team: ctx.team,
+            agentFactory: ctx.agentFactory,
+        } : undefined);
+        if (switchResult?.switched) {
+            // Update the team if a new one was created/loaded
+            if (switchResult.newTeam && ctx.setTeam) {
+                ctx.setTeam(switchResult.newTeam);
+                // Update footer with new active agent
+                const active = switchResult.newTeam.getActive();
+                ctx.ui.setActiveTeamAgent({
+                    id: active.id,
+                    displayName: active.displayName,
+                    mascot: active.mascot,
+                });
+            }
+            if (switchResult.sessionRestored) {
+                ctx.ui.print({ type: 'info', message: `Session restored (${String(switchResult.messageCount)} messages).` });
+            }
+            else {
+                ctx.ui.print({ type: 'info', message: 'Started fresh session for this project.' });
+            }
+        }
+        // Handle workflow result - execute command if returned
+        if (result?.command) {
+            // Strip leading slash and execute the command
+            const cmd = result.command.replace(/^\//, '');
+            await executeCommand(cmd, '', ctx);
+        }
+        // Sync footer with current project (may have changed during overlay)
+        syncFooterWithCurrentProject(ctx);
+        return true;
+    },
+};
+// =============================================================================
+// Anchors Command
+// =============================================================================
+export const anchorsCommand = {
+    name: 'anchors',
+    description: 'View and manage anchors (persistent context)',
+    details: 'Anchors are critical pieces of information that survive context compaction. They are always included at the top of the context window. Manage both global anchors and project-specific anchors.',
+    examples: [{ code: '/anchors' }],
+    interactions: [
+        '↑/↓ to navigate anchors',
+        '[a] Add new anchor',
+        '[e] or Enter to edit',
+        '[d] to delete',
+        '[r] to refresh',
+        'Esc to close',
+    ],
+    async execute(_args, ctx) {
+        const anchorsOverlay = new AnchorsOverlayV2();
+        const result = await ctx.ui.showOverlay(anchorsOverlay);
+        if (result?.modified) {
+            ctx.ui.print({ type: 'success', message: 'Anchors updated.' });
+        }
+        return true;
+    },
+};
+// =============================================================================
+// Design Command
+// =============================================================================
+export const designCommand = {
+    name: 'design',
+    description: 'Agent-driven requirements gathering',
+    details: 'Comprehensive requirements gathering workflow. The agent guides you through vision, features, and technical context phases, then creates a PRD and populates the backlog with 5-15 items. Best used after /new.',
+    examples: [{ code: '/design' }],
+    async execute(_args, ctx) {
+        // Check if a project is set
+        const currentProject = getCurrentProject();
+        if (!currentProject) {
+            ctx.ui.print({ type: 'error', message: 'No project selected. Run /new or /projects first.' });
+            return true;
+        }
+        // Check model tier - /design works best with large models
+        const currentModel = ctx.model ?? 'unknown';
+        if (!modelMeetsTier(currentModel, '/design')) {
+            const modelTier = getModelTier(currentModel);
+            const warningOverlay = new ModelWarningOverlayV2({
+                command: '/design',
+                currentModel,
+                currentTier: modelTier.tier,
+                suggestedModel: modelTier.suggestedUpgrade,
+                alternativeCommand: '/sketch',
+            });
+            const choice = await ctx.ui.showOverlay(warningOverlay);
+            switch (choice) {
+                case 'cancel':
+                    return true;
+                case 'alternative':
+                    // Run /sketch instead
+                    await executeCommand('sketch', '', ctx);
+                    return true;
+                case 'switch':
+                    // TODO: Hot-switch model when setModel is available in ctx
+                    ctx.ui.print({ type: 'info', message: `Continuing with ${currentModel} (model switching not yet available in V2)` });
+                    break;
+                case 'continue':
+                    // Proceed with current model
+                    break;
+            }
+        }
+        // Get design skill prompt
+        const designPrompt = getSkillPrompt('design');
+        if (!designPrompt) {
+            ctx.ui.print({ type: 'error', message: 'Design skill not found.' });
+            return true;
+        }
+        // Build full message for agent with project context
+        const fullMessage = `I want to design my project and create the backlog.
+
+## PROJECT CONTEXT (IMPORTANT)
+- Project Name: ${currentProject.name} (ID: ${String(currentProject.id)})
+- This is a NEW project being designed from scratch
+- Do NOT scan the filesystem - the current directory is NOT the project
+- Do NOT use detect_project, glob, read_file, or ls tools
+- Focus ONLY on gathering requirements via ask_user questions
+
+## DOCUMENT STORAGE (CRITICAL)
+Save all documents and backlog items using the database - do NOT write files directly.
+- For backlog items: \`workitem_add({ type: "feature", title: "...", description: "...", priority: "high" })\`
+- For documents: \`project_document_add({ doc_type: "prd", title: "...", content: "..." })\`
+- The database is the source of truth for all project documents
+- Do NOT use write_file or edit tools for documentation
+
+${designPrompt}
+
+Please start by using todo_write to track the design phases, then begin with Phase 1: Vision. Use the ask_user tool to gather information efficiently.`;
+        // Queue message for agent
+        ctx.queueAgentMessage({
+            message: fullMessage,
+            displayMessage: 'Start the design process for my project.',
+        });
+        return true;
+    },
+};
+// =============================================================================
+// Sketch Command
+// =============================================================================
+export const sketchCommand = {
+    name: 'sketch',
+    description: 'Quick 6-question project outline',
+    details: 'Lightweight alternative to /design. Asks 6 quick questions and creates 3-8 backlog items. Good for small projects or when you want to get started quickly.',
+    examples: [{ code: '/sketch' }],
+    execute(_args, ctx) {
+        // Check if a project is set
+        const currentProject = getCurrentProject();
+        if (!currentProject) {
+            ctx.ui.print({ type: 'error', message: 'No project selected. Run /new or /projects first.' });
+            return Promise.resolve(true);
+        }
+        // Get sketch skill prompt
+        const sketchPrompt = getSkillPrompt('sketch');
+        if (!sketchPrompt) {
+            ctx.ui.print({ type: 'error', message: 'Sketch skill not found.' });
+            return Promise.resolve(true);
+        }
+        // Build full message for agent with project context
+        const fullMessage = `I want to quickly outline my project.
+
+## PROJECT CONTEXT (IMPORTANT)
+- Project Name: ${currentProject.name} (ID: ${String(currentProject.id)})
+- This is a NEW project being designed from scratch
+- Do NOT scan the filesystem - the current directory is NOT the project
+- Do NOT use detect_project, glob, read_file, or ls tools
+- Focus ONLY on gathering requirements via ask_user questions
+
+## DOCUMENT STORAGE (CRITICAL)
+Save all documents and backlog items using the database - do NOT write files directly.
+- For backlog items: \`workitem_add({ type: "feature", title: "...", description: "..." })\`
+- For documents: \`project_document_add({ doc_type: "prd", title: "...", content: "..." })\`
+- Do NOT use write_file or edit tools for documentation
+
+${sketchPrompt}
+
+Please start by asking me about the type of application I'm building using the ask_user_simple tool.`;
+        // Queue message for agent
+        ctx.queueAgentMessage({
+            message: fullMessage,
+            displayMessage: 'Quick project outline.',
+        });
+        return Promise.resolve(true);
+    },
+};
+// =============================================================================
+// Refine Command
+// =============================================================================
+export const refineCommand = {
+    name: 'refine',
+    description: 'Iterative refinement of requirements',
+    details: 'Iteratively refine backlog items. Can focus on a specific item or let the agent suggest what to refine. Useful for breaking down large items or adding acceptance criteria.',
+    examples: [
+        { code: '/refine', description: 'Agent picks item to refine' },
+        { code: '/refine REQ-003', description: 'Refine specific item' },
+    ],
+    async execute(args, ctx) {
+        // Check if a project is set
+        const currentProject = getCurrentProject();
+        if (!currentProject) {
+            ctx.ui.print({ type: 'error', message: 'No project selected. Run /new or /projects first.' });
+            return true;
+        }
+        // Check if project has work items in database
+        const counts = workItemRepository.getStatusCounts(currentProject.id);
+        const totalItems = counts.backlog + counts.in_progress + counts.completed + counts.skipped;
+        if (totalItems === 0) {
+            ctx.ui.print({ type: 'error', message: 'No backlog items found. Run /design first to create initial requirements.' });
+            return true;
+        }
+        // Check if a specific item ID was provided (e.g., /refine REQ-001)
+        const itemId = args.trim().toUpperCase();
+        const isFocusedRefine = itemId && /^[A-Z]+-\d{3}$/.test(itemId);
+        // For full refine mode (no item ID), check model tier and warn
+        if (!isFocusedRefine) {
+            const currentModel = ctx.model ?? 'unknown';
+            if (!modelMeetsTier(currentModel, '/refine')) {
+                const modelTier = getModelTier(currentModel);
+                const warningOverlay = new ModelWarningOverlayV2({
+                    command: '/refine',
+                    currentModel,
+                    currentTier: modelTier.tier,
+                    suggestedModel: modelTier.suggestedUpgrade,
+                    alternativeCommand: '/refine <ITEM-ID>',
+                });
+                const choice = await ctx.ui.showOverlay(warningOverlay);
+                switch (choice) {
+                    case 'cancel':
+                        return true;
+                    case 'alternative':
+                        ctx.ui.print({ type: 'info', message: 'Tip: Use /refine <ITEM-ID> for focused refinement with smaller models.' });
+                        ctx.ui.print({ type: 'info', message: '   Example: /refine REQ-001' });
+                        return true;
+                    case 'switch':
+                        // TODO: Hot-switch model when setModel is available in ctx
+                        ctx.ui.print({ type: 'info', message: `Continuing with ${currentModel} (model switching not yet available in V2)` });
+                        break;
+                    case 'continue':
+                        break;
+                }
+            }
+        }
+        // Get appropriate skill prompt
+        const skillName = isFocusedRefine ? 'refine-item' : 'refine';
+        const refinePrompt = getSkillPrompt(skillName);
+        if (!refinePrompt) {
+            ctx.ui.print({ type: 'error', message: `${skillName} skill not found.` });
+            return true;
+        }
+        // Build message based on mode
+        const userIntent = isFocusedRefine
+            ? `I want to refine backlog item ${itemId}.`
+            : 'I want to refine my project requirements.';
+        const agentInstructions = isFocusedRefine
+            ? `Please use workitem_query to find item "${itemId}", then guide me through refining it using workitem_update.`
+            : 'Please start by using workitem_query with limit:10 to get an overview, then ask me what I\'d like to focus on using ask_user_simple.';
+        const fullMessage = `${userIntent}
+
+## PROJECT CONTEXT (IMPORTANT)
+- Project Name: ${currentProject.name} (ID: ${String(currentProject.id)})
+- Do NOT scan the filesystem - the current directory is NOT the project
+- Do NOT use detect_project, glob, read_file, or ls tools
+- Use ONLY database tools to access project data
+
+## DOCUMENT STORAGE (CRITICAL)
+Use database tools for all updates - do NOT write files directly.
+- Use \`workitem_query\` to read items
+- Use \`workitem_update\` to modify items
+- Do NOT use write_file or edit tools
+
+${refinePrompt}
+
+${agentInstructions}`;
+        // Queue message for agent
+        ctx.queueAgentMessage({
+            message: fullMessage,
+            displayMessage: userIntent,
+        });
+        return true;
+    },
+};
+// =============================================================================
+// Build Command
+// =============================================================================
+export const buildCommand = {
+    name: 'build',
+    description: 'Implement a backlog item',
+    details: 'Picks the highest priority backlog item (or a specific one) and guides the agent through implementing it. Includes planning, coding, testing, and committing. Auto-detects if project scaffold is needed first.',
+    examples: [
+        { code: '/build', description: 'Pick highest priority item' },
+        { code: '/build REQ-003', description: 'Build specific item' },
+        { code: '/build scaffold', description: 'Create project structure first' },
+    ],
+    async execute(args, ctx) {
+        const argTrimmed = args.trim();
+        // Handle `/build scaffold` - redirect to scaffold command
+        if (argTrimmed.toLowerCase() === 'scaffold') {
+            await executeCommand('scaffold', '', ctx);
+            return true;
+        }
+        // Check if a project is set
+        const currentProject = getCurrentProject();
+        if (!currentProject) {
+            ctx.ui.print({ type: 'error', message: 'No project selected. Run /new or /projects first.' });
+            return true;
+        }
+        // Check if project has a path set (REQUIRED for building)
+        if (!currentProject.path) {
+            ctx.ui.print({ type: 'error', message: 'Project path not set. Cannot build without a target directory.' });
+            ctx.ui.print({ type: 'info', message: 'Tip: Update the project path in /projects to specify where files should be created.' });
+            return true;
+        }
+        // Warn if cwd doesn't match project path (common source of confusion)
+        const buildCwd = process.cwd();
+        if (buildCwd !== currentProject.path) {
+            ctx.ui.print({ type: 'warning', message: `Working directory differs from project path!` });
+            ctx.ui.print({ type: 'info', message: `  cwd:     ${buildCwd}` });
+            ctx.ui.print({ type: 'info', message: `  project: ${currentProject.path}` });
+            ctx.ui.print({ type: 'info', message: `Files will be created/modified in the project path, not cwd.` });
+        }
+        // Parse item ID argument (e.g., "REQ-001")
+        const requestedItemId = argTrimmed.toUpperCase();
+        const isSpecificItem = requestedItemId && /^[A-Z]+-\d{3}$/.test(requestedItemId);
+        // Find the item to build
+        let selectedItem;
+        if (isSpecificItem) {
+            // Get specific item by ID
+            selectedItem = workItemRepository.getByItemId(currentProject.id, requestedItemId);
+            if (!selectedItem) {
+                ctx.ui.print({ type: 'error', message: `Work item "${requestedItemId}" not found.` });
+                return true;
+            }
+            if (selectedItem.status !== 'backlog') {
+                ctx.ui.print({ type: 'warning', message: `Work item "${requestedItemId}" is already ${selectedItem.status}. Use /backlog to view status.` });
+                return true;
+            }
+        }
+        else {
+            // Auto-select highest priority backlog item
+            selectedItem = workItemRepository.getNext(currentProject.id);
+            if (!selectedItem) {
+                ctx.ui.print({ type: 'info', message: 'No backlog items found. Create items with /design or /backlog first.' });
+                ctx.ui.print({ type: 'info', message: 'Or run /build scaffold to create the project foundation.' });
+                return true;
+            }
+        }
+        // Check model tier for full builds (not targeted item)
+        if (!isSpecificItem) {
+            const currentModel = ctx.model ?? 'unknown';
+            if (!modelMeetsTier(currentModel, '/build')) {
+                const modelTier = getModelTier(currentModel);
+                const warningOverlay = new ModelWarningOverlayV2({
+                    command: '/build',
+                    currentModel,
+                    currentTier: modelTier.tier,
+                    suggestedModel: modelTier.suggestedUpgrade,
+                    alternativeCommand: `/build ${selectedItem.itemId}`,
+                });
+                const choice = await ctx.ui.showOverlay(warningOverlay);
+                switch (choice) {
+                    case 'cancel':
+                        return true;
+                    case 'alternative':
+                        ctx.ui.print({ type: 'info', message: `Tip: Use /build ${selectedItem.itemId} to build a specific item with smaller models.` });
+                        return true;
+                    case 'switch':
+                        ctx.ui.print({ type: 'info', message: `Continuing with ${currentModel} (model switching not yet available in V2)` });
+                        break;
+                    case 'continue':
+                        break;
+                }
+            }
+        }
+        // Get build skill prompt and replace placeholders
+        let buildPrompt = getSkillPrompt('build');
+        if (!buildPrompt) {
+            ctx.ui.print({ type: 'error', message: 'Build skill not found.' });
+            return true;
+        }
+        // Replace {{projectPath}} and item placeholders with actual values
+        buildPrompt = buildPrompt
+            .replace(/\{\{projectPath\}\}/g, currentProject.path)
+            .replace(/\{\{item_id\}\}/g, selectedItem.itemId)
+            .replace(/\{\{item_title\}\}/g, selectedItem.title)
+            .replace(/\{\{item_type\}\}/g, selectedItem.type)
+            .replace(/\{\{item_priority\}\}/g, selectedItem.priority)
+            .replace(/\{\{item_description\}\}/g, selectedItem.description ?? 'No description provided');
+        // Build full message for agent with explicit project path context
+        const fullMessage = `I want to implement backlog item ${selectedItem.itemId}: "${selectedItem.title}".
+
+## PROJECT CONTEXT (CRITICAL)
+- Project Name: ${currentProject.name} (ID: ${String(currentProject.id)})
+- **Project Directory: ${currentProject.path}**
+- ALL files MUST be created/modified in this directory
+
+## WORK ITEM DETAILS
+- Item ID: ${selectedItem.itemId}
+- Type: ${selectedItem.type}
+- Priority: ${selectedItem.priority}
+- Description: ${selectedItem.description ?? 'No description provided'}
+
+## TOOL RESTRICTIONS (CRITICAL)
+- Do NOT use detect_project or find_project_root
+- Do NOT scan filesystem to detect project type
+- The project path above is the ONLY source of truth for where to create/modify files
+- Use \`project_document_get\` to read PRD and architecture docs from the database
+- Use \`workitem_query\` to read related backlog items from the database
+- Use \`workitem_update\` to update the item status when done
+
+## FILE OPERATIONS (CRITICAL)
+When creating or modifying files:
+- Use absolute paths starting with: ${currentProject.path}/
+- Example: write_file({ path: "${currentProject.path}/src/index.ts", ... })
+- NEVER use relative paths
+- IGNORE the current working directory (cwd) - it may be different from the project!
+- The user may have started the CLI from a different folder
+
+${buildPrompt}
+
+Please start by:
+1. Using todo_write to plan the implementation steps
+2. Reading project documents from the database (project_document_list, project_document_get)
+3. Updating the work item status to 'in_progress' using workitem_update
+4. Implementing the feature
+5. Updating the work item status to 'completed' when done`;
+        // Queue message for agent
+        ctx.queueAgentMessage({
+            message: fullMessage,
+            displayMessage: `Build ${selectedItem.itemId}: ${selectedItem.title}`,
+        });
+        return true;
+    },
+};
+// =============================================================================
+// Note Command
+// =============================================================================
+export const noteCommand = {
+    name: 'note',
+    description: 'Create a session note capturing work done',
+    details: 'Creates a structured markdown note summarizing the current session including changes made, decisions, blockers, and next steps. Optionally provide a title.',
+    examples: [
+        { code: '/note', description: 'Auto-generated title' },
+        { code: '/note "Fixed auth bug"', description: 'Custom title' },
+    ],
+    execute(args, ctx) {
+        // Check if a project is set
+        const currentProject = getCurrentProject();
+        if (!currentProject) {
+            ctx.ui.print({ type: 'error', message: 'No project selected. Run /new or /projects first.' });
+            return Promise.resolve(true);
+        }
+        // Get session-notes skill prompt
+        const notePrompt = getSkillPrompt('session-notes');
+        if (!notePrompt) {
+            ctx.ui.print({ type: 'error', message: 'Session-notes skill not found.' });
+            return Promise.resolve(true);
+        }
+        // Check for optional title argument
+        const noteTitle = args.trim();
+        // Build title instruction based on whether title was provided
+        const titleInstruction = noteTitle
+            ? `The session title is: "${noteTitle}"`
+            : 'Please ask me for a title using ask_user_simple, or generate one from the session summary.';
+        // Build full message for agent
+        const fullMessage = `I want to create a session note capturing what we've done.
+
+## PROJECT CONTEXT
+- Project Name: ${currentProject.name} (ID: ${String(currentProject.id)})
+
+## DOCUMENT STORAGE (CRITICAL)
+Save session notes using the database - do NOT write files directly.
+- Tool: \`project_document_add({ doc_type: "session-note", title: "...", content: "..." })\`
+- The database is the source of truth for all project documents
+- Do NOT use write_file or edit tools for documentation
+
+${notePrompt}
+
+${titleInstruction}
+
+Review the conversation context to understand what was accomplished, then create the session note.`;
+        // Queue message for agent
+        ctx.queueAgentMessage({
+            message: fullMessage,
+            displayMessage: noteTitle
+                ? `Create session note: "${noteTitle}"`
+                : 'Create a session note for this session.',
+        });
+        return Promise.resolve(true);
+    },
+};
+// =============================================================================
+// PRD Command
+// =============================================================================
+export const prdCommand = {
+    name: 'prd',
+    description: 'Amend or enhance the Product Requirements Document',
+    details: 'Update or refine the PRD created during /design. The agent reads the existing PRD and guides you through updating specific sections.',
+    examples: [
+        { code: '/prd', description: 'Interactive section selection' },
+        { code: '/prd vision', description: 'Update vision section' },
+        { code: '/prd scope', description: 'Update scope section' },
+    ],
+    execute(args, ctx) {
+        // Check if a project is set
+        const currentProject = getCurrentProject();
+        if (!currentProject) {
+            ctx.ui.print({ type: 'error', message: 'No project selected. Run /new or /projects first.' });
+            return Promise.resolve(true);
+        }
+        // Get PRD skill prompt
+        const prdPrompt = getSkillPrompt('prd');
+        if (!prdPrompt) {
+            ctx.ui.print({ type: 'error', message: 'PRD skill not found.' });
+            return Promise.resolve(true);
+        }
+        // Check for optional section argument
+        const section = args.trim().toLowerCase();
+        const validSections = ['vision', 'scope', 'technical', 'success'];
+        const sectionInstruction = validSections.includes(section)
+            ? `The user wants to update the "${section}" section specifically.`
+            : 'Ask the user which section they want to update using ask_user_simple.';
+        // Build full message for agent with project context
+        const fullMessage = `I want to update the Product Requirements Document.
+
+## DOCUMENT STORAGE (CRITICAL)
+Save PRD updates using the database - do NOT write files directly.
+- Project: ${currentProject.name} (ID: ${String(currentProject.id)})
+- Tool: \`project_document_add({ doc_type: "prd", title: "Product Requirements Document", content: "..." })\`
+- The database is the source of truth for all project documents
+- Do NOT use write_file or edit tools for documentation
+
+${prdPrompt}
+
+${sectionInstruction}
+
+Start by reading the existing PRD from the database using project_document_get({ doc_type: "prd" }). If no document exists yet, create a new one.`;
+        // Queue message for agent
+        ctx.queueAgentMessage({
+            message: fullMessage,
+            displayMessage: section
+                ? `Update PRD: ${section} section`
+                : 'Update the Product Requirements Document',
+        });
+        return Promise.resolve(true);
+    },
+};
+// =============================================================================
+// Scaffold Command
+// =============================================================================
+export const scaffoldCommand = {
+    name: 'scaffold',
+    description: 'Create project foundation/structure',
+    details: 'Creates the base project structure (folders, config files, dependencies) based on tech stack from COMPILR.md. Use this before implementing features if starting from scratch. Alias for /build scaffold.',
+    examples: [{ code: '/scaffold' }],
+    async execute(_args, ctx) {
+        // Check if a project is set
+        const currentProject = getCurrentProject();
+        if (!currentProject) {
+            ctx.ui.print({ type: 'error', message: 'No project selected. Run /new or /projects first.' });
+            return true;
+        }
+        // Check if project has a path set (REQUIRED for scaffolding)
+        if (!currentProject.path) {
+            ctx.ui.print({ type: 'error', message: 'Project path not set. Cannot scaffold without a target directory.' });
+            ctx.ui.print({ type: 'info', message: 'Tip: Update the project path in /projects to specify where files should be created.' });
+            return true;
+        }
+        // Warn if cwd doesn't match project path (common source of confusion)
+        const cwd = process.cwd();
+        if (cwd !== currentProject.path) {
+            ctx.ui.print({ type: 'warning', message: `Working directory differs from project path!` });
+            ctx.ui.print({ type: 'info', message: `  cwd:     ${cwd}` });
+            ctx.ui.print({ type: 'info', message: `  project: ${currentProject.path}` });
+            ctx.ui.print({ type: 'info', message: `Files will be created in the project path, not cwd.` });
+        }
+        // Check model tier - /scaffold works best with large models
+        const currentModel = ctx.model ?? 'unknown';
+        if (!modelMeetsTier(currentModel, '/scaffold')) {
+            const modelTier = getModelTier(currentModel);
+            const warningOverlay = new ModelWarningOverlayV2({
+                command: '/scaffold',
+                currentModel,
+                currentTier: modelTier.tier,
+                suggestedModel: modelTier.suggestedUpgrade,
+            });
+            const choice = await ctx.ui.showOverlay(warningOverlay);
+            switch (choice) {
+                case 'cancel':
+                    return true;
+                case 'switch':
+                    ctx.ui.print({ type: 'info', message: `Continuing with ${currentModel} (model switching not yet available in V2)` });
+                    break;
+                case 'continue':
+                    // Proceed with current model
+                    break;
+            }
+        }
+        // Get scaffold skill prompt and replace path placeholder
+        let scaffoldPrompt = getSkillPrompt('scaffold');
+        if (!scaffoldPrompt) {
+            ctx.ui.print({ type: 'error', message: 'Scaffold skill not found.' });
+            return true;
+        }
+        // Replace {{projectPath}} placeholder with actual path
+        scaffoldPrompt = scaffoldPrompt.replace(/\{\{projectPath\}\}/g, currentProject.path);
+        // Build full message for agent with explicit project path context
+        const fullMessage = `I want to create the project scaffold/foundation.
+
+## PROJECT CONTEXT (CRITICAL)
+- Project Name: ${currentProject.name} (ID: ${String(currentProject.id)})
+- **Project Directory: ${currentProject.path}**
+- ALL files MUST be created in this directory
+
+## TOOL RESTRICTIONS (CRITICAL)
+- Do NOT use detect_project or find_project_root
+- Do NOT scan filesystem to detect project type
+- The project path above is the ONLY source of truth for where to create files
+- Use \`project_document_get\` to read PRD and architecture docs from the database
+- Use \`workitem_query\` to read backlog items from the database
+
+## FILE CREATION (CRITICAL)
+When creating files:
+- Use absolute paths starting with: ${currentProject.path}/
+- Example: write_file({ path: "${currentProject.path}/package.json", ... })
+- NEVER use relative paths
+- IGNORE the current working directory (cwd) - it may be different from the project!
+- The user may have started the CLI from a different folder
+
+${scaffoldPrompt}
+
+Please start by reading the project documents from the database using project_document_list and project_document_get. Then create a plan with todo_write before generating files.`;
+        // Queue message for agent
+        ctx.queueAgentMessage({
+            message: fullMessage,
+            displayMessage: 'Create project scaffold.',
+        });
+        return true;
+    },
+};
+// =============================================================================
+// Arch Command
+// =============================================================================
+export const archCommand = {
+    name: 'arch',
+    description: 'Create architecture documentation (ADRs, diagrams, etc.)',
+    details: 'Guides you through creating architecture documentation. Choose from ADRs (Architecture Decision Records), system diagrams, data models, or API designs. The agent asks questions and generates properly formatted documentation.',
+    examples: [
+        { code: '/arch', description: 'Interactive type selection' },
+        { code: '/arch decision', description: 'Create ADR directly' },
+        { code: '/arch diagram', description: 'Create system diagram' },
+    ],
+    interactions: [
+        '↑/↓ or 1-5 to select type',
+        'Enter to confirm',
+        'Esc to cancel',
+    ],
+    async execute(_args, ctx) {
+        // Check if a project is set (use database, not filesystem)
+        const currentProject = getCurrentProject();
+        if (!currentProject) {
+            ctx.ui.print({ type: 'error', message: 'No project selected. Run /new or /projects first.' });
+            return true;
+        }
+        // TODO: Check model tier and show warning if too small (like legacy)
+        // Show type selection overlay
+        const archOverlay = new ArchTypeOverlayV2();
+        const archChoice = await ctx.ui.showOverlay(archOverlay);
+        if (!archChoice) {
+            // User cancelled
+            return true;
+        }
+        // Get architecture skill prompt
+        const archPrompt = getSkillPrompt('architecture');
+        if (!archPrompt) {
+            ctx.ui.print({ type: 'error', message: 'Architecture skill not found.' });
+            return true;
+        }
+        // Build the document type description for display
+        const docTypeLabels = {
+            'adr': 'Architecture Decision Record',
+            'diagram': 'System Diagram',
+            'data-model': 'Data Model',
+            'api': 'API Design',
+            'custom': 'Custom Documentation',
+        };
+        const displayType = archChoice.customTopic
+            ? `Custom: ${archChoice.customTopic}`
+            : docTypeLabels[archChoice.type];
+        // Replace placeholders in skill prompt
+        const finalPrompt = archPrompt
+            .replace('{{doc_type}}', archChoice.type)
+            .replace('{{#if custom_topic}}Custom Topic: {{custom_topic}}{{/if}}', archChoice.customTopic ? `Custom Topic: ${archChoice.customTopic}` : '');
+        // Build full message for agent with project context
+        const fullMessage = `I want to create architecture documentation.
+
+## DOCUMENT STORAGE (CRITICAL)
+Save architecture documentation using the database - do NOT write files directly.
+- Project: ${currentProject.name} (ID: ${String(currentProject.id)})
+- Tool: \`project_document_add({ doc_type: "architecture", title: "...", content: "..." })\`
+- The database is the source of truth for all project documents
+- Do NOT use write_file or edit tools for documentation
+
+${finalPrompt}
+
+Please start by using project_document_list to find any existing PRD, and workitem_query to understand the project backlog. Then use ask_user to gather the information needed for this ${archChoice.type} document.`;
+        // Queue message for agent
+        ctx.queueAgentMessage({
+            message: fullMessage,
+            displayMessage: `Create ${displayType} documentation.`,
+        });
+        return true;
+    },
+};
+// =============================================================================
+// Docs Command
+// =============================================================================
+export const docsCommand = {
+    name: 'docs',
+    description: 'View project documents (PRD, architecture, etc.)',
+    details: 'Opens an overlay to browse and read documents stored in the database for the active project. Documents are created by /design, /arch, and other workflow commands.',
+    examples: [
+        { code: '/docs', description: 'List all documents' },
+    ],
+    interactions: [
+        '↑/↓ or j/k to navigate',
+        'Enter to view document',
+        '↑/↓ to scroll content',
+        'Esc to go back or close',
+    ],
+    async execute(_args, ctx) {
+        // Loop: show list → detail → back to list (until user cancels list or Ctrl+C from detail)
+        let showList = true;
+        while (showList) {
+            // Show document list (inline overlay)
+            const docsOverlay = new DocsOverlayV2();
+            const listResult = await ctx.ui.showOverlay(docsOverlay);
+            // User cancelled the list (Esc/Ctrl+C) - exit
+            if (!listResult?.selectedDocument || listResult.cancelled) {
+                showList = false;
+                continue;
+            }
+            // Show selected document in fullscreen detail overlay
+            const detailOverlay = new DocumentDetailOverlayV2(listResult.selectedDocument);
+            const detailResult = await ctx.ui.showOverlay(detailOverlay);
+            // Ctrl+C from detail - exit completely
+            // Esc/q from detail (goBack=true) - loop back to show list again
+            showList = detailResult?.goBack === true;
+        }
+        return true;
+    },
+};
+// =============================================================================
+// Projects Command
+// =============================================================================
+export const projectsCommand = {
+    name: 'projects',
+    description: 'View and manage projects',
+    details: 'Opens an interactive overlay to browse, filter, and manage projects tracked in the database. You can view details, open projects, archive, restore, or delete them.',
+    examples: [{ code: '/projects' }],
+    interactions: [
+        'Tab cycles: All → Active → Paused → Completed → Archived',
+        '↑/↓ or j/k to navigate',
+        'Enter to view details and actions',
+        'x to archive/restore project',
+        'd to delete project',
+        'a to show/hide archived',
+        'Esc to close',
+    ],
+    async execute(_args, ctx) {
+        // Track project ID before overlay (for session switch handling)
+        const oldProjectId = getCurrentProjectIdForTracking();
+        const projectsOverlay = new ProjectsOverlayV2();
+        await ctx.ui.showOverlay(projectsOverlay);
+        // Handle project switch if it occurred (includes team switching)
+        const switchResult = await handleProjectSwitch(oldProjectId, ctx.agent ?? null, ctx.team && ctx.agentFactory ? {
+            team: ctx.team,
+            agentFactory: ctx.agentFactory,
+        } : undefined);
+        if (switchResult?.switched) {
+            const current = getCurrentProject();
+            // Update the team if a new one was created/loaded
+            if (switchResult.newTeam && ctx.setTeam) {
+                ctx.setTeam(switchResult.newTeam);
+                // Update footer with new active agent
+                const active = switchResult.newTeam.getActive();
+                ctx.ui.setActiveTeamAgent({
+                    id: active.id,
+                    displayName: active.displayName,
+                    mascot: active.mascot,
+                });
+            }
+            if (switchResult.sessionRestored) {
+                ctx.ui.print({ type: 'success', message: `Switched to "${current?.displayName ?? 'project'}" - session restored (${String(switchResult.messageCount)} messages).` });
+            }
+            else {
+                ctx.ui.print({ type: 'success', message: `Switched to "${current?.displayName ?? 'project'}" - fresh session.` });
+            }
+        }
+        // Sync footer with current project (may have changed during overlay)
+        syncFooterWithCurrentProject(ctx);
+        return true;
+    },
+};
+// =============================================================================
+// Export All Project Commands
+// =============================================================================
+export const projectCommands = [
+    newCommand,
+    initCommand,
+    backlogCommand,
+    workflowCommand,
+    anchorsCommand,
+    designCommand,
+    sketchCommand,
+    refineCommand,
+    buildCommand,
+    noteCommand,
+    prdCommand,
+    scaffoldCommand,
+    archCommand,
+    docsCommand,
+    projectsCommand,
+];