cairn-work 0.7.1 → 0.7.2

package/README.md

@@ -1,241 +1,160 @@
-# Cairn 🦮
+# Cairn
 
-AI-native project management where markdown files are the source of truth.
+Project management for AI agents. Markdown files are the source of truth.
 
-## Quick Start
+## Setup
 
 ```bash
 npm install -g cairn-work
 cairn onboard
 ```
 
-That's it! Cairn will detect your AI agent (Clawdbot, Claude Code, Cursor, etc.) and configure everything automatically.
+This creates a workspace and writes two context files your agent reads automatically:
 
-## What is Cairn?
+- **`CLAUDE.md`** — Compact reference for day-to-day operations (statuses, CLI commands, autonomy rules)
+- **`.cairn/planning.md`** — Full guide for creating projects and tasks with real content
 
-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.
+No agent-specific configuration. Any AI agent that can read files is ready to go.
 
-**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
+## How it works
 
-## Installation
+You and your AI agent share a folder of markdown files. Projects have charters. Tasks have objectives. Status fields track where everything stands — like a kanban board backed by text files.
 
-### Global Install (Recommended)
-
-```bash
-npm install -g cairn-work
-# or
-bun install -g cairn-work
 ```
-
-### Test Locally
-
-```bash
-git clone https://github.com/gregoryehill/cairn-cli.git
-cd cairn-cli
-bun install
-bun link
+~/cairn/
+  CLAUDE.md                        # Agent context (auto-generated)
+  .cairn/planning.md               # Planning guide (auto-generated)
+  projects/
+    launch-app/
+      charter.md                   # Why, success criteria, context
+      tasks/
+        setup-database.md          # Individual task
+        build-api.md
+        deploy.md
+  inbox/                           # Ideas to triage
 ```
 
-## Commands
-
-### `cairn onboard`
+### The workflow
 
-Set up Cairn and configure your AI agent automatically.
+1. **You create a project** — tell your agent what you want to build. It creates the project and tasks using `cairn create`, fills in real content (not placeholders), and sets everything to `pending`.
 
-```bash
-cairn onboard                    # Auto-detect agent
-cairn onboard --agent clawdbot   # Specific agent
-cairn onboard --force            # Re-run onboarding
-```
+2. **You manage the board** — move tasks to `next_up` or `in_progress` when you're ready to start. Or tell your agent "work on the API task" and it picks it up.
 
-### `cairn init`
+3. **The agent keeps status updated** — when it starts a task, it moves to `in_progress`. When it finishes, it moves to `review` (so you can approve) or `completed` (if you gave it full autonomy). If it gets stuck, it moves to `blocked` and tells you what it needs.
 
-Initialize workspace without agent configuration.
+4. **You always know where things stand** — statuses are the shared language. The agent is accountable for keeping them accurate.
 
-```bash
-cairn init                # Create workspace in current directory
-cairn init --path /custom # Custom location
-```
+### Statuses
 
-### `cairn create`
+`pending` · `next_up` · `in_progress` · `review` · `blocked` · `completed`
 
-Create projects and tasks.
+### Autonomy
 
-```bash
-# Create a project
-cairn create project "Launch My App"
+Each task has an autonomy level that controls what the agent can do:
 
-# Create a task
-cairn create task "Set up database" \\
-  --project launch-my-app
-```
+| Level | Agent behavior | Finishes as |
+|-------|---------------|-------------|
+| `propose` | Plans the approach, doesn't do the work | `review` |
+| `draft` | Does the work, no irreversible actions | `review` |
+| `execute` | Does everything, including deploy/publish/send | `completed` |
 
-### `cairn doctor`
+Default is `draft` — the agent works but you approve before anything ships.
 
-Check workspace health and fix issues.
-
-```bash
-cairn doctor
-```
+## Commands
 
-### `cairn update-skill`
+### `cairn onboard`
 
-Update agent skill documentation.
+Set up workspace and write agent context files.
 
 ```bash
-cairn update-skill              # Update all detected agents
-cairn update-skill --agent cursor  # Specific agent
+cairn onboard                  # Interactive setup
+cairn onboard --path ./mywork  # Non-interactive, specific path
+cairn onboard --force          # Re-run on existing workspace
 ```
 
-### `cairn update`
+### `cairn create`
 
-Check for and install CLI updates.
+Create projects and tasks. Always pass real content — the CLI enforces `--description` and `--objective`.
 
 ```bash
-cairn update  # Check npm for latest version and prompt to upgrade
-```
+cairn create project "Launch App" \
+  --description "Ship the MVP by March" \
+  --objective "We need to validate the idea with real users" \
+  --criteria "App live on production, 10 beta signups" \
+  --context "React Native, Supabase backend, deploy to Vercel"
 
-## 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
+cairn create task "Set up database" \
+  --project launch-app \
+  --description "Configure Supabase tables and RLS policies" \
+  --objective "Database schema matches the data model, RLS prevents cross-tenant access"
 ```
 
-### 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*
-```
+### `cairn doctor`
 
-## Updates
+Check workspace health — verifies folder structure, `CLAUDE.md`, and `.cairn/planning.md` exist.
 
 ```bash
-cairn update
+cairn doctor
 ```
 
-Checks npm for the latest version and prompts to upgrade.
+### `cairn update-skill`
+
+Refresh `CLAUDE.md` and `.cairn/planning.md` with the latest templates (e.g. after a CLI update).
 
-Or update manually:
 ```bash
-npm update -g cairn
+cairn update-skill
 ```
 
-Updates only affect the CLI and agent skills. Your workspace files are never touched.
-
-## Configuration
+### `cairn update`
 
-Cairn uses sensible defaults:
-- **Workspace:** Current directory or `~/cairn`
-- **Agent detection:** Automatic
-- **Files:** Plain markdown with YAML frontmatter
+Check for a new CLI version and install it.
 
-Override workspace location:
 ```bash
-export CAIRN_WORKSPACE=/custom/path
+cairn update
 ```
 
-## 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
+## File format
 
-### Agent not detected
+All files use YAML frontmatter + markdown sections.
 
-```bash
-cairn doctor              # Check setup
-cairn onboard --force     # Re-run onboarding
-```
-
-### Workspace issues
+**Charter** (`charter.md`):
+```yaml
+---
+title: Launch App
+status: in_progress
+priority: 1
+default_autonomy: draft
+---
 
-```bash
-cairn doctor              # Auto-fix common issues
-cairn init --path ~/cairn  # Recreate structure
+## Why This Matters
+## Success Criteria
+## Context
+## Work Log
 ```
 
-### Skill not updating
+**Task** (`tasks/setup-database.md`):
+```yaml
+---
+title: Set up database
+assignee: agent-name
+status: pending
+autonomy: draft
+---
 
-```bash
-cairn update-skill        # Refresh agent skill
+## Objective
+## Work Log
 ```
 
-## Development
+The agent logs all work in the `## Work Log` section with timestamps and its name.
 
-```bash
-git clone https://github.com/gregoryehill/cairn-cli.git
-cd cairn-cli
-bun install
-bun link                  # Test locally
-```
+## Troubleshooting
 
-Run tests:
 ```bash
-bun test
+cairn doctor              # Diagnose issues
+cairn onboard --force     # Regenerate context files
+cairn update-skill        # Refresh templates after CLI update
 ```
 
-## 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
+MIT

package/package.json

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