@compilr-dev/cli 0.5.0 → 0.5.2

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

@@ -0,0 +1,168 @@
+/**
+ * Architecture Tutorial
+ *
+ * Walkthrough of the /arch command for creating architecture documentation.
+ */
+export const archTutorial = (s) => ({
+    id: 'arch',
+    title: 'Architecture Docs',
+    description: 'Create architecture documentation',
+    pages: [
+        // Page 1: Introduction
+        {
+            title: 'Architecture Documentation',
+            lines: [
+                '',
+                `  The ${s.primary('/arch')} command creates architecture documentation`,
+                `  — ADRs, system diagrams, data models, and API designs.`,
+                '',
+                `  ${s.secondary('Usage:')}`,
+                '',
+                `    ${s.primary('/arch')}           Interactive type selection`,
+                `    ${s.primary('/arch decision')}  Create an ADR directly`,
+                `    ${s.primary('/arch diagram')}   Create a system diagram`,
+                '',
+                `  ${s.secondary('Document types:')}`,
+                '',
+                `    ${s.muted('•')} ${s.primaryBold('Decision Record (ADR)')}  "Why we chose X over Y"`,
+                `    ${s.muted('•')} ${s.primaryBold('System Diagram')}         Mermaid component diagram`,
+                `    ${s.muted('•')} ${s.primaryBold('Data Model')}             Entities and relationships`,
+                `    ${s.muted('•')} ${s.primaryBold('API Design')}             Endpoints and contracts`,
+                `    ${s.muted('•')} ${s.primaryBold('Custom topic')}           Specify your own`,
+                '',
+            ],
+        },
+        // Page 2: Type Selection
+        {
+            title: 'Type Selection',
+            lines: [
+                '',
+                `  When you run ${s.primary('/arch')}, a selection overlay appears:`,
+                '',
+                `    ${s.muted('Architecture Documentation')}`,
+                '',
+                `    ${s.muted('What would you like to document?')}`,
+                '',
+                `    ${s.primary('>')} ${s.muted('Decision Record (ADR)')}`,
+                `      ${s.muted('System Diagram')}`,
+                `      ${s.muted('Data Model')}`,
+                `      ${s.muted('API Design')}`,
+                `      ${s.muted('Custom topic...')}`,
+                '',
+                `  ${s.secondary('Navigation:')}`,
+                `    ${s.muted('↑/↓')}     Navigate options`,
+                `    ${s.muted('Enter')}   Select and start`,
+                `    ${s.muted('Esc')}     Cancel`,
+                '',
+                `  After selection, the agent reads your PRD and backlog`,
+                `  to understand the project before asking questions.`,
+                '',
+            ],
+        },
+        // Page 3: The Conversation Flow
+        {
+            title: 'The Conversation Flow',
+            lines: [
+                '',
+                `  The agent follows a structured process:`,
+                '',
+                `    ${s.primary('1.')} Reads existing project documents`,
+                '',
+                `       ${s.muted('● project_document_list()')}`,
+                `       ${s.muted('● project_document_get(prd)')}`,
+                `       ${s.muted('● workitem_query()')}`,
+                '',
+                `    ${s.primary('2.')} Asks targeted questions about your architecture`,
+                '',
+                `       ${s.muted('What tech stack are you using?')}`,
+                `       ${s.muted('How do frontend and backend communicate?')}`,
+                `       ${s.muted('What data storage approach?')}`,
+                '',
+                `    ${s.primary('3.')} Creates the document with diagrams`,
+                '',
+                `       ${s.muted('● project_document_add(architecture)')}`,
+                `         ${s.muted('⎿  Document "System Architecture" saved')}`,
+                '',
+                `  The document is saved to the ${s.primaryBold('database')}, not the filesystem.`,
+                '',
+            ],
+        },
+        // Page 4: What Gets Created
+        {
+            title: 'What Gets Created',
+            lines: [
+                '',
+                `  Depending on the type, you get different outputs:`,
+                '',
+                `  ${s.primaryBold('ADR (Decision Record):')}`,
+                `    ${s.muted('Context, decision, alternatives considered,')}`,
+                `    ${s.muted('consequences, and status.')}`,
+                '',
+                `  ${s.primaryBold('System Diagram:')}`,
+                `    ${s.muted('Mermaid component diagram showing services,')}`,
+                `    ${s.muted('databases, APIs, and data flow.')}`,
+                '',
+                `  ${s.primaryBold('Data Model:')}`,
+                `    ${s.muted('Entity-relationship diagram, table schemas,')}`,
+                `    ${s.muted('relationships, and constraints.')}`,
+                '',
+                `  ${s.primaryBold('API Design:')}`,
+                `    ${s.muted('Endpoints, request/response formats,')}`,
+                `    ${s.muted('authentication, and error handling.')}`,
+                '',
+                `  All documents support Markdown with Mermaid diagrams.`,
+                '',
+            ],
+        },
+        // Page 5: Viewing Documents
+        {
+            title: 'Viewing Documents',
+            lines: [
+                '',
+                `  After creating architecture docs, view them with ${s.primary('/docs')}:`,
+                '',
+                `    ${s.muted('Documents [2/2]')}`,
+                '',
+                `    ${s.muted(' All  PRD  ARCH  DESIGN  NOTES  PLANS')}`,
+                '',
+                `    ${s.primary('>')} ${s.muted('PRD       Product Requirements Document')}`,
+                `      ${s.muted('ARCH      System Architecture')}`,
+                '',
+                `  Press ${s.primaryBold('Enter')} to open the full document viewer`,
+                `  with scrolling and search.`,
+                '',
+                `  You can also ask the agent to reference architecture`,
+                `  docs during development:`,
+                '',
+                `    ${s.muted('"Check the architecture doc before implementing"')}`,
+                `    ${s.muted('"Does this match our ADR for the API?"')}`,
+                '',
+            ],
+        },
+        // Page 6: Related Commands
+        {
+            title: 'Related Commands',
+            lines: [
+                '',
+                `  ${s.secondary('Document commands:')}`,
+                '',
+                `    ${s.primary('/arch')}      Create architecture documentation`,
+                `    ${s.primary('/prd')}       Update the Product Requirements Document`,
+                `    ${s.primary('/docs')}      Browse and view all documents`,
+                '',
+                `  ${s.secondary('Typical documentation flow:')}`,
+                '',
+                `    ${s.primary('/design')} → ${s.primary('/prd')} → ${s.primary('/arch')} → ${s.primary('/scaffold')}`,
+                `    ${s.muted('  plan      refine    document    build')}`,
+                '',
+                `  ${s.warning('TIP:')} You can create multiple architecture docs.`,
+                `  For example, one ADR per major decision, plus a`,
+                `  system diagram and data model.`,
+                '',
+                `  ${s.warning('TIP:')} Run ${s.primary('/arch')} again after major changes to`,
+                `  keep your architecture documentation up to date.`,
+                '',
+            ],
+        },
+    ],
+});

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

