cairn-work 0.2.0

package/README.md

@@ -0,0 +1,241 @@
+# Cairn 🏔️
+
+AI-native project management where markdown files are the source of truth.
+
+## Quick Start
+
+```bash
+npm install -g cairn
+cairn onboard
+```
+
+That's it! Cairn will detect your AI agent (Clawdbot, Claude Code, Cursor, etc.) and configure everything automatically.
+
+## What is Cairn?
+
+Cairn is a project management system designed for working with AI agents. Instead of databases and web UIs, Cairn uses simple markdown files that both you and your AI agent can read and edit.
+
+**Key features:**
+- **Files are the source of truth** - No database, just markdown
+- **AI-native** - Designed for AI agents to understand and work with
+- **Agent detection** - Auto-configures for Clawdbot, Claude Code, Cursor, Windsurf
+- **Simple hierarchy** - Projects → Tasks
+- **Status tracking** - pending, active, review, blocked, completed
+
+## Installation
+
+### Global Install (Recommended)
+
+```bash
+npm install -g cairn
+# or
+bun install -g cairn
+```
+
+### Test Locally
+
+```bash
+git clone https://github.com/gregoryehill/cairn-cli.git
+cd cairn-cli
+bun install
+bun link
+```
+
+## Commands
+
+### `cairn onboard`
+
+Set up Cairn and configure your AI agent automatically.
+
+```bash
+cairn onboard                    # Auto-detect agent
+cairn onboard --agent clawdbot   # Specific agent
+cairn onboard --force            # Re-run onboarding
+```
+
+### `cairn init`
+
+Initialize workspace without agent configuration.
+
+```bash
+cairn init                # Create workspace in current directory
+cairn init --path /custom # Custom location
+```
+
+### `cairn create`
+
+Create projects and tasks.
+
+```bash
+# Create a project
+cairn create project "Launch My App"
+
+# Create a task
+cairn create task "Set up database" \\
+  --project launch-my-app
+```
+
+### `cairn doctor`
+
+Check workspace health and fix issues.
+
+```bash
+cairn doctor
+```
+
+### `cairn update-skill`
+
+Update agent skill documentation.
+
+```bash
+cairn update-skill              # Update all detected agents
+cairn update-skill --agent cursor  # Specific agent
+```
+
+### `cairn update`
+
+Check for and install CLI updates.
+
+```bash
+cairn update  # Check npm for latest version and prompt to upgrade
+```
+
+## Supported Agents
+
+Cairn auto-detects and configures:
+
+- **[Clawdbot](https://clawd.bot)** - Full integration via skills system
+- **Claude Code** - Workspace context integration
+- **Cursor** - .cursorrules integration
+- **Windsurf** - Workspace integration
+- **Generic** - Manual setup instructions for any AI agent
+
+## How It Works
+
+### File Structure
+
+```
+~/cairn/
+  projects/
+    launch-my-app/
+      charter.md           # Project overview
+      tasks/
+        setup-database.md  # Individual task
+        deploy-api.md      # Another task
+  inbox/                   # Incoming ideas
+  _drafts/                 # Work in progress
+```
+
+### Project → Task
+
+**Project** - A goal or initiative (e.g., "Launch My App")
+**Task** - An atomic piece of work (e.g., "Set up database")
+
+### Status Workflow
+
+`pending` → `active` → `review` → `completed`
+
+Or if blocked: `active` → `blocked` → `active`
+
+### Working with AI Agents
+
+After onboarding, your agent understands how to:
+- Create and update projects/tasks
+- Follow status workflows
+- Log work with timestamps
+- Ask for input when blocked
+
+**Example conversation:**
+```
+You: "Help me plan out my app launch"
+Agent: "I'll create a project structure. What's your app called?"
+You: "TaskMaster - a todo app"
+Agent: *creates project with tasks for backend, frontend, deployment*
+```
+
+## Updates
+
+```bash
+cairn update
+```
+
+Checks npm for the latest version and prompts to upgrade.
+
+Or update manually:
+```bash
+npm update -g cairn
+```
+
+Updates only affect the CLI and agent skills. Your workspace files are never touched.
+
+## Configuration
+
+Cairn uses sensible defaults:
+- **Workspace:** Current directory or `~/cairn`
+- **Agent detection:** Automatic
+- **Files:** Plain markdown with YAML frontmatter
+
+Override workspace location:
+```bash
+export CAIRN_WORKSPACE=/custom/path
+```
+
+## Philosophy
+
+1. **Context is King** - Keep all context in one place
+2. **Files > Databases** - Text files are portable and future-proof
+3. **Simple Beats Complete** - Start simple, add complexity when needed
+4. **AI-First** - Designed for human-AI collaboration
+
+## Troubleshooting
+
+### Agent not detected
+
+```bash
+cairn doctor              # Check setup
+cairn onboard --force     # Re-run onboarding
+```
+
+### Workspace issues
+
+```bash
+cairn doctor              # Auto-fix common issues
+cairn init --path ~/cairn  # Recreate structure
+```
+
+### Skill not updating
+
+```bash
+cairn update-skill        # Refresh agent skill
+```
+
+## Development
+
+```bash
+git clone https://github.com/gregoryehill/cairn-cli.git
+cd cairn-cli
+bun install
+bun link                  # Test locally
+```
+
+Run tests:
+```bash
+bun test
+```
+
+## Contributing
+
+Contributions welcome! Open an issue or PR on GitHub.
+
+## License
+
+MIT © Gregory Hill
+
+## Links
+
+- **GitHub:** https://github.com/gregoryehill/cairn-cli
+- **npm:** https://www.npmjs.com/package/cairn
+
+---
+
+Built with ❤️ for AI-human collaboration

package/bin/cairn.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { readFileSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJson = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+
+const program = new Command();
+
+program
+  .name('cairn')
+  .description('🏔️  AI-native project management')
+  .version(packageJson.version);
+
+// Import commands
+import onboard from '../lib/commands/onboard.js';
+import init from '../lib/commands/init.js';
+import create from '../lib/commands/create.js';
+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
+program
+  .command('onboard')
+  .description('Set up Cairn and configure your AI agent')
+  .option('--force', 'Force re-onboarding even if already set up')
+  .option('--agent <type>', 'Specify agent type (clawdbot|claude-code|cursor|generic)')
+  .option('--path <path>', 'Custom workspace path')
+  .action(onboard);
+
+// Init command - workspace only, no agent setup
+program
+  .command('init')
+  .description('Initialize Cairn workspace (without agent configuration)')
+  .option('--path <path>', 'Custom workspace path (default: current directory)')
+  .action(init);
+
+// Create command - create projects/tasks
+program
+  .command('create <type> <name>')
+  .description('Create a project or task')
+  .option('--project <slug>', 'Parent project (required for tasks)')
+  .option('--assignee <name>', 'Assignee name', 'you')
+  .option('--status <status>', 'Initial status', 'pending')
+  .option('--due <date>', 'Due date (YYYY-MM-DD)')
+  .option('--description <text>', 'Short description')
+  .option('--objective <text>', 'Detailed objective')
+  .action(create);
+
+// Doctor command - check workspace health
+program
+  .command('doctor')
+  .description('Check workspace health and fix issues')
+  .action(doctor);
+
+// Update-skill command - refresh agent skill
+program
+  .command('update-skill')
+  .description('Update agent skill documentation')
+  .option('--agent <type>', 'Specific agent to update')
+  .action(updateSkill);
+
+// Update command - check for and install updates
+program
+  .command('update')
+  .description('Check for and install Cairn CLI updates')
+  .action(update);
+
+// Parse and handle errors
+program.parseAsync(process.argv).catch((error) => {
+  console.error(chalk.red('Error:'), error.message);
+  process.exit(1);
+});

package/bin/cairn.test.js

@@ -0,0 +1,26 @@
+import { describe, test, expect } from 'bun:test';
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+describe('CLI Executable', () => {
+  test('cairn.js exists and is executable', () => {
+    const cliPath = join(__dirname, 'cairn.js');
+    expect(existsSync(cliPath)).toBe(true);
+  });
+  
+  test('cairn.js has shebang', () => {
+    const cliPath = join(__dirname, 'cairn.js');
+    const content = require('fs').readFileSync(cliPath, 'utf-8');
+    expect(content.startsWith('#!/usr/bin/env node')).toBe(true);
+  });
+  
+  test('cairn.js imports commander', () => {
+    const cliPath = join(__dirname, 'cairn.js');
+    const content = require('fs').readFileSync(cliPath, 'utf-8');
+    expect(content).toContain('commander');
+  });
+});

package/lib/agents/claude-code.js

@@ -0,0 +1,91 @@
+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 Cairn for Claude Code
+ * Adds agent-skill.md to workspace context
+ */
+export async function setupClaudeCode(workspacePath) {
+  const cwd = process.cwd();
+  const contextDir = join(cwd, '.claude-code');
+  const skillTemplate = join(__dirname, '../../skills/agent-skill.template.md');
+  const skillDest = join(contextDir, 'cairn-skill.md');
+  
+  // Create context directory
+  if (!existsSync(contextDir)) {
+    mkdirSync(contextDir, { recursive: true });
+  }
+  
+  // Read template and replace workspace placeholders
+  let skillContent = readFileSync(skillTemplate, 'utf-8');
+  const workspaceRoot = dirname(workspacePath);
+  
+  skillContent = skillContent
+    .replace(/\{\{WORKSPACE_PATH\}\}/g, workspacePath)
+    .replace(/\{\{WORKSPACE_ROOT\}\}/g, workspaceRoot);
+  
+  // Write skill to workspace
+  writeFileSync(skillDest, skillContent);
+  console.log(chalk.green('✓'), 'Cairn skill added to Claude Code workspace');
+  
+  // Create instructions file
+  const instructionsPath = join(contextDir, 'cairn-instructions.md');
+  const instructions = `# Cairn Project Management
+
+This workspace uses Cairn for project management.
+
+**Workspace:** ${workspacePath}
+
+**Skill documentation:** Read \`cairn-skill.md\` in this directory for the complete workflow.
+
+**Key points:**
+- All project files are in markdown format at ${workspacePath}
+- Files are the source of truth (no database)
+- Follow the project → task hierarchy
+- Always update status before asking blocking questions
+- Log all work in the Work Log section
+
+Refer to cairn-skill.md for detailed instructions on working with Cairn files.
+`;
+  
+  writeFileSync(instructionsPath, instructions);
+  console.log(chalk.green('✓'), 'Cairn instructions added');
+  
+  return true;
+}
+
+/**
+ * Get setup instructions for Claude Code
+ */
+export function getClaudeCodeInstructions(workspacePath) {
+  return `
+${chalk.bold('Claude Code Setup Complete!')}
+
+Your Cairn workspace: ${chalk.cyan(workspacePath)}
+Context added at: ${chalk.cyan('.claude-code/')}
+
+${chalk.bold('Test it:')}
+Ask Claude Code:
+  ${chalk.yellow('"Read .claude-code/cairn-skill.md and help me create a project"')}
+
+${chalk.dim('Note: You may need to reload the workspace for changes to take effect.')}
+`;
+}
+
+/**
+ * Verify Claude Code setup
+ */
+export function verifyClaudeCode() {
+  const contextPath = join(process.cwd(), '.claude-code', 'cairn-skill.md');
+  
+  if (!existsSync(contextPath)) {
+    return { success: false, message: 'Cairn skill not found in workspace' };
+  }
+  
+  return { success: true, message: 'Claude Code setup verified' };
+}

package/lib/agents/clawdbot.js

@@ -0,0 +1,85 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+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 Cairn for Clawdbot
+ * Installs skill file from template (agent detects its own identity)
+ */
+export async function setupClawdbot(workspacePath) {
+  const clawdbotSkillsDir = join(homedir(), '.clawdbot', 'skills', 'cairn');
+  const skillTemplate = join(__dirname, '../../skills/agent-skill.template.md');
+  const skillDest = join(clawdbotSkillsDir, 'SKILL.md');
+  
+  // Create skills directory if it doesn't exist
+  if (!existsSync(clawdbotSkillsDir)) {
+    mkdirSync(clawdbotSkillsDir, { recursive: true });
+  }
+  
+  // Read template and replace workspace placeholders only
+  let skillContent = readFileSync(skillTemplate, 'utf-8');
+  
+  // Determine workspace root (parent of workspace path, e.g., /home/user from /home/user/cairn)
+  const workspaceRoot = dirname(workspacePath);
+  
+  // Replace workspace placeholders (agent will detect its own name)
+  skillContent = skillContent
+    .replace(/\{\{WORKSPACE_PATH\}\}/g, workspacePath)
+    .replace(/\{\{WORKSPACE_ROOT\}\}/g, workspaceRoot);
+  
+  // Write skill file
+  writeFileSync(skillDest, skillContent);
+  console.log(chalk.green('✓'), 'Cairn skill added to Clawdbot');
+  
+  // Create a config file with workspace path
+  const configPath = join(clawdbotSkillsDir, 'config.json');
+  const config = {
+    workspacePath,
+    version: '0.1.0',
+    installedAt: new Date().toISOString()
+  };
+  writeFileSync(configPath, JSON.stringify(config, null, 2));
+  
+  return true;
+}
+
+/**
+ * Get setup instructions for Clawdbot
+ */
+export function getClawdbotInstructions(workspacePath) {
+  return `
+${chalk.bold('Clawdbot Setup Complete!')}
+
+Your Cairn workspace: ${chalk.cyan(workspacePath)}
+Skill installed at: ${chalk.cyan('~/.clawdbot/skills/cairn/')}
+
+${chalk.bold('Test it:')}
+In your next Clawdbot session, try:
+  ${chalk.yellow('"Help me create a project called Launch My App"')}
+
+The skill will be automatically available in new sessions.
+`;
+}
+
+/**
+ * Verify Clawdbot setup
+ */
+export function verifyClawdbot() {
+  const clawdbotPath = join(homedir(), '.clawdbot');
+  const skillPath = join(clawdbotPath, 'skills', 'cairn', 'SKILL.md');
+  
+  if (!existsSync(clawdbotPath)) {
+    return { success: false, message: 'Clawdbot directory not found' };
+  }
+  
+  if (!existsSync(skillPath)) {
+    return { success: false, message: 'Cairn skill not installed' };
+  }
+  
+  return { success: true, message: 'Clawdbot setup verified' };
+}

package/lib/agents/cursor.js

@@ -0,0 +1,107 @@
+import { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync } 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 Cairn for Cursor
+ * Adds to .cursorrules or creates .cursor/ directory with skill
+ */
+export async function setupCursor(workspacePath) {
+  const cwd = process.cwd();
+  const cursorRulesPath = join(cwd, '.cursorrules');
+  const skillTemplate = join(__dirname, '../../skills/agent-skill.template.md');
+  
+  // Strategy 1: Add to .cursorrules if it exists
+  if (existsSync(cursorRulesPath)) {
+    const existing = readFileSync(cursorRulesPath, 'utf8');
+    const cairnRule = `
+
+# Cairn Project Management
+
+This project uses Cairn for project management.
+
+**Workspace:** ${workspacePath}
+
+When working with project management tasks:
+1. All files are in markdown format at ${workspacePath}
+2. Follow project → task hierarchy
+3. Update status before asking for blocking information
+4. Log all work with timestamps
+
+See .cursor/cairn-skill.md for complete workflow documentation.
+`;
+    
+    if (!existing.includes('Cairn Project Management')) {
+      writeFileSync(cursorRulesPath, existing + cairnRule);
+      console.log(chalk.green('✓'), 'Cairn rules added to .cursorrules');
+    } else {
+      console.log(chalk.yellow('⚠'), '.cursorrules already contains Cairn rules');
+    }
+  }
+  
+  // Strategy 2: Create .cursor/ directory with skill
+  const cursorDir = join(cwd, '.cursor');
+  if (!existsSync(cursorDir)) {
+    mkdirSync(cursorDir, { recursive: true });
+  }
+  
+  // Read template and replace workspace placeholders
+  let skillContent = readFileSync(skillTemplate, 'utf-8');
+  const workspaceRoot = dirname(workspacePath);
+  
+  skillContent = skillContent
+    .replace(/\{\{WORKSPACE_PATH\}\}/g, workspacePath)
+    .replace(/\{\{WORKSPACE_ROOT\}\}/g, workspaceRoot);
+  
+  const skillDest = join(cursorDir, 'cairn-skill.md');
+  writeFileSync(skillDest, skillContent);
+  console.log(chalk.green('✓'), 'Cairn skill added to .cursor/');
+  
+  // Create config
+  const configPath = join(cursorDir, 'cairn-config.json');
+  const config = {
+    workspacePath,
+    version: '0.1.0',
+    installedAt: new Date().toISOString()
+  };
+  writeFileSync(configPath, JSON.stringify(config, null, 2));
+  
+  return true;
+}
+
+/**
+ * Get setup instructions for Cursor
+ */
+export function getCursorInstructions(workspacePath) {
+  return `
+${chalk.bold('Cursor Setup Complete!')}
+
+Your Cairn workspace: ${chalk.cyan(workspacePath)}
+Configuration: ${chalk.cyan('.cursor/')} and ${chalk.cyan('.cursorrules')}
+
+${chalk.bold('Test it:')}
+Ask Cursor:
+  ${chalk.yellow('"Read .cursor/cairn-skill.md and help me create a project"')}
+
+${chalk.dim('Note: Cursor should automatically pick up .cursorrules on next prompt.')}
+`;
+}
+
+/**
+ * Verify Cursor setup
+ */
+export function verifyCursor() {
+  const cwd = process.cwd();
+  const rulesPath = join(cwd, '.cursorrules');
+  const skillPath = join(cwd, '.cursor', 'cairn-skill.md');
+  
+  if (!existsSync(rulesPath) && !existsSync(skillPath)) {
+    return { success: false, message: 'Cairn not configured for Cursor' };
+  }
+  
+  return { success: true, message: 'Cursor setup verified' };
+}

package/lib/agents/detect.js

@@ -0,0 +1,60 @@
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+/**
+ * Detect which AI agent(s) are available in the environment
+ * @returns {Object} { primary: string, detected: string[] }
+ */
+export function detectAgents() {
+  const detected = [];
+  
+  // Check for Clawdbot
+  const clawdbotPath = join(homedir(), '.clawdbot');
+  if (existsSync(clawdbotPath)) {
+    detected.push('clawdbot');
+  }
+  
+  // Check for Claude Code
+  // Claude Code typically sets environment variables or has workspace indicators
+  if (process.env.ANTHROPIC_API_KEY || process.env.CLAUDE_CODE_WORKSPACE) {
+    detected.push('claude-code');
+  }
+  
+  // Check for Cursor
+  // Cursor uses .cursorrules file or sets env variables
+  if (existsSync('.cursorrules') || process.env.CURSOR_WORKSPACE) {
+    detected.push('cursor');
+  }
+  
+  // Check for Windsurf
+  if (process.env.WINDSURF_WORKSPACE) {
+    detected.push('windsurf');
+  }
+  
+  // Determine primary agent (first detected, or generic)
+  const primary = detected[0] || 'generic';
+  
+  return { primary, detected };
+}
+
+/**
+ * Get agent display name
+ */
+export function getAgentName(type) {
+  const names = {
+    'clawdbot': 'Clawdbot',
+    'claude-code': 'Claude Code',
+    'cursor': 'Cursor',
+    'windsurf': 'Windsurf',
+    'generic': 'Generic AI Agent'
+  };
+  return names[type] || type;
+}
+
+/**
+ * Check if an agent type is supported
+ */
+export function isSupportedAgent(type) {
+  return ['clawdbot', 'claude-code', 'cursor', 'windsurf', 'generic'].includes(type);
+}