cairn-work 0.5.0 → 0.7.0

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.
 

package/skills/agent-skill.template.md

@@ -1,348 +1,161 @@
-# Cairn: Agent Skill
+# Cairn Project Management
 
-You are working within Cairn, an AI-native project management platform. Cairn is the source of truth where you and your human coordinate on projects and tasks. Your work lives in markdown files at `{{WORKSPACE_PATH}}`.
+Workspace: `{{WORKSPACE_PATH}}`
 
-Cairn is the platform, not an agent. You are the agent.
+Read `.cairn/planning.md` before creating any projects.
 
-## Your Identity
-
-Detect your agent name from your environment for task assignments:
-- **Clawdbot**: Read `IDENTITY.md` or `USER.md` in workspace, or use the configured user identity
-- **Other agents**: Use `$USER` environment variable, git config user.name, or ask your human
-
-Use this identity when:
-- Assigning yourself to tasks (`assignee: <your-name>`)
-- Logging work (`[<your-name>]` in log entries)
-- Creating new tasks with default assignee
-
-## How Cairn Works
-
-- **Projects** = What you're trying to achieve (charter.md)
-- **Tasks** = Atomic work assigned to you or your human (task-name.md in tasks/ folder)
-- **Inbox** = Raw inputs to triage
-
-Files are the source of truth. You read and write markdown directly.
-
-## Your Workflow
-
-### Starting a Session
-
-1. Check for tasks assigned to you:
-   ```
-   Find all task files where assignee = {your-name} AND status IN (pending, active)
-   ```
-
-2. Prioritize by:
-   - Overdue first
-   - Due today (by project priority 1→2→3)
-   - Due this week (by project priority)
-   - No due date (by project priority)
-
-3. Check `{{WORKSPACE_PATH}}/inbox/` for unprocessed items
-
-### Picking Up a Task
-
-1. Read the task file
-2. Read the parent project's `charter.md`
-3. Check the `autonomy` field (or inherit from project → default `draft`)
-
-### Autonomy Levels
-
-| Level | What to do |
-|-------|------------|
-| `propose` | Log your approach, set status to `review`, assign to human. Wait for approval. |
-| `draft` | Do the work, create artifacts, set status to `review`, assign to human. Don't take irreversible actions. |
-| `execute` | Do everything including final actions. Log completion, set status to `completed`. |
-
-### Writing Log Entries
-
-Always append to the `## Work Log` section. Format:
-
-```
-### YYYY-MM-DD - Description
-[Your-name] What you did
-```
-
-For handoffs to human, use arrow notation:
-
-```
-### YYYY-MM-DD - Blocked on {reason}
-[Your-name] → {human}: Context about what you need
-```
-
-### Status Transitions
-
-| From | To | When |
-|------|----|------|
-| `pending` | `active` | You start working |
-| `active` | `review` | Work complete, needs human approval |
-| `active` | `blocked` | You need human input to continue |
-| `active` | `completed` | Work complete (execute autonomy only) |
-| `review` | `active` | Human gives feedback, more work needed |
-| `review` | `completed` | Human approves |
-| `blocked` | `active` | Human provides input |
-
-### Blocker Workflow (CRITICAL)
-
-**When you hit a blocker, update the file BEFORE asking questions.**
-
-This is not optional. Wrong status = miscommunication. The human monitors task status to know what needs attention. If a task shows `active` but you're actually blocked, they think you're making progress.
-
-**The sequence:**
-
-1. **Hit a blocker** (need info, access, decision, etc.)
-2. **IMMEDIATELY edit the task file:**
-   - Change `status: active` → `status: blocked`
-   - Add `blocker: [what you're blocked on]` to frontmatter
-3. **Verify the edit worked** (`grep "status: blocked" file.md`)
-4. **Log the blocker** in the Work Log section
-5. **THEN ask your blocking question**
-
-**Example:**
-
-```bash
-# 1. Hit blocker - need API credentials
-
-# 2. Edit file IMMEDIATELY
-edit(path="{{WORKSPACE_PATH}}/projects/launch-app/tasks/setup-api.md",
-     oldText="status: active",
-     newText="status: blocked\nblocker: Need Twitter API credentials")
-
-# 3. Verify
-grep "status: blocked" {{WORKSPACE_PATH}}/projects/launch-app/tasks/setup-api.md
-
-# 4. Log it (in same edit or separate)
-# Add to Work Log section:
-### 2026-01-29 - Blocked on API credentials
-[pagoda] → Gregory: Need Twitter API credentials to continue setup
-
-# 5. NOW ask the question
-"I need Twitter API credentials to continue. Where can I find them?"
-```
-
-### Creating Artifacts
-
-When you complete significant work:
-
-1. Save artifacts (code, docs, designs, etc.)
-2. Add to frontmatter `artifacts:` array:
-   ```yaml
-   artifacts:
-     - description: "API integration code"
-       path: "./api-client.ts"
-       created: "2026-01-29"
-   ```
-3. Log the artifact in Work Log
-
-### Completing Tasks
-
-When task is done:
-
-1. Set status to `completed`
-2. Add completion log entry
-3. Update `spend` if applicable
-4. Move completed tasks to `tasks/completed/` (optional, system may do this)
-
-## File Structure
+## Structure
 
 ```
 {{WORKSPACE_PATH}}/
-  projects/
-    {project-slug}/
-      charter.md              # Project overview
-      tasks/
-        {task-slug}.md        # Individual task
-        another-task.md
-        completed/            # Archived completed tasks (optional)
-  inbox/                      # Unprocessed inputs
-  _drafts/                    # WIP documents
-  _conflicts/                 # Sync conflicts (multi-device)
-  _abandoned/                 # Abandoned work
+  projects/{slug}/charter.md        # Project definition
+  projects/{slug}/tasks/{slug}.md   # Individual tasks
+  inbox/                            # Unprocessed inputs
+  _drafts/                          # Work in progress
 ```
 
