cairn-work 0.6.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);
 
@@ -61,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

@@ -85,7 +85,7 @@ async function createProject(workspacePath, name, slug, options) {
   const charter = `---
 title: ${name}
 description: ${expandNewlines(options.description) || name}
-status: active
+status: in_progress
 priority: 2
 created: ${getToday()}
 due: ${options.due || getDueDate(30)}

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,24 +4,20 @@ 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'));
-  
-  // Determine if running non-interactively (agent provided via --agent flag)
-  const nonInteractive = !!options.agent;
+
+  // 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) {
     if (nonInteractive) {
-      // Non-interactive: default to current directory
       workspacePath = process.cwd();
     } else {
       const currentDir = process.cwd();
@@ -54,7 +50,6 @@ export default async function onboard(options) {
   // Check if already set up
   if (workspaceExists(workspacePath) && !options.force) {
     if (nonInteractive) {
-      // Non-interactive: just proceed with re-configuring the agent
       console.log(chalk.dim('Workspace already exists at'), workspacePath);
     } else {
       const { proceed } = await inquirer.prompt([{
@@ -70,82 +65,30 @@ export default async function onboard(options) {
       }
     }
   }
-  
-  // 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)}`);
-    } else {
-      agentType = 'generic';
-      console.log(chalk.yellow('ℹ'), 'No specific agent detected - using generic setup');
-    }
-  }
-  
-  // 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.6.0",
+  "version": "0.7.0",
   "description": "AI-native project management - work with AI agents using markdown files",
   "type": "module",
   "bin": {

package/skills/agent-planning.template.md

@@ -61,7 +61,7 @@ Good:
 Create 3-8 tasks per project. Each task should be:
 - **Atomic**: Completable in one work session
 - **Specific**: Clear what "done" means without reading other tasks
-- **Ordered**: Set the first task to `status: active`, the rest to `pending`
+- **Ordered**: All tasks default to `status: pending`. Only set `--status next_up` if the user asks you to begin work immediately.
 
 Think in phases:
 1. **Setup/Foundation** — Environment, tooling, project scaffolding
@@ -72,7 +72,7 @@ Think in phases:
 cairn create task "Task Name" \
   --project project-slug \
   --description "What this accomplishes in one sentence" \
-  --status active \
+  --status pending \
   --due YYYY-MM-DD
 ```
 
@@ -183,7 +183,7 @@ render on all routes.
 
 When breaking down a project, think about what blocks what:
 
-1. **Foundation tasks come first** — These set up the project, install tools, create the base structure. Set the first one to `status: active`.
+1. **Foundation tasks come first** — These set up the project, install tools, create the base structure. All tasks start as `status: pending` by default.
 
 2. **Core tasks depend on foundation** — These build the actual features. Set to `status: pending` until foundation tasks are done.
 
@@ -275,7 +275,7 @@ Here's what a fully fleshed-out project looks like after an agent processes "Cre
 ---
 title: Build Marketing Website
 description: Design and develop a responsive marketing website with homepage, about, contact, and blog
-status: active
+status: in_progress
 priority: 2
 created: 2026-01-30
 due: 2026-03-01
@@ -325,7 +325,7 @@ Assumptions:
 title: Initialize project and tooling
 description: Scaffold Next.js project with TypeScript, Tailwind, and dev tooling
 assignee: you
-status: active
+status: pending
 created: 2026-01-30
 due: 2026-02-03
 autonomy: draft
@@ -503,7 +503,7 @@ Chrome, Safari, and Firefox latest versions.
 ---
 title: Add Dark Mode
 description: Implement system-aware dark mode with manual toggle across the site
-status: active
+status: in_progress
 priority: 2
 created: 2026-01-30
 due: 2026-02-10
@@ -547,7 +547,7 @@ Use `next-themes` or a lightweight custom hook.
 title: Implement theme system
 description: Add dark mode infrastructure with Tailwind class strategy and theme provider
 assignee: you
-status: active
+status: pending
 created: 2026-01-30
 due: 2026-02-04
 autonomy: draft
@@ -654,7 +654,7 @@ in both modes.
 
 4. **Vague tasks** — "Work on the frontend" is not a task. "Build the homepage with hero section, features grid, and CTA" is a task.
 
-5. **No sequencing** — All tasks set to `active` at once. Set only the first task (or first parallel set) to `active`, rest to `pending`.
+5. **No sequencing** — All tasks created with random statuses. Create all tasks as `pending` by default. Only use `next_up` when the user explicitly asks you to begin work.
 
 6. **Ignoring the charter** — Jumping straight to tasks without filling in Why, Success Criteria, and Context. The charter is how the human verifies you understood their intent.