@@ -0,0 +1,7 @@
+/**
+ * Backlog Management Tutorial
+ *
+ * Walkthrough of the /backlog command for viewing and managing work items.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const backlogTutorial: TutorialBuilder;

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

@@ -0,0 +1,103 @@
+/**
+ * Backlog Management Tutorial
+ *
+ * Walkthrough of the /backlog command for viewing and managing work items.
+ */
+export const backlogTutorial = (s) => ({
+    id: 'backlog',
+    title: 'Backlog Management',
+    description: 'Track and prioritize work',
+    pages: [
+        // Page 1: Introduction
+        {
+            title: 'Backlog Management',
+            lines: [
+                '',
+                `  The ${s.primary('/backlog')} command opens an interactive overlay`,
+                `  to view and manage your project's work items.`,
+                '',
+                `  Work items are created by ${s.primary('/design')} or ${s.primary('/sketch')},`,
+                `  or you can add them manually from the overlay.`,
+                '',
+                `  Each item has a ${s.primary('type')}, ${s.primary('status')}, ${s.primary('priority')},`,
+                `  and optional ${s.primary('owner')} (team agent).`,
+                '',
+            ],
+        },
+        // Page 2: List View
+        {
+            title: 'List View',
+            lines: [
+                '',
+                `  The main view shows all work items with filter tabs:`,
+                '',
+                `     ${s.primaryBold('Backlog')} ${s.muted('[3/3]')}`,
+                '',
+                `      ${s.primary('All')}  Active  Feature  Bug  Tech  Chore`,
+                `      ${s.muted('(Tab Switch · 1-6 Jump)')}`,
+                '',
+                `     ${s.primary('>')} CHR-001  chore    unassigned  ${s.muted('📋')}  ${s.warning('critical')}  Project scaffolding`,
+                `       REQ-002  feature  unassigned  ${s.muted('📋')}  ${s.primary('high')}      User authentication`,
+                `       REQ-003  feature  unassigned  ${s.muted('📋')}  ${s.primary('high')}      Create itineraries`,
+                '',
+                `     ${s.muted('Desc: Create project structure, install...')}`,
+                '',
+                `  Use ${s.primary('Tab')} or ${s.primary('1-6')} to switch filter tabs.`,
+                `  The description preview updates as you navigate.`,
+                '',
+            ],
+        },
+        // Page 3: Item Detail / Edit
+        {
+            title: 'Item Detail',
+            lines: [
+                '',
+                `  Press ${s.primary('Enter')} on an item to open the detail view:`,
+                '',
+                `     ${s.primaryBold('Edit Item')}  CHR-001`,
+                '',
+                `     Project scaffolding and setup`,
+                '',
+                `     ${s.primary('>')} Type: Chore`,
+                `       Status: ${s.muted('📋')} Backlog`,
+                `       Priority: Critical`,
+                `       Owner: unassigned`,
+                '',
+                `     Description:`,
+                `       Create project structure, install dependencies,`,
+                `       configure build system, set up dev environment.`,
+                '',
+                `  Use ${s.primary('←/→')} or ${s.primary('h/l')} to change field values inline.`,
+                `  Press ${s.primary('Esc')} to go back to the list.`,
+                '',
+            ],
+        },
+        // Page 4: Keyboard Shortcuts & Tips
+        {
+            title: 'Shortcuts & Tips',
+            lines: [
+                '',
+                `  ${s.secondary('List view shortcuts:')}`,
+                '',
+                `    ${s.primary('↑/↓')} or ${s.primary('j/k')}    Navigate items`,
+                `    ${s.primary('←/→')} or ${s.primary('h/l')}    Switch pages`,
+                `    ${s.primary('Tab')}            Cycle filter tabs`,
+                `    ${s.primary('1-6')}            Jump to filter tab`,
+                `    ${s.primary('/')}              Search items`,
+                `    ${s.primary('a')}              Add new work item`,
+                `    ${s.primary('Enter')}          Open item detail`,
+                `    ${s.primary('q')} or ${s.primary('Esc')}      Close`,
+                '',
+                `  ${s.secondary('Detail view shortcuts:')}`,
+                '',
+                `    ${s.primary('↑/↓')} or ${s.primary('j/k')}    Select field`,
+                `    ${s.primary('←/→')} or ${s.primary('h/l')}    Change value`,
+                `    ${s.primary('Esc')}            Back to list`,
+                '',
+                `  ${s.warning('TIP:')} To build a backlog item, ask the AI:`,
+                `  ${s.muted('"Build CHR-001: Project scaffolding and setup"')}`,
+                '',
+            ],
+        },
+    ],
+});

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

