cairn

# Cairn — AI-Native Project Management

Cairn gives you and your AI agent a shared workspace of markdown files for managing projects and tasks. Statuses are the shared language. Any AI that can read files is ready to go.

## Installation

```bash
npm install -g cairn-work
cairn onboard
```

`cairn onboard` creates `~/cairn/` with auto-generated context files (`AGENTS.md` and `.cairn/planning.md`) that agents read automatically.

## Community

- Follow [@letcairnwork](https://x.com/letcairnwork) on X
- Visit [letcairn.work](https://letcairn.work/)
- [Submit issues](https://github.com/letcairnwork/cairn-cli/issues)
- [Join the discussion](https://github.com/letcairnwork/cairn-cli/discussions)

## Core Commands

### Workspace

- `cairn status` — Overview with task counts
- `cairn my` — Your assigned tasks
- `cairn active` — All in-progress tasks
- `cairn doctor` — Diagnose workspace health

### Projects & Tasks

- `cairn create project "Name" --description "..." --objective "..."` — Create a project with charter
- `cairn create task "Name" --project <slug> --description "..." --objective "..."` — Create a task
- `cairn list tasks [--status pending,in_progress] [--project slug]` — List tasks with filters
- `cairn search "keyword"` — Find tasks by content

### Task Workflow

- `cairn start <task-slug>` — Begin work (sets `in_progress`)
- `cairn note <task-slug> "Progress update"` — Add a status note
- `cairn artifact <task-slug> "Artifact Name"` — Create a linked deliverable
- `cairn done <task-slug>` — Finish work (moves to `review` or `completed`)
- `cairn block <task-slug> "Reason"` — Mark as blocked

### Maintenance

- `cairn update-skill` — Refresh context files after CLI updates
- `cairn upgrade` — Update CLI to latest version

## Workspace Structure

```
~/cairn/
  AGENTS.md                  # Agent context (auto-generated)
  .cairn/planning.md         # Planning guide (auto-generated)
  projects/
    project-slug/
      charter.md             # Why, success crite...

# Cairn

[![npm version](https://img.shields.io/npm/v/cairn-work.svg)](https://www.npmjs.com/package/cairn-work)
[![GitHub Discussions](https://img.shields.io/github/discussions/letcairnwork/cairn-cli)](https://github.com/letcairnwork/cairn-cli/discussions)
[![Follow @letcairnwork](https://img.shields.io/twitter/follow/letcairnwork?style=social)](https://x.com/letcairnwork)

Project management for AI agents. Markdown files are the source of truth.

## Setup

```bash
npm install -g cairn-work
cairn onboard
```

This creates a workspace and writes two context files your agent reads automatically:

- **`AGENTS.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

No agent-specific configuration. Any AI agent that can read files is ready to go.

## Quick Start

```bash
# See what you're working on
cairn my

# Start a task
cairn start implement-auth

# Add notes as you work
cairn note implement-auth "Using passport.js for OAuth"

# Create an artifact (deliverable document, code, etc.)
cairn artifact implement-auth "API Design Doc"

# Mark it done
cairn done implement-auth

# Check workspace status
cairn status
```

For complete command reference, see [COMMANDS.md](COMMANDS.md).

## How it works

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.

```
~/cairn/
  AGENTS.md                        # Agent context (auto-generated)
  .cairn/planning.md               # Planning guide (auto-generated)
  projects/
    launch-app/
      charter.md                   # Why, success criteria, context
      artifacts/                   # Project deliverables
        api-design.md
        test-plan.md
      tasks/
        setup-database.md          # Individual task
        build-api.md
        deploy.md
  inbox/...