cairn-work 0.5.0 → 0.7.0

package/bin/cairn.js

@@ -25,12 +25,12 @@ import doctor from '../lib/commands/doctor.js';
 import updateSkill from '../lib/commands/update-skill.js';
 import update from '../lib/commands/update.js';
 
-// Onboard command - full setup with agent detection
+// Onboard command - workspace setup with context files
 program
   .command('onboard')
-  .description('Set up Cairn and configure your AI agent')
+  .description('Set up Cairn workspace and agent context')
   .option('--force', 'Force re-onboarding even if already set up')
-  .option('--agent <type>', 'Specify agent type (clawdbot|claude-code|cursor|generic)')
+  .option('--agent <type>', 'Ignored (kept for backwards compatibility)')
   .option('--path <path>', 'Custom workspace path')
   .action(onboard);
 
@@ -51,6 +51,8 @@ program
   .option('--due <date>', 'Due date (YYYY-MM-DD)')
   .option('--description <text>', 'Short description')
   .option('--objective <text>', 'Detailed objective')
+  .option('--criteria <text>', 'Success criteria (projects only)')
+  .option('--context <text>', 'Background context (projects only)')
   .action(create);
 
 // Doctor command - check workspace health
@@ -59,11 +61,10 @@ program
   .description('Check workspace health and fix issues')
   .action(doctor);
 
-// Update-skill command - refresh agent skill
+// Update-skill command - refresh workspace context
 program
   .command('update-skill')
-  .description('Update agent skill documentation')
-  .option('--agent <type>', 'Specific agent to update')
+  .description('Refresh workspace context files (CLAUDE.md + .cairn/planning.md)')
   .action(updateSkill);
 
 // Update command - check for and install updates

package/lib/commands/create.js

@@ -4,6 +4,11 @@ import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { resolveWorkspace } from '../setup/workspace.js';
 
