@litmers/cursorflow-orchestrator 0.1.9 → 0.1.12

package/examples/demo-project/_cursorflow/tasks/demo-test/README.md

@@ -2,53 +2,70 @@
 
 This directory contains test tasks for demonstrating CursorFlow with real LLM execution.
 
+## Alternative: Generate with Prepare Command
+
+Instead of using these pre-made files, you can generate similar tasks using:
+
+```bash
+# Simple approach
+cursorflow prepare CreateUtils --preset simple --prompt "Create src/utils.js with capitalize, sum, unique functions"
+cursorflow prepare AddTests --preset simple --prompt "Create src/utils.test.js with tests for utils"
+
+# Or use a single complex task
+cursorflow prepare UtilsWithTests --preset complex --prompt "Create utility module with tests"
+```
+
 ## Tasks Overview
 
 ### 01-create-utils.json
 Creates a utility module with basic functions:
-- capitalize(str)
-- sum(arr)
-- unique(arr)
+- `capitalize(str)` - Capitalizes first letter
+- `sum(arr)` - Sums array of numbers
+- `unique(arr)` - Returns unique elements
 
 **Model**: sonnet-4.5
 **Estimated time**: 1-2 minutes
+**Acceptance Criteria**: 5 criteria including function verification
 
 ### 02-add-tests.json
 Adds simple tests for the utility functions without requiring any testing framework.
 
 **Model**: sonnet-4.5
 **Estimated time**: 1-2 minutes
+**Acceptance Criteria**: 5 criteria including test coverage
 
 ## Running the Demo
 
 ### Prerequisites
 - cursor-agent CLI installed (`npm install -g @cursor/agent`)
-- Valid Cursor API key configured
+- Valid Cursor authentication (sign in via Cursor IDE)
 
-### Run the test
+### 1. Validate first
+```bash
+cursorflow doctor --tasks-dir _cursorflow/tasks/demo-test/
+```
 
+### 2. Run the test
 ```bash
-# From your project directory (after cursorflow init)
 cursorflow run _cursorflow/tasks/demo-test/
 ```
 
-### Monitor execution
-
-In a separate terminal:
+### 3. Monitor execution
 ```bash
-# Watch mode (updates every 2 seconds)
+# Interactive dashboard (recommended)
+cursorflow monitor latest
+
+# Or watch mode
 cursorflow monitor --watch --interval 2
 ```
 
-### Check results
-
-After completion:
+### 4. Check results
 ```bash
-# View the logs
-ls -la _cursorflow/logs/runs/
-
-# Check the latest run
+# View lane status
 cursorflow monitor
+
+# Check git branches
+git branch | grep cursorflow
 ```
 
 ## What to Expect
@@ -56,14 +73,16 @@ cursorflow monitor
 1. **Orchestrator** will create 2 lanes (one per task)
 2. **Each lane** will:
    - Create a Git worktree
-   - Create a branch (`cursorflow/demo-XXXXX--01-create-utils`, etc.)
+   - Create a branch (`cursorflow/demo-utils-*`, `cursorflow/demo-tests-*`)
    - Execute the LLM agent with the prompt
+   - Run AI code review (if enabled)
    - Commit changes
    - Push the branch
 3. **Monitor** will show:
-   - Lane status (running, completed, failed)
+   - Lane status (pending, running, completed, failed)
    - Progress (current task / total tasks)
-   - Real-time updates in watch mode
+   - Dependencies (if any)
+   - Real-time updates
 
 ## Expected Output Structure
 
@@ -88,6 +107,16 @@ _cursorflow/
         └── README.md (this file)
 ```
 
+## Cleanup
+
+After testing:
+```bash
+# Clean branches and worktrees
+cursorflow clean branches --dry-run  # Preview
+cursorflow clean branches            # Execute
+cursorflow clean worktrees           # Clean worktrees
+```
+
 ## Troubleshooting
 
 ### If cursor-agent is not found
@@ -95,15 +124,27 @@ _cursorflow/
 npm install -g @cursor/agent
 ```
 
-### If API key is missing
-Check your Cursor IDE settings and ensure you're authenticated.
+### If authentication fails
+1. Open Cursor IDE
+2. Sign in to your account
+3. Verify AI features work in the IDE
+4. Run `cursorflow doctor` to check
 
 ### If worktree creation fails
-Make sure you're in a Git repository with at least one commit.
+Make sure you're in a Git repository with at least one commit:
+```bash
+git log --oneline -1
+```
+
+### If branch conflicts occur
+```bash
+cursorflow doctor --tasks-dir _cursorflow/tasks/demo-test/
+```
 
 ## Notes
 
