diff --git a/.readme/walkthrough.md b/.readme/walkthrough.md
index b62a0a6..a234d21 100644
--- a/.readme/walkthrough.md
+++ b/.readme/walkthrough.md
@@ -10,6 +10,7 @@ Each session stays short, and the specs on disk carry everything from one sessio
## Before you start
- **Node.js 18 or newer.** Check with `node --version`. No Node? Get it from [nodejs.org](https://nodejs.org/) (the LTS download), or run `winget install OpenJS.NodeJS.LTS` on Windows, `brew install node` on macOS, or use `nvm` on Linux. Then open a new terminal.
+- **Git.** Check with `git --version`. The installer is fetched from GitHub with Git, and without it npm stops with `spawn git ENOENT`. No Git? Get it from [git-scm.com](https://git-scm.com/downloads), or run `winget install Git.Git` on Windows, `brew install git` on macOS, or use your package manager on Linux. Then open a new terminal.
- **Start from your project.** Open your terminal in the project you want to work on (`cd` into it) before you run anything. Plan2Code works on the folder you start it in.
- **Ways in.** `plan2code` (Claude Code, Devin or Codex), or type `/plan2code` in your agent (`$plan2code` in Codex).
- **No agent yet?** Install Claude Code, Codex or Devin first, or let the `plan2code` command's setup page walk you through it.
diff --git a/QUICK-REFERENCE.md b/QUICK-REFERENCE.md
index ddb3ddc..88b55bd 100644
--- a/QUICK-REFERENCE.md
+++ b/QUICK-REFERENCE.md
@@ -3,6 +3,7 @@
## Before you start
- **Node.js 18 or newer.** Check with `node --version`. No Node? Get it from [nodejs.org](https://nodejs.org/) (the LTS download), or run `winget install OpenJS.NodeJS.LTS` on Windows, `brew install node` on macOS, or use `nvm` on Linux. Then open a new terminal.
+- **Git.** Check with `git --version`. The installer is fetched from GitHub with Git, and without it npm stops with `spawn git ENOENT`. No Git? Get it from [git-scm.com](https://git-scm.com/downloads), or run `winget install Git.Git` on Windows, `brew install git` on macOS, or use your package manager on Linux. Then open a new terminal.
- **Start from your project.** Open your terminal in the project you want to work on (`cd` into it) before you run anything. Plan2Code works on the folder you start it in.
- **Ways in.** `plan2code` (Claude Code, Devin or Codex), or type `/plan2code` in your agent (`$plan2code` in Codex).
- **No agent yet?** Install Claude Code, Codex or Devin first, or let the `plan2code` command's setup page walk you through it.
diff --git a/README.md b/README.md
index 14394ce..577000f 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,7 @@ The dashboard, in a project halfway through a build. It suggests the next step f
### Before you start
- **Node.js 18 or newer.** Check with `node --version`. No Node? Get it from [nodejs.org](https://nodejs.org/) (the LTS download), or run `winget install OpenJS.NodeJS.LTS` on Windows, `brew install node` on macOS, or use `nvm` on Linux. Then open a new terminal.
+- **Git.** Check with `git --version`. The installer is fetched from GitHub with Git, and without it npm stops with `spawn git ENOENT`. No Git? Get it from [git-scm.com](https://git-scm.com/downloads), or run `winget install Git.Git` on Windows, `brew install git` on macOS, or use your package manager on Linux. Then open a new terminal.
- **Start from your project.** Open your terminal in the project you want to work on (`cd` into it) before you run anything. Plan2Code works on the folder you start it in.
- **Ways in.** `plan2code` (Claude Code, Devin or Codex), or type `/plan2code` in your agent (`$plan2code` in Codex).
- **No agent yet?** Install Claude Code, Codex or Devin first, or let the `plan2code` command's setup page walk you through it.
diff --git a/docs/index.html b/docs/index.html
index 2a8765d..1a27c5e 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -3,878 +3,736 @@
-Plan2Code: plan and build with your AI agent
-
-
+Plan2Code: plan it, approve it, let it build
+
+
+
+
+
+
-
+
+
+
+
+
Skip to the content
+
+
+
+
+
+
Plan2Code is a short, structured workflow where your AI agent asks, you decide, and the specs land in your repo as plain files. Version 3 adds an optional desktop app that holds the dashboard and your agent side by side.
-
-
Before you start
-
-
Node.js 18 or newer. Check with node --version. No Node? Get it from nodejs.org (the LTS download), or run winget install OpenJS.NodeJS.LTS on Windows, brew install node on macOS, or use nvm on Linux. Then open a new terminal.
-
Start from your project. Open your terminal in the project you want to work on (cd into it) before you run anything. Plan2Code works on the folder you start it in.
-
Ways in.plan2code (Claude Code, Devin or Codex), or type /plan2code in your agent ($plan2code in Codex).
-
No agent yet? Install Claude Code, Codex or Devin first, or let the plan2code command's setup page walk you through it.
-
+
+
Plan it. Approve it.Let it build.
+
+
Plan2Code is a spec-driven workflow for AI coding agents. Its desktop app puts the plan, your agent and every sign-off in one window, and what you decide lands in your repo as plain files.
Click a station, or tab to one and press Enter. Arrow keys move between stations.
+
+
The plan on the left. The agent on the right.
+
The desktop app opens on the dashboard and runs your agent in a terminal panel it owns. Every page of a session opens inside the window: questions, the living plan, the code review, the git board, your notebook. It is a small native app for Windows, macOS and Linux, and it talks to nothing but your own machine.
-
-
JavaScript is off, so every station is listed in full below.
-
-
-
-
-
Step 0Optional
-
Pathfinder
-
A foggy idea becomes a clear list of decisions, settled one question at a time. The agent asks a few at a time, each option with its trade-off written under it, and you pick. Skip it when you already know what you want.
-
/plan2code-0-pathfinder
-
- Questions arrive a few at a time on a page in your browser.
-
-
-
-
-
Step 1
-
Plan
-
Requirements, technical design and your approval: the shape of what gets built. No code is written until the plan hits 90% confidence. In the desktop app, Plan and Revise Plan can offer helpers matched to the job.
-
/plan2code-1-plan
-
- The plan so far, with every assumption written down where you can argue with it.
-
-
-
-
-
Step 2
-
Document
-
The plan becomes a checklist of small tasks, grouped into phases, that a developer can just do. They are checkboxes in spec files in your repo.
-
/plan2code-2-document
-
-
-
-
-
-
Step 3Once per phase
-
Implement
-
Builds the next phase, task by task, with a report and your sign-off at the end. Implement + review adds a careful review of the changes before the sign-off.
-
In the desktop app, the Implementation Loop can build a whole spec phase by phase instead, each phase in a fresh agent, and write a report.
-
/plan2code-3-implement
-
/plan2code-3-implement-review
-
- Tasks tick off as they land.
-
-
-
-
-
Step 4
-
Finalize
-
Checks the work, writes the summary, files the specs away and suggests the commit message.
-
/plan2code-4-finalize
-
- Every ending says what to run next.
-
-
-
-
-
Any time
-
Quick task
-
Too small for the full process? A quick plan, then it just builds it.
-
/plan2code-quick-task
-
-
-
-
-
-
Any time
-
Review
-
A second opinion on the changes. Problems ranked, and you pick what gets fixed.
-
/plan2code-review
-
-
-
-
-
-
Any time
-
Handoff
-
Pack the current session into a document a fresh session can pick up cold.
-
/plan2code-handoff
-
-
-
-
-
-
Any time
-
Codebase X-ray
-
Explains how and why an area works, or ranks the rough spots worth fixing into a brief for planning.
-
/plan2code-xray
-
-
-
-
-
-
Any time
-
Diagnose a bug
-
Finds a bug's cause and writes it up without fixing it, then hands the fix to Quick task, or to Plan when it is big.
-
/plan2code-diagnose
-
-
-
-
-
-
Any time
-
Changelog
-
Picks the next version and drafts the entries, which you edit before Git commits them.
-
/plan2code-changelog
-
-
-
-
-
-
Any time
-
Git
-
A board for branches, pull, push and commits that opens on the likely next step. The screenshot is just below the map.
-
/plan2code-git
-
-
-
-
-
-
New in v3Any time
-
Get a PR ready
-
Picks the checks that cover your branch's changes, runs them, and says Ready, Ready with notes or Not ready. Then it writes a PR description for you to copy. It never commits, pushes or opens the PR, and it can read an optional test map.
-
/plan2code-pr-prep
-
-
-
-
- Checks for this branch
-
passed A check chosen for the changed files
-
passed Another check for the changed files
-
note One thing worth a look before review
- Ready with notes
-
PR descriptionCopy description
-
-
An illustration, not a screenshot.
-
-
-
-
-
-
New in v3Any time
-
Write missing tests
-
Finds source files that no test covers. Once you approve its plan, it writes tests in your project's own style. It never changes source code, and it can read an optional test map.
-
/plan2code-test
-
-
-
-
- Source files with no test
-
no testa source file
-
no testanother source file
-
covereda file with tests
-
Plan: tests to write, in your styleApprove plan
-
-
An illustration, not a screenshot.
-
-
-
-
-
-
-
-
-
-
-
The git board
-
Three tabs, Changes, Branches and Sync, and it opens on the one holding your likely next step: commit, pull, push, publish, open a pull request or tidy up branches. That step is one main button. Each tab badges what is waiting on it, a stopped rebase or merge gets one block with every file marked, and nothing is pushed, published or deleted without asking. It never force-pushes.
-
-
-
-
-
-
-
-
What is new in v3
-
Version 3.0.0 adds a desktop app and what runs inside it, plus two utilities. None of it replaces the page or the terminal flow.
-
+
-
The desktop app
-
-
One window: the dashboard as the main surface and your agent in a terminal panel the app owns (Claude Code, Devin, Codex or your own). New Session replaces the agent with a fresh one on a brief the app builds from its own record of the session, so in-progress work carries over. Update skills brings the installed skills level with the app, and the taskbar shows when Plan2Code needs you. Ask, Workspace, Help, Preferences, Git and Notebook open inside the window.
-
+
+
Dock the terminal where you want it
+
Right or bottom, collapsed to a strip, or maximized. A badge on a collapsed panel says when the agent may need you.
-
The Implementation Loop
-
-
Builds a whole spec phase by phase, each phase in a fresh agent, and writes a report. It lives in the desktop app and replaces the old plan2code-loop CLI. Set strength per phase runs each phase on the model and effort of a strength you choose: Thrifty, Balanced, Best or Match my session. The loop strip and the report show what each phase ran on.
-
-
-
Phase 1Balanceddone
-
Phase 2Bestdone
-
Phase 3Balancedrunning
-
Phase 4Thriftywaiting
-
-
An illustration of the loop strip, not a screenshot.
-
+
+
New Session, in one click
+
The app writes a brief from its own record of the session and starts a fresh agent on it, so a long conversation never gets to go stale.
-
Helpers matched to the job
-
-
Helpers (subagents) run at a strength and effort chosen for their task, never tied to one vendor. Plan and Revise Plan offer them now. A Subagents dialog turns them on or off per project and skill, with a Helper strength choice (Balanced, Thrifty, Best or Match my session), and a Subagents tab shows what each helper ran with.
-
+
+
Your agent, your model
+
A launch card asks which agent, model and effort to start on. Claude Code, Devin and Codex are built in, and any other agent CLI can be added.
-
Bring any agent
-
-
Add your own agent CLI under User Preferences. A first-run setup page shows which built-in agents are found, install commands for your OS, and a Check again button.
-
-
-
-
Get a PR ready
-
-
/plan2code-pr-prep picks the checks that cover your branch's changes, runs them, says Ready, Ready with notes or Not ready, and writes a PR description to copy. It never commits, pushes or opens the PR.
-
-
-
-
Write missing tests
-
-
/plan2code-test finds source files no test covers and, once you approve its plan, writes tests in the project's own style. It never changes source code.
-
-
-
-
Activities
-
-
A die in the console's top bar opens thirteen small games to play while you wait. A game pauses the moment Plan2Code needs you. They are off until you turn them on.
-
-
-
-
Start from your Notebook
-
-
Start Pathfinder, Plan, Quick Task, Diagnose or Revise plan from a Notebook tab. The agent reads the tab only once you send it.
-
+
+
It tells you when it is your move
+
A dot on the taskbar entry turns green when a question or a sign-off is waiting, so the window can sit behind your other work.
-
+
-
How a session goes
-
One page, from the first card to the sign-off. Your agent does the work in its terminal (or the app's terminal panel); you do your part here.
-
-
-
-
-
-
-
-
1
-
Pick a card, answer on the page
-
Pick a step on the dashboard and it starts right there. Questions arrive a few at a time, each option with its trade-off written under it.
+
+
+
Start the loop. Go to lunch.
+
The Implementation Loop builds every remaining phase of a spec, one after another, while you do something else. It lives in the desktop app.
+
+
A fresh agent for every phaseA long spec never grows into one tired conversation.
+
The app decides when a phase countsIt reads the spec's marks, runs your quick check, then makes one local commit. It never pushes.
+
A model per phaseThrifty for the boilerplate, Best for the hard part. A phase that crashes gets one retry, one step up.
+
It reaches you where you areDiscord, Slack, Teams, Google Chat or any webhook, when it waits on you or finishes.
+
-
-
-
-
-
-
-
-
2
-
Watch it build
-
Tasks tick off as they land, and the line beside Planny says what is being worked on right now.
-
-
-
-
-
-
-
-
-
-
3
-
Sign off
-
Read the completion report, then approve the phase or ask for changes. In Implement, you can also have the code reviewed first.
+
+
+
+
+ Building Phase 3 of 4: API endpoints
+ run 17m
+ Stop after this phase
+
+
+
+
Phase
Runs on
Build
Review
Quick check
Commit
+
+
1Project setup
Thrifty
4 tasks
clean
npm run build
9c1e7f0
+
2Tasks model
Balanced
5 tasks
2 fixed
npm run build
a41c9e2
+
3API endpoints
Best
task 6 of 11
fresh agent
npm run build
local only
+
4Errors and docs
Thrifty
6 tasks
fresh agent
npm run build
local only
+
+
+
+
✅ Phase completePlan2Code loop on task-api: Phase 2 of 4 (Tasks model) is complete. Done: 5 tasks, committed "Add the tasks model" (a41c9e2). Next: Phase 3, API endpoints. Elapsed: phase 6m, run 14m.
+
+
Illustration with example data. The message is the one the loop sends to your chat.
+
+
It would rather stop than guess. The loop ends on a stop screen, with the evidence, when:
+
+
the phase's tests or your quick check fail
+
a Critical finding is left after the re-check
+
a task is blocked, or the spec conflicts with itself
+
a commit is refused, by a pre-commit hook for example
+
a staged file looks like a secret
+
you press Stop, now or after this phase
+
+
-
+
-
What the page gives you
-
The same workflow as the terminal, with more room to think. The page is there whether or not you use the desktop app.
-
-
Trade-offs in plain view
Questions arrive a few at a time, each option with its trade-off written under it, so you choose rather than guess.
-
Review before you approve
Review the code first, on the sign-off card, reviews exactly the files the phase changed. You tick which findings get fixed, then approve.
-
The Ask tab
A chat beside the cards for anything you want to know. It is answered at the agent's next check-in and never holds up your answers.
-
Attachments on notes
Paste a screenshot or attach a document to a note on any question, and show instead of describe.
-
A notebook of your own
A private pad for each project folder, in Markdown with pictures. It never goes into your project, and the agent reads a tab only when you start a workflow from it and send it.
-
Workspace folders
Add a shared library or a design folder as read-only context, and point at it by its @name.
-
Session meter
A ring in the top bar turns from green to red as a session grows long, and suggests when a fresh one would serve you better.
-
Runs on your machine
A small program Plan2Code starts for you serves the page on 127.0.0.1. No account, no dependencies, and nothing leaves your computer.
+
+
Underneath, it is skills and files.
+
The app is optional. The workflow is a set of Agent Skills, and each step is a slash command that runs in your agent's own terminal. Every step writes Markdown the next one reads, so any session, any agent and any engineer can pick up cold.
-
-
-
-
-
-
- The Ask tab, answered between tasks.
-
-
-
-
-
-
- Every ending says what to run next.
-
-
-
-
-
-
- Your own notebook, private to the folder.
-
-
-
-
-
-
-
-
The rules
-
Four rules do most of the work.
-
-
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.
-
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 code, and writes every assumption down where you can argue with it.
-
Checkboxes are the state, not the chat.
Progress lives in the spec files. Any agent, any session, resumes cold from them.
-
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.
+
+
0
Pathfinder optional
A foggy idea becomes a list of decisions, settled one question at a time.
/plan2code-0-pathfinderwrites pathfinder/map.md
+
1
Plan
Requirements, your real codebase, the design. It will not finalize under 90% confidence.
/plan2code-1-planwrites PLAN-DRAFT.md
+
2
Document
The plan becomes phases of small tasks, each phase readable on its own.
An independent second opinion. Every finding cites a file and a line.
/plan2code-reviewreads only, fixes what you pick
+
4
Finalize
Checks every task against its spec, writes the summary, files the specs away.
/plan2code-4-finalizemoves to specs--completed/
-
-
-
When the agent is not running, you lose nothing. The plan, the tasks and the ticks are files in your repo, so a fresh session picks up where the last one stopped.
+
+
+
+
The checkboxes are the state
+
Progress lives in the spec files, not in the chat. Close the window mid-phase and nothing is lost.
+
specs/task-api/
+├─ PLAN-DRAFT-2026-11-02.md
+├─ overview.md phases 1 and 2 done
+├─ phase-1.md [x] 4 of 4
+├─ phase-2.md [x] 5 of 5
+├─ phase-3.md [/] 5 of 11
+│ [x] 3.5 PATCH /tasks/:id
+│ [/] 3.6 DELETE /tasks/:id
+│ [ ] 3.7 One error shape
+└─ phase-4.md [ ] 0 of 6
+
+
+
And a drawer of skills for any time
+
Each one is a card on the dashboard and a command in the terminal.
+
+
/plan2code-quick-taskToo small for the full process: a quick plan, then it builds.
+
/plan2code-diagnoseFinds a bug's cause and writes it up, without fixing it.
+
/plan2code-xrayExplains how and why an area of the code works.
+
/plan2code-pr-prepRuns the checks your branch needs and writes the PR description.
+
/plan2code-testFinds code with no tests and writes them in your project's style.
+
/plan2code-dead-codeFinds code nothing uses and removes only what you pick.
+
/plan2code-1b-revise-planRequirements moved mid-build: revise the specs, not the code.
+
/plan2code-handoffPacks a session into a document a fresh one resumes from.
+
/plan2code-gitBranches, pull, push and commits, asking before anything leaves.
+
/plan2code-changelogPicks the next version and drafts the entries.
+
+
+
The skills install into every agent the skills CLI supports, including Claude Code, Cursor, GitHub Copilot, Windsurf, Codex, Devin, OpenCode, Gemini CLI, Cline, Goose and Zed. Each skill asks whether you want its page or plain terminal prompts, so the whole workflow also runs over SSH with no window at all.
-
-
+
+
+
Four rules do most of the work.
+
+
Keep each session short.
Start fresh when the session meter turns red, and always before a big plan or build step. Planning context leaking into implementation is where most agent drift starts.
+
No code until the plan hits 90% confidence.
Under the threshold the agent keeps asking and keeps reading your code, and writes every assumption down where you can argue with it.
+
Checkboxes are the state, not the chat.
Progress lives in the spec files. Any agent, in any session, resumes cold from them.
+
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.
+
+
+
+
+
+
+
+
More room to think than a prompt.
+
The page is served on 127.0.0.1 by a small program with zero dependencies. No account, and nothing leaves your computer.
+
+
+
+
+ A living plan. What has been agreed so far, with every assumption marked where you can argue with it.
+
+
+
+ Ask, beside the cards. A chat for anything you want to know, answered at the agent's next check-in. It never holds up your answers.
+
+
+
+ A private notebook. Markdown and pictures, one pad per folder. The agent reads a tab only when you start a workflow from it.
+
+
+
+ A clear next step. Every ending says what happened and what to run next, with one button to carry on in the same session.
+
+
+
+ Every skill is a card. The any-time skills sit on the dashboard beside the steps, each with what it does and the command behind it.
+
+
+
+ A git board. Changes, Branches and Sync, opening on your likely next step. It asks before anything is pushed, published or deleted, and it never force-pushes.
+
+
+
That is Planny. He waves when it is your turn, walks while the agent works, and throws his arms up when you approve a phase.
+
+
+
+
+
-
Prefer the terminal?
-
The desktop app is optional, and the workflow, the specs and the skills are the same without it. plan2code --classic keeps the terminal flow, and every skill also runs right in the terminal. Each one asks at the start whether you want the page or the terminal; add --web to skip the question and go straight to the page.
The skills, the plan2code command and, if you say yes, the desktop app. Run it again any time to update. MIT licensed.
-
# the terminal flow
-plan2code --classic
-# or, in your agent
-/plan2code
-/plan2code-1-plan --web plan a REST API for tasks
-
-
-
-
-
-
Install
-
Run it again any time to update.
-
-
Before you start
-
-
Node.js 18 or newer. Check with node --version. No Node? Get it from nodejs.org (the LTS download), or run winget install OpenJS.NodeJS.LTS on Windows, brew install node on macOS, or use nvm on Linux. Then open a new terminal.
-
Start from your project. Open your terminal in the project you want to work on (cd into it) before you run anything. Plan2Code works on the folder you start it in.
-
Ways in.plan2code (Claude Code, Devin or Codex), or type /plan2code in your agent ($plan2code in Codex).
-
No agent yet? Install Claude Code, Codex or Devin first, or let the plan2code command's setup page walk you through it.
+
+
+
Before you start
+
+
Node.js 18 or newer. Check with node --version. No Node? Get it from nodejs.org (the LTS download), or run winget install OpenJS.NodeJS.LTS on Windows, brew install node on macOS, or use nvm on Linux. Then open a new terminal.
+
Git. Check with git --version. The installer is fetched from GitHub with Git, and without it npm stops with spawn git ENOENT. No Git? Get it from git-scm.com, or run winget install Git.Git on Windows, brew install git on macOS, or use your package manager on Linux. Then open a new terminal.
+
Start from your project. Open your terminal in the project you want to work on (cd into it) before you run anything. Plan2Code works on the folder you start it in.
+
Ways in.plan2code (Claude Code, Devin or Codex), or type /plan2code in your agent ($plan2code in Codex).
+
No agent yet? Install Claude Code, Codex or Devin first, or let the plan2code command's setup page walk you through it.
Then, from your project, run plan2code. With the app installed it opens the app, and plan2code --classic keeps the agent in your terminal. Already inside your agent? Type /plan2code ($plan2code in Codex).
+
The app is checked before it is kept. The installer downloads the build for your system (Windows x64, macOS on Apple silicon or Intel, Linux x64) and verifies it against the release's checksum list. This first release is unsigned, so your system may ask you to allow it once. Read the app guide.
+
Back at your prompt with nothing printed? The installer always opens a menu, so no output at all means npm could not reach the repository and hid the reason. git ls-remote https://github.com/jparkerweb/plan2code.git shows why.
then, from your project, run plan2code (Claude Code, Devin or Codex), or type /plan2code in your agent ($plan2code in Codex).
-
It always opens a menu; no output at all means npm could not reach the repository and hid the reason: git ls-remote https://github.com/jparkerweb/plan2code.git shows why.
-
The installer also offers the desktop app. Answer Y to install it: the file is checked against the release's checksum before it is kept. There are builds for Windows x64, macOS (Apple silicon and Intel) and Linux x64, and the app needs Node.js 18 or newer. Plan2Code works without it.
@@ -882,9 +740,12 @@ plan2code --classic
@@ -892,158 +753,165 @@ plan2code --classic
(function () {
var CMD = 'npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git';
var $ = function (i) { return document.getElementById(i); };
+ var calm = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
- /* Copy buttons: the install command, or the slash command in data-copy. */
- function wire(btn) {
- var label = btn.querySelector('.label');
- var text = btn.getAttribute('data-copy') || CMD;
- var timer;
- function done() {
- btn.classList.add('-done');
- label.textContent = 'Copied';
- clearTimeout(timer);
- timer = setTimeout(function () {
- btn.classList.remove('-done');
- label.textContent = 'Copy';
- }, 1800);
- }
- function fallback() {
- var ta = document.createElement('textarea');
- ta.value = text;
- ta.setAttribute('readonly', '');
- ta.style.position = 'fixed';
- ta.style.opacity = '0';
- document.body.appendChild(ta);
- ta.select();
- try { document.execCommand('copy'); done(); } catch (e) {}
- document.body.removeChild(ta);
- }
- btn.addEventListener('click', function () {
- if (navigator.clipboard && navigator.clipboard.writeText) {
- navigator.clipboard.writeText(text).then(done, fallback);
- } else {
- fallback();
+ /* Copy the install command. */
+ var copy = document.querySelector('.copy');
+ var copyTimer;
+ function copied() {
+ copy.textContent = 'Copied';
+ clearTimeout(copyTimer);
+ copyTimer = setTimeout(function () { copy.textContent = 'Copy'; }, 1800);
+ }
+ function copyFallback() {
+ var ta = document.createElement('textarea');
+ ta.value = CMD;
+ ta.setAttribute('readonly', '');
+ ta.style.position = 'fixed';
+ ta.style.opacity = '0';
+ document.body.appendChild(ta);
+ ta.select();
+ try { document.execCommand('copy'); copied(); } catch (e) {}
+ document.body.removeChild(ta);
+ }
+ copy.addEventListener('click', function () {
+ if (navigator.clipboard && navigator.clipboard.writeText) navigator.clipboard.writeText(CMD).then(copied, copyFallback);
+ else copyFallback();
+ });
+
+ /* The window: four moments of one session, played in order until someone picks one. */
+ var BEAT = 6500;
+ var MOMENTS = [
+ { mood: 'wave', st: 'Your move: pick what we are doing today.', term: [
+ ['d', '$ plan2code'], ['g', 'Plan2Code skills loaded'], ['b', '> /plan2code'],
+ ['', 'Dashboard open in this window'], ['d', 'Suggested: Plan']] },
+ { mood: 'wave', st: 'Your turn: 3 questions waiting.', term: [
+ ['b', '> /plan2code-1-plan'], ['', 'Reading src/routes and the schema'],
+ ['', 'The plan stays open until confidence reaches 90%'], ['y', '3 questions waiting on the page']] },
+ { mood: 'work', st: 'Task 6 of 11: deleting a task', term: [
+ ['b', '> /plan2code-3-implement'], ['', 'Phase 3: API endpoints'],
+ ['g', '\u2713 3.1 Register the /tasks routes plugin'], ['g', '\u2713 3.2 GET /tasks with cursor paging'],
+ ['g', '\u2713 3.3 GET /tasks/:id'], ['g', '\u2713 3.4 POST /tasks with a Zod schema'],
+ ['g', '\u2713 3.5 PATCH /tasks/:id'], ['', ' 3.6 DELETE /tasks/:id as a soft delete']] },
+ { mood: 'wave', st: 'Your turn: 1 question waiting.', term: [
+ ['g', '11 of 11 tasks done'], ['', 'Completion report written'],
+ ['y', 'Nothing is marked complete until you approve']] }
+ ];
+ var stage = $('stage'), tb = $('tb'), pl = $('pl'), st = $('st'), stamp = $('stamp'), moments = $('moments');
+ var imgs = $('surface').querySelectorAll('img');
+ var btns = moments.querySelectorAll('button');
+
+ /* The window starts tilted back and lies flat as it comes up the screen. */
+ if (!calm) {
+ var winEl = document.querySelector('.win'), ticking = false;
+ var tilt = function () {
+ ticking = false;
+ var top = stage.getBoundingClientRect().top;
+ var t = Math.max(0, Math.min(1, (top - 90) / (window.innerHeight * 0.55)));
+ winEl.style.setProperty('--tilt', (t * 20).toFixed(2) + 'deg');
+ };
+ window.addEventListener('scroll', function () { if (!ticking) { ticking = true; requestAnimationFrame(tilt); } }, { passive: true });
+ window.addEventListener('resize', tilt);
+ tilt();
+ }
+ var timers = [], at = 0, auto = !calm, seen = false;
+ moments.style.setProperty('--beat', BEAT + 'ms');
+
+ function later(fn, ms) { timers.push(setTimeout(fn, ms)); }
+ function line(l) {
+ var s = document.createElement('span');
+ if (l[0]) s.className = l[0];
+ s.textContent = l[1];
+ var cur = tb.querySelector('.cur');
+ tb.insertBefore(s, cur);
+ tb.insertBefore(document.createTextNode('\n'), cur);
+ }
+ function show(i) {
+ var m = MOMENTS[i], k;
+ at = i;
+ while (timers.length) clearTimeout(timers.pop());
+ for (k = 0; k < imgs.length; k++) imgs[k].classList.toggle('on', k === i);
+ for (k = 0; k < btns.length; k++) btns[k].setAttribute('aria-pressed', String(k === i));
+ moments.classList.toggle('auto', auto);
+ stamp.classList.remove('on');
+ pl.setAttribute('data-mood', m.mood);
+ st.textContent = m.st;
+ tb.textContent = '';
+ var cur = document.createElement('span');
+ cur.className = 'cur';
+ tb.appendChild(cur);
+ m.term.forEach(function (l, n) {
+ if (calm) line(l); else later(function () { line(l); }, 250 + n * 300);
+ });
+ if (i === 3) later(function () {
+ stamp.classList.add('on');
+ pl.setAttribute('data-mood', 'up');
+ st.textContent = 'Phase 3 approved. Phase 4 is next.';
+ line(['g', 'approved: Phase 3 closed']);
+ }, calm ? 0 : 3000);
+ if (auto) later(function () { show((i + 1) % MOMENTS.length); }, BEAT);
+ }
+ [].forEach.call(btns, function (b, i) {
+ b.addEventListener('click', function () { auto = false; show(i); });
+ });
+ [].forEach.call(document.querySelectorAll('.seg button'), function (b) {
+ b.addEventListener('click', function () {
+ var d = b.getAttribute('data-dock');
+ stage.setAttribute('data-dock', d);
+ [].forEach.call(document.querySelectorAll('.seg button'), function (o) {
+ o.setAttribute('aria-pressed', String(o === b));
+ });
+ });
+ });
+ /* Start once the window has been drafted and built, and only while it is on screen. */
+ if ('IntersectionObserver' in window && !calm) {
+ new IntersectionObserver(function (es) {
+ var on = es[0].isIntersecting;
+ if (on && !seen) { seen = true; later(function () { show(0); }, 2400); }
+ else if (on && auto) show(at);
+ else if (!on) while (timers.length) clearTimeout(timers.pop());
+ }, { threshold: 0.35 }).observe(stage);
+ }
+
+ /* The loop: phases tick through build, review, check and commit while it is on screen. */
+ var PHASES = [
+ { name: 'Project setup', cells: ['4 tasks', 'clean', 'npm run build', '9c1e7f0'] },
+ { name: 'Tasks model', cells: ['5 tasks', '2 fixed', 'npm run build', 'a41c9e2'] },
+ { name: 'API endpoints', cells: ['11 tasks', '1 fixed', 'npm run build', '3be07d5'] },
+ { name: 'Errors and docs', cells: ['6 tasks', 'clean', 'npm run build', 'f2206ac'] }
+ ];
+ var WAIT = ['', 'fresh agent', 'npm run build', 'local only'];
+ var NOW = ['building', 'reviewing', 'running', 'committing'];
+ var VERB = ['Building', 'Reviewing', 'Checking', 'Committing'];
+ var rows = $('ledger').querySelectorAll('tr'), pips = $('pips').children, lb = $('lb'), le = $('le');
+ var step = 8, loopTimer = null;
+ function drawLoop() {
+ var done = step >= 16;
+ for (var p = 0; p < 4; p++) {
+ var tds = rows[p].querySelectorAll('td');
+ for (var c = 0; c < 4; c++) {
+ var idx = p * 4 + c, td = tds[c + 1];
+ var s = idx < step ? 'done' : idx === step ? 'now' : 'wait';
+ td.setAttribute('data-s', s);
+ td.textContent = s === 'done' ? PHASES[p].cells[c] : s === 'now' ? NOW[c] : (c === 0 ? PHASES[p].cells[0] : WAIT[c]);
}
- });
- }
- var buttons = document.querySelectorAll('.copy');
- for (var i = 0; i < buttons.length; i++) wire(buttons[i]);
-
- /* The desktop window illustration. */
- var win = $('win'), tb = $('tb'), pl = $('pl'), dot = $('dot'), ns = $('ns'), flow = $('flow'), stText = $('stText');
- var agent = 'Claude Code', lastDock = 'right', busy = false;
- function esc(s) { return s.replace(/&/g, '&').replace(/' + esc(l[1]) + ''; }).join('\n') + '\n';
- }
- function base() {
- lines([
- ['d', '$ ' + agent.toLowerCase().replace(/ /g, '-')],
- ['g', 'Plan2Code skills loaded'],
- ['b', '> /plan2code-3-implement'],
- ['', 'Phase 2: 4 of 6 tasks ticked'],
- ['', 'Checking the last task...'],
- ['d', 'Waiting for your sign-off on the page']
- ]);
- }
- function dock(d) {
- win.setAttribute('data-dock', d);
- if (d !== 'hidden') lastDock = d;
- var bs = document.querySelectorAll('.seg button');
- for (var k = 0; k < bs.length; k++) bs[k].setAttribute('aria-pressed', String(bs[k].getAttribute('data-dock') === d));
- }
- var segs = document.querySelectorAll('.seg button');
- for (var s = 0; s < segs.length; s++) (function (b) {
- b.addEventListener('click', function () { dock(b.getAttribute('data-dock')); });
- })(segs[s]);
- $('vt').addEventListener('click', function () {
- dock(lastDock);
- var f = document.querySelector('.seg button[aria-pressed="true"]');
- if (f) f.focus();
- });
- $('agentSel').addEventListener('change', function (e) {
- agent = e.target.value;
- $('termTitle').textContent = 'Agent Terminal: ' + agent;
- if (!busy) base();
- });
- function mood(m, t) { pl.setAttribute('data-mood', m); stText.textContent = t; }
- function step(n, st) {
- var li = $('f' + n);
- li.setAttribute('data-s', st);
- li.firstChild.textContent = st === 'done' ? '✓' : String(n);
- }
- ns.addEventListener('click', function () {
- if (busy) return;
- busy = true; ns.disabled = true;
- step(1, ''); step(2, ''); step(3, '');
- flow.hidden = false;
- dot.setAttribute('data-s', 'busy');
- var a = agent;
- step(1, 'now'); mood('wave', 'Writing a brief from this session');
- lines([['d', '$ plan2code: building the brief'], ['', 'Reading the session record...'], ['', 'Open task, phase 2: carried into the brief']]);
- setTimeout(function () {
- step(1, 'done'); step(2, 'now'); dot.setAttribute('data-s', 'off');
- mood('none', 'Agent stopped. Starting a fresh one');
- lines([['d', 'Previous ' + a + ' session closed'], ['', 'Starting a fresh ' + a + '...']]);
- }, 1500);
- setTimeout(function () {
- step(2, 'done'); step(3, 'now'); dot.setAttribute('data-s', 'busy');
- mood('rest', 'Fresh agent is reading the brief');
- lines([['g', 'Fresh ' + a + ' started'], ['', 'Reading the brief...'], ['', 'Phase 2: 4 of 6 tasks ticked, picking up at task 5']]);
- }, 2900);
- setTimeout(function () {
- step(3, 'done'); dot.setAttribute('data-s', 'on');
- mood('up', 'Work carried over. Back to it');
- lines([['g', 'Work carried over'], ['b', '> continuing phase 2, task 5'], ['d', 'Waiting for your sign-off on the page']]);
- }, 4300);
- setTimeout(function () {
- flow.hidden = true;
- mood('rest', 'Agent running. Planny is keeping an eye on it.');
- ns.disabled = false; busy = false; base();
- }, 6600);
- });
- base();
-
- /* The workflow map: select a station, show its panel, move Planny beside it. */
- var stations = [].slice.call(document.querySelectorAll('.mst'));
- var arts = [].slice.call($('panel').querySelectorAll('article'));
- var rider = $('rider'), riderPl = rider.querySelector('.planny'), box = $('mapbox');
- var current = null;
- function place() {
- if (!current) return;
- var d = current.querySelector('.mdot').getBoundingClientRect(), b = box.getBoundingClientRect();
- var w = rider.offsetWidth, h = rider.offsetHeight, x, y;
- if (window.matchMedia('(max-width:900px)').matches) {
- x = d.left - b.left - w - 8; y = d.top - b.top + d.height / 2 - h / 2;
- } else {
- x = d.left - b.left + d.width / 2 - w / 2; y = d.top - b.top - h - 3;
+ pips[p].className = (p + 1) * 4 <= step ? 'done' : Math.floor(step / 4) === p ? 'now' : '';
}
- rider.style.transform = 'translate(' + Math.round(x) + 'px,' + Math.round(y) + 'px)';
+ var ph = Math.min(3, Math.floor(step / 4));
+ lb.textContent = done ? 'Loop complete: 4 of 4 phases committed' : VERB[step % 4] + ' Phase ' + (ph + 1) + ' of 4: ' + PHASES[ph].name;
+ le.textContent = 'run ' + (1 + step * 2) + 'm';
}
- function select(st, hash) {
- var id = st.getAttribute('href').slice(1);
- stations.forEach(function (o) { o.removeAttribute('aria-current'); });
- st.setAttribute('aria-current', 'true');
- arts.forEach(function (a) { a.hidden = (a.id !== id); });
- riderPl.setAttribute('data-mood', st.getAttribute('data-mood') || 'rest');
- current = st; place();
- if (hash && history.replaceState) history.replaceState(null, '', '#' + id);
+ function tick() {
+ step = step >= 16 ? 0 : step + 1;
+ drawLoop();
+ loopTimer = setTimeout(tick, step >= 16 ? 4200 : 1300);
+ }
+ if ('IntersectionObserver' in window && !calm) {
+ new IntersectionObserver(function (es) {
+ clearTimeout(loopTimer);
+ if (es[0].isIntersecting) loopTimer = setTimeout(tick, 1300);
+ }, { threshold: 0.4 }).observe($('loopwin'));
}
- stations.forEach(function (st, i) {
- st.addEventListener('click', function (e) { e.preventDefault(); select(st, true); });
- st.addEventListener('focus', function () { if (current !== st) select(st, false); });
- st.addEventListener('keydown', function (e) {
- var n = null;
- if (e.key === 'ArrowRight' || e.key === 'ArrowDown') n = stations[i + 1] || stations[0];
- if (e.key === 'ArrowLeft' || e.key === 'ArrowUp') n = stations[i - 1] || stations[stations.length - 1];
- if (n) { e.preventDefault(); n.focus(); }
- });
- });
- var hs = location.hash && document.querySelector('.mst[href="' + location.hash + '"]');
- select(hs || document.querySelector('.mst[href="#d-plan"]'), false);
- window.addEventListener('resize', place);
- window.addEventListener('load', place);
- if (window.ResizeObserver) new ResizeObserver(place).observe(box);
})();
diff --git a/docs/screenshots/dashboard-plan-dark.webp b/docs/screenshots/dashboard-plan-dark.webp
new file mode 100644
index 0000000..863ea6f
Binary files /dev/null and b/docs/screenshots/dashboard-plan-dark.webp differ
diff --git a/docs/screenshots/dashboard-plan-light.webp b/docs/screenshots/dashboard-plan-light.webp
new file mode 100644
index 0000000..51b57a0
Binary files /dev/null and b/docs/screenshots/dashboard-plan-light.webp differ
diff --git a/scripts/capture-screenshots.mjs b/scripts/capture-screenshots.mjs
index 0a04903..ab7c55d 100644
--- a/scripts/capture-screenshots.mjs
+++ b/scripts/capture-screenshots.mjs
@@ -13,7 +13,7 @@
// The shots use the console's Ocean highlight rather than its default orange:
// it is the console's nearest to the Plan2Code blue the site and README use.
//
-// Shots: dashboard, dashboard-utilities, question, doc, build, signoff, finish, ask, git.
+// Shots: dashboard, dashboard-plan, dashboard-utilities, question, doc, build, signoff, finish, ask, git.
// --compare adds workspace, stop, delete, help, prefs and cleanup: screens the
// docs never show, for checking a change by eye against a "before" set. Its
// --out must be outside docs/screenshots/, so the set is never published.
@@ -64,6 +64,15 @@ const SHOTS = {
scrollTo: ".dash-toggle",
mustShow: ".dash-card:has(.pill.suggested)",
},
+ // The same dashboard in a project with no specs yet, where Plan is the
+ // suggested card: the landing page's first step, before the questions.
+ "dashboard-plan": {
+ workflow: "dashboard",
+ posts: ["dashboard-plan"],
+ fresh: true,
+ scrollTo: ".dash-toggle",
+ mustShow: ".dash-card:has(.pill.suggested)",
+ },
// The utility cards sit even lower: scroll until the Git card is the
// last row in frame ("cmd:" picks a card by its command).
"dashboard-utilities": {
@@ -285,6 +294,15 @@ function makeSampleProject() {
return project;
}
+// The dashboard-plan shot's project: the same name and AGENTS.md, nothing
+// planned yet. It sits in its own folder so both can be called task-api.
+function makeFreshProject() {
+ const project = path.join(SCRATCH, "fresh", "task-api");
+ fs.mkdirSync(project, { recursive: true });
+ fs.copyFileSync(path.join(SCRATCH, "task-api", "AGENTS.md"), path.join(project, "AGENTS.md"));
+ return project;
+}
+
// The Workspace shot's second folder, beside the sample project.
function makeExtraFolder() {
const dir = path.join(SCRATCH, "task-web");
@@ -580,7 +598,7 @@ async function main() {
args: ["--no-first-run", "--no-default-browser-check", "--mute-audio"],
});
for (const name of names) {
- const where = table[name].repo ? makeGitProject() : project;
+ const where = table[name].repo ? makeGitProject() : table[name].fresh ? makeFreshProject() : project;
const { sid, url } = stage(where, table[name]);
try {
if (table[name].ask) await captureAsk(browser, where, sid, url, table[name].ask);
diff --git a/scripts/screenshots/README.md b/scripts/screenshots/README.md
index 0a28ca0..c28cd33 100644
--- a/scripts/screenshots/README.md
+++ b/scripts/screenshots/README.md
@@ -8,6 +8,7 @@ and dark WebP images in `docs/screenshots/`.
| File | Stages |
| --- | --- |
| `dashboard.json` | The dashboard menu, suggesting the next build phase |
+| `dashboard-plan.json` | The dashboard in a project with no specs yet, suggesting Plan (the script builds that project) |
| `question.json` | A Plan session with three questions open (also the base of the Ask shot) |
| `doc.json` | A living document with settled, assumed and draft sections, and its review card |
| `build.json` | A phase being built: the progress bar, the task list and the current task |
diff --git a/scripts/screenshots/dashboard-plan.json b/scripts/screenshots/dashboard-plan.json
new file mode 100644
index 0000000..6d3b6ae
--- /dev/null
+++ b/scripts/screenshots/dashboard-plan.json
@@ -0,0 +1,9 @@
+{
+ "menu": {
+ "note": "Nothing is planned in task-api yet. Plan is the place to start.",
+ "recommend": "plan2code-1-plan"
+ },
+ "agent": {
+ "status": "waiting"
+ }
+}
diff --git a/scripts/test-getting-started.mjs b/scripts/test-getting-started.mjs
index c3503ae..071facb 100644
--- a/scripts/test-getting-started.mjs
+++ b/scripts/test-getting-started.mjs
@@ -31,7 +31,8 @@ function blockOf(file) {
for (const file of DOCS) {
test(`${file} tells a newcomer how to get started`, () => {
const block = blockOf(file);
- for (const needle of ['Node.js 18', 'node --version', 'nodejs.org', '/plan2code', '$plan2code']) {
+ // Git is a prerequisite too: npm fetches the installer with it (git+https).
+ for (const needle of ['Node.js 18', 'node --version', 'nodejs.org', 'git --version', 'git-scm.com', '/plan2code', '$plan2code']) {
assert.ok(block.includes(needle), `${file} is missing "${needle}" in its "Before you start" block`);
}
assert.match(block, /project you want to (work on|work in)/, `${file} does not say to start from your project`);