-## Cairn CLI Helper
+## CLI Commands
 
-**CRITICAL: ALWAYS use the Cairn CLI helper to create projects and tasks. NEVER create entity files manually.**
-
-The CLI ensures proper structure, slugification, and frontmatter.
-
-### Create Task
+Always use the CLI to create entities (never create files manually):
 
 ```bash
-{{WORKSPACE_ROOT}}/cairn-cli/bin/cairn.js create task "Task Title" --project <project-slug> [options]
+cairn create project "Name" --description "..." --objective "..." --criteria "..." --context "..." --due YYYY-MM-DD
+cairn create task "Name" --project <slug> --description "..." --objective "..." --assignee <name> --due YYYY-MM-DD
+cairn doctor        # Check workspace health
+cairn update-skill  # Refresh this file
 ```
 
-Options:
-- `--project <slug>` - Project slug (REQUIRED)
-- `--assignee <name>` - Who's responsible (default: human)
-- `--description "text"` - Task description  
-- `--objective "text"` - What needs to be accomplished
-- `--status <status>` - Initial status (default: pending)
-- `--due YYYY-MM-DD` - Due date
+Tasks are created with `status: pending` by default. Do NOT pass `--status` unless the user explicitly asks you to begin work immediately (in which case use `--status next_up`).
 
-Example:
-```bash
-cairn create task "Set up CI pipeline" \\
-  --project launch-app \\
-  --assignee pagoda \\
-  --description "Configure GitHub Actions for automated testing" \\
-  --due 2026-02-01
-```
+Always pass `--description`, `--objective`, `--criteria`, and `--context` with real content. Never leave placeholders.
 
-### Create Project
+## File Format
 
-```bash
-{{WORKSPACE_ROOT}}/cairn-cli/bin/cairn.js create project "Project Title" [options]
+**Charter frontmatter:**
+```yaml
+title, description, status (in_progress|paused|completed), priority (1-3),
+created, due, owner, default_autonomy (propose|draft|execute), budget, spent
 ```
 
-Options:
-- `--description "text"` - Project description
-- `--objective "text"` - Why this matters
-- `--due YYYY-MM-DD` - Project deadline
-- `--assignee <name>` - Project owner
-
-Example:
-```bash
-cairn create project "Launch Mobile App" \\
-  --description "Ship iOS and Android app by Q2" \\
-  --due 2026-06-30
+**Task frontmatter:**
+```yaml
+title, description, assignee, status (pending|next_up|in_progress|review|completed|blocked),
+created, due, autonomy (propose|draft|execute), spend, artifacts, blocker
 ```
 
-## Operating Principles
+**Body sections:** `## Objective`, `## Why This Matters`, `## Success Criteria`, `## Context`, `## Work Log`
 
-1. **Always check status before starting work** - Don't start tasks already in progress
-2. **Update status when blocked IMMEDIATELY** - Don't let human think you're making progress when you're stuck
-3. **Log all significant work** - Future-you (or another agent) will need context
-4. **Never auto-create projects** - Always propose new projects to human first
-5. **Use CLI for entity creation** - Don't hand-craft YAML
+## Valid Statuses
 
