@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/ui/overlay/data/tutorials/planning/design.js

@@ -0,0 +1,205 @@
+/**
+ * Design Workflow Tutorial
+ *
+ * Walkthrough of the /design command for comprehensive requirements gathering.
+ */
+export const designTutorial = (s) => ({
+    id: 'design',
+    title: 'Design Workflow',
+    description: 'Comprehensive requirements gathering',
+    pages: [
+        // Page 1: Introduction
+        {
+            title: 'Design Workflow',
+            lines: [
+                '',
+                `  The ${s.primary('/design')} command starts an AI-driven conversation`,
+                `  to gather comprehensive requirements for your project.`,
+                '',
+                `  The agent guides you through ${s.primaryBold('4 phases')}:`,
+                '',
+                `    ${s.primary('Phase 1')}  Vision - Problem, target users, pitch`,
+                `    ${s.primary('Phase 2')}  Features - Core MVP scope, deferred items`,
+                `    ${s.primary('Phase 3')}  Technical - Constraints, integrations, stack`,
+                `    ${s.primary('Phase 4')}  Backlog - Generate work items and PRD`,
+                '',
+                `  At the end, you get a structured backlog and a PRD document.`,
+                '',
+            ],
+        },
+        // Page 2: Model Recommendation
+        {
+            title: 'Model Recommendation',
+            lines: [
+                '',
+                `  The first thing ${s.primary('/design')} does is check your current model.`,
+                `  Complex workflows work best with larger models:`,
+                '',
+                `     ${s.warning('! Model Recommendation')}`,
+                '',
+                `     /design works best with larger models for complex`,
+                `     multi-question workflows.`,
+                '',
+                `     Current: ${s.muted('claude-haiku-4-5-20251001 (medium tier)')}`,
+                `     Recommended: ${s.primary('claude-sonnet-4-5-20250929 (large tier)')}`,
+                '',
+                `     ${s.primary('>')} 1. Switch to claude-sonnet-4-5-20250929 and continue`,
+                `       2. Use /sketch instead (simpler, works with any model)`,
+                `       3. Continue with current model anyway`,
+                '',
+                `     ${s.muted('Up/Down Navigate | Enter Select | Esc Cancel')}`,
+                '',
+            ],
+        },
+        // Page 3: Phase 1 - Vision Questions (Batched)
+        {
+            title: 'Phase 1: Vision Questions',
+            lines: [
+                '',
+                `  The agent asks foundational questions to understand your project.`,
+                `  Questions can come in ${s.primaryBold('batches')} (multiple at once):`,
+                '',
+                `     ${s.primaryBold('Questions')}`,
+                '',
+                `      ${s.primary('Problem')}   Target User   Pitch   Submit `,
+                '',
+                `     [1/3] What problem does 'my-project' solve?`,
+                `     What pain point are users experiencing?`,
+                '',
+                `     ${s.primary('>')} Custom: ${s.muted('_')}`,
+                '',
+                `     ${s.muted('Enter Submit | Esc Cancel custom')}`,
+                '',
+                `  Answer each question and move to the next tab.`,
+                `  The ${s.primary('*')} indicator shows which tabs are completed.`,
+                '',
+            ],
+        },
+        // Page 4: Answering Batched Questions
+        {
+            title: 'Answering Questions',
+            lines: [
+                '',
+                `  After answering, the tab shows a ${s.primary('*')} and you move to the next:`,
+                '',
+                `     ${s.primaryBold('Questions')}`,
+                '',
+                `     ${s.primary('*')} Problem  ${s.primary('Target User')}   Pitch   Submit `,
+                '',
+                `     [2/3] Who is your primary target user?`,
+                `     (e.g., solo travelers, families, business travelers)`,
+                '',
+                `     ${s.primary('>')} Custom: ${s.muted('_')}`,
+                '',
+                `     ${s.muted('Enter Submit | Esc Cancel custom')}`,
+                '',
+                `  Some questions offer predefined choices. You can always`,
+                `  select "Custom" to type your own answer.`,
+                '',
+                `  Press ${s.primary('Submit')} (last tab) when all questions are answered.`,
+                '',
+            ],
+        },
+        // Page 5: Individual Questions
+        {
+            title: 'Follow-up Questions',
+            lines: [
+                '',
+                `  The agent also asks ${s.primaryBold('individual')} follow-up questions`,
+                `  to dig deeper into specific areas:`,
+                '',
+                `     ${s.primaryBold('Question')}`,
+                '',
+                `     What features should wait for v2 or later?`,
+                `     (e.g., social sharing, group trips, translation)`,
+                '',
+                `       1. Custom: ${s.muted('_')}`,
+                '',
+                `     ${s.muted('Enter Submit | Esc Cancel')}`,
+                '',
+                '',
+                `     ${s.primaryBold('Question')}`,
+                '',
+                `     Are there any non-negotiable technical requirements?`,
+                `     (e.g., mobile-first, offline capability, real-time sync)`,
+                '',
+                `       1. Custom: ${s.muted('_')}`,
+                '',
+                `     ${s.muted('Enter Submit | Esc Cancel')}`,
+                '',
+            ],
+        },
+        // Page 6: Phase Summaries
+        {
+            title: 'Phase Summaries',
+            lines: [
+                '',
+                `  After gathering enough information, the agent summarizes`,
+                `  each phase before moving to backlog creation:`,
+                '',
+                `  ${s.primaryBold('PHASE 1 SUMMARY: Vision Confirmed')}`,
+                `    ${s.primary('*')} Problem: Travelers need all info in one place`,
+                `    ${s.primary('*')} Target Users: Solo travelers and families`,
+                `    ${s.primary('*')} Pitch: "One-stop for all your travel arrangements"`,
+                '',
+                `  ${s.primaryBold('PHASE 2 SUMMARY: MVP Features Defined')}`,
+                `    ${s.primary('*')} Core: Itinerary, booking, expense tracking`,
+                `    ${s.primary('*')} Deferred: Social sharing (v2+)`,
+                '',
+                `  ${s.primaryBold('PHASE 3 SUMMARY: Technical Context')}`,
+                `    ${s.primary('*')} Integration: Booking.com API`,
+                `    ${s.primary('*')} Stack: React/Node (flexible)`,
+                '',
+            ],
+        },
+        // Page 7: Backlog Generation
+        {
+            title: 'Backlog Generation',
+            lines: [
+                '',
+                `  In ${s.primaryBold('Phase 4')}, the agent creates work items from your`,
+                `  requirements and adds them to the project backlog:`,
+                '',
+                `  ${s.muted('Todos')}`,
+                `  ${s.success('✓')} Phase 1: Gather vision and problem statement`,
+                `  ${s.success('✓')} Phase 2: Define core features and MVP scope`,
+                `  ${s.success('✓')} Phase 3: Understand technical context`,
+                `  ${s.primary('→')} Phase 4: Create backlog and PRD document`,
+                '',
+                `  The agent calls ${s.primary('workitem_add')} to create backlog items`,
+                `  based on your answers. Each item gets a priority, type,`,
+                `  and detailed description.`,
+                '',
+                `  ${s.warning('TIP:')} After /design completes, use ${s.primary('/backlog')} to view,`,
+                `  filter, and prioritize your work items.`,
+                '',
+            ],
+        },
+        // Page 8: Tips
+        {
+            title: 'Tips & Alternatives',
+            lines: [
+                '',
+                `  ${s.secondary('Best Practices:')}`,
+                '',
+                `    ${s.primary('1.')} Use a capable model (Sonnet or Opus recommended)`,
+                `    ${s.primary('2.')} Be specific in your answers — the AI uses them to`,
+                `       generate accurate backlog items`,
+                `    ${s.primary('3.')} Don't skip the "deferred features" question — it`,
+                `       helps define clear MVP boundaries`,
+                '',
+                `  ${s.secondary('Alternatives:')}`,
+                '',
+                `    ${s.primary('/sketch')}  Quick 6-question planning (works with any model)`,
+                `    ${s.primary('/refine')}  Iterative refinement of existing requirements`,
+                '',
+                `  ${s.secondary('After /design:')}`,
+                '',
+                `    ${s.primary('/backlog')}  View and manage work items`,
+                `    ${s.primary('/prd')}      View the generated PRD document`,
+                `    ${s.primary('/build')}    Start building a backlog item`,
+                '',
+            ],
+        },
+    ],
+});

