cairn-work 0.4.0 → 0.6.0

package/README.md

@@ -5,7 +5,7 @@ AI-native project management where markdown files are the source of truth.
 ## Quick Start
 
 ```bash
-npm install -g cairn
+npm install -g cairn-work
 cairn onboard
 ```
 
@@ -27,9 +27,9 @@ Cairn is a project management system designed for working with AI agents. Instea
 ### Global Install (Recommended)
 
 ```bash
-npm install -g cairn
+npm install -g cairn-work
 # or
-bun install -g cairn
+bun install -g cairn-work
 ```
 
 ### Test Locally

package/bin/cairn.js

@@ -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

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,9 +81,10 @@ 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}
+description: ${expandNewlines(options.description) || name}
 status: active
 priority: 2
 created: ${getToday()}
@@ -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/onboard.js

@@ -14,47 +14,60 @@ import { createWorkspace, createWelcomeFile, workspaceExists } from '../setup/wo
 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;
+
   // 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) {
+      // Non-interactive: default to current directory
+      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;
+    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([{
+        type: 'confirm',
+        name: 'proceed',
+        message: `Workspace already exists at ${workspacePath}. Re-run onboarding?`,
+        default: false
+      }]);
+
+      if (!proceed) {
+        console.log(chalk.yellow('\nOnboarding cancelled.'));
+        return;
+      }
     }
   }
   

package/lib/commands/update.js

@@ -24,7 +24,7 @@ export default async function update() {
   
   try {
     // Check npm registry for latest version
-    const { stdout } = await execAsync('npm view cairn version');
+    const { stdout } = await execAsync('npm view cairn-work version');
     const latestVersion = stdout.trim();
     
     console.log(chalk.dim('Current version:'), chalk.cyan(currentVersion));
@@ -52,10 +52,10 @@ export default async function update() {
     
     // Perform update
     console.log();
-    console.log(chalk.dim('Running:'), chalk.cyan('npm install -g cairn@latest'));
+    console.log(chalk.dim('Running:'), chalk.cyan('npm install -g cairn-work@latest'));
     console.log();
     
-    const updateProcess = exec('npm install -g cairn@latest');
+    const updateProcess = exec('npm install -g cairn-work@latest');
     updateProcess.stdout.pipe(process.stdout);
     updateProcess.stderr.pipe(process.stderr);
     
@@ -68,7 +68,7 @@ export default async function update() {
       } else {
         console.log();
         console.error(chalk.red('✗'), 'Update failed');
-        console.log(chalk.dim('Try running manually:'), chalk.cyan('npm install -g cairn@latest'));
+        console.log(chalk.dim('Try running manually:'), chalk.cyan('npm install -g cairn-work@latest'));
         console.log();
         process.exit(1);
       }
@@ -77,7 +77,7 @@ export default async function update() {
   } catch (error) {
     console.error(chalk.red('Error checking for updates:'), error.message);
     console.log(chalk.dim('\nYou can update manually:'));
-    console.log(chalk.cyan('  npm install -g cairn@latest'));
+    console.log(chalk.cyan('  npm install -g cairn-work@latest'));
     console.log();
     process.exit(1);
   }

package/package.json

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

package/skills/agent-skill.template.md

@@ -175,17 +175,20 @@ The CLI ensures proper structure, slugification, and frontmatter.
 Options:
 - `--project <slug>` - Project slug (REQUIRED)
 - `--assignee <name>` - Who's responsible (default: human)
-- `--description "text"` - Task description  
+- `--description "text"` - Task description
 - `--objective "text"` - What needs to be accomplished
 - `--status <status>` - Initial status (default: pending)
 - `--due YYYY-MM-DD` - Due date
 
+**IMPORTANT:** Always pass `--description` and `--objective` with real content. If you omit them, the file will have empty sections. Write specific, actionable text — never placeholder text like "[Describe what needs to be accomplished]".
+
 Example:
 ```bash
 cairn create task "Set up CI pipeline" \\
   --project launch-app \\
   --assignee pagoda \\
   --description "Configure GitHub Actions for automated testing" \\
+  --objective "Set up a CI pipeline that runs lint, typecheck, and tests on every PR. Use GitHub Actions with a Node.js matrix for v18 and v20. Cache node_modules for faster runs." \\
   --due 2026-02-01
 ```
 
@@ -198,13 +201,20 @@ cairn create task "Set up CI pipeline" \\
 Options:
 - `--description "text"` - Project description
 - `--objective "text"` - Why this matters
+- `--criteria "text"` - Success criteria
+- `--context "text"` - Background, constraints, or dependencies
 - `--due YYYY-MM-DD` - Project deadline
 - `--assignee <name>` - Project owner
 
+**IMPORTANT:** Always pass `--description`, `--objective`, `--criteria`, and `--context` with real content. Write thoughtful, specific text for each — these sections drive the entire project. After creating the project, read the charter and fill in anything that still needs detail.
+
 Example:
 ```bash
 cairn create project "Launch Mobile App" \\
   --description "Ship iOS and Android app by Q2" \\
+  --objective "We need a mobile app to reach users who primarily use phones. The web app has 60% mobile traffic but poor mobile UX." \\
+  --criteria "App published to App Store and Play Store. Supports login, dashboard, and notifications. 4+ star rating in first month." \\
+  --context "Using React Native for cross-platform. Backend API already exists. Design mockups in Figma." \\
   --due 2026-06-30
 ```