@compilr-dev/cli 0.5.0 → 0.5.1

package/dist/ui/overlay/data/tutorials/teams/background-execution.js

@@ -0,0 +1,171 @@
+/**
+ * Background Execution Tutorial
+ *
+ * Covers running agents in background, /bg, /fg, /kill, /pending, /filter.
+ */
+export const backgroundExecutionTutorial = (s) => ({
+    id: 'background-execution',
+    title: 'Background Execution',
+    description: 'Run agents in parallel',
+    pages: [
+        // Page 1: Introduction
+        {
+            title: 'Background Execution',
+            lines: [
+                '',
+                `  Run agents in the ${s.primaryBold('background')} while you keep working`,
+                `  in the foreground. Great for parallel tasks.`,
+                '',
+                `  ${s.secondary('The & suffix:')}`,
+                '',
+                `    ${s.primary('$qa review the auth module &')}`,
+                `    ${s.primary('review the work items &')}`,
+                '',
+                `  Add ${s.primaryBold('&')} at the end of any message to run it in the`,
+                `  background. The agent processes your request while`,
+                `  you continue working.`,
+                '',
+                `    ${s.muted('[⊡_⊡] $myagent Started in background')}`,
+                `    ${s.muted('[⊡_⊡] $myagent: Running: workitem_query')}`,
+                `    ${s.muted('[⊡_⊡] $myagent: Backlog Review Summary...')}`,
+                `    ${s.muted('[⊡_⊡] $myagent Finished')} ${s.success('✓')}`,
+                '',
+            ],
+        },
+        // Page 2: Managing Background Agents
+        {
+            title: 'Managing Background Agents',
+            lines: [
+                '',
+                `  The status bar shows active background agents:`,
+                '',
+                `    ${s.warning('bg: 2')}  ${s.muted('[↓]')}`,
+                '',
+                `  Press ${s.primaryBold('Down arrow')} to select, then ${s.primaryBold('Enter')} to open /bg.`,
+                '',
+                `  ${s.primaryBold('/bg')} — View all running background agents`,
+                '',
+                `    ${s.muted('[⊡_⊡] $myagent — Running: read_file')}`,
+                `    ${s.muted('[◉_◉] $qa — Queued (1 pending)')}`,
+                `    ${s.muted('f = foreground · k = kill')}`,
+                '',
+                `  ${s.primaryBold('/fg <agent>')} — Bring agent to foreground`,
+                `  ${s.primaryBold('/kill <agent>')} — Stop a background agent`,
+                '',
+                `  Background agents run independently — their messages`,
+                `  appear inline as they complete.`,
+                '',
+            ],
+        },
+        // Page 3: Pending Requests
+        {
+            title: 'Pending Requests',
+            lines: [
+                '',
+                `  When a background agent needs your input, indicators`,
+                `  appear in the status bar:`,
+                '',
+                `    ${s.warning('pending: 1')}  ${s.muted('[↓]')}`,
+                '',
+                `  Press ${s.primaryBold('Down arrow')} to select, then ${s.primaryBold('Enter')} to open.`,
+                `  Or run ${s.primary('/pending')} (or ${s.primary('/p')}) to see requests:`,
+                '',
+                `    ${s.muted('Pending Requests (1 total)')}`,
+                '',
+                `    ${s.primary('>')} ${s.muted('[⊡_⊡] $myagent: bash: Execute command')}`,
+                `      ${s.muted('Type: Permission request')}`,
+                `      ${s.muted('[a]pprove  [d]eny')}`,
+                '',
+                `  ${s.secondary('Request types:')}`,
+                '',
+                `    ${s.primaryBold('Permission')} — Agent needs approval for an action`,
+                `      ${s.muted('Press')} ${s.primaryBold('a')} ${s.muted('to approve,')} ${s.primaryBold('d')} ${s.muted('to deny')}`,
+                '',
+                `    ${s.primaryBold('Question')} — Agent needs your answer to proceed`,
+                `      ${s.muted('Press')} ${s.primaryBold('r')} ${s.muted('or Enter to respond')}`,
+                '',
+            ],
+        },
+        // Page 4: Conversation Filtering
+        {
+            title: 'Conversation Filtering',
+            lines: [
+                '',
+                `  With multiple agents, conversations can get busy.`,
+                `  Use ${s.primary('/filter')} to focus on specific agents:`,
+                '',
+                `    ${s.primary('/filter $arch')}          Show only $arch messages`,
+                `    ${s.primary('/filter $arch $dev')}     Show $arch and $dev`,
+                `    ${s.primary('/filter --clear')}        Show all messages again`,
+                '',
+                `  Or use the overlay:`,
+                '',
+                `    ${s.primary('/filter')}   (no args) opens a checkbox overlay`,
+                '',
+                `    ${s.muted('[x] $default')}`,
+                `    ${s.muted('[ ] $pm')}`,
+                `    ${s.muted('[x] $dev')}`,
+                '',
+                `    ${s.muted('Space = toggle · a = all · n = none · Enter = apply')}`,
+                '',
+                `  Filtering is ${s.primaryBold('display-only')} — the full history is`,
+                `  preserved. Agents still see all context.`,
+                '',
+            ],
+        },
+        // Page 5: Practical Examples
+        {
+            title: 'Practical Examples',
+            lines: [
+                '',
+                `  ${s.secondary('Parallel code review:')}`,
+                '',
+                `    ${s.primary('$qa review the auth module &')}`,
+                `    ${s.primary('$arch check the API design &')}`,
+                `    ${s.muted('...continue working while they review...')}`,
+                '',
+                `  ${s.secondary('Background research:')}`,
+                '',
+                `    ${s.primary('$pm review the backlog priorities &')}`,
+                `    ${s.muted('...ask $dev about implementation...')}`,
+                '',
+                `  ${s.secondary('Queue multiple tasks:')}`,
+                '',
+                `    ${s.primary('$dev fix the login bug &')}`,
+                `    ${s.primary('$dev then update the tests &')}`,
+                `    ${s.muted('Tasks queue up — second runs after first finishes')}`,
+                '',
+                `  ${s.warning('TIP:')} Messages to the same background agent queue up.`,
+                `  Messages to different agents run in parallel.`,
+                '',
+            ],
+        },
+        // Page 6: Commands Reference
+        {
+            title: 'Commands Reference',
+            lines: [
+                '',
+                `  ${s.secondary('Background execution:')}`,
+                '',
+                `    ${s.primary('message &')}         Run current agent in background`,
+                `    ${s.primary('$agent msg &')}      Switch agent and run in background`,
+                '',
+                `  ${s.secondary('Management:')}`,
+                '',
+                `    ${s.primary('/bg')}               View background agents`,
+                `    ${s.primary('/fg <agent>')}       Bring to foreground`,
+                `    ${s.primary('/kill <agent>')}     Stop background agent`,
+                `    ${s.primary('/pending')}          View pending requests`,
+                `    ${s.primary('/filter')}           Filter conversation by agent`,
+                '',
+                `  ${s.secondary('Shortcuts:')}`,
+                '',
+                `    ${s.primary('Down arrow')}        Select status bar indicators`,
+                `    ${s.primary('/p')}                Short for /pending`,
+                `    ${s.primary('/f')}                Short for /filter`,
+                `    ${s.primary('/f --clear')}        Clear filter`,
+                '',
+            ],
+        },
+    ],
+});