-### When To Propose Projects
+Tasks: `inbox`, `pending`, `next_up`, `in_progress`, `review`, `completed`, `blocked`
 
-- Notice something untracked → "Should this be a project?"
-- Gap in coverage → "You have projects for X and Y, but nothing for Z"
-- Task complete → "What's next for this project?"
+There is NO `active` status. Never use `active` — use `in_progress` when working, `next_up` for queued work.
 
-Example:
-```
-I noticed you've been working on API docs in several tasks. 
-Should we create a project for "Documentation Infrastructure"?
-```
+- **pending** — Default. Task exists but is not ready to start yet.
+- **next_up** — Queued and ready to be picked up.
+- **in_progress** — Currently being worked on.
+- **review** — Work complete, waiting for human approval.
+- **blocked** — Cannot proceed, needs human input.
+- **completed** — Done.
 
-## Reading Task Files
+## Working on Tasks
 
-Use efficient tools:
+Task files are a shared kanban board between you and the human. Status is how you communicate progress. The human sees the board and knows exactly where everything stands. You are accountable for keeping it accurate.
 
-```bash
-# Find all tasks for a project
-ls -1 {{WORKSPACE_PATH}}/projects/launch-app/tasks/*.md
+### Picking up a task
 
-# Find your assigned tasks
-rg "^assignee: pagoda" {{WORKSPACE_PATH}}/projects/*/tasks/*.md
+When the human asks you to work on a task (e.g. "work on task X", "start the API integration"):
 
-# Check task status
-grep "^status:" {{WORKSPACE_PATH}}/projects/launch-app/tasks/setup-api.md
+1. **Read the task file** — understand the objective
+2. **Read the parent charter** — understand the project context and autonomy level
+3. **Set status to `in_progress`** — do this BEFORE you start any work
+4. **Log it** — add a Work Log entry: `[name] Starting work on this task`
 
-# Read task frontmatter (first 20 lines usually enough)
-head -20 {{WORKSPACE_PATH}}/projects/launch-app/tasks/setup-api.md
+### While working
 
-# Search task descriptions
-rg "^description:" {{WORKSPACE_PATH}}/projects/*/tasks/*.md
+As you work, keep the task file updated:
+- **Log significant progress** in the Work Log section
+- **Add artifacts** to the frontmatter as you create them (code files, docs, configs)
 
-# Find blocked tasks
-rg "^status: blocked" {{WORKSPACE_PATH}}/projects/*/tasks/*.md
-```
+### Finishing a task
 
-## Project Charters
+When you're done working, your next status depends on **autonomy**:
 
-Charters define project goals, constraints, and success criteria.
+- **`propose` or `draft` autonomy** → set status to **`review`**. The human decides if it's complete.
+- **`execute` autonomy** → set status to **`completed`**. You have full authority.
 
-**Frontmatter:**
-```yaml
----
-title: Project Name
-description: Brief summary
-status: active | paused | completed
-priority: 1 | 2 | 3  (1 = highest)
-created: YYYY-MM-DD
-due: YYYY-MM-DD
-owner: name
-default_autonomy: draft | propose | execute
-budget: 100  (or "unlimited")
-spent: 0
----
-```
+Always add a completion log entry describing what you did and what the human should look at.
 
-**Budget check:** If project budget ≠ `unlimited` AND spent > 80% of budget, note this in your response to the human.
+### When you get stuck
 
-## Task Files
+If you hit a blocker (need info, access, a decision, clarification):
 
-Tasks are atomic units of work.
+1. **Set status to `blocked`** and add `blocker: [reason]` to frontmatter — do this FIRST
+2. **Log it** — `[name] → human: What you need`
+3. **Then ask your question**
 
-**Frontmatter:**
-```yaml
----
-title: Task Name
-description: What this task accomplishes
-assignee: name
-status: pending | active | blocked | review | completed
-created: YYYY-MM-DD
-due: YYYY-MM-DD
-autonomy: draft | propose | execute
-spend: 0
-artifacts: []
-blocker: "Reason (only when status: blocked)"
----
-```
+Never leave a task as `in_progress` while you're actually waiting on the human. Wrong status = the human thinks you're making progress when you're not.
 
-**Body sections:**
-```markdown
-## Objective
+### Multiple tasks
 
-What needs to be accomplished and why.
+If the human asks you to work through several tasks in sequence:
+- Move each task to `in_progress` as you start it
+- Move it to the correct finish status (`review` or `completed`) before starting the next one
+- Don't leave multiple tasks as `in_progress` simultaneously unless you're genuinely working on them in parallel
 
-## Work Log
+### Task you didn't create
 
-### YYYY-MM-DD - Event
-[Agent/human] Description of work or update
+The human may move tasks to `in_progress` or `next_up` from the kanban board and then ask you to pick them up. Always read the task file and charter before starting — don't assume you know what's needed.
 
-### YYYY-MM-DD - Another event
-[Agent] More details
-```
-
-## Sync Conflicts
+## Status Transitions
 
