Your first Cartopian project

Before you start

You need an AI coding agent — Claude Code, Codex, Gemini, Devin, or anything similar — and a way to talk to it. IDE integrations, desktop apps, and terminal sessions all work; Cartopian doesn't care which one you pick. The agent is the software you run. Cartopian is the substrate it runs on: a directory of templates, skills, and conventions that the agent uses to turn a conversation about software into structured project state on disk.

The tutorial uses a tiny fictional project called hello-cartopian whose only deliverable is a README.md describing what the tool would do. The point is to see the protocol move, not to ship software — so when the project plan looks comically small, that's the point.

Open the workspace

A Cartopian workspace is just a directory. It holds the protocol baseline (protocol/CONVENTIONS.md), the default templates (templates/), the agent-executable skills (skills/), optional CLI wrappers (wrappers/), and a projects/ subdirectory where each project lives in its own folder.

Get one by cloning the public repository:

git clone https://github.com/fidensa/cartopian.git
cd cartopian

Open that directory in whatever you use to talk to your agent and ask the agent to init workspace if a top-level cartopian.toml doesn't already exist. The skill walks you through default role assignments, CLI handoff targets, automation policy, and a Git flag, then writes the file. From here on, you ask your agent for outcomes — initialize a project, plan it, run a task — and the agent picks the right skill. You don't type skill names anywhere yourself.

Initialize a project

Ask your agent to initialize a Cartopian project named hello-cartopian. The agent runs init project, asks you a few questions interactively (project name, kebab-case ID, any role or handoff overrides, automation overrides), and writes a fresh project directory.

projects/hello-cartopian/
├── STATE.md
├── cartopian.toml
├── CONVENTIONS.md
├── ENGINEERING.md
├── decisions/
│   └── INDEX.md
├── phases/
├── prompts/
├── reports/
├── reviews/
├── specs/
└── tasks/
    ├── open/
    ├── in-progress/
    ├── in-review/
    └── done/

Two things worth noticing on disk. First, every project is just a directory — no database, no sidecar service, nothing to keep in sync between Cartopian and the world. Second, the four task states (open/, in-progress/, in-review/, done/) are themselves directories. As a task moves, its file moves with it. There is no status: field anywhere.

Sketch a plan

Ask your agent to plan hello-cartopian. The PM runs plan project, a real conversation about what the project is, who it's for, what it must do, and what's deferred. Out of that conversation the skill writes:

• REQUIREMENTS.md — what you said you wanted.
• ENGINEERING.md — technical standards distilled from the conversation.
• IMPLEMENTATION_PLAN.md — the work decomposed into phases and plan refs.
• phases/PHASE-NN-slug.md — one rollup file per phase.
• tasks/open/TASK-NN-NNN-slug.md — tasks for the active phase, ready to run.

For hello-cartopian, the plan is intentionally trivial: one phase, one build item.

## Phase sequence

### Phase 00: Bootstrap

| Plan ref | Kind | Description |
|---|---|---|
| P00-BUILD-001 | build | Write a README.md describing what the tool would do |

If your requirements already live somewhere else — a JIRA story, a Confluence document, a PRD, a slide deck — ask your agent to use adopt requirements instead of starting a fresh conversation. If you have a structured plan to bring in too, adopt plan handles that path. Cartopian doesn't insist you start from blank.

Run a task

Ask your agent to run the next open task on hello-cartopian. The PM runs run task, and three things start happening that you can watch in your editor's file tree or your git panel:

1. The task file TASK-00-001-write-readme.md moves from tasks/open/ to tasks/in-progress/. Status is the directory.
2. The PM writes a coder prompt under prompts/ with everything the assignee needs — absolute paths, context, acceptance criteria, scope boundaries.
3. The PM hands the prompt to whichever coder is configured for this project. That can be the same agent acting in a coder role, a different agent invoked via a wrapper, or you yourself if you'd rather drive the implementation by hand.

The coder writes the README, then drops a completion report in reports/. The PM reads it, moves the task to tasks/in-review/, and hands a fresh prompt to the reviewer.

Close the loop

The reviewer reads the task, the spec (if any), and the diff, then writes a verdict — approve, request-changes, or blocked — to reviews/REVIEW-NN-NNN.md. On approve the PM moves the task to tasks/done/ and updates STATE.md. On request-changes the task goes back to tasks/in-progress/ for another round.

For hello-cartopian, that one task closes the whole plan. Ask your agent to close the plan. The PM runs close plan, optionally archives the finished plan, and resets the project surface — requirements, plan, phases, tasks, specs, reviews, decisions, prompts, reports — back to a clean slate ready for the next planning conversation. cartopian.toml is preserved across the reset; engineering standards and project conventions can carry forward at your discretion. Decisions are immutable within their plan and live in the archive after closeout if you ask for one. The project itself is long-lived; plans inside it are not.