cairn-work 0.10.0 → 0.11.1

package/bin/cairn.js

@@ -39,6 +39,8 @@ import status from '../lib/commands/status.js';
 import note from '../lib/commands/note.js';
 import edit from '../lib/commands/edit.js';
 import search from '../lib/commands/search.js';
+import triage from '../lib/commands/triage.js';
+import learn from '../lib/commands/learn.js';
 
 // Onboard command - workspace setup with context files
 program
@@ -205,6 +207,20 @@ program
   .option('--project <slug>', 'Limit search to specific project')
   .action(search);
 
+// Triage command - process inbox items interactively
+program
+  .command('triage')
+  .description('Process inbox items interactively - create tasks, delete, or skip')
+  .option('--assignee <name>', 'Default assignee for created tasks', 'you')
+  .action(triage);
+
+// Learn command - show system overview and documentation
+program
+  .command('learn')
+  .description('Show Cairn system overview and available documentation')
+  .option('--verbose', 'Show full documentation paths')
+  .action(learn);
+
 // Parse and handle errors
 program.parseAsync(process.argv).catch((error) => {
   console.error(chalk.red('Error:'), error.message);

package/lib/commands/learn.js

@@ -0,0 +1,123 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import { resolveWorkspace } from '../setup/workspace.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export default async function learn(options) {
+  console.log(chalk.cyan.bold('\n📚 Cairn System Overview\n'));
+  
+  // 1. Show workspace location
+  const workspacePath = resolveWorkspace();
+  if (workspacePath) {
+    console.log(chalk.green('✓'), 'Workspace:', chalk.cyan(workspacePath));
+  } else {
+    console.log(chalk.yellow('⚠'), 'No workspace found. Run:', chalk.cyan('cairn init'));
+  }
+  console.log();
+  
+  // 2. Project structure
+  console.log(chalk.bold('📁 Project Structure'));
+  console.log(chalk.dim('  projects/{slug}/charter.md       # Project definition'));
+  console.log(chalk.dim('  projects/{slug}/tasks/{slug}.md  # Individual tasks'));
+  console.log(chalk.dim('  inbox/                           # Unprocessed items'));
+  console.log(chalk.dim('  artifacts/                       # Shared documents'));
+  console.log(chalk.dim('  .cairn/                          # System files'));
+  console.log();
+  
+  // 3. Key concepts
+  console.log(chalk.bold('🎯 Key Concepts'));
+  console.log();
+  
+  console.log(chalk.cyan('  Statuses:'));
+  console.log(chalk.dim('    pending   → not started yet'));
+  console.log(chalk.dim('    next-up   → ready to work on'));
+  console.log(chalk.dim('    in_progress → actively working'));
+  console.log(chalk.dim('    blocked   → waiting for input'));
+  console.log(chalk.dim('    review    → awaiting approval'));
+  console.log(chalk.dim('    done      → completed'));
+  console.log();
+  
+  console.log(chalk.cyan('  Autonomy Levels:'));
+  console.log(chalk.dim('    propose → log approach only, don\'t do work'));
+  console.log(chalk.dim('    draft   → do work but need review (code changes)'));
+  console.log(chalk.dim('    execute → do everything including irreversible actions'));
+  console.log();
+  
+  console.log(chalk.cyan('  Priority & Due Dates:'));
+  console.log(chalk.dim('    P1 (urgent)       → due today'));
+  console.log(chalk.dim('    P2+ (less urgent) → due in 7 days'));
+  console.log();
+  
+  // 4. Common workflows
+  console.log(chalk.bold('🔄 Common Workflows'));
+  console.log();
+  
+  console.log(chalk.cyan('  Starting work:'));
+  console.log(chalk.dim('    cairn my                  # See your tasks'));
+  console.log(chalk.dim('    cairn start <task-slug>   # Move to in_progress'));
+  console.log();
+  
+  console.log(chalk.cyan('  While working:'));
+  console.log(chalk.dim('    cairn note <task-slug> "message"  # Add quick notes'));
+  console.log(chalk.dim('    cairn view <task-slug>            # View full details'));
+  console.log();
+  
+  console.log(chalk.cyan('  Finishing:'));
+  console.log(chalk.dim('    cairn done <task-slug>    # Auto moves to done/review'));
+  console.log(chalk.dim('    cairn block <task-slug> "reason"  # When stuck'));
+  console.log();
+  
+  console.log(chalk.cyan('  Creating new work:'));
+  console.log(chalk.dim('    cairn create task "Name" --project <slug> \\'));
+  console.log(chalk.dim('      --description "..." --objective "..."'));
+  console.log();
+  
+  // 5. Available documentation
+  if (options.verbose) {
+    console.log(chalk.bold('📖 Available Documentation\n'));
+    
+    // Check for CLI skills
+    const cliRoot = join(__dirname, '..', '..');
+    const skillsDir = join(cliRoot, 'skills');
+    if (existsSync(skillsDir)) {
+      console.log(chalk.cyan('  CLI Skills:'));
+      const skillFiles = readdirSync(skillsDir).filter(f => f.endsWith('.md'));
+      skillFiles.forEach(file => {
+        console.log(chalk.dim(`    ${join(skillsDir, file)}`));
+      });
+      console.log();
+    }
+    
+    // Check for workspace planning docs
+    if (workspacePath) {
+      const cairnDir = join(workspacePath, '.cairn');
+      if (existsSync(cairnDir)) {
+        console.log(chalk.cyan('  Workspace Documentation:'));
+        const cairnFiles = readdirSync(cairnDir).filter(f => f.endsWith('.md'));
+        cairnFiles.forEach(file => {
+          console.log(chalk.dim(`    ${join(cairnDir, file)}`));
+        });
+        console.log();
+      }
+    }
+  } else {
+    console.log(chalk.dim('Run with --verbose to see full documentation paths'));
+  }
+  
+  // 6. Quick tips
+  console.log(chalk.bold('💡 Quick Tips'));
+  console.log();
+  console.log(chalk.dim('  • Always use CLI to create entities (never edit YAML manually)'));
+  console.log(chalk.dim('  • Set status immediately when your state changes'));
+  console.log(chalk.dim('  • Use next-up for queued work, in_progress for active work'));
+  console.log(chalk.dim('  • Respect autonomy: draft→review, execute→done'));
+  console.log(chalk.dim('  • Check cairn my regularly to see your workload'));
+  console.log();
+  
+  console.log(chalk.dim('For detailed help on any command:'), chalk.cyan('cairn <command> --help'));
+  console.log();
+}

package/lib/commands/my.js

@@ -78,6 +78,7 @@ export default async function my(options) {
   
   const myTasks = {
     in_progress: [],
+    next_up: [],
     pending: [],
     blocked: [],
     review: []
@@ -105,6 +106,8 @@ export default async function my(options) {
         
         if (task.status === 'in_progress') {
           myTasks.in_progress.push(taskData);
+        } else if (task.status === 'next-up' || task.status === 'next_up') {
+          myTasks.next_up.push(taskData);
         } else if (task.status === 'pending') {
           myTasks.pending.push(taskData);
         } else if (task.status === 'blocked') {
@@ -116,8 +119,8 @@ export default async function my(options) {
     }
   }
   
-  const totalTasks = myTasks.in_progress.length + myTasks.pending.length + 
-                     myTasks.blocked.length + myTasks.review.length;
+  const totalTasks = myTasks.in_progress.length + myTasks.next_up.length + 
+                     myTasks.pending.length + myTasks.blocked.length + myTasks.review.length;
   
   if (totalTasks === 0) {
     console.log(chalk.dim(`No tasks assigned to ${myName}`));
@@ -139,6 +142,19 @@ export default async function my(options) {
     console.log();
   }
   
+  // Show next-up (ready to work on)
+  if (myTasks.next_up.length > 0) {
+    console.log(chalk.cyan.bold('⏭️  Next Up'));
+    for (const task of myTasks.next_up) {
+      console.log(chalk.bold(`  ${task.slug}`));
+      console.log(chalk.dim(`    ${task.project}`));
+      if (task.description) {
+        console.log(`    ${task.description}`);
+      }
+    }
+    console.log();
+  }
+  
   // Show blocked next (important)
   if (myTasks.blocked.length > 0) {
     console.log(chalk.red.bold('⚠️  Blocked'));

package/lib/commands/triage.js

@@ -0,0 +1,214 @@
+import { existsSync, readdirSync, readFileSync, unlinkSync } from 'fs';
+import { join, basename } from 'path';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { resolveWorkspace } from '../setup/workspace.js';
+import create from './create.js';
+
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Extract project suggestions from existing projects
+ */
+function getAvailableProjects(workspacePath) {
+  const projectsPath = join(workspacePath, 'projects');
+  if (!existsSync(projectsPath)) return [];
+  
+  return readdirSync(projectsPath, { withFileTypes: true })
+    .filter(dirent => dirent.isDirectory())
+    .map(dirent => dirent.name);
+}
+
+/**
+ * Parse inbox item content to suggest task details
+ */
+function parseInboxItem(content) {
+  // Simple heuristic: first line = title, rest = potential description
+  const lines = content.trim().split('\n').filter(l => l.trim());
+  const title = lines[0] || 'Untitled Task';
+  const description = lines.length > 1 ? lines.slice(1).join(' ').substring(0, 100) : title;
+  
+  return {
+    title: title.replace(/^#+\s*/, '').trim(), // Remove markdown headers
+    description: description.trim()
+  };
+}
+
+/**
+ * Main triage function - interactive inbox processing
+ */
+export default async function triage(options = {}) {
+  const workspacePath = resolveWorkspace();
+
+  if (!workspacePath) {
+    console.error(chalk.red('Error:'), 'No workspace found. Run:', chalk.cyan('cairn init'));
+    process.exit(1);
+  }
+
+  const inboxPath = join(workspacePath, 'inbox');
+  
+  if (!existsSync(inboxPath)) {
+    console.log(chalk.yellow('⚠'), 'Inbox folder not found');
+    console.log(chalk.dim('  Create it at:'), inboxPath);
+    return;
+  }
+
+  // Get all inbox items
+  const inboxFiles = readdirSync(inboxPath)
+    .filter(f => f.endsWith('.md'))
+    .map(f => join(inboxPath, f));
+
+  if (inboxFiles.length === 0) {
+    console.log(chalk.green('✓'), 'Inbox is empty!');
+    return;
+  }
+
+  console.log(chalk.cyan('\n📥 Inbox Triage\n'));
+  console.log(chalk.dim(`Found ${inboxFiles.length} item(s) to process\n`));
+
+  const availableProjects = getAvailableProjects(workspacePath);
+  
+  if (availableProjects.length === 0) {
+    console.log(chalk.yellow('⚠'), 'No projects found. Create one first:');
+    console.log(chalk.cyan('  cairn create project "My Project" --description "..." --objective "..." --criteria "..." --context "..."'));
+    return;
+  }
+
+  let processed = 0;
+  let skipped = 0;
+
+  for (const filePath of inboxFiles) {
+    const filename = basename(filePath);
+    const content = readFileSync(filePath, 'utf-8');
+    const parsed = parseInboxItem(content);
+
+    console.log(chalk.bold(`\n${filename}`));
+    console.log(chalk.dim('─'.repeat(60)));
+    console.log(content.substring(0, 200) + (content.length > 200 ? '...' : ''));
+    console.log(chalk.dim('─'.repeat(60)));
+
+    // Ask what to do with this item
+    const { action } = await inquirer.prompt([{
+      type: 'list',
+      name: 'action',
+      message: 'What should we do with this?',
+      choices: [
+        { name: 'Create task', value: 'create' },
+        { name: 'Delete (already done/irrelevant)', value: 'delete' },
+        { name: 'Skip (decide later)', value: 'skip' }
+      ]
+    }]);
+
+    if (action === 'skip') {
+      skipped++;
+      continue;
+    }
+
+    if (action === 'delete') {
+      unlinkSync(filePath);
+      console.log(chalk.green('✓'), 'Deleted');
+      processed++;
+      continue;
+    }
+
+    // Create task flow
+    const answers = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'project',
+        message: 'Which project?',
+        choices: [
+          ...availableProjects,
+          new inquirer.Separator(),
+          { name: chalk.dim('(create new project)'), value: '_new_' }
+        ]
+      },
+      {
+        type: 'input',
+        name: 'newProjectName',
+        message: 'New project name:',
+        when: (ans) => ans.project === '_new_'
+      },
+      {
+        type: 'input',
+        name: 'taskTitle',
+        message: 'Task title:',
+        default: parsed.title
+      },
+      {
+        type: 'input',
+        name: 'description',
+        message: 'Description:',
+        default: parsed.description
+      },
+      {
+        type: 'input',
+        name: 'objective',
+        message: 'Objective (what needs to happen):',
+        default: parsed.description
+      },
+      {
+        type: 'list',
+        name: 'status',
+        message: 'Initial status:',
+        choices: ['pending', 'in-progress', 'in-review', 'blocked'],
+        default: 'pending'
+      },
+      {
+        type: 'list',
+        name: 'priority',
+        message: 'Priority:',
+        choices: [
+          { name: 'P1 - Critical', value: '1' },
+          { name: 'P2 - High', value: '2' },
+          { name: 'P3 - Normal', value: '3' },
+          { name: 'P4 - Low', value: '4' }
+        ],
+        default: '3'
+      }
+    ]);
+
+    // Handle new project creation
+    if (answers.project === '_new_') {
+      console.log(chalk.yellow('\n⚠'), 'Creating a new project requires full details.');
+      console.log(chalk.dim('  Run:'), chalk.cyan(`cairn create project "${answers.newProjectName}" --description "..." --objective "..." --criteria "..." --context "..."`));
+      console.log(chalk.dim('  Then re-run triage.\n'));
+      skipped++;
+      continue;
+    }
+
+    // Create the task
+    try {
+      await create('task', answers.taskTitle, {
+        project: answers.project,
+        description: answers.description,
+        objective: answers.objective,
+        status: answers.status,
+        priority: answers.priority,
+        assignee: options.assignee || 'you'
+      });
+
+      // Delete inbox item after successful creation
+      unlinkSync(filePath);
+      console.log(chalk.dim('  Removed from inbox\n'));
+      processed++;
+
+    } catch (error) {
+      console.error(chalk.red('✗'), 'Failed to create task:', error.message);
+      skipped++;
+    }
+  }
+
+  // Summary
+  console.log(chalk.cyan('\n📊 Triage Complete\n'));
+  console.log(chalk.green('  Processed:'), processed);
+  if (skipped > 0) {
+    console.log(chalk.yellow('  Skipped:'), skipped);
+  }
+  console.log();
+}

package/lib/schema/task-schema.js

@@ -1,6 +1,6 @@
 // Task and Project schema definitions
 
-export const VALID_STATUSES = ['pending', 'in_progress', 'blocked', 'review', 'done', 'completed'];
+export const VALID_STATUSES = ['pending', 'next-up', 'next_up', 'in_progress', 'blocked', 'review', 'done', 'completed'];
 export const VALID_AUTONOMY_LEVELS = ['propose', 'draft', 'execute'];
 
 export const TASK_SCHEMA = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn-work",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "AI-native project management - optimized CLI for AI agents and humans working together",
   "type": "module",
   "bin": {