dotproject

Conflict-free, Git-native project tracking in plain JSON files.
Zero infrastructure. Built for concurrent autonomous agents.

Many workers, no coordinator. The comb is built one cell at a time, and no two bees need the same cell.

Your project's state lives in .project/ next to your code. Agents on parallel branches claim tasks, record progress, and verify work — and any merge of any two branches succeeds, because no two writers ever touch the same bytes.

The claim, stated precisely

• At the git layer: definition files are write-once, and every change after that is a new file named by ULID + actor. Two writers never produce the same path, so git merge never conflicts on .project/.
• At the semantic layer: conflicts aren't hidden, they're reported. Every event records what its author had seen (observed_through); when two writers change the same field concurrently, materialization still yields one deterministic answer — and names the divergence, both events, and both actors.

60-second quickstart

.project/
  project.json                  # manifest
  goals/G-off42.json            # why   — strategic targets
  milestones/M-alpha7.json      # when  — release epochs
  tasks/T-syn9b.json            # what  — execution + verification
  events/01JAR…__agent-a__T-syn9b__claimed.json   # append-only history
  snapshots/M-alpha7.01JAR….snapshot.json         # optional compaction

1. Create project.json and definition files for a goal, a milestone, and some tasks. Definition files are never edited again.
2. To change anything, append one event file: events/<ULID>__<you>__<entity>__<action>.json with a changes map.
3. Current state = fold all events over the definitions, in ULID order. Deterministic; any reader gets the same answer. See SPEC.md §6.

No install. No daemon. No dependency. A worked example lives in examples/sample-repo/ with its exact expected state in EXPECTED-STATE.md.

For agents

The dotproject skill teaches any coding agent the execution loop:

Discover (materialize state) → Claim (append event) → Work (only within the task's context_files) → Verify (run verification.command) → Emit (record the result).

It assumes only read-file, write-file, and list-files — no shell, no tool coupling. Install as a plugin (Claude Code, Codex, Cursor, Antigravity) or point any harness that reads AGENTS.md at this repo.

Planned follow-on skills over the same format: bootstrap (turn a spec or conversation into an initial .project/ tree), report (summarize state for a human), merge review (post-merge divergence report), close milestone (write the snapshot).

Installation

Claude Code

Add the marketplace and install the plugin:

# Add marketplace
claude plugin marketplace add jasonnam/dotproject

# Install plugin
claude plugin install dotproject

Or load directly from a local clone during development:

claude --plugin-dir /path/to/dotproject

Cursor

Install dotproject via plugin settings, or copy skills/dotproject/ into your workspace skills directory.

Codex / Antigravity / Other Harnesses

• Point your agent harness at skills/dotproject/SKILL.md.
• Or copy the skills/dotproject folder into your harness's active skills directory.

Initializing a Repository

To use dotproject in your own repository:

1. Create the .project/ directory tree:

   mkdir -p .project/{goals,milestones,tasks,events,snapshots}
   

2. Create .project/project.json:

   {
     "spec_version": "0.1.0",
     "id": "P-myproj",
     "name": "My Project",
     "status_vocabulary": {
       "statuses": ["pending", "claimed", "in_progress", "blocked", "completed", "cancelled"],
       "terminal": ["completed", "cancelled"]
     },
     "extensions": [],
     "meta": {}
   }
   

3. Add a pointer in your project's AGENTS.md or CLAUDE.md:

   **Working with a `.project/` tree?** Read and follow `skills/dotproject/SKILL.md`.
   

Viewer

viewers/web/index.html — open it in any browser and point it at a .project/ folder. No install, no server, no build; it reads the folder and renders the board, the depends_on graph, the event trail, and the divergence report. Nothing is written to disk.

It is a reference implementation, not the spec — but it is also the format's second independent materializer, and it reproduces examples/sample-repo/EXPECTED-STATE.md exactly. If it and SPEC.md ever disagree, the viewer is wrong.

When not to use this

Honesty over adoption:

• Solo human, linear work? Use a markdown checklist. dotproject's read path (definitions + event folds) costs more than TODO.md and pays off only when you have concurrent writers.
• Need hard enforcement? The verification gate is a trust-and-audit model — the format records commands and exit codes but cannot stop a writer from lying. Enforcement is a CI check consuming the same files.
• Need instant cross-team sync? State propagates when git merges. If you need sub-second shared state, you need a service, not files.

dotproject earns its overhead when three things are true at once: concurrent writers, state that must live in the repo, and an audit trail you can git log.

Spec

The full specification — entity model, materialization algorithm, claim protocol, divergence reporting, snapshots, extension points — is in SPEC.md. JSON Schemas are in schemas/.

License

MIT