package/dist/ui/overlay/data/tutorials/planning/docs.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Docs Tutorial
+ *
+ * Walkthrough of the /docs command for viewing and managing project documents.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const docsTutorial: TutorialBuilder;

package/dist/ui/overlay/data/tutorials/planning/docs.js

@@ -0,0 +1,143 @@
+/**
+ * Docs Tutorial
+ *
+ * Walkthrough of the /docs command for viewing and managing project documents.
+ */
+export const docsTutorial = (s) => ({
+    id: 'docs',
+    title: 'Document Browser',
+    description: 'View and manage documents',
+    pages: [
+        // Page 1: Introduction
+        {
+            title: 'Document Browser',
+            lines: [
+                '',
+                `  The ${s.primary('/docs')} command opens the document browser`,
+                `  — a tabbed overlay to view all project documents.`,
+                '',
+                `  ${s.secondary('Usage:')}`,
+                '',
+                `    ${s.primary('/docs')}    Open the document browser`,
+                '',
+                `  ${s.secondary('Documents are stored in the database, not files.')}`,
+                `  They are created by commands like ${s.primary('/design')},`,
+                `  ${s.primary('/prd')}, and ${s.primary('/arch')}.`,
+                '',
+                `  ${s.secondary('Document types:')}`,
+                '',
+                `    ${s.muted('•')} ${s.primaryBold('PRD')}      Product Requirements Document`,
+                `    ${s.muted('•')} ${s.primaryBold('ARCH')}     Architecture documentation`,
+                `    ${s.muted('•')} ${s.primaryBold('DESIGN')}   Design documents`,
+                `    ${s.muted('•')} ${s.primaryBold('NOTES')}    Session notes and general notes`,
+                `    ${s.muted('•')} ${s.primaryBold('PLANS')}    Work plans (from Plan Mode)`,
+                '',
+            ],
+        },
+        // Page 2: The Document List
+        {
+            title: 'The Document List',
+            lines: [
+                '',
+                `  The main view shows all documents with tabs for filtering:`,
+                '',
+                `    ${s.muted('Documents [2/2]')}`,
+                '',
+                `    ${s.primary(' All  PRD  ARCH  DESIGN  NOTES  PLANS')}`,
+                '',
+                `    ${s.primary('>')} ${s.muted('PRD       Product Requirements Document')}`,
+                `      ${s.muted('ARCH      System Architecture')}`,
+                '',
+                `  ${s.secondary('Navigation:')}`,
+                '',
+                `    ${s.muted('↑/↓ or j/k')}   Move between documents`,
+                `    ${s.muted('Tab')}           Switch between tabs`,
+                `    ${s.muted('1-6')}           Jump to tab by number`,
+                `    ${s.muted('/')}             Search documents`,
+                `    ${s.muted('Enter')}         Open document detail view`,
+                `    ${s.muted('q or Esc')}      Close`,
+                '',
+            ],
+        },
+        // Page 3: Document Detail View
+        {
+            title: 'Document Detail View',
+            lines: [
+                '',
+                `  Press ${s.primaryBold('Enter')} on a document to open the detail view:`,
+                '',
+                `    ${s.muted('PRD | Product Requirements Document')}`,
+                `    ${s.muted('─────────────────────────────────────')}`,
+                `    ${s.muted('Product Requirements Document')}`,
+                '',
+                `    ${s.muted('Overview')}`,
+                '',
+                `    ${s.muted('My Travel Companion is a web application')}`,
+                `    ${s.muted('that enables users to plan, organize...')}`,
+                '',
+                `    ${s.muted('─────────────────────────────────────')}`,
+                `    ${s.muted('Line 1-45 of 77 (58%)')}`,
+                '',
+                `  ${s.secondary('In the detail view:')}`,
+                '',
+                `    ${s.muted('↑/↓ or j/k')}   Scroll through content`,
+                `    ${s.muted('e or i')}        Edit the document (via agent)`,
+                `    ${s.muted('q or Esc')}      Go back to the list`,
+                '',
+            ],
+        },
+        // Page 4: Editing Documents
+        {
+            title: 'Editing Documents',
+            lines: [
+                '',
+                `  Press ${s.primaryBold('e')} or ${s.primaryBold('i')} in the detail view to edit a document.`,
+                `  This sends the document to the agent for updates.`,
+                '',
+                `  The agent will:`,
+                '',
+                `    ${s.muted('•')} Read the current document content`,
+                `    ${s.muted('•')} Ask what you want to change`,
+                `    ${s.muted('•')} Update and save back to the database`,
+                '',
+                `  ${s.secondary('You can also edit directly from the REPL:')}`,
+                '',
+                `    ${s.muted('"Update the overview section of the PRD"')}`,
+                `    ${s.muted('"Add a new section about security to the arch doc"')}`,
+                '',
+                `  Or use the dedicated commands:`,
+                '',
+                `    ${s.primary('/prd')}    Update the PRD specifically`,
+                `    ${s.primary('/arch')}   Create new architecture docs`,
+                '',
+            ],
+        },
+        // Page 5: How Documents Are Created
+        {
+            title: 'How Documents Are Created',
+            lines: [
+                '',
+                `  Documents are created by various commands:`,
+                '',
+                `  ${s.primaryBold('PRD')} documents:`,
+                `    ${s.muted('•')} ${s.primary('/design')} creates the initial PRD`,
+                `    ${s.muted('•')} ${s.primary('/sketch')} creates a quick PRD outline`,
+                `    ${s.muted('•')} ${s.primary('/prd')} updates an existing PRD`,
+                '',
+                `  ${s.primaryBold('Architecture')} documents:`,
+                `    ${s.muted('•')} ${s.primary('/arch')} creates ADRs, diagrams, data models`,
+                '',
+                `  ${s.primaryBold('Plans')}:`,
+                `    ${s.muted('•')} Created in Plan Mode (for complex tasks)`,
+                '',
+                `  ${s.primaryBold('Notes')}:`,
+                `    ${s.muted('•')} Session notes saved by the agent`,
+                '',
+                `  All documents are stored in the project database and`,
+                `  persist across sessions. Use ${s.primary('/docs')} to browse them`,
+                `  at any time.`,
+                '',
+            ],
+        },
+    ],
+});