package/dist/ui/overlay/data/tutorials/teams/multi-terminal.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Multi-Terminal Sessions Tutorial
+ *
+ * Covers multi-terminal awareness, /terminals overlay, session resume,
+ * cross-terminal notifications, and agent collision prevention.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const multiTerminalTutorial: TutorialBuilder;

package/dist/ui/overlay/data/tutorials/teams/multi-terminal.js

@@ -0,0 +1,147 @@
+/**
+ * Multi-Terminal Sessions Tutorial
+ *
+ * Covers multi-terminal awareness, /terminals overlay, session resume,
+ * cross-terminal notifications, and agent collision prevention.
+ */
+export const multiTerminalTutorial = (s) => ({
+    id: 'multi-terminal',
+    title: 'Multi-Terminal Sessions',
+    description: 'Work across multiple terminals',
+    pages: [
+        // Page 1: Overview
+        {
+            title: 'Multi-Terminal Sessions',
+            lines: [
+                '',
+                `  Each CLI instance ${s.primaryBold('registers')} in a shared database,`,
+                `  so terminals are aware of each other.`,
+                '',
+                `  ${s.secondary('Status bar indicator:')}`,
+                '',
+                `    ${s.warning('terminals: 2')}  ${s.muted('[↓]')}`,
+                '',
+                `  When more than one terminal is active, the status bar`,
+                `  shows the count. Press ${s.primaryBold('Down arrow')} to select it.`,
+                '',
+                `  ${s.secondary('View sessions:')}`,
+                '',
+                `    ${s.primary('/terminals')}     Open the terminals overlay`,
+                `    ${s.primary('/sessions')}      Alias for /terminals`,
+                '',
+                `  The overlay shows each terminal's ID, PID, active agent,`,
+                `  label, and last heartbeat. Press Enter for details.`,
+                '',
+            ],
+        },
+        // Page 2: Terminal Awareness
+        {
+            title: 'Terminal Awareness',
+            lines: [
+                '',
+                `  ${s.secondary('What each terminal knows:')}`,
+                '',
+                `    ${s.muted('•')} ${s.primaryBold('Agent roster')} — see which agents run in other terminals`,
+                `    ${s.muted('•')} ${s.primaryBold('Active agent')} — know what each terminal is working on`,
+                `    ${s.muted('•')} ${s.primaryBold('Session files')} — per-terminal files prevent clobbering`,
+                '',
+                `  ${s.secondary('Agent collision prevention:')}`,
+                '',
+                `  If Terminal 1 has a ${s.primary('$pm')} agent and you run ${s.primary('/add pm')}`,
+                `  in Terminal 2, the CLI detects the collision:`,
+                '',
+                `    ${s.info('Agent \'pm\' is active in another terminal. Using \'pm_2\' instead.')}`,
+                '',
+                `  Each terminal gets a unique agent ID automatically.`,
+                '',
+                `  ${s.secondary('Session cleanup:')}`,
+                '',
+                `  When a terminal exits, its session files are cleaned up.`,
+                `  Stale sessions (no heartbeat for 2+ minutes) are removed`,
+                `  automatically by other terminals.`,
+                '',
+            ],
+        },
+        // Page 3: Session Resume
+        {
+            title: 'Session Resume',
+            lines: [
+                '',
+                `  When you switch projects or restart, the CLI can restore`,
+                `  your previous conversation.`,
+                '',
+                `  ${s.secondary('Three resume modes (set in /config):')}`,
+                '',
+                `    ${s.primaryBold('Auto')}   Immediately restores the previous session`,
+                `    ${s.primaryBold('Ask')}    Prompts whether to restore or start fresh`,
+                `    ${s.primaryBold('Fresh')}  Always starts with a clean conversation`,
+                '',
+                `  ${s.secondary('Use /resume to manually pick a session:')}`,
+                '',
+                `    ${s.primary('/resume')}     Browse available sessions`,
+                '',
+                `  The overlay shows sessions from:`,
+                `    ${s.muted('•')} Current terminal (most recent)`,
+                `    ${s.muted('•')} Other terminals (can be claimed)`,
+                `    ${s.muted('•')} History (older sessions)`,
+                '',
+            ],
+        },
+        // Page 4: Session Claiming
+        {
+            title: 'Session Claiming',
+            lines: [
+                '',
+                `  You can ${s.primaryBold('claim')} a session from another terminal.`,
+                `  This transfers ownership to your current terminal.`,
+                '',
+                `  ${s.secondary('How it works:')}`,
+                '',
+                `    ${s.muted('1.')} Open ${s.primary('/resume')} and find the session`,
+                `    ${s.muted('2.')} Select it and press ${s.primaryBold('Enter')}`,
+                `    ${s.muted('3.')} Session files are moved to your terminal`,
+                `    ${s.muted('4.')} Team state and conversation are restored`,
+                '',
+                `  ${s.secondary('Session isolation:')}`,
+                '',
+                `  Each terminal has a unique 8-character prefix.`,
+                `  Session files like ${s.muted('current-a1b2c3d4.json')} belong to`,
+                `  that specific terminal. Claiming renames the file`,
+                `  to your terminal's prefix.`,
+                '',
+                `  ${s.warning('TIP:')} Sessions from exited terminals are fair game.`,
+                `  Active terminals keep their sessions locked.`,
+                '',
+            ],
+        },
+        // Page 5: Cross-Terminal Notifications
+        {
+            title: 'Cross-Terminal Notifications',
+            lines: [
+                '',
+                `  Terminals communicate via the shared database.`,
+                '',
+                `  ${s.secondary('Notification types:')}`,
+                '',
+                `    ${s.primaryBold('pending_request')}   Approval requests from agents`,
+                `    ${s.primaryBold('agent_finished')}    Background agent completed work`,
+                '',
+                `  ${s.secondary('How notifications arrive:')}`,
+                '',
+                `  Each terminal polls every 5 seconds for new events.`,
+                `  When a notification arrives, it appears in the`,
+                `  status bar as a navigable indicator.`,
+                '',
+                `  ${s.secondary('Status bar navigation:')}`,
+                '',
+                `    ${s.primaryBold('Down arrow')}     Enter status bar from input`,
+                `    ${s.primaryBold('Left/Right')}     Move between indicators`,
+                `    ${s.primaryBold('Enter')}          Open the relevant overlay`,
+                `    ${s.primaryBold('Escape')}         Exit status bar navigation`,
+                '',
+                `  Indicators: ${s.warning('pending')} ${s.info('bg-agents')} ${s.success('terminals')} ${s.primary('notifications')}`,
+                '',
+            ],
+        },
+    ],
+});

