Turn a one-sentence product idea into a confirmed product understanding, approved specs, dependency-aware tasks, and verified AI coding runs.
Plan2Agent requires Node.js 20 or newer.
npm install -g plan2agent
cd <project-dir>
p2a init --tools all --codex-profile quality
p2a nextp2a next reads the local project state and returns one concrete next action. Run it again whenever
you finish a planning, approval, or development step.
After initialization, open Codex, Claude Code, or Gemini CLI in the project directory and give the planning harness a product idea. You do not need to write a complete requirements document first.
| Agent | Example |
|---|---|
| Codex | Use the $p2a-harness skill to plan a service that receives webhooks, verifies signatures, and shows delivery history. |
| Claude Code | /p2a-harness Plan a service that receives webhooks, verifies signatures, and shows delivery history. |
| Gemini CLI | /p2a:harness Plan a service that receives webhooks, verifies signatures, and shows delivery history. |
The harness starts a bounded discovery interview, asking one to three high-impact questions at a time. It keeps question ids stable, records concrete answers, and turns confirmed answers into canonical product and implementation fields instead of leaving the decisions only in chat.
At round three, the harness presents a soft-limit summary and asks whether to continue, accept the current understanding, or pause. It stops at five rounds or after two no-progress rounds. Unresolved high-impact blockers remain visible and cannot be silently assumed away.
The resulting workflow pauses at explicit review gates instead of silently turning unclear requirements into code:
One-sentence idea
-> Discovery interview: 1-3 focused questions per round
-> Gate A: confirmed understanding and explicit user approval
-> Gate B: product spec and implementation plan
-> Gate C: dependency-aware task graph
-> Gate D: blocker and readiness review
-> supervised implementation and verification
-> evaluation and improvement proposals
Gate A confirmation and Gate B approval are separate decisions. Once you explicitly confirm the Gate A understanding summary, the harness continues to Gate B in the same agent session.
Each gate writes reviewable files under .plan2agent/artifacts/<project_id>/. Approve the decisions
in the active gate, complete the suggested action, and run:
p2a nextWhen Gate D is clear, next guides the transition into supervised task execution and subsequent
iterations.
AI coding tools are effective at implementation, but chat history is a fragile place to keep requirements, approvals, dependencies, and verification evidence. Plan2Agent adds a durable control layer around those tools.
| Need | Plan2Agent approach |
|---|---|
| Clear decisions before code | A bounded discovery interview and four human approval gates preserve answers, assumptions, open decisions, and approval state. |
| Traceable implementation work | Specs map to dependency-aware tasks with acceptance criteria and source references. |
| Reviewable agent execution | Tasks run in foreground-supervised sessions with run logs, changed files, and verification evidence. |
| Portable project state | Local JSON artifacts remain canonical across Codex, Claude Code, and Gemini CLI. |
| Controlled improvement | Evaluation and proposal flows recommend maintenance without silently applying self-modifying patches. |
Plan2Agent coordinates the workflow; it does not replace your coding agent, source control, or project management system.
Planning and execution state stays local to the project:
.plan2agent/
project.config.json
artifacts/<project_id>/
gate-a-intake/
intake.json
gate-b-spec/
spec.json
gate-c-task-graph/
task-graph.json
gate-d-review/
review.json
current-spec.json
iterations/
runs/
eval/
proposals/
JSON files are the source of truth and are validated against the schemas shipped with the package. Generated Markdown is a human-readable view. Closed iterations and finished run evidence provide an auditable history for later reviews.
The planning harness turns an idea into structured intake, product and implementation specs, a task graph, and a readiness review. Gate A interviews the user across the required discovery areas, presents a compact understanding summary, and requires explicit confirmation. The same session then continues to Gate B. It records uncertainty as an assumption or user decision rather than inventing a requirement.
After Gate D, use p2a next to identify the next safe action. A task execution records its agent
tool, workspace, changed files, verification commands, result, and failure classification. A task is
not done until required evidence passes the monitor gate.
For direct control of a ready task:
p2a execute plan \
--artifacts .plan2agent/artifacts/<project_id> \
--task <task-id>See the Supervised Execution Reference for start, resume, finish, retry, batch, and milestone-review procedures.
Iterations preserve the approved spec, derive change tasks, track maintenance work, and archive
closed history. A later Gate A reuses relevant confirmed answers from the baseline and asks again
only where the new idea changes or conflicts with them. p2a next guides close/open transitions;
p2a iteration exposes the lower-level controls.
The eval flow grades run evidence, compares results, and groups recurring failures. The proposal flow can turn supported findings into human-reviewed maintenance tasks. It never applies a patch merely because a proposal exists.
Plan2Agent Memory is an optional store and search
backend for artifacts, history, and lineage. Local .plan2agent/ files remain canonical when Memory
is unavailable or not configured.
Plan2Agent installs one p2a entrypoint:
| Command | Purpose |
|---|---|
p2a init |
Initialize project state and provider assets. |
p2a next |
Return one state-based next action and its reason. |
p2a info |
Show project, artifact, task, and run status. |
p2a doctor |
Diagnose configuration, assets, and local drift. |
p2a update |
Preview or apply safe package-managed asset updates. |
p2a upgrade |
Preview or apply broader toolkit migrations. |
p2a enhance |
Enable optional capabilities such as Memory and proposals. |
p2a validate |
Validate planning, task, run, eval, proposal, and Memory artifacts. |
p2a iteration |
Manage iteration initialization, close/open cycles, diffs, and maintenance. |
p2a tasks |
Inspect and transition task state. |
p2a runs |
Record, verify, finish, and inspect run evidence. |
p2a execute |
Supervise a task from plan through verified finish. |
p2a eval |
Grade, compare, analyze, generate, and summarize evaluations. |
p2a proposals |
Mine, review, curate, approve, and summarize improvement proposals. |
p2a memory |
Check, synchronize, search, and inspect optional Memory data. |
Run p2a --help for the top-level command surface and use the
CLI Reference for detailed options and examples.
Plan2Agent is intentionally human-supervised and local-first.
It is a good fit when you want:
- explicit product decisions before implementation;
- reviewable specs and agent-ready task graphs;
- foreground Codex, Claude Code, or Gemini CLI execution;
- verification evidence and regression history;
- human-approved maintenance and improvement loops.
It is not designed for:
- unattended background coding;
- unofficial provider API automation;
- automatic dependency installation, merging, pushing, or PR creation without approval;
- treating a remote service as the canonical project state;
- replacing Git or an issue tracker.
Canonical skills and subagent definitions live under .agents/. Plan2Agent generates and validates
provider-specific surfaces for:
- Codex
- Claude Code
- Gemini CLI
Parity checks keep provider mirrors aligned with the canonical definitions. The agent itself stays in the foreground tool session; Plan2Agent does not call provider APIs directly.
The core planning, validation, iteration, execution, eval, and proposal flows work without companion services.
| Project | Purpose |
|---|---|
| plan2agent-memory | Optional artifact history, search, hash comparison, and lineage service. |
| plan2agent-feature-radar | Optional research workflow that exports evidence for planning without selecting requirements automatically. |
- Quickstart — shortest path from installation to the first Gate artifacts
- CLI Reference — commands, options, and examples
- Harness Guide — Gate A-D, schemas, evidence, and troubleshooting
- Iteration Spec — iteration layout, diffs, close/open, and run tracking
- Supervised Execution Reference — task execution, monitor gates, retries, and reviews
- Harness Implementation Spec — skills, subagents, mirrors, and implementation rules
- Product Roadmap — current product direction and remaining work
Clone the repository, use Node.js 20 or newer, and run:
npm test
npm run test:package
node scripts/sync_cli_assets.mjs
node scripts/check_cli_parity.mjs
node scripts/run_fixtures.mjsThe runtime is Node.js ESM and uses the Node.js standard library. Repository structure:
.agents/ canonical skills and CLI-neutral subagents
.claude/ generated Claude Code mirrors
.codex/ generated Codex mirrors
.gemini/ generated Gemini CLI commands and agents
docs/ user guides and implementation references
fixtures/ golden and negative fixtures
plans/ roadmap and completed planning notes
schemas/ JSON schemas for Plan2Agent artifacts
scripts/ toolkit, validation, runtime, eval, proposal, and Memory CLIs
Plan2Agent is under active development. Version 0.1.0 establishes the public npm package and the
local-first planning, supervised execution, evaluation, proposal, and optional Memory workflows.
Autonomous provider execution and unapproved remote side effects remain outside the default safety
model.
Plan2Agent is available under the MIT License.