package/dist/ui/overlay/data/tutorials/planning/prd.d.ts

@@ -0,0 +1,7 @@
+/**
+ * PRD Tutorial
+ *
+ * Walkthrough of the /prd command for updating the Product Requirements Document.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const prdTutorial: TutorialBuilder;

package/dist/ui/overlay/data/tutorials/planning/prd.js

@@ -0,0 +1,173 @@
+/**
+ * PRD Tutorial
+ *
+ * Walkthrough of the /prd command for updating the Product Requirements Document.
+ */
+export const prdTutorial = (s) => ({
+    id: 'prd',
+    title: 'Product Requirements',
+    description: 'Update the PRD',
+    pages: [
+        // Page 1: Introduction
+        {
+            title: 'Product Requirements Document',
+            lines: [
+                '',
+                `  The ${s.primary('/prd')} command updates your Product Requirements Document`,
+                `  — an interactive conversation to refine project scope and goals.`,
+                '',
+                `  ${s.secondary('Usage:')}`,
+                '',
+                `    ${s.primary('/prd')}           Update PRD (choose section)`,
+                `    ${s.primary('/prd vision')}    Update the vision section`,
+                `    ${s.primary('/prd scope')}     Update the scope section`,
+                `    ${s.primary('/prd technical')} Update technical requirements`,
+                `    ${s.primary('/prd success')}   Update success criteria`,
+                '',
+                `  ${s.secondary('What it does:')}`,
+                '',
+                `    ${s.muted('•')} Reads the current PRD from the database`,
+                `    ${s.muted('•')} Shows you the existing content`,
+                `    ${s.muted('•')} Asks targeted questions about what to update`,
+                `    ${s.muted('•')} Saves the updated PRD to the database`,
+                '',
+            ],
+        },
+        // Page 2: When to Use
+        {
+            title: 'When to Use /prd',
+            lines: [
+                '',
+                `  ${s.secondary('After /design or /sketch:')}`,
+                `  Your initial PRD is created during the design process.`,
+                `  Use ${s.primary('/prd')} to refine specific sections later.`,
+                '',
+                `  ${s.secondary('When requirements change:')}`,
+                `  As your project evolves, update the PRD to reflect`,
+                `  new goals, features, or constraints.`,
+                '',
+                `  ${s.secondary('Before /scaffold or /build:')}`,
+                `  Make sure your PRD is up to date so the agent`,
+                `  has clear requirements to work from.`,
+                '',
+                `  ${s.secondary('Model:')} Works with any model tier.`,
+                '',
+                `  ${s.warning('NOTE:')} Documents are stored in the ${s.primaryBold('database')},`,
+                `  not the filesystem. Use ${s.primary('/docs')} to view all`,
+                `  project documents.`,
+                '',
+            ],
+        },
+        // Page 3: The Conversation Flow
+        {
+            title: 'The Conversation Flow',
+            lines: [
+                '',
+                `  When you run ${s.primary('/prd')}, the agent:`,
+                '',
+                `    ${s.primary('1.')} Reads the current PRD from the database`,
+                '',
+                `       ${s.muted('● project_document_get(prd)')}`,
+                `         ${s.muted('⎿  Current PRD content...')}`,
+                '',
+                `    ${s.primary('2.')} Asks which section to update`,
+                '',
+                `       ${s.primary('>')} ${s.muted('1. Overview & Problem Statement')}`,
+                `         ${s.muted('2. Goals & Success Metrics')}`,
+                `         ${s.muted('3. User Stories')}`,
+                `         ${s.muted('4. Requirements')}`,
+                `         ${s.muted('5. All sections comprehensively')}`,
+                '',
+                `    ${s.primary('3.')} Shows current content and asks questions`,
+                '',
+                `       ${s.muted('How would you describe the app?')}`,
+                `       ${s.muted('What problem does it solve?')}`,
+                `       ${s.muted('Who are the target users?')}`,
+                '',
+            ],
+        },
+        // Page 4: Multi-Field Questions
+        {
+            title: 'Multi-Field Questions',
+            lines: [
+                '',
+                `  The agent uses multi-field questions to gather details`,
+                `  efficiently in a single overlay:`,
+                '',
+                `    ${s.muted('Questions')}`,
+                '',
+                `    ${s.primary('  Overview   Problem   Users   Submit')}`,
+                '',
+                `    ${s.muted('[1/3] How would you describe the app?')}`,
+                '',
+                `    ${s.muted('> Custom: _')}`,
+                '',
+                `  Each field captures a specific piece of information.`,
+                `  Navigate with the tabs at the top, or answer in order.`,
+                '',
+                `  After you submit all answers, the agent composes the`,
+                `  updated PRD section and saves it to the database.`,
+                '',
+                `  ${s.muted('● project_document_add(prd)')}`,
+                `    ${s.muted('⎿  Document "Product Requirements Document" saved')}`,
+                '',
+            ],
+        },
+        // Page 5: What Gets Updated
+        {
+            title: 'What Gets Updated',
+            lines: [
+                '',
+                `  A typical PRD contains these sections:`,
+                '',
+                `    ${s.primaryBold('Overview')}`,
+                `    ${s.muted('What the app does and key capabilities')}`,
+                '',
+                `    ${s.primaryBold('Problem Statement')}`,
+                `    ${s.muted('Pain points the app solves')}`,
+                '',
+                `    ${s.primaryBold('Target Users')}`,
+                `    ${s.muted('Who the app is for')}`,
+                '',
+                `    ${s.primaryBold('Goals & Success Metrics')}`,
+                `    ${s.muted('Measurable outcomes')}`,
+                '',
+                `    ${s.primaryBold('User Stories')}`,
+                `    ${s.muted('"As a user, I want to..."')}`,
+                '',
+                `    ${s.primaryBold('Functional Requirements')}`,
+                `    ${s.muted('Feature specifications with priority')}`,
+                '',
+                `    ${s.primaryBold('Non-Functional Requirements')}`,
+                `    ${s.muted('Performance, security, accessibility')}`,
+                '',
+            ],
+        },
+        // Page 6: Related Commands
+        {
+            title: 'Related Commands',
+            lines: [
+                '',
+                `  ${s.secondary('Document commands:')}`,
+                '',
+                `    ${s.primary('/prd')}       Update the Product Requirements Document`,
+                `    ${s.primary('/arch')}      Create or update Architecture Document`,
+                `    ${s.primary('/docs')}      View and manage all project documents`,
+                '',
+                `  ${s.secondary('Planning workflow:')}`,
+                '',
+                `    ${s.primary('/design')} → ${s.primary('/prd')} → ${s.primary('/arch')} → ${s.primary('/scaffold')} → ${s.primary('/build')}`,
+                `    ${s.muted('  plan      refine    design     setup      code')}`,
+                '',
+                `  ${s.secondary('Or the quick path:')}`,
+                '',
+                `    ${s.primary('/sketch')} → ${s.primary('/scaffold')} → ${s.primary('/build')}`,
+                `    ${s.muted('  outline    setup      code')}`,
+                '',
+                `  ${s.warning('TIP:')} You can update the PRD at any point during`,
+                `  development — not just at the beginning.`,
+                '',
+            ],
+        },
+    ],
+});

package/dist/ui/overlay/data/tutorials/planning/scaffold.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Scaffold Tutorial
+ *
+ * Walkthrough of the /scaffold command for creating project foundations.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const scaffoldTutorial: TutorialBuilder;