Planning a BIG project. Too big for plan mode?
You need Masterplan.

In your editor

Your IDE has a plan inside the IDE. Open a second window with a different agent on the same project, two plans, not one. Open a third with a different provider, three plans, none aware of each other. Masterplan is the one plan all of them read from, claim from, and write back to. Same project, same plan, every agent.

What Masterplan does

Masterplan is an MCP tool that runs project work-tracking as a database-coordinated workflow. Plans persist across sessions in the local SQLite. Items have IDs, dependencies, statuses, assignee types, and a parent-child hierarchy (phase → sprint → task). The next action atomically claims the next available task, the database update happens in the same transaction that returns the item, so parallel agents never collide. Heartbeat leases auto-release abandoned claims. Completion auto-unblocks every dependent task. Bulk import takes a 200-item JSON plan and loads it in one call. Every change is on the append-only audit log, 15 distinct activity types, fully reconstructible months later.

How it actually works

A plan that lives inside one AI agent’s session vanishes the moment the conversation ends. A plan written into a Markdown file lives, but no AI agent can claim a task, mark progress, or know what another agent already did. Masterplan is what plan-mode wanted to be: a persistent, shared, cross-agent project plan that any AI agent on any session can read, claim from, update, and complete, and that the database guarantees nobody steps on each other while they work. Open Claude Code in one window, Gemini CLI in another, two more Codex sessions in two more terminals, and all four read the same plan, each claims a different task, none collide. This is the central coordination layer that turns "I have multiple AI agents" from a chaotic mess into actual parallel engineering throughput.

This is genuinely different from plan-mode. Plan-mode in any single AI harness is excellent at producing a plan, then dies. The plan is gone when the conversation ends. Even if you save it as Markdown, no other agent has a structured way to act on it, task IDs, dependency edges, claim state, completion tracking, audit trail, none of that exists in a .md file. Masterplan is a structured work-tracking layer with claim coordination baked in at the database level. The plan persists across sessions. Tasks have IDs you can pass to other tools (Port, Code Review). Dependencies are real edges in a graph, not paragraphs of prose. Claims are atomic. Completion auto-unblocks dependents. Activity is logged. This is the difference between "here is what we should do" (plan-mode) and "here is the system that runs the work" (Masterplan).

Masterplan does not care which AI provider an agent uses. Claude Code from Anthropic, Gemini CLI from Google, Codex CLI from OpenAI, any other MCP-speaking harness, all of them read the same masterplans and masterplan_items tables in your project’s local Twira database. Switching agents mid-task does not lose context. Claude Code claims task #142 on Monday, hits a corner of the problem better suited to Gemini’s reasoning, releases the claim, opens a Gemini session; Gemini claims #142, finishes it, marks it complete; and Claude Code on Wednesday picks up the dependent task #143 that was auto-unblocked when #142 closed. No reformatting, no copy-paste, no losing track of what the prior agent was doing.

Atomic claims are what make parallel sessions actually work. Pass claim: true to next and the call atomically claims the next available task. The database update happens in the same transaction that returns the item, so another session calling next at the exact same instant gets a different item, never the same one. Five sessions running twira masterplan next --claim true --session_id agent-A (B, C, D, E) in a loop work through a 200-item plan in roughly one-fifth the wall time. This guarantee is not best-effort; it is enforced by SQLite transaction semantics. Without atomic claiming this would be a coordination nightmare. With it, multi-agent project work is a single flag.

Heartbeat-backed leases mean crashed sessions do not block work. Every claim carries a lease_minutes (default 30, configurable per-item) and a last_heartbeat timestamp. The heartbeat refreshes on every update call. If an agent crashes, idles, or simply forgets the task, once last_heartbeat plus lease_minutes is in the past, the next call to next auto-reclaims the abandoned item and offers it to a fresh session. No manual cleanup, no permanently-blocked work, no "who has this task and where did they go?" archaeology.

The dependency graph moves on its own. Tasks can declare dependencies (depends_on: [42, 67, 89]). A task with unmet dependencies is blocked, not pending, and the next call skips it. When you complete a task, Twira walks every task that depended on it and checks whether all its dependencies are now met; if yes, that task auto-flips from blocked to pending and becomes claimable. Cascade unblocks fire transitively, so completing one foundational task can unblock a chain of dependent work in milliseconds. The dependency graph is not advisory; it is the live scheduler.