package/dist/ui/overlay/data/tutorials/teams/task-assignment.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Task Assignment Tutorial
+ *
+ * Covers work item and todo assignment, handoffs, artifacts, and coordinator.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const taskAssignmentTutorial: TutorialBuilder;

package/dist/ui/overlay/data/tutorials/teams/task-assignment.js

@@ -0,0 +1,204 @@
+/**
+ * Task Assignment Tutorial
+ *
+ * Covers work item and todo assignment, handoffs, artifacts, and coordinator.
+ */
+export const taskAssignmentTutorial = (s) => ({
+    id: 'task-assignment',
+    title: 'Task Assignment',
+    description: 'Assign work to agents',
+    pages: [
+        // Page 1: Introduction
+        {
+            title: 'Task Assignment',
+            lines: [
+                '',
+                `  Agents can ${s.primaryBold('claim')} and ${s.primaryBold('hand off')} tasks to each other,`,
+                `  giving your team structured ownership of work.`,
+                '',
+                `  ${s.secondary('Two types of tasks can be assigned:')}`,
+                '',
+                `    ${s.primaryBold('Work Items')} — Backlog items (persistent, in database)`,
+                `    ${s.muted('    "Implement user authentication" (REQ-001)')}`,
+                '',
+                `    ${s.primaryBold('Todos')} — Session tasks (temporary, current session)`,
+                `    ${s.muted('    "Fix type errors" "Run tests"')}`,
+                '',
+                `  ${s.secondary('The basic flow:')}`,
+                '',
+                `    ${s.muted('1.')} Agent claims a task  →  status: ${s.primaryBold('in_progress')}`,
+                `    ${s.muted('2.')} Agent does the work`,
+                `    ${s.muted('3.')} Agent hands off or completes`,
+                '',
+            ],
+        },
+        // Page 2: Work Item Assignment
+        {
+            title: 'Work Item Assignment',
+            lines: [
+                '',
+                `  Agents use tools to claim and hand off backlog items:`,
+                '',
+                `  ${s.primaryBold('Claiming:')}`,
+                '',
+                `    ${s.muted('● workitem_claim({ workitem_id: 5, owner: "self" })')}`,
+                `      ${s.muted('⎿  Work item claimed by $dev')}`,
+                '',
+                `    Sets status to ${s.primaryBold('in_progress')} and assigns the owner.`,
+                '',
+                `  ${s.primaryBold('Handing off:')}`,
+                '',
+                `    ${s.muted('● workitem_handoff({')}`,
+                `    ${s.muted('    workitem_id: 5,')}`,
+                `    ${s.muted('    to_agent: "qa",')}`,
+                `    ${s.muted('    note: "Ready for testing"')}`,
+                `    ${s.muted('  })')}`,
+                '',
+                `  ${s.primaryBold('Querying by owner:')}`,
+                '',
+                `    ${s.muted('workitem_query({ owner: "self" })')}   My items`,
+                `    ${s.muted('workitem_query({ owner: "unassigned" })')} Free items`,
+                '',
+            ],
+        },
+        // Page 3: Todo Assignment
+        {
+            title: 'Todo Assignment',
+            lines: [
+                '',
+                `  Session todos work the same way:`,
+                '',
+                `  ${s.primaryBold('Claiming a todo:')}`,
+                '',
+                `    ${s.muted('● todo_claim({ todo_index: 2, owner: "self" })')}`,
+                `      ${s.muted('⎿  Todo claimed by $dev')}`,
+                '',
+                `  ${s.primaryBold('Handing off a todo:')}`,
+                '',
+                `    ${s.muted('● todo_handoff({')}`,
+                `    ${s.muted('    todo_index: 2,')}`,
+                `    ${s.muted('    to_agent: "qa",')}`,
+                `    ${s.muted('    note: "Tests written, please verify"')}`,
+                `    ${s.muted('  })')}`,
+                '',
+                `  ${s.secondary('Typical multi-agent workflow:')}`,
+                '',
+                `    ${s.muted('$pm creates todo plan with todo_write')}`,
+                `    ${s.muted('$dev claims implementation todos')}`,
+                `    ${s.muted('$qa claims testing todos')}`,
+                `    ${s.muted('$dev hands off to $qa when code is ready')}`,
+                '',
+            ],
+        },
+        // Page 4: Team Artifacts
+        {
+            title: 'Team Artifacts',
+            lines: [
+                '',
+                `  Agents can publish ${s.primaryBold('artifacts')} — named pieces of work`,
+                `  that the whole team can reference.`,
+                '',
+                `  ${s.secondary('Artifact types:')}`,
+                '',
+                `    ${s.primaryBold('Design')}     System designs, API specs`,
+                `    ${s.primaryBold('Plan')}       Implementation plans, roadmaps`,
+                `    ${s.primaryBold('Review')}     Code reviews, QA reports`,
+                `    ${s.primaryBold('Decision')}   Architecture decisions (ADRs)`,
+                `    ${s.primaryBold('Note')}       General notes, meeting notes`,
+                '',
+                `  ${s.secondary('Browsing artifacts:')}`,
+                '',
+                `    ${s.primary('/artifact')}    Open the artifacts overlay`,
+                '',
+                `    ${s.muted('Tabs: All | Design | Plan | Review | Decision | Note')}`,
+                '',
+                `  Artifacts persist across sessions and are stored`,
+                `  per-project. They help agents share structured work.`,
+                '',
+            ],
+        },
+        // Page 5: Coordinator Mode
+        {
+            title: 'Coordinator Mode',
+            lines: [
+                '',
+                `  The ${s.primaryBold('default agent')} acts as ${s.primaryBold('coordinator')} and can`,
+                `  delegate tasks to specialists running in the background.`,
+                '',
+                `  ${s.secondary('How it works:')}`,
+                '',
+                `    ${s.muted('1.')} Coordinator calls ${s.primary('delegate_background')} tool`,
+                `    ${s.muted('2.')} Specialist runs the task in the background`,
+                `    ${s.muted('3.')} On completion, coordinator is auto-notified`,
+                '',
+                `  ${s.secondary('delegate_background parameters:')}`,
+                '',
+                `    ${s.primaryBold('agentId')}         Target specialist (e.g., "dev", "qa")`,
+                `    ${s.primaryBold('task')}            Detailed task description`,
+                `    ${s.primaryBold('todoIndex')}       Optional: link to a todo item`,
+                `    ${s.primaryBold('expectedOutput')}  Optional: what to produce`,
+                '',
+                `  ${s.secondary('Agent status:')}`,
+                '',
+                `    ${s.success('running')}  — Started immediately (agent was free)`,
+                `    ${s.warning('queued')}   — Agent busy, starts when free`,
+                '',
+            ],
+        },
+        // Page 6: Completion & Auto-Resume
+        {
+            title: 'Completion & Auto-Resume',
+            lines: [
+                '',
+                `  When a specialist finishes, the coordinator gets a`,
+                `  ${s.primaryBold('completion event')} with results and artifacts.`,
+                '',
+                `  ${s.secondary('Two delivery scenarios:')}`,
+                '',
+                `  ${s.primaryBold('Immediate')} — Coordinator is idle:`,
+                `    Coordinator auto-resumes with the completion summary.`,
+                '',
+                `  ${s.primaryBold('Deferred')} — Coordinator is busy:`,
+                `    Events queue up and are delivered with the next message.`,
+                '',
+                `  ${s.secondary('Completion message includes:')}`,
+                '',
+                `    ${s.muted('•')} Agent name and status (completed / failed)`,
+                `    ${s.muted('•')} Original task description`,
+                `    ${s.muted('•')} Result summary and any artifacts created`,
+                '',
+                `  ${s.warning('TIP:')} Specialists are scoped — they only work on the`,
+                `  delegated task and stop when done. Artifacts persist`,
+                `  for the coordinator to reference later.`,
+                '',
+            ],
+        },
+        // Page 7: Putting It Together
+        {
+            title: 'Putting It Together',
+            lines: [
+                '',
+                `  ${s.secondary('Example: Coordinated feature development')}`,
+                '',
+                `    ${s.muted('1.')} Coordinator delegates architecture to ${s.primary('$arch')}`,
+                `    ${s.muted('2.')} ${s.primary('$arch')} publishes artifact, auto-notifies coordinator`,
+                `    ${s.muted('3.')} Coordinator delegates implementation to ${s.primary('$dev')}`,
+                `    ${s.muted('4.')} Coordinator delegates tests to ${s.primary('$qa')}`,
+                `    ${s.muted('5.')} Results flow back as completion events`,
+                '',
+                `  ${s.secondary('Commands reference:')}`,
+                '',
+                `    ${s.primary('/team')}          Manage your team`,
+                `    ${s.primary('/artifact')}      Browse team artifacts`,
+                `    ${s.primary('/bg')}            View background agents`,
+                `    ${s.primary('/pending')}       Handle agent requests`,
+                `    ${s.primary('/filter')}        Filter conversation`,
+                '',
+                `  ${s.warning('TIP:')} You don't need all of this to get started.`,
+                `  Most users just need ${s.primary('$agent')} switching and`,
+                `  the occasional ${s.primary('&')} for background work.`,
+                '',
+            ],
+        },
+    ],
+});

package/dist/ui/overlay/data/tutorials/teams/team-overview.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Team Overview Tutorial
+ *
+ * Introduction to multi-agent teams and the /team command.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const teamOverviewTutorial: TutorialBuilder;