DOCUMENTATION
Cartopian, in five sections.
Cartopian is a filesystem-first project governance protocol for AI-native development. These docs are intentionally minimal: what the protocol is, how a project is shaped, and where to look in the public tool repo when you want the source of truth.
What is Cartopian
Cartopian is a protocol for governing software projects between humans and AI agents. It treats the filesystem as the source of truth: every phase, task, spec, decision, and review is a plain markdown file in a known directory. The protocol does not depend on a database, a SaaS service, or a particular AI tool. It runs on whatever editor, shell, and agent you already use.
The point of writing all this down is durable memory. A conversation window scrolls away; a requirements.md file does not. When you bring a new agent into a project — or come back to it yourself a month later — the protocol gives you a walk-up-and-read account of what was decided and why.
Project structure and lifecycle
A Cartopian project is a directory. At its root sit the project-level documents — requirements, engineering standards, the active implementation plan, and a small state file. Below those, work decomposes into phases, and each phase opens tasks under tasks/open/. As a task moves, its file moves with it, from open/ to in-progress/ to in-review/ to done/. The directory is the status; there is no separate field to keep in sync.
Reviews record verdicts on tasks. Decisions capture why a particular path was chosen and are immutable — superseding a decision means writing a new one, not editing the old one. Specs are the single-file contracts a task is built against. Naming is load-bearing throughout: phase-scoped prefixes (PHASE-NN, TASK-NN-NNN) form a trace chain from the implementation plan all the way down to the smallest review.
Templates
Cartopian ships a default set of templates for the artifacts the protocol asks you to author: tasks, specs, prompts, reviews, reports, decisions, requirements, engineering standards, implementation plans, and plan closeouts. They are starting points, not rigid forms — every project should adapt them to its own shape.
What templates do guarantee is that the same kinds of files look the same across projects. An agent that has worked on one Cartopian project can pick up a task file in a different one and immediately know where to find the goal, the acceptance criteria, the dependencies, and the test gate.
Skills (guided workflows)
Skills are agent-executable guided workflows. They give an AI agent a deterministic procedure for the routine moves a project makes — running a task, opening a review, closing a phase, resetting a plan. Each skill is its own markdown file under skills/, and the workflow is documented inside the file itself.
Skills are invoked by natural-language name. The name is derived from the skill's filename at runtime: run-task.md becomes run task, init-project.md becomes init project. That mapping is dynamic, not a maintained list, so adding a new skill is just adding a new file. Skills are how the protocol stays consistent across different agents and different operators — the same workflow runs the same way.
Configuration
Each Cartopian project is configured by a cartopian.toml file at its root, with optional defaults at the workspace level. Configuration covers role assignments, CLI handoff targets for those roles, and per-project Git behaviour. Git itself is optional and is controlled by a flag in the same file.
Roles describe kind, not tool names. The four basic roles — PM, Operator, Coder, Reviewer — take values like human, agent, or none. Which CLI an agent role hands off to is configured separately under [handoffs.*]. The same agent can serve multiple roles, and the same role can be served by a different agent on a different project, without changing the protocol or the templates.