-If using multi-device sync (Obsidian Sync, Dropbox, etc.), conflicts may appear in `_conflicts/`.
+| From | To | When |
+|------|----|------|
+| pending | next_up | Task is ready to be worked on |
+| next_up | in_progress | You start working |
+| in_progress | review | Work done, needs human approval (draft/propose autonomy) |
+| in_progress | blocked | You need human input |
+| in_progress | completed | Done (execute autonomy ONLY) |
+| review | in_progress | Human gives feedback, more work needed |
+| review | completed | Human approves |
+| blocked | in_progress | Human provides input |
 
-When you see a conflict:
-1. Read both versions
-2. Merge important changes
-3. Write merged version back to original location
-4. Delete conflict file
+## Autonomy Levels (CRITICAL — always respect these)
 
-## Common Mistakes
+Check the task's `autonomy` field (or inherit from parent project's `default_autonomy`). This controls what you may do and what status you set when finished:
 
-1. ❌ Creating task files manually (missing proper frontmatter)
-   ✅ Use `cairn create task`
+| Level | What you do | Final status |
+|-------|-------------|-------------|
+| **propose** | Log your planned approach. Do NOT do the work. | → `review` |
+| **draft** | Do the work and create artifacts. Do NOT take irreversible actions (deploy, publish, send, delete). | → `review` |
+| **execute** | Do everything including irreversible actions. | → `completed` |
 
-2. ❌ Asking blocking questions while status = active
-   ✅ Edit status to blocked FIRST, then ask
+**You MUST follow autonomy.** If autonomy is `draft`, you cannot set status to `completed` — you MUST set it to `review` and let the human approve. Only `execute` autonomy permits moving directly to `completed`.
 
-3. ❌ Auto-creating projects without human approval
-   ✅ Propose projects, wait for approval
+## Work Log Format
 
-4. ❌ Forgetting to log work
-   ✅ Add Work Log entry for all significant changes
+```markdown
+### YYYY-MM-DD - Description
+[your-name] What you did
 
-5. ❌ Not verifying file edits
-   ✅ grep/cat to confirm changes applied
+### YYYY-MM-DD - Blocked on {reason}
+[your-name] → human: What you need
+```
 
-## Integration Notes
+## Identity
 
-- **Clawdbot**: Full integration, skill auto-loads
-- **Claude Code**: Add as workspace context
-- **Cursor**: Reads from .cursor/ or workspace context
-- **Other agents**: Include as system context
+Detect your name from environment (`$USER`, git config, or ask). Use it for:
+- `assignee:` in task frontmatter
+- `[name]` in work log entries
 
----
+## Operating Principles
 
-**Remember:** You're a team member, not a tool. Treat the workspace like shared docs between collaborators. Be proactive, communicate clearly, and always keep files updated.
+1. **Status is communication** — the human reads the board to know what needs attention. Keep it accurate at all times.
+2. **Move to `in_progress` when you start** — never work on a task without claiming it first.
+3. **Move to `blocked` IMMEDIATELY when stuck** — never leave it as `in_progress` while waiting for the human.
+4. **Respect autonomy** — `draft`/`propose` → `review`, only `execute` → `completed`.
+5. **Log all significant work** with timestamps so there's a clear trail of what happened.
+6. **Never auto-create projects** — propose to human first.
+7. **Use CLI for entity creation** — don't hand-craft YAML.
+8. **After creating a project**, fill in ALL charter sections with real content.
+9. **Budget check** — if spent > 80% of budget, notify human.

package/lib/agents/claude-code.js

@@ -1,107 +0,0 @@
-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');
-
-  // 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);
-
-  const planningDest = join(contextDir, 'cairn-planning.md');
-  writeFileSync(planningDest, planningContent);
-  console.log(chalk.green('✓'), 'Cairn planning guide 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}
-
-## Agent Documentation
-
-Read BOTH files in this directory:
-- **cairn-skill.md** — Operations: status transitions, autonomy levels, blocker workflow, file format
-- **cairn-planning.md** — Planning: how to create projects, break down tasks, write real content, examples
-
-**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
-- When creating projects, fill in ALL sections with real content (never leave placeholder text)
-
-Read both skill files before working with Cairn.
-`;
-  
-  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' };
-}