A small, local-first control plane for agent-driven software work.
plans keeps implementation plans outside source repositories and gives them a simple lifecycle,
typed metadata, deterministic validation, and a machine-readable interface for execution tools.
It does not run coding agents itself. Execution is intentionally kept separate.
Coding agents are good at implementing scoped tasks, but the surrounding workflow still needs structure:
- what should be implemented;
- which repository owns the work;
- whether the task is ready for implementation;
- what state the work is currently in;
- what other plans it depends on;
- what was actually implemented and verified.
Keeping this state only in chat sessions, issue trackers, or individual repositories makes it difficult to build a consistent workflow across multiple repositories and agent harnesses.
plans provides a small filesystem-based layer for that state.
The system is split into two responsibilities:
plans
planning / control plane
│
│ plan inspect --json
▼
execution layer
│
▼
coding agent
│
▼
target repository
plans owns:
- plan creation;
- typed metadata;
- validation and readiness;
- lifecycle transitions;
- machine-readable plan inspection.
The execution layer owns:
- repository checkout resolution;
- workspace preparation;
- harness selection;
- provider and model selection;
- agent invocation;
- process and session management.
This separation keeps plans independent from a particular agent, model, machine, or repository checkout layout.
Plans move through:
drafts → next → open → done
│ │ │
└───────┴──────┴──→ discarded
| State | Meaning |
|---|---|
drafts |
The plan is still being designed. Open questions and incomplete sections are allowed. |
next |
The plan is implementation-ready and contains no unresolved design questions. |
open |
Implementation has started. |
done |
Completion criteria and deterministic result gates have passed. |
discarded |
The plan was intentionally abandoned or discarded. |
The allowed transitions are drafts -> next, next -> open, and any of drafts, next, or open
to discarded. done and discarded are terminal. The only open -> done operation is
plan complete; the generic transition command rejects that move.
Readiness is intentionally separate from execution. Moving a plan to next means an implementation
agent should be able to start work without redesigning the task first.
Plan state is stored separately from this repository.
Set:
export PLANS_HOME="$HOME/Projects/plans-data"A typical layout is:
$PLANS_HOME/
├── plans/
│ ├── drafts/
│ ├── next/
│ ├── open/
│ ├── done/
│ └── discarded/
└── repos.yaml
This repository contains the tooling and plan schema.
PLANS_HOME contains the actual planning state and can live in a separate private Git repository.
Plans refer to repositories by logical name rather than filesystem path.
Execution tooling may describe repository checkouts in:
$PLANS_HOME/repos.yaml
plans does not read this registry or resolve checkouts; repos.yaml and REPOS_HOME are
execution-layer conventions.
For example:
repositories:
plans:
path: plans
url: git@github.com:akrisanov/plans.git
default_branch: main
local-agent-stack:
path: local-agent-stack
url: git@github.com:akrisanov/local-agent-stack.git
default_branch: mainpath is relative to REPOS_HOME:
export REPOS_HOME="$HOME/Projects"A plan can therefore refer simply to:
repository: local-agent-stackwithout knowing where that repository is checked out on the current machine.
Absolute checkout paths do not belong in plans or repos.yaml.
The project requires Python 3.12+ and uses uv.
Clone the repository and install the development environment:
git clone https://github.com/akrisanov/plans.git
cd plans
uv syncTo make the plan command available globally while keeping it linked to the local checkout:
uv tool install --editable .Verify the installation:
plan --help| Command | Description |
|---|---|
plan add <id> --repository <repository> |
Create a new plan in drafts. |
plan list |
List plans grouped by lifecycle state. |
plan show <id> |
Print the plan contents. |
plan inspect <id> --json |
Emit normalized machine-readable plan information. |
plan validate <id> |
Validate metadata, structure, and implementation readiness. |
plan ready <id> |
Check implementation readiness and move a valid draft to next. |
plan complete <id> |
Validate completion results and move an open plan to done. |
plan transition <id> <state> |
Perform a valid lifecycle transition (except open to done). |
plan --help |
Show CLI help. |
plan <command> --help |
Show help for a specific command. |
Execution tooling should use:
plan inspect <id> --jsonExample:
{
"id": "add-feature",
"state": "next",
"status": "next",
"repository": "my-repository",
"created_at": "2026-09-19",
"updated_at": "2026-09-19",
"depends_on": [],
"prs": [],
"path": "plans/next/add-feature.md"
}state represents the actual lifecycle location of the plan.
status comes from its metadata.
path is relative to PLANS_HOME.
The command requires --json and emits exactly these fields. It rejects unknown or duplicate IDs and
plans whose directory state disagrees with their metadata status. It intentionally does not expose
machine-specific repository checkout paths.
Plan frontmatter is a closed schema: unknown fields are rejected.
| Field | Type | Required | Meaning |
|---|---|---|---|
id |
string | yes | Plan ID; plans created by the CLI use lowercase kebab-case. |
status |
lifecycle status | yes | draft, next, open, done, or discarded; must match the directory. |
repository |
string | yes | Logical repository name, never a checkout path. |
created_at |
date | yes | Creation date. |
updated_at |
date | yes | Stored update date. |
depends_on |
list of strings | no | Other plan IDs; defaults to []. |
prs |
list of strings | no | Pull request references; defaults to []. |
Dates are serialized as YYYY-MM-DD. plan add sets both dates to the current UTC date. Successful
lifecycle commands preserve created_at and set updated_at to the current UTC date. The CLI does
not detect content edits or update updated_at for them. The metadata model records dependencies and
pull requests but does not schedule work or create pull requests.
Typed metadata parsing and state/status consistency are baseline structural checks performed while
plans are loaded. plan validate <id> additionally runs the implementation-readiness checks without
changing lifecycle state. plan ready <id> is restricted to drafts; it runs the same checks and then
moves the plan to next. A direct plan transition <id> next follows the same validated path.
A draft is ready when its required implementation sections are present, non-placeholder, and actionable. The required readiness sections are:
ProblemGoalDecisionsImplementationVerificationDone when
Done when must contain at least one meaningful Markdown checklist item. The canonical forms are
- [ ] criterion before completion and - [x] criterion after it. Contextual and
post-implementation sections may remain incomplete at the readiness stage.
The canonical plan structure lives in the template shipped with the package rather than being duplicated in this README.
plan complete <id> is the only supported open to done path. It first applies the normal
structural and readiness checks, then requires:
- every canonical
Done whenitem to use- [x] ...; - a
Resultssection with no unresolvedTODO; - a non-empty
Results / ImplementationCommitvalue; - non-placeholder
Results / Verificationcontent; - non-placeholder
Results / Deviationscontent (Noneis explicit and accepted).
Branch, PR, and the frontmatter prs list are optional. A failed completion leaves the plan open
and unchanged. A successful completion updates its status and date and moves it to done.
plans deliberately does not invoke coding agents.
Execution tools consume its public interface, primarily:
plan inspect <id> --jsonFor example, local-agent-stack contains a runner that:
- inspects the plan;
- verifies that it is in
next; - verifies that the selected plan is committed and unchanged in Git;
- resolves the target repository through
repos.yamlandREPOS_HOME; - performs the remaining deterministic preflight checks;
- transitions the plan to
open; - starts the selected agent harness in the target repository.
This preserves the exact implementation-ready plan used for execution in Git history. The check belongs to the execution layer rather than plans itself.
Example:
cd ~/Projects/local-agent-stack
uv run scripts/run-plan add-feature --harness piThe runner currently supports Pi.
Agent failure does not automatically complete or roll back a plan. Once implementation has started,
the plan remains open until its results are recorded and plan complete <id> succeeds. Direct
plan transition <id> done is not supported.
Install dependencies:
uv syncRun the test suite:
uv run pytestRun linting and formatting checks:
uv run ruff check .
uv run ruff format --check .Run type checking:
uv run ty checkPlans use logical repository names. They do not contain local checkout paths, agent executable paths, or machine-specific configuration.
plans decides what is ready to execute and tracks its lifecycle.
Execution tooling decides how and where an agent runs.
Anything that can be checked without an LLM should be checked before invoking one.
Plans are plain Markdown with typed YAML metadata. They can be inspected, versioned, reviewed, and manipulated without a service or database.
The plan format is not tied to Pi, Codex, Goose, or any particular model provider.
The v1 core is feature-complete and is being stabilized through real usage.
create
↓
draft
↓
ready
↓
next
↓
checkpoint
↓
run
↓
open
↓
agent
↓
review
↓
complete
↓
done
Plan creation, validation, readiness, inspection, lifecycle management, and completion have been exercised end to end on real implementation work.
The implementation-ready next plan is preserved in Git before execution begins, and the verified result is recorded separately when the plan is completed. This keeps both the input to implementation and its final outcome recoverable from Git history.
The v1 public contracts are now being stabilized through continued dogfooding before the v1.0.0 release.
MIT © 2026 Andrey Krisanov