@@ -0,0 +1,7 @@
+/**
+ * Build Tutorial
+ *
+ * Walkthrough of the /build command for implementing backlog items.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const buildTutorial: TutorialBuilder;

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

@@ -0,0 +1,173 @@
+/**
+ * Build Tutorial
+ *
+ * Walkthrough of the /build command for implementing backlog items.
+ */
+export const buildTutorial = (s) => ({
+    id: 'build',
+    title: 'Building Features',
+    description: 'Implement backlog items',
+    pages: [
+        // Page 1: Introduction
+        {
+            title: 'Building Features',
+            lines: [
+                '',
+                `  The ${s.primary('/build')} command implements a backlog item end-to-end`,
+                `  — backend, frontend, tests, lint, and git commit.`,
+                '',
+                `  ${s.secondary('Usage:')}`,
+                '',
+                `    ${s.primary('/build REQ-003')}     Build a specific item by ID`,
+                `    ${s.primary('/build')}             Pick from your backlog`,
+                '',
+                `  ${s.secondary('What it does:')}`,
+                '',
+                `    ${s.muted('•')} Reads the backlog item and project context`,
+                `    ${s.muted('•')} Creates a step-by-step todo plan`,
+                `    ${s.muted('•')} Implements backend models, services, and routes`,
+                `    ${s.muted('•')} Implements frontend components and views`,
+                `    ${s.muted('•')} Runs build and lint, fixes any errors`,
+                `    ${s.muted('•')} Creates a git commit and updates the backlog`,
+                '',
+            ],
+        },
+        // Page 2: Prerequisites
+        {
+            title: 'Prerequisites',
+            lines: [
+                '',
+                `  Before running ${s.primary('/build')}, you need:`,
+                '',
+                `    ${s.primary('1.')} An active project with a scaffolded codebase`,
+                `       ${s.muted('(run /scaffold first if you haven\'t)')}`,
+                `    ${s.primary('2.')} Backlog items to implement`,
+                `       ${s.muted('(created by /design, /sketch, or /backlog)')}`,
+                '',
+                `  The agent reads your existing code to match patterns:`,
+                '',
+                `    ${s.muted('● read_file(/my-app/backend/src/index.ts)')}`,
+                `      ${s.muted('⎿  import express from \'express\'')}`,
+                `         ${s.muted('...')}`,
+                '',
+                `  This ensures new code follows your project's conventions`,
+                `  — same folder structure, naming, and style.`,
+                '',
+                `  ${s.secondary('Model:')} Works with ${s.primaryBold('medium')} tier models and above.`,
+                `  Haiku can build features but larger models produce better code.`,
+                '',
+            ],
+        },
+        // Page 3: Confirmation Flow
+        {
+            title: 'Confirmation Flow',
+            lines: [
+                '',
+                `  When you run ${s.primary('/build REQ-003')}, the agent:`,
+                '',
+                `    ${s.primary('1.')} Queries the backlog to find the item`,
+                '',
+                `       ${s.muted('● workitem_query()')}`,
+                `         ${s.muted('⎿  46: Create and manage itineraries [high]')}`,
+                '',
+                `    ${s.primary('2.')} Shows the item and asks for confirmation`,
+                '',
+                `       ${s.muted('REQ-003: Create and manage itineraries')}`,
+                `       ${s.muted('Allow users to create trips, add destinations,')}`,
+                `       ${s.muted('set dates, and build a timeline.')}`,
+                '',
+                `       ${s.primary('>')} ${s.muted('1. Yes, let\'s build it')}`,
+                `         ${s.muted('2. No, pick a different item')}`,
+                `         ${s.muted('3. Cancel')}`,
+                '',
+                `    ${s.primary('3.')} Updates the work item status to ${s.primaryBold('in_progress')}`,
+                '',
+            ],
+        },
+        // Page 4: The Build Plan
+        {
+            title: 'The Build Plan',
+            lines: [
+                '',
+                `  After confirmation, the agent creates a todo plan.`,
+                `  A typical feature build has ${s.primaryBold('8-11 steps')}:`,
+                '',
+                `    ${s.muted('☐')} Create data models and types`,
+                `    ${s.muted('☐')} Create backend API routes (CRUD)`,
+                `    ${s.muted('☐')} Create backend services for business logic`,
+                `    ${s.muted('☐')} Create frontend components`,
+                `    ${s.muted('☐')} Implement creation form`,
+                `    ${s.muted('☐')} Implement list view`,
+                `    ${s.muted('☐')} Implement detail/management view`,
+                `    ${s.muted('☐')} Add validation and error handling`,
+                `    ${s.muted('☐')} Test all endpoints and UI interactions`,
+                `    ${s.muted('☐')} Run linter and fix issues`,
+                `    ${s.muted('☐')} Create git commit`,
+                '',
+                `  The plan adapts to your item — a backend-only feature`,
+                `  won't have frontend steps, and vice versa.`,
+                '',
+            ],
+        },
+        // Page 5: During Execution
+        {
+            title: 'During Execution',
+            lines: [
+                '',
+                `  Building a feature typically takes ${s.primaryBold('2-5 minutes')} and uses`,
+                `  ${s.primaryBold('15-40 tool calls')}. You'll see progress in real-time:`,
+                '',
+                `  ${s.muted('● write_file(/my-app/backend/src/models/types.ts)')}`,
+                `    ${s.muted('⎿  File written')}`,
+                '',
+                `  ${s.muted('● write_file(/my-app/backend/src/services/service.ts)')}`,
+                `    ${s.muted('⎿  File written')}`,
+                '',
+                `  ${s.muted('● edit(/my-app/backend/src/index.ts)')}`,
+                `    ${s.muted('⎿  File edited')}`,
+                '',
+                `  The footer shows todo progress as items complete:`,
+                '',
+                `  ${s.success('✓')} Create data models and types`,
+                `  ${s.success('✓')} Create backend API routes (CRUD)`,
+                `  ${s.success('✓')} Create backend services`,
+                `  ${s.primary('→')} Create frontend components`,
+                `  ${s.muted('☐')} Run linter and fix issues`,
+                `  ${s.muted('☐')} Create git commit`,
+                '',
+            ],
+        },
+        // Page 6: Result & Quality
+        {
+            title: 'Result & Quality',
+            lines: [
+                '',
+                `  When done, the agent runs build + lint and provides a summary:`,
+                '',
+                `    ${s.success('✓')} Build: 0 errors (frontend + backend compiled)`,
+                `    ${s.success('✓')} Lint: 0 errors, 0 warnings`,
+                `    ${s.success('✓')} Git: Commit with detailed message`,
+                '',
+                `  The backlog item is automatically marked ${s.primaryBold('completed')}.`,
+                '',
+                `  ${s.secondary('If lint or build fails:')}`,
+                `  The agent will fix errors and re-run until clean.`,
+                '',
+                `  ${s.secondary('What to do next:')}`,
+                '',
+                `    ${s.primary('/backlog')}    View remaining work items`,
+                `    ${s.primary('/build')}      Implement the next item`,
+                `    ${s.muted('or just ask')}  "Build REQ-004"`,
+                '',
+                `  ${s.secondary('The typical workflow:')}`,
+                '',
+                `    ${s.primary('/scaffold')} → ${s.primary('/build')} → ${s.primary('/build')} → ${s.primary('/build')} ...`,
+                `    ${s.muted('  setup       feat 1     feat 2     feat 3')}`,
+                '',
+                `  ${s.warning('TIP:')} You can also say "Build the authentication feature"`,
+                `  in normal chat — ${s.primary('/build')} is a shortcut.`,
+                '',
+            ],
+        },
+    ],
+});

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

@@ -0,0 +1,7 @@
+/**
+ * Design Workflow Tutorial
+ *
+ * Walkthrough of the /design command for comprehensive requirements gathering.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const designTutorial: TutorialBuilder;