+function expandNewlines(text) {
+  if (!text) return text;
+  return text.replace(/\\n/g, '\n');
+}
+
 function slugify(text) {
   return text
     .toLowerCase()
@@ -47,11 +52,28 @@ export default async function create(type, name, options) {
 
 async function createProject(workspacePath, name, slug, options) {
   const projectPath = join(workspacePath, 'projects', slug);
-  
+
   if (existsSync(projectPath)) {
     console.error(chalk.red('Error:'), `Project already exists: ${slug}`);
     process.exit(1);
   }
+
+  // Require meaningful content — don't create empty charters
+  const missing = [];
+  if (!options.description) missing.push('--description');
+  if (!options.objective) missing.push('--objective');
+  if (!options.criteria) missing.push('--criteria');
+  if (!options.context) missing.push('--context');
+  if (missing.length > 0) {
+    console.error(chalk.red('Error:'), `Missing required flags: ${missing.join(', ')}`);
+    console.log(chalk.dim('Projects need real content for every section. Example:'));
+    console.log(chalk.cyan(`  cairn create project "${name}" \\`));
+    console.log(chalk.cyan(`    --description "One-line summary" \\`));
+    console.log(chalk.cyan(`    --objective "Why this matters and what problem it solves" \\`));
+    console.log(chalk.cyan(`    --criteria "Specific measurable outcomes that define done" \\`));
+    console.log(chalk.cyan(`    --context "Tech stack, constraints, dependencies, assumptions"`));
+    process.exit(1);
+  }
   
   // Create folders
   mkdirSync(projectPath, { recursive: true });
@@ -59,10 +81,11 @@ async function createProject(workspacePath, name, slug, options) {
   
   // Create charter.md
   const charterPath = join(projectPath, 'charter.md');
+  const section = (text) => text ? `\n${expandNewlines(text)}\n` : '\n';
   const charter = `---
 title: ${name}
-description: ${options.description || name}
-status: active
+description: ${expandNewlines(options.description) || name}
+status: in_progress
 priority: 2
 created: ${getToday()}
 due: ${options.due || getDueDate(30)}
@@ -73,19 +96,11 @@ spent: 0
 ---
 
 ## Why This Matters
-
-${options.objective || '[Describe why this project is important]'}
-
+${section(options.objective)}
 ## Success Criteria
-
-- [ ] [Define what success looks like]
-- [ ] [Add measurable outcomes]
-- [ ] [Specify completion criteria]
-
+${section(options.criteria)}
 ## Context
-
-[Add relevant background, constraints, or dependencies]
-
+${section(options.context)}
 ## Work Log
 
 ### ${getToday()} - Created
@@ -122,16 +137,30 @@ async function createTask(workspacePath, name, slug, options) {
   }
   
   const taskPath = join(tasksDir, `${slug}.md`);
-  
+
   if (existsSync(taskPath)) {
     console.error(chalk.red('Error:'), `Task already exists: ${slug}`);
     process.exit(1);
   }
-  
+
+  // Require meaningful content — don't create empty tasks
+  const missing = [];
+  if (!options.objective) missing.push('--objective');
+  if (!options.description) missing.push('--description');
+  if (missing.length > 0) {
+    console.error(chalk.red('Error:'), `Missing required flags: ${missing.join(', ')}`);
+    console.log(chalk.dim('Tasks need real content. Example:'));
+    console.log(chalk.cyan(`  cairn create task "${name}" --project ${projectSlug} \\`));
+    console.log(chalk.cyan(`    --description "One-line summary" \\`));
+    console.log(chalk.cyan(`    --objective "What needs to happen and what done looks like"`));
+    process.exit(1);
+  }
+
   // Create task file
+  const taskSection = (text) => text ? `\n${expandNewlines(text)}\n` : '\n';
   const task = `---
 title: ${name}
-description: ${options.description || name}
+description: ${expandNewlines(options.description) || name}
 assignee: ${options.assignee || 'you'}
 status: ${options.status || 'pending'}
 created: ${getToday()}
@@ -142,9 +171,7 @@ artifacts: []
 ---
 
 ## Objective
-
-${options.objective || '[Describe what needs to be accomplished]'}
-
+${taskSection(options.objective)}
 ## Work Log
 
 ### ${getToday()} - Created

package/lib/commands/doctor.js

@@ -5,11 +5,8 @@ import { join } from 'path';
 import chalk from 'chalk';
 import ora from 'ora';
 
-import { detectAgents, getAgentName } from '../agents/detect.js';
-import { verifyClawdbot } from '../agents/clawdbot.js';
-import { verifyClaudeCode } from '../agents/claude-code.js';
-import { verifyCursor } from '../agents/cursor.js';
-import { validateWorkspace, createWorkspace, createWelcomeFile, resolveWorkspace } from '../setup/workspace.js';
+import { validateWorkspace, createWelcomeFile, resolveWorkspace } from '../setup/workspace.js';
+import { verifyWorkspaceContext } from '../setup/context.js';
 
 export default async function doctor() {
   console.log(chalk.bold.cyan('\n🦮  Cairn Doctor\n'));
@@ -18,7 +15,7 @@ export default async function doctor() {
   const workspacePath = resolveWorkspace() || join(homedir(), 'cairn');
   let issues = [];
   let warnings = [];
-  
+
   // Check 1: Workspace exists
   const spinner = ora('Checking workspace').start();
   if (!existsSync(workspacePath)) {
@@ -39,51 +36,24 @@ export default async function doctor() {
       spinner.succeed('Workspace structure valid');
     }
   }
-  
-  // Check 2: Agent configuration
-  const agentSpinner = ora('Checking agent configuration').start();
-  const { primary, detected } = detectAgents();
-  
-  if (detected.length === 0) {
-    agentSpinner.info('No specific agent detected');
-    warnings.push({
-      problem: 'No AI agent auto-detected',
-      fix: 'Run: cairn onboard --agent <type>'
-    });
-  } else {
-    agentSpinner.succeed(`Detected: ${detected.map(getAgentName).join(', ')}`);
-    
-    // Verify each detected agent
-    for (const agent of detected) {
-      const verifySpinner = ora(`Verifying ${getAgentName(agent)}`).start();
-      let result;
-      
-      switch (agent) {
-        case 'clawdbot':
-          result = verifyClawdbot();
-          break;
-        case 'claude-code':
-          result = verifyClaudeCode();
-          break;
-        case 'cursor':
-          result = verifyCursor();
-          break;
-        default:
-          result = { success: true, message: 'No verification available' };
-      }
-      
-      if (result.success) {
-        verifySpinner.succeed(result.message);
-      } else {
-        verifySpinner.fail(result.message);
-        issues.push({
-          problem: `${getAgentName(agent)}: ${result.message}`,
-          fix: `Run: cairn onboard --agent ${agent} --force`
-        });
-      }
+
+  // Check 2: Context files (CLAUDE.md + .cairn/planning.md)
+  const contextSpinner = ora('Checking workspace context').start();
+  if (existsSync(workspacePath)) {
+    const result = verifyWorkspaceContext(workspacePath);
+    if (result.success) {
+      contextSpinner.succeed(result.message);
+    } else {
+      contextSpinner.fail(result.message);
+      issues.push({
+        problem: result.message,
+        fix: 'Run: cairn onboard --force --path ' + workspacePath
+      });
     }
+  } else {
+    contextSpinner.skip('Skipped (no workspace)');
   }
-  
+
   // Check 3: README exists
   const readmeSpinner = ora('Checking README').start();
   const readmePath = join(workspacePath, 'README.md');
@@ -100,11 +70,11 @@ export default async function doctor() {
       console.log(chalk.green('✓'), 'README created');
     }
   }
-  
+
   // Summary
   console.log();
   console.log(chalk.bold('Summary:\n'));
-  
+
   if (issues.length === 0 && warnings.length === 0) {
     console.log(chalk.green('✓'), chalk.bold('Everything looks good!'));
     console.log();
@@ -113,7 +83,7 @@ export default async function doctor() {
     console.log();
     return;
   }
-  
+
   if (issues.length > 0) {
     console.log(chalk.red.bold(`${issues.length} issue(s) found:\n`));
     for (const issue of issues) {
@@ -122,7 +92,7 @@ export default async function doctor() {
       console.log();
     }
   }
-  
+
   if (warnings.length > 0) {
     console.log(chalk.yellow.bold(`${warnings.length} warning(s):\n`));
     for (const warning of warnings) {
@@ -131,7 +101,7 @@ export default async function doctor() {
       console.log();
     }
   }
-  
+
   console.log(chalk.dim('Run'), chalk.cyan('cairn --help'), chalk.dim('for more commands.'));
   console.log();
 }

package/lib/commands/onboard.js

@@ -4,135 +4,91 @@ import chalk from 'chalk';
 import inquirer from 'inquirer';
 import ora from 'ora';
 
-import { detectAgents, getAgentName } from '../agents/detect.js';
-import { setupClawdbot, getClawdbotInstructions } from '../agents/clawdbot.js';
-import { setupClaudeCode, getClaudeCodeInstructions } from '../agents/claude-code.js';
-import { setupCursor, getCursorInstructions } from '../agents/cursor.js';
-import { setupGeneric, getGenericInstructions } from '../agents/generic.js';
 import { createWorkspace, createWelcomeFile, workspaceExists } from '../setup/workspace.js';
+import { setupWorkspaceContext } from '../setup/context.js';
 
 export default async function onboard(options) {
   console.log(chalk.bold.cyan('\n🦮  Cairn Onboarding\n'));
-  
+
+  // Accept --agent for backwards compat but ignore it.
+  // Non-interactive when --agent or --path is provided.
+  const nonInteractive = !!(options.agent || options.path);
+
   // Prompt for workspace path (if not provided)
   let workspacePath = options.path;
   if (!workspacePath) {
-    const currentDir = process.cwd();
-    const cairnDir = join(homedir(), 'cairn');
-
-    const { location } = await inquirer.prompt([{
-      type: 'list',
-      name: 'location',
-      message: 'Where should Cairn store your project files?',
-      choices: [
-        { name: `Here (${currentDir})`, value: currentDir },
-        { name: `~/cairn`, value: cairnDir },
-        { name: 'Somewhere else...', value: '__custom__' }
-      ]
-    }]);
+    if (nonInteractive) {
+      workspacePath = process.cwd();
+    } else {
+      const currentDir = process.cwd();
+      const cairnDir = join(homedir(), 'cairn');
 
-    if (location === '__custom__') {
-      const { customPath } = await inquirer.prompt([{
-        type: 'input',
-        name: 'customPath',
-        message: 'Enter the full path:'
+      const { location } = await inquirer.prompt([{
+        type: 'list',
+        name: 'location',
+        message: 'Where should Cairn store your project files?',
+        choices: [
+          { name: `Here (${currentDir})`, value: currentDir },
+          { name: `~/cairn`, value: cairnDir },
+          { name: 'Somewhere else...', value: '__custom__' }
+        ]
       }]);
-      workspacePath = customPath;
-    } else {
-      workspacePath = location;
+
+      if (location === '__custom__') {
+        const { customPath } = await inquirer.prompt([{
+          type: 'input',
+          name: 'customPath',
+          message: 'Enter the full path:'
+        }]);
+        workspacePath = customPath;
+      } else {
+        workspacePath = location;
+      }
     }
   }
-  
+
   // Check if already set up
   if (workspaceExists(workspacePath) && !options.force) {
-    const { proceed } = await inquirer.prompt([{
-      type: 'confirm',
-      name: 'proceed',
-      message: `Workspace already exists at ${workspacePath}. Re-run onboarding?`,
-      default: false
-    }]);
-    
-    if (!proceed) {
-      console.log(chalk.yellow('\nOnboarding cancelled.'));
-      return;
-    }
-  }
-  
-  // Step 1: Detect agents
-  let agentType = options.agent;
-  
-  if (!agentType) {
-    const spinner = ora('Detecting AI agents').start();
-    const { primary, detected } = detectAgents();
-    spinner.stop();
-    
-    if (detected.length > 1) {
-      console.log(chalk.green('✓'), `Detected agents: ${detected.map(getAgentName).join(', ')}`);
-      
-      const { selected } = await inquirer.prompt([{
-        type: 'list',
-        name: 'selected',
-        message: 'Multiple agents detected. Which one do you want to configure?',
-        choices: detected.map(type => ({
-          name: getAgentName(type),
-          value: type
-        }))
-      }]);
-      
-      agentType = selected;
-    } else if (detected.length === 1) {
-      agentType = primary;
-      console.log(chalk.green('✓'), `Detected: ${getAgentName(agentType)}`);
+    if (nonInteractive) {
+      console.log(chalk.dim('Workspace already exists at'), workspacePath);
     } else {
-      agentType = 'generic';
-      console.log(chalk.yellow('ℹ'), 'No specific agent detected - using generic setup');
+      const { proceed } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'proceed',
+        message: `Workspace already exists at ${workspacePath}. Re-run onboarding?`,
+        default: false
+      }]);
+
+      if (!proceed) {
+        console.log(chalk.yellow('\nOnboarding cancelled.'));
+        return;
+      }
     }
   }
-  
-  // Step 2: Create workspace
+
+  // Step 1: Create workspace
   console.log();
   createWorkspace(workspacePath);
   createWelcomeFile(workspacePath);
-  
-  // Step 3: Set up agent
+
+  // Step 2: Write context files (CLAUDE.md + .cairn/planning.md)
   console.log();
-  const setupSpinner = ora(`Configuring ${getAgentName(agentType)}`).start();
-  
+  const setupSpinner = ora('Writing workspace context').start();
+
   try {
-    switch (agentType) {
-      case 'clawdbot':
-        await setupClawdbot(workspacePath);
-        setupSpinner.succeed(`${getAgentName(agentType)} configured`);
-        console.log(getClawdbotInstructions(workspacePath));
-        break;
-        
-      case 'claude-code':
-        await setupClaudeCode(workspacePath);
-        setupSpinner.succeed(`${getAgentName(agentType)} configured`);
-        console.log(getClaudeCodeInstructions(workspacePath));
-        break;
-        
-      case 'cursor':
-        await setupCursor(workspacePath);
-        setupSpinner.succeed(`${getAgentName(agentType)} configured`);
-        console.log(getCursorInstructions(workspacePath));
-        break;
-        
-      case 'generic':
-      default:
-        await setupGeneric(workspacePath);
-        setupSpinner.stop();
-        console.log(getGenericInstructions(workspacePath));
-        break;
-    }
+    await setupWorkspaceContext(workspacePath);
+    setupSpinner.succeed('Workspace context configured');
   } catch (error) {
     setupSpinner.fail('Setup failed');
     console.error(chalk.red('Error:'), error.message);
     process.exit(1);
   }
-  
+
   // Success!
   console.log(chalk.bold.green('\n🎉 Onboarding complete!\n'));
+  console.log(chalk.dim('Workspace:'), chalk.cyan(workspacePath));
+  console.log(chalk.dim('Context:'), chalk.cyan('CLAUDE.md'), '+', chalk.cyan('.cairn/planning.md'));
+  console.log();
   console.log(chalk.dim('Next steps:'));
   console.log(chalk.dim('  1. Open your workspace and tell your agent:'));
   console.log(chalk.dim('     "I use Cairn for project management. Run `cairn --help`'));

package/lib/commands/update-skill.js

@@ -1,14 +1,11 @@
 import chalk from 'chalk';
 import ora from 'ora';
 
-import { detectAgents, getAgentName } from '../agents/detect.js';
-import { setupClawdbot } from '../agents/clawdbot.js';
-import { setupClaudeCode } from '../agents/claude-code.js';
-import { setupCursor } from '../agents/cursor.js';
 import { resolveWorkspace } from '../setup/workspace.js';
+import { setupWorkspaceContext } from '../setup/context.js';
 
 export default async function updateSkill(options) {
-  console.log(chalk.bold.cyan('\n🦮  Updating Agent Skill\n'));
+  console.log(chalk.bold.cyan('\n🦮  Updating Workspace Context\n'));
 
   const workspacePath = resolveWorkspace();
 
@@ -16,54 +13,19 @@ export default async function updateSkill(options) {
     console.error(chalk.red('Error:'), 'No workspace found. Run:', chalk.cyan('cairn init'));
     process.exit(1);
   }
-  
-  // Determine which agents to update
-  let agentsToUpdate = [];
-  
-  if (options.agent) {
-    agentsToUpdate = [options.agent];
-  } else {
-    const { detected } = detectAgents();
-    if (detected.length === 0) {
-      console.log(chalk.yellow('⚠'), 'No agents detected');
-      console.log(chalk.dim('Specify agent:'), chalk.cyan('cairn update-skill --agent <type>'));
-      return;
-    }
-    agentsToUpdate = detected;
-  }
-  
-  // Update each agent
-  for (const agent of agentsToUpdate) {
-    const spinner = ora(`Updating ${getAgentName(agent)}`).start();
-    
-    try {
-      switch (agent) {
-        case 'clawdbot':
-          await setupClawdbot(workspacePath);
-          spinner.succeed(`${getAgentName(agent)} skill updated`);
-          break;
-          
-        case 'claude-code':
-          await setupClaudeCode(workspacePath);
-          spinner.succeed(`${getAgentName(agent)} skill updated`);
-          break;
-          
-        case 'cursor':
-          await setupCursor(workspacePath);
-          spinner.succeed(`${getAgentName(agent)} skill updated`);
-          break;
-          
-        default:
-          spinner.info(`${getAgentName(agent)} - no auto-update available`);
-      }
-    } catch (error) {
-      spinner.fail(`Failed to update ${getAgentName(agent)}`);
-      console.error(chalk.red('Error:'), error.message);
-    }
+
+  const spinner = ora('Refreshing CLAUDE.md and .cairn/planning.md').start();
+
+  try {
+    await setupWorkspaceContext(workspacePath);
+    spinner.succeed('Workspace context updated');
+  } catch (error) {
+    spinner.fail('Failed to update workspace context');
+    console.error(chalk.red('Error:'), error.message);
   }
-  
+
   console.log();
-  console.log(chalk.green('✓'), 'Agent skills updated');
+  console.log(chalk.green('✓'), 'Agent context files refreshed');
   console.log(chalk.dim('Your agents now have the latest Cairn workflow documentation.'));
   console.log();
 }

package/lib/setup/context.js

@@ -0,0 +1,70 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Set up agent-agnostic workspace context.
+ * Writes CLAUDE.md to workspace root and .cairn/planning.md.
+ * Works with any AI agent that can read files.
+ */
+export async function setupWorkspaceContext(workspacePath) {
+  const workspaceRoot = dirname(workspacePath);
+
+  // Read skill template and replace placeholders
+  const skillTemplate = join(__dirname, '../../skills/agent-skill.template.md');
+  let skillContent = readFileSync(skillTemplate, 'utf-8');
+  skillContent = skillContent
+    .replace(/\{\{WORKSPACE_PATH\}\}/g, workspacePath)
+    .replace(/\{\{WORKSPACE_ROOT\}\}/g, workspaceRoot);
+
+  // Write CLAUDE.md to workspace root
+  const claudeMdPath = join(workspacePath, 'CLAUDE.md');
+  writeFileSync(claudeMdPath, skillContent);
+  console.log(chalk.green('✓'), 'CLAUDE.md written to workspace root');
+
+  // Create .cairn directory
+  const cairnDir = join(workspacePath, '.cairn');
+  if (!existsSync(cairnDir)) {
+    mkdirSync(cairnDir, { recursive: true });
+  }
+
+  // Read planning template and replace placeholders
+  const planningTemplate = join(__dirname, '../../skills/agent-planning.template.md');
+  let planningContent = readFileSync(planningTemplate, 'utf-8');
+  planningContent = planningContent
+    .replace(/\{\{WORKSPACE_PATH\}\}/g, workspacePath)
+    .replace(/\{\{WORKSPACE_ROOT\}\}/g, workspaceRoot);
+
+  // Write .cairn/planning.md
+  const planningPath = join(cairnDir, 'planning.md');
+  writeFileSync(planningPath, planningContent);
+  console.log(chalk.green('✓'), '.cairn/planning.md written');
+
+  return true;
+}
+
+/**
+ * Verify workspace context files exist.
+ */
+export function verifyWorkspaceContext(workspacePath) {
+  const claudeMd = join(workspacePath, 'CLAUDE.md');
+  const planningMd = join(workspacePath, '.cairn', 'planning.md');
+
+  const issues = [];
+
+  if (!existsSync(claudeMd)) {
+    issues.push('CLAUDE.md not found in workspace root');
+  }
+  if (!existsSync(planningMd)) {
+    issues.push('.cairn/planning.md not found');
+  }
+
+  if (issues.length > 0) {
+    return { success: false, message: issues.join('; ') };
+  }
+  return { success: true, message: 'Workspace context files verified' };
+}

package/lib/setup/workspace.js

@@ -84,7 +84,7 @@ Cairn uses markdown files with YAML frontmatter:
 ---
 title: My Project
 description: What we're building
-status: active
+status: in_progress
 priority: 1
 owner: me
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn-work",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "AI-native project management - work with AI agents using markdown files",
   "type": "module",
   "bin": {