cairn-work 0.11.0 → 0.11.2

package/bin/cairn.js

@@ -40,6 +40,7 @@ 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
@@ -213,6 +214,13 @@ program
   .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/doctor.js

@@ -8,6 +8,7 @@ import jsYaml from 'js-yaml';
 
 import { validateWorkspace, createWelcomeFile, resolveWorkspace } from '../setup/workspace.js';
 import { verifyWorkspaceContext } from '../setup/context.js';
+import { validateTaskFrontmatter, validateProjectFrontmatter, VALID_STATUSES } from '../schema/task-schema.js';
 
 function parseFrontmatter(content) {
   const lines = content.split('\n');
@@ -43,6 +44,83 @@ function isUrl(str) {
   return str.startsWith('http://') || str.startsWith('https://') || str.startsWith('obsidian://');
 }
 
+function validateFrontmatter(workspacePath) {
+  const projectsDir = join(workspacePath, 'projects');
+  const results = {
+    totalTasks: 0,
+    totalProjects: 0,
+    tasksWithErrors: [],
+    projectsWithErrors: []
+  };
+  
+  if (!existsSync(projectsDir)) {
+    return results;
+  }
+  
+  const projects = readdirSync(projectsDir).filter(item => {
+    const path = join(projectsDir, item);
+    return statSync(path).isDirectory();
+  });
+  
+  for (const project of projects) {
+    // Check project charter
+    const charterPath = join(projectsDir, project, 'charter.md');
+    if (existsSync(charterPath)) {
+      results.totalProjects++;
+      const content = readFileSync(charterPath, 'utf8');
+      const frontmatter = parseFrontmatter(content);
+      
+      if (frontmatter) {
+        const errors = validateProjectFrontmatter(frontmatter);
+        if (errors.length > 0) {
+          results.projectsWithErrors.push({
+            project,
+            file: 'charter.md',
+            errors
+          });
+        }
+      }
+    }
+    
+    // Check tasks
+    const tasksDir = join(projectsDir, project, 'tasks');
+    if (!existsSync(tasksDir)) {
+      continue;
+    }
+    
+    const taskFiles = readdirSync(tasksDir).filter(f => f.endsWith('.md'));
+    
+    for (const taskFile of taskFiles) {
+      const taskPath = join(tasksDir, taskFile);
+      const content = readFileSync(taskPath, 'utf8');
+      const frontmatter = parseFrontmatter(content);
+      
+      if (!frontmatter) {
+        results.tasksWithErrors.push({
+          project,
+          file: taskFile,
+          errors: ['Unable to parse frontmatter']
+        });
+        continue;
+      }
+      
+      results.totalTasks++;
+      
+      const errors = validateTaskFrontmatter(frontmatter);
+      if (errors.length > 0) {
+        results.tasksWithErrors.push({
+          project,
+          file: taskFile,
+          frontmatter,
+          errors
+        });
+      }
+    }
+  }
+  
+  return results;
+}
+
 function validateArtifacts(workspacePath) {
   const projectsDir = join(workspacePath, 'projects');
   const results = {
@@ -215,7 +293,29 @@ export default async function doctor() {
     }
   }
 
-  // Check 4: Validate artifacts
+  // Check 4: Validate frontmatter
+  const frontmatterSpinner = ora('Validating task and project frontmatter').start();
+  let frontmatterResults = { totalTasks: 0, totalProjects: 0, tasksWithErrors: [], projectsWithErrors: [] };
+  
+  if (existsSync(workspacePath)) {
+    frontmatterResults = validateFrontmatter(workspacePath);
+    
+    const totalErrors = frontmatterResults.tasksWithErrors.length + frontmatterResults.projectsWithErrors.length;
+    
+    if (totalErrors > 0) {
+      frontmatterSpinner.fail(`Found ${totalErrors} frontmatter error(s)`);
+      issues.push({
+        problem: `${totalErrors} task(s)/project(s) have invalid frontmatter`,
+        fix: 'See details below'
+      });
+    } else {
+      frontmatterSpinner.succeed(`Frontmatter valid (${frontmatterResults.totalTasks} tasks, ${frontmatterResults.totalProjects} projects)`);
+    }
+  } else {
+    frontmatterSpinner.skip('Skipped (no workspace)');
+  }
+
+  // Check 5: Validate artifacts
   const artifactSpinner = ora('Checking task artifacts').start();
   let artifactResults = { totalTasks: 0, completedTasks: 0, completedWithoutArtifacts: [], tasksWithArtifacts: [], brokenArtifacts: [] };
   
@@ -286,6 +386,37 @@ export default async function doctor() {
     }
   }
 
+  // Detailed frontmatter report
+  if (frontmatterResults.tasksWithErrors.length > 0) {
+    console.log(chalk.red.bold('Tasks with frontmatter errors:\n'));
+    for (const task of frontmatterResults.tasksWithErrors.slice(0, 10)) {
+      console.log(chalk.red('  ✗'), `${task.project}/${task.file.replace('.md', '')}`);
+      for (const error of task.errors) {
+        console.log(chalk.dim('      -'), error);
+        
+        // Add helpful suggestions for common errors
+        if (error.includes('Invalid status') && task.frontmatter && task.frontmatter.status === 'active') {
+          console.log(chalk.dim('        Suggestion: Change "active" to "in_progress"'));
+        }
+      }
+    }
+    if (frontmatterResults.tasksWithErrors.length > 10) {
+      console.log(chalk.dim(`  ... and ${frontmatterResults.tasksWithErrors.length - 10} more`));
+    }
+    console.log();
+  }
+  
+  if (frontmatterResults.projectsWithErrors.length > 0) {
+    console.log(chalk.red.bold('Projects with frontmatter errors:\n'));
+    for (const project of frontmatterResults.projectsWithErrors) {
+      console.log(chalk.red('  ✗'), `${project.project}/charter.md`);
+      for (const error of project.errors) {
+        console.log(chalk.dim('      -'), error);
+      }
+    }
+    console.log();
+  }
+
   // Detailed artifact report
   if (artifactResults.completedWithoutArtifacts.length > 0) {
     console.log(chalk.yellow.bold('Completed tasks without artifacts:\n'));

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/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.11.0",
+  "version": "0.11.2",
   "description": "AI-native project management - optimized CLI for AI agents and humans working together",
   "type": "module",
   "bin": {