-- These tasks are designed to be simple and quick
-- No external dependencies required
+- These tasks run in parallel (no dependencies)
+- Each task creates its own isolated branch
+- AI code review is enabled by default
 - All operations are Git-safe (branches only, no main changes)
 - Logs are preserved for inspection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litmers/cursorflow-orchestrator",
-  "version": "0.1.9",
+  "version": "0.1.12",
   "description": "Git worktree-based parallel AI agent orchestration system for Cursor",
   "main": "dist/cli/index.js",
   "bin": {

package/src/cli/clean.ts

@@ -16,6 +16,26 @@ interface CleanOptions {
   dryRun: boolean;
   force: boolean;
   all: boolean;
+  help: boolean;
+}
+
+function printHelp(): void {
+  console.log(`
+Usage: cursorflow clean <type> [options]
+
+Clean up resources created by CursorFlow.
+
+Types:
+  branches               Remove local feature branches
+  worktrees              Remove temporary Git worktrees
+  logs                   Clear log directories
+  all                    Remove all of the above (default)
+
+Options:
+  --dry-run              Show what would be removed without deleting
+  --force                Force removal (ignore uncommitted changes)
+  --help, -h             Show help
+  `);
 }
 
 function parseArgs(args: string[]): CleanOptions {
@@ -25,11 +45,18 @@ function parseArgs(args: string[]): CleanOptions {
     dryRun: args.includes('--dry-run'),
     force: args.includes('--force'),
     all: args.includes('--all'),
+    help: args.includes('--help') || args.includes('-h'),
   };
 }
 
 async function clean(args: string[]): Promise<void> {
   const options = parseArgs(args);
+  
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
   const config = loadConfig();
   const repoRoot = git.getRepoRoot();
 

package/src/cli/doctor.ts

@@ -13,13 +13,15 @@
  */
 
 import * as logger from '../utils/logger';
-import { runDoctor } from '../utils/doctor';
+import { runDoctor, saveDoctorStatus } from '../utils/doctor';
+import { runInteractiveAgentTest } from '../utils/cursor-agent';
 
 interface DoctorCliOptions {
   json: boolean;
   tasksDir: string | null;
   executor: string | null;
   includeCursorAgentChecks: boolean;
+  testAgent: boolean;
 }
 
 function printHelp(): void {
@@ -33,12 +35,13 @@ Options:
   --tasks-dir <path>     Also validate lane files (run preflight)
   --executor <type>      cursor-agent | cloud
   --no-cursor            Skip Cursor Agent install/auth checks
+  --test-agent           Run interactive agent test (to approve MCP/permissions)
   --help, -h             Show help
 
 Examples:
   cursorflow doctor
+  cursorflow doctor --test-agent
   cursorflow doctor --tasks-dir _cursorflow/tasks/demo-test/
-  cursorflow doctor --json
   `);
 }
 
@@ -51,6 +54,7 @@ function parseArgs(args: string[]): DoctorCliOptions {
     tasksDir: tasksDirIdx >= 0 ? (args[tasksDirIdx + 1] || null) : null,
     executor: executorIdx >= 0 ? (args[executorIdx + 1] || null) : null,
     includeCursorAgentChecks: !args.includes('--no-cursor'),
+    testAgent: args.includes('--test-agent'),
   };
 
   if (args.includes('--help') || args.includes('-h')) {
@@ -69,6 +73,8 @@ function printHumanReport(report: ReturnType<typeof runDoctor>): void {
 
   if (report.issues.length === 0) {
     logger.success('All checks passed');
+    console.log('\n💡 Tip: If this is your first run, we recommend running:');
+    console.log('   cursorflow doctor --test-agent\n');
     return;
   }
 
@@ -106,6 +112,11 @@ function printHumanReport(report: ReturnType<typeof runDoctor>): void {
 async function doctor(args: string[]): Promise<void> {
   const options = parseArgs(args);
 
+  if (options.testAgent) {
+    const success = runInteractiveAgentTest();
+    process.exit(success ? 0 : 1);
+  }
+
   const report = runDoctor({
     cwd: process.cwd(),
     tasksDir: options.tasksDir || undefined,
@@ -119,6 +130,11 @@ async function doctor(args: string[]): Promise<void> {
     printHumanReport(report);
   }
 
+  // Save successful doctor run status
+  if (report.ok && report.context.repoRoot) {
+    saveDoctorStatus(report.context.repoRoot, report);
+  }
+
   process.exit(report.ok ? 0 : 1);
 }
 

package/src/cli/index.ts

@@ -7,15 +7,21 @@ import * as logger from '../utils/logger';
 // Command functions signature
 type CommandFn = (args: string[]) => Promise<void>;
 
-// Lazy load commands to speed up help/version output
+/**
+ * Command Registry
+ */
 const COMMANDS: Record<string, CommandFn> = {
   init: require('./init'),
+  prepare: require('./prepare'),
   run: require('./run'),
   monitor: require('./monitor'),
   clean: require('./clean'),
   resume: require('./resume'),
   doctor: require('./doctor'),
   signal: require('./signal'),
+  models: require('./models'),
+  setup: require('./setup-commands').main,
+  'setup-commands': require('./setup-commands').main,
 };
 
 function printHelp(): void {
@@ -27,12 +33,14 @@ function printHelp(): void {
 
 \x1b[1mCOMMANDS\x1b[0m
   \x1b[33minit\x1b[0m [options]              Initialize CursorFlow in project
+  \x1b[33mprepare\x1b[0m <feature> [opts]    Prepare task directory and JSON files
   \x1b[33mrun\x1b[0m <tasks-dir> [options]   Run orchestration (DAG-based)
   \x1b[33mmonitor\x1b[0m [run-dir] [options] \x1b[36mInteractive\x1b[0m lane dashboard
   \x1b[33mclean\x1b[0m <type> [options]      Clean branches/worktrees/logs
   \x1b[33mresume\x1b[0m <lane> [options]     Resume interrupted lane
   \x1b[33mdoctor\x1b[0m [options]            Check environment and preflight
   \x1b[33msignal\x1b[0m <lane> <msg>         Directly intervene in a running lane
+  \x1b[33mmodels\x1b[0m [options]            List available AI models
 
 \x1b[1mGLOBAL OPTIONS\x1b[0m
   --config <path>             Config file path
@@ -41,9 +49,10 @@ function printHelp(): void {
 
 \x1b[1mEXAMPLES\x1b[0m
   $ \x1b[32mcursorflow init --example\x1b[0m
+  $ \x1b[32mcursorflow prepare NewFeature --lanes 3\x1b[0m
   $ \x1b[32mcursorflow run _cursorflow/tasks/MyFeature/\x1b[0m
   $ \x1b[32mcursorflow monitor latest\x1b[0m
-  $ \x1b[32mcursorflow signal lane-1 "Please use pnpm instead of npm"\x1b[0m
+  $ \x1b[32mcursorflow models\x1b[0m
 
 \x1b[1mDOCUMENTATION\x1b[0m
   https://github.com/eungjin-cigro/cursorflow#readme
@@ -58,7 +67,10 @@ function printVersion(): void {
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
   
-  if (args.length === 0 || args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+  // Only show global help if no arguments provided or if first argument is help-related
+  const isGlobalHelp = args.length === 0 || args[0] === 'help' || (args.length === 1 && (args[0] === '--help' || args[0] === '-h'));
+  
+  if (isGlobalHelp) {
     printHelp();
     return;
   }

package/src/cli/init.ts

@@ -291,15 +291,17 @@ async function init(args: string[]): Promise<void> {
   logger.section('✅ CursorFlow initialized successfully!');
   
   console.log('\n📚 Next steps:\n');
-  console.log('  1. Review cursorflow.config.js');
-  console.log('  2. Type "/" in Cursor IDE to see available commands');
+  console.log('  1. Review \x1b[32mcursorflow.config.js\x1b[0m');
+  console.log('  2. Type \x1b[33m"/"\x1b[0m in Cursor IDE to see available commands');
   
   if (options.example) {
-    console.log(`  3. Run: cursorflow run ${config.tasksDir}/example/`);
+    console.log(`  3. Run: \x1b[32mcursorflow run ${config.tasksDir}/example/\x1b[0m`);
   } else {
-    console.log('  3. Create tasks with: cursorflow prepare MyFeature');
+    console.log('  3. Create your first task: \x1b[32mcursorflow prepare MyFeature\x1b[0m');
   }
   
+  console.log('\n💡 Tip: Use \x1b[33mcursorflow models\x1b[0m to see available AI models.');
+  
   console.log('\n📖 Documentation:');
   console.log('  https://github.com/eungjin-cigro/cursorflow#readme');
   console.log('');

package/src/cli/models.ts

@@ -0,0 +1,83 @@
+/**
+ * CursorFlow models command
+ * 
+ * List available models
+ */
+
+import * as logger from '../utils/logger';
+import { getAvailableModels } from '../utils/cursor-agent';
+
+/**
+ * Model details metadata
+ */
+const MODEL_METADATA: Record<string, { name: string; provider: string; description: string }> = {
+  'sonnet-4.5': { name: 'Claude 3.7 Sonnet', provider: 'Anthropic', description: 'General implementation, fast work (Most versatile)' },
+  'sonnet-4.5-thinking': { name: 'Claude 3.7 Sonnet (Thinking)', provider: 'Anthropic', description: 'Code review, deeper reasoning (Thinking model)' },
+  'opus-4.5': { name: 'Claude 4.0 Opus', provider: 'Anthropic', description: 'Complex tasks, high quality (Advanced)' },
+  'opus-4.5-thinking': { name: 'Claude 4.0 Opus (Thinking)', provider: 'Anthropic', description: 'Architecture design (Premium)' },
+  'gpt-5.2': { name: 'GPT-5.2', provider: 'OpenAI', description: 'General tasks' },
+  'gpt-5.2-high': { name: 'GPT-5.2 High Reasoning', provider: 'OpenAI', description: 'Advanced reasoning (High performance)' },
+  'gemini-3-flash': { name: 'Gemini 3 Flash', provider: 'Google', description: 'General tasks' },
+  'gemini-3-pro': { name: 'Gemini 3 Pro', provider: 'Google', description: 'Advanced reasoning (High performance)' }
+};
+
+function printHelp(): void {
+  console.log(`
+Usage: cursorflow models [options]
+
+List available AI models for use in tasks.
+
+Options:
+  --list, -l         List models in a table (default)
+  --json             Output as JSON
+  --help, -h         Show help
+
+Examples:
+  cursorflow models
+  cursorflow models --json
+  `);
+}
+
+async function models(args: string[]): Promise<void> {
+  const isJson = args.includes('--json');
+  const isHelp = args.includes('--help') || args.includes('-h');
+
+  if (isHelp) {
+    printHelp();
+    return;
+  }
+
+  // Fetch available models from cursor-agent
+  const availableModelIds = getAvailableModels();
+  
+  const modelsData = availableModelIds.map(id => {
+    const meta = MODEL_METADATA[id] || { 
+      name: id, 
+      provider: 'Unknown', 
+      description: 'Discovered via cursor-agent' 
+    };
+    return { id, ...meta };
+  });
+
+  if (isJson) {
+    console.log(JSON.stringify(modelsData, null, 2));
+    return;
+  }
+
+  logger.section('🤖 Available AI Models (from cursor-agent)');
+  
+  const maxIdLen = Math.max(...modelsData.map(m => m.id.length), 10);
+  const maxNameLen = Math.max(...modelsData.map(m => m.name.length), 15);
+  const maxProviderLen = Math.max(...modelsData.map(m => m.provider.length), 10);
+
+  console.log(`  ${'ID'.padEnd(maxIdLen)}  ${'Name'.padEnd(maxNameLen)}  ${'Provider'.padEnd(maxProviderLen)}  Description`);
+  console.log(`  ${'─'.repeat(maxIdLen)}  ${'─'.repeat(maxNameLen)}  ${'─'.repeat(maxProviderLen)}  ${'─'.repeat(30)}`);
+
+  for (const m of modelsData) {
+    console.log(`  ${m.id.padEnd(maxIdLen)}  ${m.name.padEnd(maxNameLen)}  ${m.provider.padEnd(maxProviderLen)}  ${m.description}`);
+  }
+
+  console.log('\n💡 Tip: Use these IDs in your task JSON files under the "model" field.\n');
+}
+
+export = models;

package/src/cli/monitor.ts

@@ -19,6 +19,20 @@ interface LaneWithDeps {
 interface MonitorOptions {
   runDir?: string;
   interval: number;
+  help: boolean;
+}
+
+function printHelp(): void {
+  console.log(`
+Usage: cursorflow monitor [run-dir] [options]
+
+Interactive lane dashboard to track progress and dependencies.
+
+Options:
+  [run-dir]              Run directory to monitor (default: latest)
+  --interval <seconds>   Refresh interval (default: 2)
+  --help, -h             Show help
+  `);
 }
 
 enum View {
@@ -754,6 +768,12 @@ function findLatestRunDir(logsDir: string): string | null {
  * Monitor lanes
  */
 async function monitor(args: string[]): Promise<void> {
+  const help = args.includes('--help') || args.includes('-h');
+  if (help) {
+    printHelp();
+    return;
+  }
+
   const watchIdx = args.indexOf('--watch');
   const intervalIdx = args.indexOf('--interval');
   const interval = intervalIdx >= 0 ? parseInt(args[intervalIdx + 1] || '2') || 2 : 2;