Fourteen actions cover the full work-coordination loop. Reading the plan goes through status (progress summary plus who-claimed-what and what-is-blocked-by-what), list (filter items by status, phase, assignee, parent), and list_plans (inventory of plans in the project). The work loop itself is next (get next available, optionally claim atomically), claim (claim a specific item by ID), update (log progress, refreshes heartbeat), complete (mark done, auto-unblocks dependents), defer (postpone with a reason), and release (give back a claim without completing). Authoring uses add (create one item with optional dependencies), import (bulk-load a JSON array, with depends_on_keys resolving to IDs at import time), and move (reparent in the hierarchy). Plan-level operations are create_plan (new named plan with owner and metadata) and archive_plan (close out a finished plan).

A plan models real work, not just abstract tasks. Each item has one of eleven item types: task (the default), port (links to Port workflows via port_scope), build, test, infra, phase (top-level grouping), sprint (mid-level grouping), milestone, manual (human-only), decision (an architectural call), and review. The type is not cosmetic; it drives filtering, defaults, and how other Twira tools react. A port-type item with port_scope: "set:billing-rebuild" is automatically linked to the corresponding Port discovery set, so agents working on that task get the Port context attached.

The work-state machine has six statuses and three assignee types. Statuses move from pending (the default, claimable once dependencies are met) to in_progress (claimed by someone) to completed. There are three escape hatches: deferred (postponed with a reason), blocked (dependencies unmet, auto-managed), and cancelled (explicit kill). Assignee types control claimability: ai (only AI agents can claim), human (only humans can claim), and either (the default). The human assignee type is the "do not let the agent decide this one" lever; pair it with a decision item type and you have a structured human-in-the-loop checkpoint.

The hierarchy is phase, sprint, task. Items have an optional parent_id, so a plan can model the real shape of the work: a phase containing several sprints, each containing several tasks. Status rolls up automatically, a phase is completed when all its sprints are; a sprint is completed when all its tasks are. The move action reparents items so the hierarchy stays clean as the plan evolves. List queries can filter by parent_id to get "every task under this sprint" in a single call.

Bulk import loads an entire plan from JSON in one call. The import action takes an array of items, each carrying its own item_key, title, description, phase, priority, item_type, depends_on_keys (referencing other items by key, resolved to IDs at import time), parent_key, arch_ref, port_scope, lease_minutes, and metadata. The whole plan is created in one transaction. Use this when you already have a structured plan, from a plan-review session, from a project-tracker export, from a hand-written YAML, and want to bring it in one shot.

The append-only audit log is the masterplan_updates table. Every modification writes one row, with the activity type one of fifteen: created, claimed, progress, note, completed, deferred, blocked, unblocked, released, cancelled, auto_progress, session_end, status_changed, assigned, or metadata_updated. Every row carries the session ID, session name, actor, timestamp, old and new values, the message, and which files were touched. A few months from now you can reconstruct exactly who claimed which task, when, what they wrote in their progress note, when they completed it, and what files they modified. A complete forensic trail.

Completion can surface context to the next agent. When you complete an item you can pass files_modified (a list of paths) and symbols_created (a list of names). The data lives in the metadata field, and the next agent working on a dependent task sees both, so they know which files have changed since the dependency was last checked, and which symbols are now available to reference. This is the small detail that prevents agents from rewriting what the prior agent just wrote.

Per-session delta push keeps every active agent informed without flooding the context. The masterplan_session_state table tracks each session’s last_seen_version (the highest masterplan_updates.id it has been shown). A pre-prompt hook, the dashboard, or any other consumer can ask "what changed since I last looked?" and get only the delta, no re-fetching the full plan every turn. With single-millisecond queries against an indexed column, it stays cheap to keep every active agent informed about what every other agent has just done.

Masterplan is the spine that ties the toolkit together. Items carry port_scope (linking a task to a Port discovery set), arch_ref (free-text reference to an architecture decision, doc, or RFC), and discovered_during (when a sub-task is discovered while executing another task, this records the parent so the relationship is preserved). The code-review skill creates a Masterplan item for every confirmed-but-deferred review finding, that no-deferral policy means every finding either gets fixed now or becomes a tracked task here. The plan-review skill writes its accepted modifications into Masterplan items. Masterplan is the work-tracker that the rest of the toolkit feeds into and reads from.

Tier is Pro. Masterplan is gated by the masterplan feature flag. The shared, cross-agent, claim-coordinated work-tracking surface is one of the most valuable Pro capabilities Twira ships, and the right hook for the Pro tier alongside Lore (cross-agent memory) and Team (cross-model collaboration).

Setup is zero. Masterplan is enabled on every Pro licence. No configuration required; the masterplan tables (masterplans, masterplan_items, masterplan_dependencies, masterplan_updates, masterplan_session_state) are created on first use in .Twira/sessions.db. The plan is project-local, every developer cloning the repo gets their own database unless you set up a sharing path. Most teams either commit a JSON snapshot for hand-off, or use the same masterplan from a shared filesystem for in-flight coordination.