mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-17 04:45:33 -08:00
Sync upstream v2.4.0 into v2.4.1: welcome dialog, bug/idea button with issue templates, version in Help, gear preferences and ocean default accent, plus web console screenshots, new landing page and web-console-first docs
AI Assisted
This commit is contained in:
1 parent
0d7c2e140b
commit
cb86034de9
288 files changed
+25222
-4767
No files matched your search
@@ -1,22 +1,34 @@
|
||||
|
||||
# Plan2Code
|
||||
|
||||
<img src="https://raw.githubusercontent.com/jparkerweb/plan2code/main/docs/banner.png" alt="banner" data="object-fit:contain;" style="max-width:1024px;">
|
||||
**A spec-driven workflow for AI coding agents.**
|
||||
|
||||
**A spec-driven workflow for AI coding agents. Send the plan — the build follows.**
|
||||
<img src="docs/banner.jpg" alt="Plan2Code: plan and build with your AI agent, on one page. Planny, the mascot, acts out the five steps: Pathfinder, Plan, Document, Implement and Finalize." data="object-fit:contain;" style="max-width:1024px;">
|
||||
|
||||
An AI agent is a fine builder and a terrible client. Plan2Code stops making it both: you approve a
|
||||
plan, the plan becomes a set of phase documents in your repo, and the agent builds to those documents
|
||||
one phase at a time. Progress lives in files instead of chat history — so the next session, the next
|
||||
agent, and the next engineer all start from the same specs.
|
||||
You work through Plan2Code on a page in your browser. The dashboard lists every step as a card, and
|
||||
each step's questions, progress and sign-offs arrive on that same page while your agent does the
|
||||
work. What you decide still lands in your repo as plain files: an approved plan becomes phase
|
||||
documents, and the agent builds to them one phase at a time, so the next session, the next agent and
|
||||
the next engineer all start from the same specs.
|
||||
|
||||
Six commands, each posted separately. Two of them are optional.
|
||||
One command opens it, every step is a card, and the terminal is always there if you prefer it.
|
||||
|
||||
Version 2.4.0 · MIT · 📖 [plan2code.jparkerweb.com](https://plan2code.jparkerweb.com)
|
||||
Version 2.4.1 · MIT · 📖 [plan2code.jparkerweb.com](https://plan2code.jparkerweb.com)
|
||||
|
||||
---
|
||||
|
||||
## Install
|
||||
## See it
|
||||
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/dashboard-dark.webp">
|
||||
<img src="docs/screenshots/dashboard-light.webp" alt="The Plan2Code dashboard for a project mid-build: a Set up card, then the steps in order, with the Implement card marked Suggested and reading Phase 3 of 4 is next.">
|
||||
</picture>
|
||||
|
||||
The dashboard, in a project halfway through a build. It suggests the next step for the spec you pick.
|
||||
|
||||
---
|
||||
|
||||
## Install and start
|
||||
|
||||
Requires [Node.js](https://nodejs.org/) 18 or later and network access — installation runs through
|
||||
the [skills CLI](https://skills.sh). Re-run any time to update.
|
||||
@@ -43,14 +55,18 @@ Either route lands you on the same menu:
|
||||
╚═════════════════════════════════════════════════════════╝
|
||||
```
|
||||
|
||||
**Supported tools:** every agent supported by the skills CLI, including Claude Code · Cursor ·
|
||||
GitHub Copilot · Windsurf · Codex · Continue · Codeium · Zed · Amp · OpenCode · Devin · Crush · Pi ·
|
||||
Gemini CLI · Cline · Roo · Kilo · Goose · Trae · Qwen Code.
|
||||
### Start
|
||||
|
||||
The installer keeps one canonical copy of each skill under `~/.agents/skills/` and links it into
|
||||
agents that maintain their own directory. Update later with `npx skills update -g`.
|
||||
1. In any project, run `plan2code`. It starts Claude Code or Devin on the dashboard, and the
|
||||
dashboard opens in your browser.
|
||||
2. Pick a card.
|
||||
|
||||
The installer also adds a global `plan2code` command. Run it from any project and the Plan2Code
|
||||
Already inside your agent? Type `/plan2code` instead.
|
||||
|
||||
<details>
|
||||
<summary>About the plan2code command</summary>
|
||||
|
||||
The installer adds `plan2code` as a global command (Custom `C` → `D` adds just the command). Run it from any project and the Plan2Code
|
||||
dashboard opens right there, in **Claude Code** or **Devin**. With both installed it asks which and
|
||||
remembers your pick; `plan2code --cli claude` or `--cli devin` skips the question, and `--model <name>`
|
||||
chooses the model. It works in cmd, PowerShell, Git Bash, macOS and Linux shells, and needs the
|
||||
@@ -58,6 +74,14 @@ Claude Code or Devin CLI on your `PATH`. It starts the agent with permission pro
|
||||
(`--permission-mode bypassPermissions` in Claude Code, `--permission-mode bypass` in Devin); run
|
||||
`claude /plan2code` yourself if you want prompts. The installer then offers a desktop shortcut (answer `y`),
|
||||
which opens a folder picker first. Uninstalling (`U`) removes both.
|
||||
</details>
|
||||
|
||||
**Supported tools:** every agent supported by the skills CLI, including Claude Code · Cursor ·
|
||||
GitHub Copilot · Windsurf · Codex · Continue · Codeium · Zed · Amp · OpenCode · Devin · Crush · Pi ·
|
||||
Gemini CLI · Cline · Roo · Kilo · Goose · Trae · Qwen Code.
|
||||
|
||||
The installer keeps one canonical copy of each skill under `~/.agents/skills/` and links it into
|
||||
agents that maintain their own directory. Update later with `npx skills update -g`.
|
||||
|
||||
Use the installer rather than calling `skills add` against the repository root: recursive discovery
|
||||
would also find maintainer-only skills under `.claude/skills/`. The installer targets `skills/`
|
||||
@@ -78,6 +102,49 @@ npm install && npx husky
|
||||
|
||||
---
|
||||
|
||||
## A session on the page
|
||||
|
||||
**Answer the questions.** They arrive a few at a time, each option with its trade-off written beside
|
||||
it, and a progress bar says how far along you are.
|
||||
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/question-dark.webp">
|
||||
<img src="docs/screenshots/question-light.webp" alt="A Plan question card, How tasks are paged, with three options, the first marked Suggested, each with its trade-off underneath.">
|
||||
</picture>
|
||||
|
||||
**Watch the build.** Tasks tick off as they land, and the line beside Planny says what is being
|
||||
worked on right now.
|
||||
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/build-dark.webp">
|
||||
<img src="docs/screenshots/build-light.webp" alt="A phase of a task API being built: 5 of 11 done on the progress bar, and the phase's task list with the first five ticked.">
|
||||
</picture>
|
||||
|
||||
**Sign off.** Read the completion report, then approve the phase or ask for changes. In Implement,
|
||||
you can also have the code reviewed first; Implement + review has already done it.
|
||||
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/signoff-dark.webp">
|
||||
<img src="docs/screenshots/signoff-light.webp" alt="The Approve this phase card, with a button to read the completion report and three choices: Review the code first, Approve this phase, and I want changes.">
|
||||
</picture>
|
||||
|
||||
**Ask a quick question any time.** The Ask tab is a chat beside the cards, answered at the agent's
|
||||
next check-in, and it never holds up your answers.
|
||||
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/ask-dark.webp">
|
||||
<img src="docs/screenshots/ask-light.webp" alt="The Ask tab: the question Where are tasks paged? and Plan2Code's answer naming the file.">
|
||||
</picture>
|
||||
|
||||
There is more on the page when you need it. Notes on any question can carry screenshots and
|
||||
documents. The folder label in the bottom bar opens your workspace, where you add other folders
|
||||
as read-only context and point at them by `@name`. The session meter in the top bar turns from green
|
||||
to red as a session grows long and suggests a fresh one. **Stop session** saves your place and gives
|
||||
you the command to carry on later, and **Back to the dashboard** takes you home to pick the next
|
||||
step in the same session.
|
||||
|
||||
---
|
||||
|
||||
## The workflow
|
||||
|
||||
```
|
||||
@@ -90,39 +157,37 @@ npm install && npx husky
|
||||
│decide what │ │ draw it as │ │build to the│ ╎ optional ╎ │verify, sum,│
|
||||
│ to build │ │phase specs │ │ drawing │ ╎ any time ╎ │ archive │
|
||||
└────────────┘ └────────────┘ └────────────┘ └╴╴╴╴╴╴╴╴╴╴╴╴┘ └────────────┘
|
||||
new chat new chat new chat/phase new chat new chat
|
||||
short sessions: fresh when the meter turns red, and before a big step
|
||||
├◀─────────────── one feature, start to archive ──────────────────▶┤
|
||||
```
|
||||
|
||||
Every box is its own conversation. That is not a style preference — planning context leaking into
|
||||
implementation is where most agent drift starts.
|
||||
Each box is a card on the dashboard. Chaining a couple of small steps in one session is fine, but
|
||||
start a fresh session before a big plan or build step: planning context leaking into implementation
|
||||
is where most agent drift starts.
|
||||
|
||||
| Command | Use it when |
|
||||
|---------|-------------|
|
||||
| `/plan2code` | Open the web console dashboard: every skill below as a card, launched on the page |
|
||||
| `/plan2code-0-pathfinder` | The idea is too big and unclear to plan. Charts it as decisions, clears them one at a time, hands a hot plan draft to Step 1 |
|
||||
| `/plan2code-1-plan` | Starting a feature. Full requirements → architecture pass |
|
||||
| `/plan2code-2-document` | Planning is done. Turn the plan into phase specs |
|
||||
| `/plan2code-3-implement` | Build the next phase (one per conversation) |
|
||||
| `/plan2code-3-implement-review` | Build the next phase and review it before you approve it (instead of `/plan2code-3-implement`) |
|
||||
| `/plan2code-review` | Independent second opinion on local changes, then optional fixes |
|
||||
| `/plan2code-4-finalize` | All phases done. Validate, summarize, archive |
|
||||
| `/plan2code-init` | Generate this repo's `AGENTS.md` so every agent starts informed |
|
||||
| `/plan2code-init-update` | Fold what you learned this session back into `AGENTS.md` |
|
||||
| `/plan2code-quick-task` | A small change that doesn't warrant the full sequence |
|
||||
| `/plan2code-1b-revise-plan` | Requirements moved mid-build. Revise the specs, not the code |
|
||||
| `/plan2code-handoff` | Compact this conversation into a doc the next one resumes from |
|
||||
The dashboard's cards, and when each one lights up for the spec you pick:
|
||||
|
||||
Every skill asks at the start whether to work in the terminal or in the **web console**, a local
|
||||
browser page for the questions, sign-offs, build progress and the document taking shape. Add `--web`
|
||||
to any command to skip the question: `/plan2code-1-plan --web plan a lunch voting app`.
|
||||
| Card | What it is for | Lights up when |
|
||||
|------|----------------|----------------|
|
||||
| Set up this project | Reads your project and writes AGENTS.md, the guide every later step works from. | The project has no AGENTS.md yet |
|
||||
| Refresh AGENTS.md | Brings AGENTS.md and its notes up to date with what the project has learned lately. | The project has an AGENTS.md |
|
||||
| Pathfinder | A foggy idea becomes a clear list of decisions, settled one question at a time. | You start fresh, or the spec is still being explored |
|
||||
| Plan | Requirements, technical design and your approval: the shape of what gets built. | You start fresh, or the spec has a finished Pathfinder map or a drafted plan |
|
||||
| Revise the plan | Requirements changed mid-build? Adjust the plan without starting over. | The spec is written up into phases and not fully built |
|
||||
| Document | The plan becomes a checklist of small tasks, grouped into phases, that a developer can just do. | The spec has a drafted plan |
|
||||
| Implement | Builds the next phase, task by task, with a report and your sign-off at the end. | The spec has phases with tasks still to build |
|
||||
| Implement + review | One phase built, then a careful review of the changes, then your sign-off. All in one run. | The spec has phases with tasks still to build |
|
||||
| Finalize | Checks the work, writes the summary, files the specs away and suggests the commit message. | Every task in the spec is done |
|
||||
| Quick task | Too small for the full process? A quick plan, then it just builds it. | Always |
|
||||
| Review | A second opinion on the changes. Problems ranked, and you pick what gets fixed. | Always |
|
||||
| Handoff | Pack this conversation into a document a fresh session can pick up cold. | Always |
|
||||
|
||||
---
|
||||
|
||||
## The four rules that do most of the work
|
||||
|
||||
**1 · A fresh conversation for each step, and each implementation phase.**
|
||||
Step 3 gets a new chat per phase, not one chat for all of them.
|
||||
**1 · Keep each session short.**
|
||||
Chaining a couple of small skills on the dashboard is fine. Start a fresh console session when the session meter turns red, and always before a big planning or build step. The specs on disk carry everything between sessions.
|
||||
|
||||
**2 · No code until the plan hits 90% confidence.**
|
||||
Step 1 will not finalize below the threshold. Under it, the agent keeps asking and keeps reading your
|
||||
@@ -131,8 +196,9 @@ code — and writes every assumption down where you can argue with it.
|
||||
**3 · Checkboxes are the state, not the chat.**
|
||||
Progress lives in the spec files. Any agent, any session, resumes cold from them.
|
||||
|
||||
**4 · Reply `approved` to close a phase.**
|
||||
Nothing advances on a guess about what you meant.
|
||||
**4 · Approve a phase to close it.**
|
||||
On the sign-off card, or by replying `approved` in the terminal. Nothing advances on a guess about
|
||||
what you meant.
|
||||
|
||||
---
|
||||
|
||||
@@ -182,11 +248,14 @@ keep the two out of each other's way.
|
||||
|
||||
## The six steps in detail
|
||||
|
||||
Each one travels on its own — a fresh conversation, opened and closed, with the specs on disk as the
|
||||
only thing carried between them.
|
||||
Each step is its own run, and the specs on disk are the only thing carried from one to the next.
|
||||
Chain a small one onto the last, or start a fresh session for a big one (rule 1).
|
||||
|
||||
### 0 · Pathfinder 🧭 — optional, new in 2.0
|
||||
|
||||
On the page: one question at a time with the options and their trade-offs, the map growing in its own
|
||||
tab, and a **Write a brief** button for a printable summary.
|
||||
|
||||
Some ideas are too big and unclear to plan: you can feel the shape of the work but you can't write
|
||||
it as requirements, so planning would just invent the answers. Pathfinder finds the *way* to the
|
||||
destination; Step 1 then walks it.
|
||||
@@ -218,6 +287,9 @@ sub-issues) → `PLAN-DRAFT-<date>.md`. The draft is always a local file — tha
|
||||
|
||||
### 1 · Plan 🤔
|
||||
|
||||
On the page: questions in batches of up to three, the phase breakdown as a list you can reorder and
|
||||
edit, and a sign-off at each stage.
|
||||
|
||||
The agent works as a senior architect through six phases, stopping for you after each: requirements
|
||||
analysis · system context (reading your actual codebase) · tech stack (needs your explicit sign-off) ·
|
||||
architecture design · technical specification · transition decision.
|
||||
@@ -228,6 +300,9 @@ It won't finalize below **90% confidence**, and every assumption it makes is wri
|
||||
|
||||
### 2 · Document 📝
|
||||
|
||||
On the page: a question only where the plan leaves something open, each phase file appearing as its
|
||||
own tab as it is written, and one sign-off at the end.
|
||||
|
||||
The plan becomes the drawing. One `overview.md` with the phase checklist, plus one file per phase of
|
||||
one-story-point tasks. Each phase is **self-contained** — an agent opening `Phase 3.md` cold needs
|
||||
nothing else to build it. Unit and E2E tests are excluded unless you ask for them.
|
||||
@@ -239,6 +314,9 @@ dependencies, safe to run in separate agents at once.
|
||||
|
||||
### 3 · Implement ⚡
|
||||
|
||||
On the page: a progress bar and the phase's task list ticking over as tasks land, then the completion
|
||||
report and a sign-off card where you approve, ask for changes, or have the code reviewed first.
|
||||
|
||||
Point it at `overview.md` and it does the rest: finds the next unchecked phase, implements every task
|
||||
exactly as specified, ticks tasks off as they land, then reviews its own work against the spec and
|
||||
writes a completion summary.
|
||||
@@ -252,6 +330,9 @@ same way, runs a focused review and the fixes you pick, and only then asks for a
|
||||
|
||||
### Review 🔬 — optional, any time
|
||||
|
||||
On the page: a few questions on scope, the findings as a report you can read in full, and a list
|
||||
where you tick what gets fixed.
|
||||
|
||||
An independent second opinion, not a rubber stamp. It figures out its own scope (conversation
|
||||
context, your instruction, or the git diff as a fallback), analyses across 11 dimensions, and ranks
|
||||
findings Critical / Warning / Suggestion. Every finding cites a file and a line, or it gets dropped —
|
||||
@@ -262,6 +343,9 @@ implementation step, but there's no wrong time to run it.
|
||||
|
||||
### 4 · Finalize 🧹
|
||||
|
||||
On the page: the task audit and the summary as reports, a list of the doc updates to approve, and a
|
||||
confirmation before anything is archived.
|
||||
|
||||
Validates every task against its phase spec, writes the summary and the list of files touched, flags
|
||||
the docs that drifted (`README`, `CHANGELOG`, `AGENTS.md`), then archives the whole spec folder —
|
||||
`pathfinder/` included — to `specs--completed/`. That folder is the record of *why* the code looks
|
||||
@@ -284,6 +368,30 @@ like this.
|
||||
|
||||
---
|
||||
|
||||
## Prefer the terminal?
|
||||
|
||||
Every skill also runs right in the terminal. Each one asks at the start whether you want the web
|
||||
console or the terminal; add `--web` to skip the question and go straight to the web console:
|
||||
`/plan2code-1-plan --web plan a REST API for tasks`.
|
||||
|
||||
| Command | Use it when |
|
||||
|---------|-------------|
|
||||
| `/plan2code` | Open the dashboard in the web console: every skill below as a card, launched on the page |
|
||||
| `/plan2code-0-pathfinder` | The idea is too big and unclear to plan. Charts it as decisions, clears them one at a time, hands a hot plan draft to Step 1 |
|
||||
| `/plan2code-1-plan` | Starting a feature. Full requirements → architecture pass |
|
||||
| `/plan2code-2-document` | Planning is done. Turn the plan into phase specs |
|
||||
| `/plan2code-3-implement` | Build the next phase (one per conversation) |
|
||||
| `/plan2code-3-implement-review` | Build the next phase and review it before you approve it (instead of `/plan2code-3-implement`) |
|
||||
| `/plan2code-review` | Independent second opinion on local changes, then optional fixes |
|
||||
| `/plan2code-4-finalize` | All phases done. Validate, summarize, archive |
|
||||
| `/plan2code-init` | Generate this repo's `AGENTS.md` so every agent starts informed |
|
||||
| `/plan2code-init-update` | Fold what you learned this session back into `AGENTS.md` |
|
||||
| `/plan2code-quick-task` | A small change that doesn't warrant the full sequence |
|
||||
| `/plan2code-1b-revise-plan` | Requirements moved mid-build. Revise the specs, not the code |
|
||||
| `/plan2code-handoff` | Compact this conversation into a doc the next one resumes from |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**The skills aren't recognised.** Re-run the installer and restart your AI tool. Confirm the global
|
||||
@@ -309,6 +417,18 @@ the requirements.
|
||||
**Too many or too few phases.** Fix it in Step 2 — a phase should be a logical grouping of work, not
|
||||
a fixed size.
|
||||
|
||||
**The page says it lost contact with Plan2Code.** Nothing you typed is lost, and the page reconnects
|
||||
by itself. If the link has stopped working, tell the agent: it restarts the session and gives you a
|
||||
new link.
|
||||
|
||||
**The agent runs on another machine, or over SSH.** The page is served on `127.0.0.1` of the machine
|
||||
the agent runs on, so your browser can only reach it there. A forwarded port often works; otherwise
|
||||
work in the terminal, which loses nothing.
|
||||
|
||||
**You closed the tab.** Open the link again. Everything is where you left it, including answers you
|
||||
had typed but not sent. The page's program stops about two minutes after the last tab closes, so
|
||||
after that, ask the agent to resume the session for a new link.
|
||||
|
||||
---
|
||||
|
||||
## Customizing
|
||||
@@ -324,6 +444,7 @@ edits out through the skills CLI.
|
||||
|
||||
Core reference:
|
||||
|
||||
- **[.readme/web-console.md](.readme/web-console.md)**: the full guide to the web console, from the dashboard to the last sign-off
|
||||
- **[QUICK-REFERENCE.md](QUICK-REFERENCE.md)** — the one-page card: commands, inputs, outputs, decision tree
|
||||
- **[.readme/walkthrough.md](.readme/walkthrough.md)** — one feature from a sentence to archived specs, session by session
|
||||
- **[AGENTS.md](AGENTS.md)** — architecture and contributor guide for this repo
|
||||
@@ -331,7 +452,6 @@ Core reference:
|
||||
|
||||
Optional tooling — none of it is required to use the workflow:
|
||||
|
||||
- **[.readme/web-console.md](.readme/web-console.md)**: the browser dashboard, and working through every step on one page
|
||||
- **[.readme/autonomous-loop.md](.readme/autonomous-loop.md)** — `plan2code-loop`, a hands-off alternative to Step 3
|
||||
- **[.readme/status-line.md](.readme/status-line.md)** — three-line Claude Code status bar: model, context, quota, diff
|
||||
- **[.readme/metrics.md](.readme/metrics.md)** — `plan2code-metrics`, measuring and improving the prompts themselves
|
||||
|
||||
Reference in new issue
Block a user