@compilr-dev/cli 0.4.0 → 0.5.0

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

@@ -0,0 +1,814 @@
+/**
+ * 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, InitSetupOverlayV2, 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';
+// =============================================================================
+// 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',
+    async execute(_args, ctx) {
+        const newProjectOverlay = new NewProjectOverlayV2();
+        const result = await ctx.ui.showOverlay(newProjectOverlay);
+        // User cancelled
+        if (!result?.created) {
+            return true;
+        }
+        // Project was created - show success messages
+        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 {
+                const project = projectRepository.create({
+                    name: result.projectName,
+                    display_name: result.projectName.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()),
+                    description: result.description,
+                    path: result.projectPath,
+                    type: 'general',
+                    workflow_mode: result.workflowMode ?? 'flexible',
+                });
+                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` });
+            }
+            catch (dbError) {
+                ctx.ui.print({ type: 'warning', message: `Could not register in database: ${dbError.message}` });
+            }
+        }
+        // Show next steps
+        ctx.ui.print({ type: 'info', message: '' });
+        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!` });
+        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: 'View CLI setup status',
+    async execute(_args, ctx) {
+        const initSetupOverlay = new InitSetupOverlayV2();
+        await ctx.ui.showOverlay(initSetupOverlay);
+        return true;
+    },
+};
+// =============================================================================
+// Backlog Command
+// =============================================================================
+export const backlogCommand = {
+    name: 'backlog',
+    description: 'View and manage project backlog',
+    async execute(_args, ctx) {
+        const backlogOverlay = new BacklogOverlayV2();
+        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',
+    async execute(_args, ctx) {
+        const workflowOverlay = new WorkflowOverlayV2();
+        const result = await ctx.ui.showOverlay(workflowOverlay);
+        // 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)',
+    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',
+    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',
+    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',
+    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: 'Build a backlog item',
+    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',
+    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: 'Update the Product Requirements Document',
+    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.md file to understand current state.`;
+        // 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 scaffold/foundation',
+    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',
+    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, design, notes)',
+    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 all projects',
+    async execute(_args, ctx) {
+        const projectsOverlay = new ProjectsOverlayV2();
+        await ctx.ui.showOverlay(projectsOverlay);
+        // 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,
+];