Release 3.1.1: relicense under Apache 2.0 and rewrite the README and site around the six steps
AI Assisted
No files matched your search
@@ -32,20 +32,32 @@ body:
|
||||
label: Which skill or tool?
|
||||
options:
|
||||
- Dashboard (/plan2code)
|
||||
- Init / Init Update
|
||||
- Init / Init update
|
||||
- Pathfinder
|
||||
- Plan / Revise Plan
|
||||
- Quick Task
|
||||
- Plan / Revise plan
|
||||
- Document
|
||||
- Implement / Implement + Review
|
||||
- Review
|
||||
- Finalize
|
||||
- Handoff
|
||||
- Web console (page itself)
|
||||
- Implementation Loop (desktop app)
|
||||
- Finalize
|
||||
- Quick task
|
||||
- Review
|
||||
- X-ray
|
||||
- Diagnose
|
||||
- PR Prep
|
||||
- Test
|
||||
- Dead Code
|
||||
- Update dependencies
|
||||
- UI Prototype
|
||||
- Git
|
||||
- Changelog
|
||||
- Handoff
|
||||
- Learning
|
||||
- Activities (the games)
|
||||
- Web console (page itself)
|
||||
- The plan2code launcher (command line)
|
||||
- Installer
|
||||
- Metrics
|
||||
- Status line
|
||||
- Installer
|
||||
- Other
|
||||
validations:
|
||||
required: true
|
||||
@@ -55,6 +67,7 @@ body:
|
||||
label: Where were you working?
|
||||
options:
|
||||
- Web console
|
||||
- Desktop app
|
||||
- Terminal
|
||||
- Not sure
|
||||
validations:
|
||||
@@ -64,7 +77,7 @@ body:
|
||||
attributes:
|
||||
label: Plan2Code version
|
||||
description: Found in version.json, the installer banner, or at the bottom of the web console's Help dialog.
|
||||
placeholder: "2.4.0"
|
||||
placeholder: "3.1.0"
|
||||
- type: input
|
||||
id: environment
|
||||
attributes:
|
||||
|
||||
@@ -1 +1,11 @@
|
||||
blank_issues_enabled: false
|
||||
contact_links:
|
||||
- name: Read the docs
|
||||
url: https://plan2code.jparkerweb.com
|
||||
about: The guides, the quick reference and the walkthrough.
|
||||
- name: Desktop app guide
|
||||
url: https://github.com/jparkerweb/plan2code/blob/main/docs/desktop-app.md
|
||||
about: Install, start, update and the not-code-signed prompts of the desktop app.
|
||||
- name: Report a security problem
|
||||
url: https://github.com/jparkerweb/plan2code/security/advisories/new
|
||||
about: Report a vulnerability privately, not as a public issue.
|
||||
@@ -0,0 +1,23 @@
|
||||
# Plan2Code guides
|
||||
|
||||
The long-form guides that sit beside the [README](../README.md). The README is the short version: what Plan2Code is and how to install it.
|
||||
|
||||
## Using
|
||||
|
||||
- [walkthrough.md](walkthrough.md): one feature from a sentence to archived specs, session by session.
|
||||
- [web-console.md](web-console.md): the web console guide, from the dashboard to the last sign-off.
|
||||
- [steps.md](steps.md): what each of the six steps asks, writes and hands on.
|
||||
- [launcher.md](launcher.md): the `plan2code` command, its flags, and using an agent other than Claude Code, Devin or Codex.
|
||||
- [activities.md](activities.md): the small games behind the die in the console's top bar.
|
||||
- [status-line.md](status-line.md): the optional three-line Claude Code status bar.
|
||||
|
||||
Also: [QUICK-REFERENCE.md](../QUICK-REFERENCE.md) (the one-page card) and [docs/desktop-app.md](../docs/desktop-app.md) (the desktop app and the Implementation Loop).
|
||||
|
||||
## Maintaining
|
||||
|
||||
- [web-console-internals.md](web-console-internals.md): how the console works, its security model, every route, driving it by hand and refreshing the screenshots.
|
||||
- [web-console-design.md](web-console-design.md): why the console is shaped the way it is.
|
||||
- [metrics.md](metrics.md): `plan2code-metrics`, measuring and improving the prompts themselves.
|
||||
- [test-bot.md](test-bot.md): `plan2code-bot`, the harness that runs the whole workflow unattended.
|
||||
|
||||
For the code layout, see [AGENTS.md](../AGENTS.md).
|
||||
@@ -0,0 +1,43 @@
|
||||
# The plan2code command and other agents
|
||||
|
||||
The command-line side of Plan2Code: what `plan2code` does when you run it, and how to use an agent other than Claude Code, Devin or Codex. Back to the [README](../README.md#install-and-start).
|
||||
|
||||
## About the plan2code command
|
||||
|
||||
Install (`I`) adds `plan2code` as a global command (Advanced `A` → `D` adds just the command). Run it from any project and the Plan2Code
|
||||
dashboard opens right there, in **Claude Code**, **Devin** or **Codex**. With more than one installed it asks which and
|
||||
remembers your pick; `plan2code --cli claude`, `--cli devin` or `--cli codex` skips the question, and `--model <name>`
|
||||
chooses the model. It works in cmd, PowerShell, Git Bash, macOS and Linux shells, and needs the
|
||||
Claude Code, Devin or Codex CLI on your `PATH`. After you pick the agent it asks whether to turn its
|
||||
permission prompts off (Yes by default; `--permission-mode bypassPermissions` in Claude Code, `--permission-mode bypass`
|
||||
in Devin, `--dangerously-bypass-approvals-and-sandbox` in Codex, a custom agent's bypass arguments, and no question for a
|
||||
custom agent that has none; for Codex the question names its sandbox, which that flag turns off too). It asks on every
|
||||
launch and remembers no answer. `plan2code --keep-permissions` keeps the prompts without asking, and
|
||||
`plan2code --bypass-permissions` turns them off without asking. With no terminal to ask on (a script or a pipe) the
|
||||
prompts stay on unless `--bypass-permissions` is given. The installer then offers a desktop shortcut (answer `y`),
|
||||
which opens a folder menu first: Choose a folder, with the project folders you opened lately under it (with none yet, it goes straight to the folder dialog). In a terminal, `plan2code` offers the same recent folders as a numbered menu. Uninstalling (`U`, or `plan2code uninstall` from any terminal) removes both.
|
||||
|
||||
## Using another agent CLI, or none yet
|
||||
|
||||
Plan2Code runs inside an AI coding agent CLI. With no agent it can run (none of Claude Code,
|
||||
Devin or Codex, and no working custom agent),
|
||||
`plan2code` opens a setup page in your browser (the web console runs it, so no agent is needed).
|
||||
The page lists each agent as **Found**, **Found outside PATH** or **Not found**, with its install
|
||||
commands for your system, a Copy button per command and an **Install page** link. Install one and
|
||||
press **Check again**: no restart needed. An agent found outside `PATH` gets **Use it from here**,
|
||||
which saves where it was found so you never touch `PATH` yourself. Below the list sit five starter
|
||||
templates (GitHub Copilot CLI, OpenCode, Gemini CLI, Pi and Cursor CLI) for agents Plan2Code does not ship.
|
||||
**Start with this agent** carries the run straight on in the same tab, onto the new agent's
|
||||
dashboard. Naming a built-in that is missing with `--cli <name>` opens the same page on that agent
|
||||
(a missing custom agent prints its own steps and exits 127). In the
|
||||
desktop app a **Set up an agent** button opens the same page in the window and returns to the
|
||||
launch card with the found agent picked. Where no page can open, such as over SSH or with no
|
||||
display, `plan2code` prints the install commands and install pages and exits with code 127.
|
||||
|
||||
Once an agent is running, to use a different agent CLI, open the web console's **User Preferences → Agents & models** and add it: a name, the
|
||||
command, and (optionally) its arguments, the start prompt, arguments for skipping permission prompts, and
|
||||
how it takes a model. Custom agents are saved in `~/.plan2code/agents.json` and used by both the
|
||||
`plan2code` command (listed after the built-ins; `--cli <id>` picks one) and the desktop app's picker. The
|
||||
`/plan2code` start prompt only does something in an agent that loads the installed Plan2Code skills; for
|
||||
any other, leave the start prompt blank and start a skill yourself. Details in
|
||||
[web-console.md](web-console.md#agents--models).
|
||||
@@ -1,4 +1,4 @@
|
||||
# Metrics & Self-Improvement
|
||||
# Metrics and Self-Improvement
|
||||
|
||||
`plan2code-metrics` closes the loop on the workflow itself: it collects data from your finished
|
||||
specs, aggregates it across runs and prompt generations, then uses AI to diagnose which step is
|
||||
|
||||
@@ -0,0 +1,107 @@
|
||||
# The six steps in detail
|
||||
|
||||
Back to the [README](../README.md#the-workflow). 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)
|
||||
|
||||
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.
|
||||
|
||||
1. **Name the destination** — one or two lines fixing what this effort is finding its way to. Settled
|
||||
first, because it fixes scope. It also asks where the map should live: **local files** under
|
||||
gitignored `specs/` (private, solo — the default), or **GitHub Issues** (a map issue with one
|
||||
sub-issue per decision, native blocking, so your team can see and work the frontier in the tracker).
|
||||
2. **Chart the map** — a breadth-first grilling surfaces the open decisions. Anything you can phrase
|
||||
*sharply* becomes a question file; anything you can only sense stays listed as fog.
|
||||
3. **Clear the questions one at a time** — resolving one burns off the fog behind it, graduating
|
||||
whatever just became sharp into new questions. After each decision it offers a menu: take the next
|
||||
question here, or start fresh — recommended after about three, to keep the agent sharp.
|
||||
Ask for a **brief** at any point and you get a dated, plain-English summary of what has been
|
||||
decided, what is still open, and what is next — meeting minutes, with no jargon in them.
|
||||
4. **Hand off** — when nothing is left to decide, it writes a `PLAN-DRAFT` that
|
||||
`/plan2code-1-plan` resumes from at Phase 4, with requirements, context, and scope already
|
||||
answered.
|
||||
|
||||
**Question types:** `grill` (a decision only you can make — the default) · `research` (a fact gates
|
||||
it; background agents resolve these, several in parallel) · `sketch` (you need something concrete to
|
||||
react to) · `legwork` (manual work that has to happen before a decision is possible).
|
||||
|
||||
It never answers its own questions, and it **plans, it never builds.** When the urge to just build it
|
||||
arrives, the map is done. Skip Step 0 entirely when you already know what you're building.
|
||||
|
||||
**Out:** `specs/<feature>/pathfinder/map.md` + `questions/` (or a `pathfinder:map` issue and its
|
||||
sub-issues) → `PLAN-DRAFT-<date>.md`. The draft is always a local file — that is what Step 1 reads.
|
||||
|
||||
## 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 seven phases, stopping for you after each: requirements
|
||||
analysis · system context (reading your actual codebase) · scope assessment (a large project saves and
|
||||
resumes in a fresh session) · tech stack (needs your explicit sign-off) · architecture design ·
|
||||
technical specification · transition decision.
|
||||
|
||||
It won't finalize below **90% confidence**, and every assumption it makes is written into the draft.
|
||||
|
||||
**In:** a description of the feature. **Out:** `PLAN-DRAFT-<date>.md` + `PLAN-CONVERSATION-<date>.md`
|
||||
|
||||
## 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.
|
||||
|
||||
The overview also identifies the **parallel execution groups**: phases with no shared files or
|
||||
dependencies, safe to run in separate agents at once.
|
||||
|
||||
**In:** the `PLAN-DRAFT`. **Out:** `overview.md` + `phase-1…N.md`
|
||||
|
||||
## 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.
|
||||
|
||||
One phase per conversation. It won't run tests unless the phase says to.
|
||||
|
||||
**In:** `specs/<feature>/overview.md`. **Out:** working code, and updated checkboxes.
|
||||
|
||||
Want a second pair of eyes before you sign off? `/plan2code-3-implement-review` builds the phase the
|
||||
same way, runs a focused review and the fixes you pick, and only then asks for approval.
|
||||
|
||||
## 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 —
|
||||
and the review pass is read-only. It fixes things only if you ask, and verifies each fix afterwards.
|
||||
|
||||
Spec-aware when `specs/` exists, and works fine without it. Most useful right after a planning or
|
||||
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
|
||||
like this.
|
||||
|
||||
**In:** `specs/<feature>/overview.md`. **Out:** archived specs.
|
||||
@@ -9,7 +9,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.
|
||||
- **Node.js 18 or newer** (22 or newer if you install Claude Code with npm). 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).
|
||||
@@ -96,7 +96,7 @@ Parallel execution groups: Phase 3 and Phase 4 don't share files.
|
||||
## Sessions 3 to N: Implement, one phase each
|
||||
|
||||
Look at the session meter in the top bar first. Plan and Document add 2 points each, so after
|
||||
those two the meter is at 4: **Session: getting long**, in yellow. That is the cue to close this
|
||||
those two the meter is at 4: **Conversation: getting long**, in yellow. That is the cue to close this
|
||||
console session and start a fresh one for the build (run `plan2code` again). This is the first of
|
||||
the four rules:
|
||||
|
||||
@@ -134,7 +134,7 @@ Repeat. A fresh session each time. It always finds the next open phase itself.
|
||||
When you reach a parallel group, it offers you the choice: open a second agent, take the other
|
||||
phase, and the `[/]` marks keep them from colliding.
|
||||
|
||||
Pick **Implement + review** instead when review should run automatically before phase approval.
|
||||
Pick **Implement + Review** instead when review should run automatically before phase approval.
|
||||
**Review** remains available on the dashboard for an independent second opinion at any other time.
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,293 @@
|
||||
# The web console, inside
|
||||
|
||||
For people who change the console or drive it by hand: how it works, the security model, every route, and how to refresh the screenshots. Using the console? Read [the web console guide](web-console.md) instead.
|
||||
|
||||
## How it works
|
||||
|
||||
Nothing is installed. The skills ship a small zero-dependency Node server
|
||||
(`references/web-console/`), and the workflow step starts it when you say yes.
|
||||
|
||||
```
|
||||
agent server (detached) your browser
|
||||
| | |
|
||||
|-- open (binds the port, starts ->| |
|
||||
| the server AND the browser) ---|---------------------------->|
|
||||
|<-- http://127.0.0.1:PORT/s/TOK/ |<---- the page, first state -|
|
||||
| | already inside it |
|
||||
|-- post the first questions ----->|---- pushed to the page ---->|
|
||||
|-- wait --seconds 240 ----------->| |
|
||||
| (returns every 4 minutes with | |
|
||||
| progress, then waits again) |<---- you press Send --------|
|
||||
|<-- your answers -----------------| |
|
||||
```
|
||||
|
||||
The server runs detached rather than as a background task of the agent, because
|
||||
agent background tasks get killed at various timeouts, and that would take your
|
||||
half-finished answers with them.
|
||||
|
||||
**It is built to show you something fast.** A browser takes most of a second to
|
||||
turn up after it is asked, so `open` binds the page's port itself and sends the
|
||||
browser there before the server has even finished starting; the server takes
|
||||
the port over a moment later, and the browser's request waits for it rather
|
||||
than being refused. The page arrives with the session already inside it, so it
|
||||
draws the real screen without asking for anything first, in your own theme and
|
||||
colors from the first frame. On a Windows laptop the page is in front of you in
|
||||
roughly the time the browser itself takes to open.
|
||||
|
||||
**It stays up while the page is open.** The page pings it every few seconds, so
|
||||
the idle clock never runs down while you are there. Close the tab and it shuts
|
||||
itself down about two minutes later; it stops after four hours unless answers
|
||||
you sent are still waiting for the agent, and the agent stops it outright when
|
||||
the session ends.
|
||||
|
||||
**The setup session hands its tab to the agent it finds.** A `setup` session is
|
||||
agent-less: nothing reads its sends, so the page's agent-silence and question
|
||||
rules are switched off and only the idle deadline ends it. The `plan2code`
|
||||
launcher started the session and polls it for a pick; **Start with this agent**
|
||||
posts an `__start` action the launcher collects, and it spawns that agent with
|
||||
two environment variables, `PLAN2CODE_SETUP_ANNOUNCE` (the setup server's
|
||||
address) and `PLAN2CODE_SETUP_TOKEN` (a per-session token). The new agent's own
|
||||
`open` then POSTs its sign-in URL to `POST /handover` on the setup server
|
||||
instead of opening a browser; the token guards the route, the setup page gets a
|
||||
`move` event on its `/events` stream carrying the URL, and the tab follows it
|
||||
onto the new session. Inside the desktop app none of this runs: `open` finds no
|
||||
setup variables (the launcher scrubs the app ones from the setup console it
|
||||
starts), the page tells the app `agent-found` instead, and the app closes the
|
||||
setup page and picks the agent itself.
|
||||
|
||||
That also means **the server routinely outlives the agent**. It is the agent, not
|
||||
the server, that reads your answers, and the two fail separately. The page tells
|
||||
the two apart: the **?** button at the top right opens Help, whose *What this
|
||||
page is* tab says which halves are talking right now (and *When something
|
||||
looks stuck* covers what to check), and Planny stops looking busy once
|
||||
nothing is listening rather than spinning at you indefinitely.
|
||||
|
||||
**State lives in three places**, and none of them is your repository (the one
|
||||
exception being the note attachments the agent keeps for a spec, above):
|
||||
|
||||
| Where | What | Survives |
|
||||
| --- | --- | --- |
|
||||
| `~/.plan2code/console/sessions/<id>/` | the questions, your draft, your answers | 30 days after the session was last touched |
|
||||
| `~/.plan2code/console/sessions/<id>/workspace.json`, `ledger.ndjson`, `workspace-cursor.json` | the workspace's folders (paths, names, descriptions — never their contents), the session meter's events, and how far the agent has been told of workspace changes. Kept beside the session, so they outlive every dashboard hop | with the session |
|
||||
| `~/.plan2code/console/sessions/<id>/uploads/` | images and documents attached to notes and quick questions | 30 days after the session was last touched |
|
||||
| `~/.plan2code/handoffs/<id>.md`, `<id>.json` | each handoff's document, and which checkout, spec and skill it belongs to and whether it was picked up (`handoffs.mjs` is their one owner) | 30 days after it was last touched, picked up or not |
|
||||
| `~/.plan2code/notepads/<folder-name>-<12 hex>/` | your notebook for one folder: `meta.json`, `tabs.json` and, per tab, `tabs/<id>/note.md` and `tabs/<id>/images/` (`notepads.mjs` is their one owner; the agent never reads them, except a tab you send) | until you delete it through Cleanup, which offers it once its newest file is 30 days old |
|
||||
| `~/.plan2code/console/looks.json` | your role, theme, colors, sounds and card width, the Show Activities and Play activity sounds switches (`hideActivities`, `activitySounds`), the last activity picked (`lastActivity`), best scores (flat `activityBest<Id>` keys: `activityBestSnake`, one per Mini golf course from `activityBestGolfPirate` to `activityBestGolfFrost`, `activityBestTrails`, `activityBestBugs`, `activityBestDrive`, `activityBestStack`, `activityBestBumper`, `activityBestRapids`, `activityBestFuse`, `activityBestHop`, `activityBestBounce`, `activityBestGhoul`, `activityBestFlock`) and each game's memo (`activityMemo<Id>`: Snake's surprises found, Light Trails' furthest arena, Bug Hunt's bugs, bosses and power-ups found, Sunset Drive's roads found, Stack Deploy's highest floor, Bumper Ring's furthest arena, Rapids Run's furthest dam, Hot Potato's furthest venue, Crossing Rush's furthest zone, Bounce Road's furthest stage, Ghoul Rush's most stages cleared in a run, Flock Dash's furthest stage) | always |
|
||||
| `~/.plan2code/console/subagents.json` | your Subagents switch, instruction and limit, per project folder and skill | always |
|
||||
| `~/.plan2code/console/sessions/<id>/subagents-setting.json`, `subagents-cursor.json` | this session's copy of the switch, and how far the agent has been told of it | with the session |
|
||||
| `~/.plan2code/agents.json` | your custom agent CLIs (User Preferences → Agents & models), read by the `plan2code` command and the desktop app | always |
|
||||
| your system temp directory | the port, process id and session token | until reboot |
|
||||
|
||||
Each of the workspace and meter files has exactly one writer: the server owns
|
||||
`workspace.json` (the page changes it only through the `/workspace` routes
|
||||
under Security), and `console.mjs` owns `ledger.ndjson` and
|
||||
`workspace-cursor.json`. The meter's count is never stored; it is folded from
|
||||
the ledger every time (`public/meter.js`), so a repeated `post` never counts
|
||||
twice. The logic lives in small pure modules the tests import directly —
|
||||
`public/workspace.js` (names, the footer label, the change lines the agent
|
||||
reads), `public/meter.js` and `public/mentions.js` (the `@name` popover) — and
|
||||
**Browse…** runs the per-OS picker in `picker.mjs`, copied from the
|
||||
`plan2code` launcher and kept in step with it by a test.
|
||||
|
||||
**Old sessions clean themselves up.** Each time a session opens, whole session
|
||||
folders nobody has touched for 30 days are deleted — questions, drafts,
|
||||
answers, uploads and all, paused or not — along with stray scratch files
|
||||
(`.json` / `.mjs`) left at the top of `~/.plan2code/console/` for as long, and
|
||||
handoffs in `~/.plan2code/handoffs/` untouched for as long, both files each.
|
||||
Your `looks.json` and the `console-dir` pointer are never touched, and neither
|
||||
is the session being opened. Nothing of value goes with them: the page is
|
||||
never the record, `specs/` in your project is.
|
||||
|
||||
**Or clean up on demand.** *User Preferences → System → Cleanup* → **Find files to
|
||||
clean up** lists, with sizes, everything in `~/.plan2code/` that is not
|
||||
needed: sessions untouched for 30 days (never the one you are in), anything at
|
||||
the top of `~/.plan2code/console/` other than `sessions/`, `runtime/`,
|
||||
`looks.json`, `workspaces.json`, `loop-setup.json`, `loop-reports.json`,
|
||||
`subagents.json`, `pr-hosts.json`, `console-dir` and `update-check.json`, and
|
||||
anything at the top of `~/.plan2code/` other than `console/`, `bin/`,
|
||||
`launcher.json`, `install.json` (what you installed, which `plan2code update`
|
||||
reads), `models.json`, `handoffs/` (old handoffs go by age, above),
|
||||
`notepads/`, `app/` and `app.json` (the desktop app and its settings) and
|
||||
`agents.json` (your custom agents). Each notebook whose newest file is 30 days old or
|
||||
more is listed as one item, *Notebook for* its folder, and goes whole; no
|
||||
automatic sweep ever removes one. It also lists each
|
||||
folder in the project's `specs--completed/` whose newest file is more than 30
|
||||
days old: archived specs Finalize moved there. Only a folder git tracks is
|
||||
deleted: `specs--completed/` is usually gitignored, so git couldn't restore
|
||||
it, and Cleanup keeps it and says why instead. A stray is listed once
|
||||
it has sat untouched for an hour, so a lock or temp file another session is
|
||||
writing right now is never caught. **Delete N items** removes
|
||||
only the rows you left ticked. A console running from another home
|
||||
(`PLAN2CODE_CONSOLE_HOME`) only ever looks inside that home.
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
It is a local dev server that reads files in your project (never writing to it)
|
||||
and keeps its own state in your home folder, so it is built to be boring about
|
||||
this:
|
||||
|
||||
- Bound to `127.0.0.1` only, never `0.0.0.0`. Not reachable from your network.
|
||||
- A `Host` header allow-list, which is what stops a website you happen to be
|
||||
visiting from talking to it through a DNS rebinding trick.
|
||||
- A 128-bit token in the link, swapped for an `HttpOnly; SameSite=Strict` cookie
|
||||
on first load so it leaves your address bar, your history and any screenshot.
|
||||
- A strict Content Security Policy with no inline script allowed.
|
||||
- Markdown written by the agent is turned into page elements directly and never
|
||||
into an HTML string, so a document that quotes a hostile README cannot run
|
||||
anything. It shows up as text, which is what it is.
|
||||
- Uploads are named by the server (`<uuid>.jpg`, or `<uuid>.<ext>` with the
|
||||
extension taken from the allow-list, via `crypto.randomUUID()`), never by the
|
||||
file name you sent, and live only under the session's own `uploads/`. The
|
||||
server checks the bytes: a JPEG header for images (4 MB cap), and for
|
||||
documents a `%PDF-` header or strict UTF-8 with no NUL byte (10 MB cap).
|
||||
Documents are served back only under a fixed type (`application/pdf`, or
|
||||
`text/plain` for text and code) with `nosniff` (and `sandbox` on text), so
|
||||
the Sent box can link them. A send may only point at
|
||||
uploads inside that session's `uploads/`, images in `images` and documents
|
||||
in `files`.
|
||||
|
||||
### Routes
|
||||
|
||||
The upload routes, the send, the overview and handoff reads, the workspace and the notebook. Like every page route, they are on `127.0.0.1`
|
||||
behind the session cookie, and the ones that write also check the request's
|
||||
origin.
|
||||
|
||||
| Route | Does |
|
||||
| --- | --- |
|
||||
| `POST /upload` | Raw bytes, original name in `x-p2c-name`. `Content-Type: image/jpeg`: writes `uploads/<uuid>.jpg` and answers `{ ok, id, kind: "image", path, url, name, size }`; not a JPEG → 415, over 4 MB → 413. `Content-Type: application/octet-stream`: a document, its extension from the name's allow-listed extension; writes `uploads/<uuid>.<ext>` and answers `{ ok, id, kind: "file", path, name, size }` with no `url`; not an allowed extension or contents that do not match → 415 `type`, over 10 MB → 413. Any other content type → 415. |
|
||||
| `GET /uploads/<id>.<ext>` | Serves an upload: an image as `image/jpeg` (the thumbnail after a reload), a document as `application/pdf` or `text/plain; charset=utf-8` with `nosniff` and, on text, `Content-Security-Policy: sandbox`. Only `<uuid>.<allowed ext>` names under `uploads/`; anything else is 404. |
|
||||
| `DELETE /uploads/<id>.<ext>` | Deletes an image or document removed before sending. 204, or 404 if it is not there. |
|
||||
| `POST /submit` | The Send. A note may carry `images` and `files`, each `[{ path, name }]`: at most 5 together, images in `images` and documents in `files`, every path inside this session's `uploads/`, otherwise 400. |
|
||||
| `POST /chat` | A Quick question `{ text, about?, images?, files?, conversation }`, or `{ reset: true, conversation }` for New conversation. Appended to the session's `chat.ndjson`. 400 `too-long` (over 4,000 characters), `image`, `file` or `bad`; 409 `offline`, `stale` or `limit` (10 per conversation). Never refused because a card send is still uncollected. |
|
||||
| `POST /chat/decision` | Approve or Decline on an edit the agent proposed: `{ re, decision, text?, conversation }`. Once per proposal; does not count toward the 10. |
|
||||
| `GET /overview?spec=specs/<name>[&file=map\|draft]` | The Overview tab's read of `<spec>/overview.md` (or, with `file=`, the Map tab's `pathfinder/map.md` or the Plan draft tab's live `PLAN-DRAFT-*.md`), as `text/markdown` with `cache-control: no-store` and the file's spec-relative name, URL-encoded, in `x-spec-file`. A missing file is a 204. On the dashboard `spec` must be one of the scanned specs; elsewhere the session's own spec is used. The file's real path must stay inside the project, so `../`, absolute paths and symlinks pointing out all get the same 204 as a missing file, as does an unscanned `spec` or an unknown `file`. |
|
||||
| `GET /agents-doc[?file=<name>]` | The Dashboard's AGENTS.md tab: `AGENTS.md` (the default) or one `.agents-docs/<name>.md`, as `text/markdown` with `cache-control: no-store`. A dashboard only; any other file name, a missing file or a path that leaves the project is a 204. |
|
||||
| `GET /prototypes?spec=specs/<name>` | The Prototypes tab's list: `{ files: [{ name, kind }] }` (`kind` `md` or `html`) for the files directly in `<spec>/prototypes/`, or a 204 when there are none. The spec is chosen as for `/overview`. |
|
||||
| `GET /prototype?spec=specs/<name>&name=<file>.md` | One `.md` from `<spec>/prototypes/`, as `text/markdown` with `cache-control: no-store`; any other name, a missing file or a path that leaves the folder is a 204. |
|
||||
| `POST /open-prototype` | `{ spec, name }`: opens one `.html` from `<spec>/prototypes/` in the person's default browser. 404 for any other name, 500 when no browser could start. |
|
||||
| `GET /handoff?id=<id>` | *Read it all*: the handoff's `.md` from `~/.plan2code/handoffs/`, as `text/markdown` with `cache-control: no-store`. A dashboard only, and only an id its own scan listed: a used, unknown or malformed id is 404. |
|
||||
| `POST /learning/pause` | Pause for me: `{ paused: boolean }` (origin-checked; anything else is 400 `bad-request`, and 409 `not-on` unless Learning is On or Paused for you). Writes the personal pause on this machine only (`pause.json` under `~/.plan2code/learning/<key>/`), the server's only write for Learning, and repaints the row with no agent. |
|
||||
| `GET /learning/state` | The Learning row's state worked out now, `{ state, pausedSince, waiting, oldestDays }` (`{}` when the project's settings file is from a format it cannot read), with `cache-control: no-store`. |
|
||||
| `GET /learning/lessons` | Open the lessons, read only: `{ files: [{ name, title, text }] }` from the project's lessons (`.plan2code/lessons/`, saved with the repository), `general.md` first, then the other `.md` files in name order (plain files only, at most 100 of 512 KB each), with `cache-control: no-store`. |
|
||||
| `GET /workspace` | The Workspace dialog's list: folders, `missing`, `remote` and the agent's folder `issues`. `?check=1` re-checks every folder on disk first. |
|
||||
| `POST /workspace/add` | `{ path, name?, description? }`. The path is resolved against the folder the session started in (`~` expanded) and must be a folder: 400 `not-a-folder`, `duplicate` (with its `name`; compared case-insensitively on Windows and macOS), `bad-name`, or `name-taken` with a `suggest`. Answers the new entry, `nested: true` when it sits inside another folder in the list. |
|
||||
| `POST /workspace/edit` | `{ id, name?, description? }`. Renames or re-describes one folder: 400 `bad-name` / `name-taken`, 404 `unknown`. |
|
||||
| `POST /workspace/remove` | `{ id }`. 400 `original` for the folder the session started in, 404 `unknown`. |
|
||||
| `POST /workspace/browse` | Opens the system folder picker and answers `{ path }` or `{ cancelled: true }`; never adds anything itself. 409 `busy` while one is open, 404 `no-picker` when the session looks remote or no picker exists. |
|
||||
| `GET /notepad[?tab=<id>]` | The notepad for the folder this session runs in: `{ tabs: [{ id, name, sent? }], last, tab: { id, text, savedAt, images: [{ id, url, thumb }] } | null }`, with the tab's `text`, `savedAt` and `images` repeated at the top. Without `tab` it answers the last one used; 404 `no-such-tab` for an id it does not have. A notepad in the first shape answers one virtual tab, Notes. Reading never creates or moves a file. |
|
||||
| `POST /notepad/text?tab=<id>` | `{ text }`. Saves that tab's `note.md` and answers `{ ok, savedAt }`; 400 `bad`, 404 `no-such-tab`, 413 `too-long` (over 1 MB). |
|
||||
| `POST /notepad/image?tab=<id>` | Raw `image/jpeg` (the page re-encodes every picture first). Writes the tab's `images/<uuid>.jpg` and answers `{ ok, id, url }`; 415 `not-jpeg`, 413 `too-large` (over 4 MB), 409 `too-many` (200 pictures in the tab). |
|
||||
| `POST /notepad/thumb?id=<uuid>&tab=<id>` | Raw `image/jpeg`: that picture's thumbnail. 404 `not-found` or `no-such-tab`, 415 `not-jpeg`, 413 `too-large`. |
|
||||
| `POST /notepad/image/delete?tab=<id>` | `{ id }`. Deletes a picture and its thumbnail; 404 `not-found` or `no-such-tab`. |
|
||||
| `POST /notepad/tab` | `{ name }`. Makes a tab, which becomes the last one used, and answers `{ ok, id, name }`; 400 `bad-name`, 409 `duplicate-name` (any case) or `too-many-tabs` (20). |
|
||||
| `POST /notepad/tab/rename` | `{ id, name }`. Answers `{ ok, id, name }`; 400 `bad-name`, 404 `no-such-tab`, 409 `duplicate-name`. |
|
||||
| `POST /notepad/tab/delete` | `{ id }`. Removes the tab from the index, then its folder (text and pictures); 404 `no-such-tab`. |
|
||||
| `POST /notepad/tab/order` | `{ order: [id] }`, every current id exactly once; 400 `bad` otherwise. |
|
||||
| `POST /notepad/tab/last` | `{ id }`. Remembers the open tab; 404 `no-such-tab`. |
|
||||
| `POST /notepad/tab/sent` | `{ id, workflow, spec? }`. Records that the tab was sent (`workflow` one of `pathfinder`, `plan`, `quick-task`, `revise-plan`, `diagnose`, `ui-prototype`; `spec` like `specs/<name>`) as `sent: { workflow, spec?, at }` on its `tabs.json` entry, shown back in `GET /notepad`'s `tabs`. The page posts it only after the Send that carried the filled box; 400 `bad-sent`, 404 `no-such-tab`. |
|
||||
| `GET /notepad/images/<tab>/<uuid>.jpg`, `<uuid>.thumb.jpg` | Serves a picture or its thumbnail as `image/jpeg`, only by a tab id and a UUID name, a regular file (never a link) whose real path stays inside `~/.plan2code/notepads/`; anything else is 404. |
|
||||
| `POST /subagents` | `{ on, instruction, max }` (`instruction: null` for the shipped default). Saves the switch for this project and skill and answers `{ ok, setting }`; 400 `not-offered` on a skill without the switch, `bad`, `too-long` (over 2,000 characters) or `max` (outside 1 to 20). |
|
||||
| `GET /agents` | The agents view's data: your custom agents and the shipped built-ins and templates, each entry merged with its lookup result `{ state, path, where, folder }`: `state` is `found` (on PATH), `outside` (saved Windows PATH, npm's global folder or an install folder) or `missing`, and `where` says which search found it. Built-ins carry their `install` lines for the server's OS only. |
|
||||
| `POST /agents` | `{ agents, replace? }`. Saves the custom-agent list to `~/.plan2code/agents.json`, validated first (400 `{ error, index, field }`); 409 while the file holds entries `GET /agents` could not read, unless `replace: true`. |
|
||||
| `POST /agents/test` | `{ command }`. Where a command would run from (`{ found, path }`), for the form's Test button; never runs it. |
|
||||
| `POST /agents/use-path` | `{ id }`. "Use it from here": saves the location the lookup found off PATH as the agent's `command` (a built-in becomes a new custom entry; 404 unknown, 409 `not-found`). |
|
||||
| `POST /handover` | Setup sessions only, and only with the session's setup token in `x-plan2code-token`: the new agent's `open` posts `{ url }` here, the server broadcasts a `move` event with it and the setup tab follows. 409 `moved` once it has happened. |
|
||||
|
||||
## For maintainers
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Source | `src/web-console/` (one row per file in the files tables of the `.agents-docs/AGENTS-architecture-*.md` area files; a test keeps it complete) |
|
||||
| Ships as | `skills/<every skill>/references/web-console/` |
|
||||
| Wiring | one `additionalReferences` entry per skill in `install.js`; the dashboard's menu lives in `public/skills.js` (each entry's `card`; `SKILL_CATALOG` in `public/answers.js` is a lookup on it) |
|
||||
| Agent contract | a card, `src/web-console/console.md` (read once), plus pointers: the console names a topic file (`console-*.md`, `notes/<workflow>.md`, `building.md` / `building-review.md`) in its own `read` output, once per session per topic, when its moment comes; `console.mjs help <topic>` prints any of them. A `stop` with no `finish`, or a `finish` while `stopWarning` is set, is refused with the fix; `stop --session <sid> --force` ends a dead page or an abandoned session anyway. Patches are one line, with lettered options and the console's own defaults filled in; a refused patch names the field and the fix. Byte budgets keep the card, the notes and a sample session's outputs from growing back (`scripts/test-console-wire-budgets.mjs`) |
|
||||
| Tests | `node --test scripts/test-web-console-*.mjs` (split by area, shared setup in `scripts/web-console-test-helpers.mjs`), also run by `npm test` |
|
||||
| Start-up benchmark | `node scripts/bench-web-console.mjs` (needs a local Chrome or Edge for the paint columns, driven through `playwright-core` from `npm install`; `--browser-delay 900` models a real browser launch, `--roundtrip` times Send→agent and post→page) |
|
||||
| Screenshots | `node scripts/capture-screenshots.mjs` (needs a local Chrome or Edge, driven through `playwright-core` from `npm install`; `PLAN2CODE_TEST_BROWSER=chrome|msedge` forces one) |
|
||||
| Dependencies | none at runtime. `marked` 15.0.7 (MIT) is vendored for its lexer only, and CodeMirror 6 (MIT) for the notebook's editor as one bundled file, `public/vendor/codemirror.esm.js`, made by the dev-only `node scripts/vendor-codemirror.mjs` from a pinned lock (about 500 KB, loaded only when the Notebook is first opened); the page's policy blocks the `<style>` element CodeMirror writes, so the editor lives in a shadow root where it adopts its rules as a constructed stylesheet (steps in the architecture doc's Notebook point) |
|
||||
|
||||
Edit `src/` only. `skills/` is a committed build artifact: regenerate it with
|
||||
`npm run build:skills` and commit it with the source change, since `npm test`
|
||||
(via `--verify-skills`) fails when it drifts from `src/`.
|
||||
|
||||
### Driving it by hand
|
||||
|
||||
You do not need an agent to poke at the console. Point `PLAN2CODE_CONSOLE_HOME`
|
||||
somewhere disposable first, so you never touch a real session:
|
||||
|
||||
```bash
|
||||
export PLAN2CODE_CONSOLE_HOME=/tmp/p2c-play # Windows: $env:PLAN2CODE_CONSOLE_HOME
|
||||
|
||||
cat > /tmp/payload.json <<'JSON'
|
||||
{ "workflow": "pathfinder", "title": "Playing about",
|
||||
"items": [ { "id": "q1", "kind": "choice", "title": "Export format",
|
||||
"body": "Pick one.",
|
||||
"options": [ { "k": "A", "text": "CSV", "recommended": true },
|
||||
{ "k": "B", "text": "Excel" } ],
|
||||
"token": { "A": "a", "B": "b" } } ],
|
||||
"agent": { "status": "waiting" } }
|
||||
JSON
|
||||
|
||||
node src/web-console/console.mjs open --file /tmp/payload.json # prints the URL, opens the browser
|
||||
node src/web-console/console.mjs wait --session <sid> --seconds 60
|
||||
node src/web-console/console.mjs stop --all
|
||||
```
|
||||
|
||||
`node src/web-console/console.mjs help` prints the same command summary an
|
||||
agent gets when it finds the binary before the docs.
|
||||
|
||||
`wait` exits `0` with the answers, `10` if nobody has finished yet, `20` if the
|
||||
server died, `30` on Cancel. Pick `--seconds` to sit under whatever your harness
|
||||
allows a single command: it is a poller, so killing it costs nothing, and a
|
||||
collected result is printed before it is marked collected, which means an
|
||||
interrupted handover can only repeat itself, never lose an answer. `status`
|
||||
lists sessions and flags any whose answers were submitted but never collected.
|
||||
|
||||
When something misbehaves, the session directory is the whole story:
|
||||
`state.json` (what the agent published), `draft.json` (what the person has typed
|
||||
but not sent), `result.json` (what they sent), `events.ndjson` (an append-only
|
||||
log you can `cat`), and `server.log`.
|
||||
|
||||
Set `--idle-ms 60000` on `open` if you want the server to shut itself down
|
||||
quickly while experimenting.
|
||||
|
||||
Two environment variables help when the start is what you are looking at:
|
||||
|
||||
| Variable | Does |
|
||||
| --- | --- |
|
||||
| `PLAN2CODE_CONSOLE_TRACE=1` | `open` prints a timeline of its steps to stderr (roots found, server spawned, port bound, browser sent, state written, server listening). |
|
||||
| `PLAN2CODE_BROWSER` | The command that opens the link instead of the system default, run through the shell with the link appended, e.g. `PLAN2CODE_BROWSER='firefox --new-tab'`. |
|
||||
|
||||
Every `console.mjs open` of an installed console (one run from a version folder
|
||||
under `~/.plan2code/console/`) also writes its own directory to
|
||||
`$PLAN2CODE_CONSOLE_HOME/console-dir` (or `~/.plan2code/console/console-dir`
|
||||
when the override is unset): it is how an agent finds the console on a later
|
||||
session without searching the skill install dirs. A console run from a source
|
||||
checkout leaves the pointer alone.
|
||||
|
||||
The vendored file is `src/web-console/public/vendor/marked.esm.js`,
|
||||
sha256 `7a7d9a521ac9384e0c3a075120a7c486cbd0c3c32cc5601bbb79a23e97403690`.
|
||||
Only `marked.lexer()` is used; the rendering is ours, in `public/render.js`, and
|
||||
builds DOM nodes rather than HTML so nothing needs sanitizing.
|
||||
|
||||
### Refreshing the screenshots
|
||||
|
||||
The docs and the landing page show the console through the images in
|
||||
`docs/screenshots/`, one light and one dark WebP per screen. Rerun the capture
|
||||
after any change a person would see on the page: a new layout, a renamed
|
||||
button, a different color.
|
||||
|
||||
```bash
|
||||
node scripts/capture-screenshots.mjs # every screen
|
||||
node scripts/capture-screenshots.mjs --only dashboard # one screen
|
||||
```
|
||||
|
||||
Each screen is staged with no agent, from the payloads in
|
||||
`scripts/screenshots/` (its README names the file behind each screen), in a
|
||||
throwaway sample project and console home that the script removes when it is
|
||||
done. It prints each file's size and warns over 300 KB.
|
||||
|
||||
Open every image before you commit it: the right screen, both themes, nothing
|
||||
cut off, and no username, home path or real project name anywhere on it.
|
||||
@@ -8,7 +8,7 @@ Plan2Code is a structured 4-step workflow methodology for AI-assisted software d
|
||||
|
||||
**Version:** Check `version.json` for current version
|
||||
**Author:** Justin Parker
|
||||
**License:** MIT
|
||||
**License:** Apache 2.0
|
||||
|
||||
Plan2Code is started from the project the person works in (`cd` into it, then run `plan2code`), not from this repository; every newcomer doc says so, next to the Node.js 18+ requirement.
|
||||
|
||||
@@ -36,13 +36,13 @@ Details: [Status line](./.agents-docs/AGENTS-architecture-statusline.md)
|
||||
|
||||
## Web Console
|
||||
|
||||
Optional local browser UI (`src/web-console/`, zero dependencies, detached `node` server on `127.0.0.1`) installed once under `~/.plan2code/console/<version>/` (`installSharedConsole` in `install.js`) and reached from every skill through a forwarding stub, `src/web-console-stub/console.mjs`. The bare `plan2code` skill opens its dashboard, a card menu that launches any skill in the same session. Pages cover questions, sign-off gates (with an in-page code review, and in Implement, Implement + Review and Quick Task a **Changes** tab: a `diff` doc block fed by the `changes.mjs` skill script, parsed by `public/diff-parse.js` and drawn by `public/diff-view.js`), build progress, the living document, a spec's saved prototypes (a **Prototypes** tab: an `.md` read in place, an `.html` opened in the default browser), an **Ask** chat, a read-only **Workspace** of extra folders (remembered per folder and spec in `~/.plan2code/console/workspaces.json`), a session meter, a **git board** for the `git` workflow (three tabs, Changes, Branches and Sync, opening on the likely next step; branches, pull, push, commits and pull-request links, drawn from `state.git`; contract in `notes/git.md`), **Stop with a handoff** (handoffs live in `~/.plan2code/handoffs/`, owned by `handoffs.mjs`, swept after 30 days, and offered as dashboard chips to pick up in the same session), a private **Notebook** in the top bar (named tabs of Markdown and pictures, a live-preview CodeMirror editor, one notepad per folder in `~/.plan2code/notepads/`, owned by `notepads.mjs`, private: the agent reads a tab only when you start Pathfinder, Plan, Quick Task, Diagnose, UI Prototype or Revise plan from the dashboard with it and send the box it fills (an idea box marked `fill: "note"`, up to five ticked pictures attached), which then marks the tab sent via `POST /notepad/tab/sent`; the agent CLI never imports the store; removed only through Cleanup once a month untouched), **Activities** behind the top bar's die (thirteen small games, Snake, Mini golf, Light Trails, Bug Hunt, Sunset Drive, Stack Deploy, Bumper Ring, Rapids Run, Hot Potato, Crossing Rush, Bounce Road, Ghoul Rush and Flock Dash, listed in `public/activities.js` with one module per game under `public/activities/` (Ghoul Rush is its own folder of modules, `public/activities/ghoul-rush/`) and a card line (`blurb`) each, a picker of game rows in two columns, ordered Recently played or A to Z (saved in `activityOrder`), with never-picked games under Not played yet, once two are listed, that plays one game at a time (another pick drops the last game's round), driven by `screens/activities.js` (keys, key releases for a game with `release()`, canvas pointer events for a game with `pointer()`, one frame timer), paused whenever the person's turn comes and resumed only by the person (while that pause's banner is up, only by its **Unpause game** button), best scores in flat `activityBest<Id>` keys in `looks.json` (and the time each game was last picked in `activityPlayed<Id>`) (lowest wins for a game that sets `lowerIsBetter`; Mini golf opens on a dashboard of its six 18-hole courses, one file each under `public/activities/golf-course-<id>.js`, and keeps a best per course, `activityBestGolf<Course>`), and one number a game may keep between sessions in `activityMemo<Id>` (Snake's tally of surprises found, Light Trails' furthest arena, Bug Hunt's tally of finds, Sunset Drive's roads found, Stack Deploy's highest floor, Bumper Ring's furthest arena, Rapids Run's furthest dam, Hot Potato's furthest venue, Crossing Rush's furthest zone, Bounce Road's furthest stage, Ghoul Rush's most stages cleared in a run, Flock Dash's furthest stage), never shown to the agent), a built-in 23-topic Help, the app-only **Implementation Loop** (a dashboard card and a setup screen drawn by the page, `public/screens/loop-setup.js`; the last setup remembered per project in `~/.plan2code/console/loop-setup.json`, owned by `loop-setup.mjs`; a page that locks while `state.loop.driving` is set, until the app posts `loopEnd`; a skill run with `--loop` reports a `loopOutcome` instead of asking for sign-off, per `notes/loop.md`), a first-run Welcome, User Preferences (gear: four tabs, Appearance, Agents & models, System and Sounds & activities, on the `public/tabs.js` helper Help also uses, with `public/prefs.js`, `screens/prefs-dialog.js` and `screens/agents-view.js`), an agent-less **setup** page (the `setup` workflow `plan2code` or the desktop app opens when no agent can run: each built-in's found / outside-PATH / missing state from `agent-lookup.mjs`, install lines, Check again, Use it from here, starter templates and Start, which hands the tab to the new agent through a token-guarded `POST /handover` and a `move` event; the app shows it in its window from a Set up an agent button instead) and a bug/idea link to GitHub issues. On opted-in skills (every workflow but the dashboard, setup, Changelog, Git, Handoff and UI Prototype) a **SLine truncated
|
||||
Optional local browser UI (`src/web-console/`, zero dependencies, detached `node` server on `127.0.0.1`) installed once under `~/.plan2code/console/<version>/` (`installSharedConsole` in `install.js`) and reached from every skill through a forwarding stub, `src/web-console-stub/console.mjs`. The bare `plan2code` skill opens its dashboard, a card menu that launches any skill in the same session. Pages cover questions, sign-off gates (with an in-page code review, and in Implement, Implement + Review and Quick task a **Changes** tab: a `diff` doc block fed by the `changes.mjs` skill script, parsed by `public/diff-parse.js` and drawn by `public/diff-view.js`), build progress, the living document, a spec's saved prototypes (a **Prototypes** tab: an `.md` read in place, an `.html` opened in the default browser), an **Ask** chat, a read-only **Workspace** of extra folders (remembered per folder and spec in `~/.plan2code/console/workspaces.json`), a session meter, a **git board** for the `git` workflow (three tabs, Changes, Branches and Sync, opening on the likely next step; branches, pull, push, commits and pull-request links, drawn from `state.git`; contract in `notes/git.md`), **Stop with a handoff** (handoffs live in `~/.plan2code/handoffs/`, owned by `handoffs.mjs`, swept after 30 days, and offered as dashboard chips to pick up in the same session), a private **Notebook** in the top bar (named tabs of Markdown and pictures, a live-preview CodeMirror editor, one notepad per folder in `~/.plan2code/notepads/`, owned by `notepads.mjs`, private: the agent reads a tab only when you start Pathfinder, Plan, Quick task, Diagnose, UI Prototype or Revise plan from the dashboard with it and send the box it fills (an idea box marked `fill: "note"`, up to five ticked pictures attached), which then marks the tab sent via `POST /notepad/tab/sent`; the agent CLI never imports the store; removed only through Cleanup once a month untouched), **Activities** behind the top bar's die (thirteen small games, Snake, Mini golf, Light Trails, Bug Hunt, Sunset Drive, Stack Deploy, Bumper Ring, Rapids Run, Hot Potato, Crossing Rush, Bounce Road, Ghoul Rush and Flock Dash, listed in `public/activities.js` with one module per game under `public/activities/` (Ghoul Rush is its own folder of modules, `public/activities/ghoul-rush/`) and a card line (`blurb`) each, a picker of game rows in two columns, ordered Recently played or A to Z (saved in `activityOrder`), with never-picked games under Not played yet, once two are listed, that plays one game at a time (another pick drops the last game's round), driven by `screens/activities.js` (keys, key releases for a game with `release()`, canvas pointer events for a game with `pointer()`, one frame timer), paused whenever the person's turn comes and resumed only by the person (while that pause's banner is up, only by its **Unpause game** button), best scores in flat `activityBest<Id>` keys in `looks.json` (and the time each game was last picked in `activityPlayed<Id>`) (lowest wins for a game that sets `lowerIsBetter`; Mini golf opens on a dashboard of its six 18-hole courses, one file each under `public/activities/golf-course-<id>.js`, and keeps a best per course, `activityBestGolf<Course>`), and one number a game may keep between sessions in `activityMemo<Id>` (Snake's tally of surprises found, Light Trails' furthest arena, Bug Hunt's tally of finds, Sunset Drive's roads found, Stack Deploy's highest floor, Bumper Ring's furthest arena, Rapids Run's furthest dam, Hot Potato's furthest venue, Crossing Rush's furthest zone, Bounce Road's furthest stage, Ghoul Rush's most stages cleared in a run, Flock Dash's furthest stage), never shown to the agent), a built-in 23-topic Help, the app-only **Implementation Loop** (a dashboard card and a setup screen drawn by the page, `public/screens/loop-setup.js`; the last setup remembered per project in `~/.plan2code/console/loop-setup.json`, owned by `loop-setup.mjs`; a page that locks while `state.loop.driving` is set, until the app posts `loopEnd`; a skill run with `--loop` reports a `loopOutcome` instead of asking for sign-off, per `notes/loop.md`), a first-run Welcome, User Preferences (gear: four tabs, Appearance, Agents & models, System and Sounds & activities, on the `public/tabs.js` helper Help also uses, with `public/prefs.js`, `screens/prefs-dialog.js` and `screens/agents-view.js`), an agent-less **setup** page (the `setup` workflow `plan2code` or the desktop app opens when no agent can run: each built-in's found / outside-PATH / missing state from `agent-lookup.mjs`, install lines, Check again, Use it from here, starter templates and Start, which hands the tab to the new agent through a token-guarded `POST /handover` and a `move` event; the app shows it in its window from a Set up an agent button instead) and a bug/idea link to GitHub issues. On opted-in skills (every workflow but the dashboard, setup, Changelog, Git, Handoff and UI Prototype) a **SLine truncated
|
||||
|
||||
One agent list and one lookup rule serve the launcher, the console and the app: `src/launcher/agents.json` (the built-ins and starter templates with per-OS install data) and `src/web-console/agent-lookup.mjs` (`loadAgentList()` and `findAgent()`, both copied by `install.js` into `~/.plan2code/bin/`); the app carries a Rust twin held to the same cases by `scripts/fixtures/agent-lookup-cases.json`.
|
||||
|
||||
**Learning** (lessons about a codebase, kept with it): the dashboard draws a Learning row (Not set up, Off, On or Paused for you, with a Pause for me switch and a More menu) and, while lessons are waiting, a banner with Review, both from the scan's `learning` field (`public/screens/learning-row.js`, `public/styles/learning.css`); skills ask for approval through the `lessons` card kind. The server's only write for it is the personal pause, on this machine only (`POST /learning/pause`, under `~/.plan2code/learning/`); every change to the project's Learning files (`.plan2code/settings.json` and `.plan2code/lessons/`) goes through the `lessons.mjs` skill script, which shares one core with the scan, `src/web-console/learning.mjs`.
|
||||
Building or changing an Activities game: follow the game rules in [Activities](./.agents-docs/AGENTS-architecture-activities.md) ("Building an Activities game": lives in the solid lives pill, the endless-lives code (`cheat(on)`) in every game with lives, banners placed away from the player and see-through over what matters, pausing left to the window).
|
||||
Details: [Web console server and contract](./.agents-docs/AGENTS-architecture-console.md), [page](./.agents-docs/AGENTS-architecture-console-page.md), [design points](./.agents-docs/AGENTS-architecture-console-design.md), [Activities](./.agents-docs/AGENTS-architecture-activities.md) (and the Ghoul Rush and Bounce Road files it links) and [.readme/web-console.md](./.readme/web-console.md)
|
||||
Details: [Web console server and contract](./.agents-docs/AGENTS-architecture-console.md), [page](./.agents-docs/AGENTS-architecture-console-page.md), [design points](./.agents-docs/AGENTS-architecture-console-design.md), [Activities](./.agents-docs/AGENTS-architecture-activities.md) (and the Ghoul Rush and Bounce Road files it links) [.readme/web-console.md](./.readme/web-console.md) (the user guide), [.readme/activities.md](./.readme/activities.md) and [.readme/web-console-internals.md](./.readme/web-console-internals.md) (routes, security, driving it by hand, refreshing screenshots)
|
||||
Why the agent-facing console docs are shaped as they are (the card, pointers, refusals): [Web Console Contract](./.agents-docs/AGENTS-web-console-contract.md); it never ships.
|
||||
|
||||
## Skill Scripts
|
||||
|
||||
@@ -2,7 +2,37 @@
|
||||
|
||||
All notable changes to Plan2Code will be documented in this file.
|
||||
|
||||
## v3.1.0
|
||||
<!-- Format from 3.1.0 on: `## vX.Y.Z (YYYY-MM-DD)` with the date from version.json; a minor release opens with a three-bullet `### Highlights`; sections run Added, Changed, Fixed; game changes sit under one Activities line; tooling and test lines go under "For contributors". Older headings have no date and are not backfilled. -->
|
||||
|
||||
## v3.1.1 (2026-11-17)
|
||||
|
||||
### ✨ Added
|
||||
|
||||
- **install**: the install command now ends in `#release`, a branch that moves to each published release, so a new install never gets unfinished work from `main`.
|
||||
- **launcher**: `plan2code update` installs the newest release and prints one short summary (`Updating <old> -> <new>`, or `Already on <new>`); `--main` takes the newest work instead, `--tag <release>` goes back to an earlier one, and `--force` reinstalls.
|
||||
- **launcher**: `plan2code uninstall` lists what it removes and what it keeps in `~/.plan2code/`, with sizes; `--purge` also removes the desktop app's own data, and `--yes` skips the questions.
|
||||
- **launcher**: `plan2code --help` and `--version`; arguments after `--` go to the agent unchanged.
|
||||
- **desktop app**: Update and restart in the top bar installs the newest release with live progress and reopens on the same project, asking first when an agent or a loop is running.
|
||||
- **desktop app**: the window remembers its size and place, and the terminal gets a right-click menu, copy on select, font size keys and clickable links; new keyboard shortcuts work from both panes.
|
||||
- **docs**: a SECURITY.md for private vulnerability reports, and the issue form links to the docs, the desktop app guide and security.
|
||||
|
||||
### 🔧 Changed
|
||||
|
||||
- **license**: Plan2Code is now licensed under Apache 2.0 (it was MIT), with a NOTICE file.
|
||||
- **installer**: plainer output, with no colors or boxes when piped (`NO_COLOR` is honored), a spinner while the skills install, the exact PATH line for your shell when the command is not found, and a clear stop on Node.js older than 18.
|
||||
- **web console**: a broad visual refresh (spacing, type, shadow and motion tokens, shared top-bar icons); "Helpers" is now "Subagents" everywhere, and the meter says "Conversation".
|
||||
- **web console**: Clear acts at once with a 10-second Undo, the finish screen shows one main button, Help groups its topics with a filter and opens with `?`, and Cleanup shows what it will delete and its size.
|
||||
- **desktop app**: its own confirm dialogs (Cancel first and focused), plain-language errors with the details underneath, the console's theme from the first paint, and a top bar that folds extra buttons into a "+N more" menu.
|
||||
- **UI Prototype**: the carry-over card opens ticked as suggested, each item tagged Keep or Free up with its reason.
|
||||
- **docs**: the README is rewritten and shorter, the long guides moved into `.readme/`, the site hosts its own fonts and has a social card, and the screenshots are refreshed (Notepad is now Notebook).
|
||||
- **For contributors**: the release workflow fast-forwards the `release` branch, new `make-site-images`, `make-social-card` and `make-app-placeholders` scripts, more screenshot fixtures, and wider launcher, installer, app and console tests.
|
||||
|
||||
### 🐛 Fixed
|
||||
|
||||
- **launcher**: `plan2code update --main` reinstalls even when the version number has not moved (unreleased work on `main` keeps the last release's number), `uninstall` runs the newest release's installer, and a failed update no longer blocks the retry with "Already on".
|
||||
- **desktop app**: on macOS Ctrl+C stays the interrupt even with text selected, `uninstall --purge` also removes the saved window state, the PATH lookup works under fish, and loop spec names may contain dots.
|
||||
|
||||
## v3.1.0 (2026-11-15)
|
||||
|
||||
### ✨ Added
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ The web console is the main way in: a local page where questions, documents, bui
|
||||
| ------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
|
||||
| From your project (shell) | `plan2code` | Opens Claude Code, Devin or Codex on the dashboard (`--cli claude` / `devin` / `codex` to choose) |
|
||||
| Inside any agent | `/plan2code` (`$plan2code` in Codex) | Opens the dashboard: a card for every skill, launched on the same page |
|
||||
| Install | `npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git` | Installs the skills and the `plan2code` command (re-run it to update without the `plan2code` command) |
|
||||
| Install | `npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git#release` | Installs the skills and the `plan2code` command (to update, run `plan2code update`; re-running the install command also works, and removes nothing) |
|
||||
| Update | `plan2code update` | Updates the skills, command, app and status line, with no menu (metrics and the bot only from a git checkout: `node install.js`); never uninstalls anything |
|
||||
| Uninstall | `plan2code uninstall` | Removes the skills, command, app and dev tools after a Y/N; then asks whether `~/.plan2code/` (your notebooks, handoffs, settings) goes too. `--yes` skips the questions and keeps your data, `--purge` deletes it |
|
||||
| Straight into a skill | `/plan2code-1-plan --web` (any step) | Skips the "web console or terminal?" question and opens the page |
|
||||
@@ -25,7 +25,11 @@ The install command always opens a menu. Back at your prompt with no output at a
|
||||
|
||||
Pick a skill on the dashboard and the same page becomes that session. Details: [.readme/web-console.md](.readme/web-console.md) · worked example: [.readme/walkthrough.md](.readme/walkthrough.md).
|
||||
|
||||
The **Notebook** icon in the top bar opens a private scratch pad for the folder you are in (Markdown and pictures, kept in `~/.plan2code/notepads/`). Private: the agent never reads your Notebook. A tab reaches it only when you start a workflow with it.
|
||||
The **Notebook** icon in the top bar opens a private scratch pad for the folder you are in (Markdown and pictures, kept in `~/.plan2code/notepads/`); the agent reads a tab only when you send it by starting a skill from that tab.
|
||||
|
||||
**Desktop app:** the installer also offers a window with the dashboard and your agent's terminal side by side; once installed, `plan2code` opens it.
|
||||
`plan2code --classic` keeps the agent in your terminal instead.
|
||||
The **Implementation Loop** (app only) builds every remaining phase of a spec unattended, one fresh agent per phase: [docs/desktop-app.md](docs/desktop-app.md).
|
||||
|
||||
## Commands
|
||||
|
||||
@@ -45,13 +49,14 @@ Every command below is what a dashboard card runs. Typed on its own, each one as
|
||||
| 3 | /plan2code-3-implement | overview.md | Implemented code |
|
||||
| 3+review | /plan2code-3-implement-review | overview.md | Reviewed implementation ready for approval (alternative to `/plan2code-3-implement`) |
|
||||
| 4 | /plan2code-4-finalize | overview.md | Archived specs |
|
||||
| handoff | /plan2code-handoff | Conversation | Self-contained handoff doc (OS temp dir by default, or a folder you pick such as `handoffs/`) |
|
||||
| handoff | /plan2code-handoff | Conversation | Self-contained handoff doc, saved in `~/.plan2code/handoffs/` and listed on the dashboard to pick up |
|
||||
| xray | /plan2code-xray | An area, or none | An explanation citing files and commits, or `ARCHITECTURE-BRIEF-<date>.md` with the rough spots you picked |
|
||||
| diagnose | /plan2code-diagnose | A bug, or none | `DIAGNOSIS-<date>.md` with the cause and its evidence, then Quick Task (or Plan for a big fix) to fix it |
|
||||
| diagnose | /plan2code-diagnose | A bug, or none | `DIAGNOSIS-<date>.md` with the cause and its evidence, then Quick task (or Plan for a big fix) to fix it |
|
||||
| pr-prep | /plan2code-pr-prep | Your branch | A readiness verdict (Ready, Ready with notes, Not ready) and a PR description to copy; no commits, no push |
|
||||
| test | /plan2code-test | An area, or none | New unit and integration tests in the project's style, run; a bug handed to Diagnose; no source changes |
|
||||
| dead-code | /plan2code-dead-code | A folder, or none | Findings labeled Safe, Check first or Warning, then only the removals you pick, checked by the tests and build; no commits, no installs |
|
||||
| ui-prototype | /plan2code-ui-prototype | A screen or flow, or none | One page of several versions with live dials, your pick pasted back; `prototypes/<name>.html` and `.md` in a spec on a yes; no code changes |
|
||||
| deps | /plan2code-deps | Your manifests | Each update labeled Safe, Check first or Warning, then only the ones you pick applied in batches with your checks after each; a ticked Warning writes `UPGRADE-<date>.md`; no commits |
|
||||
| changelog | /plan2code-changelog | Your branch | `CHANGELOG.md` entries and the `package.json` version, from the default branch's latest version |
|
||||
| git | /plan2code-git | Your repo | Commits (`<subject>` / `AI Assisted`), branches, pull with conflict help, push, publish |
|
||||
|
||||
@@ -67,13 +72,20 @@ specs/
|
||||
│ ├── questions/NN-<slug>.md # one decision question per file
|
||||
│ └── briefs/brief-<date>.md # on-demand plain-English decision briefs
|
||||
│ # (GitHub Issues backend: map issue + sub-issues instead)
|
||||
├── prototypes/ # From Prototype a screen (saved on a yes)
|
||||
│ └── <name>.html + <name>.md # the page, and the choice it made
|
||||
├── PLAN-DRAFT-<date>.md # From Step 1 (verified plan)
|
||||
├── PLAN-CONVERSATION-<date>.md # From Step 1 (conversation log)
|
||||
├── DIAGNOSIS-<date>.md # From Diagnose a bug
|
||||
├── UPGRADE-<date>.md # From Update dependencies (a ticked Warning)
|
||||
├── overview.md # From Step 2
|
||||
└── phase-X.md # From Step 2
|
||||
├── phase-X.md # From Step 2
|
||||
└── LOOP-SUMMARY-<date>.md # From the Implementation Loop (desktop app)
|
||||
|
||||
specs--completed/ # After Step 4
|
||||
└── <feature-name>/ # Archived specs
|
||||
|
||||
.plan2code/ # Saved with the repository: the project's lessons and the Learning switch
|
||||
```
|
||||
|
||||
Note: `<date>` uses YYYYMMDD format (e.g., `20250204`)
|
||||
|
||||
@@ -1,19 +1,33 @@
|
||||
|
||||
# Plan2Code
|
||||
|
||||
**A spec-driven workflow for AI coding agents.**
|
||||
[](https://github.com/jparkerweb/plan2code/releases/latest) [](LICENSE) 
|
||||
|
||||
<img src="docs/banner.jpg" alt="banner" data="object-fit:contain;" style="max-width:1024px;">
|
||||
**Plan it. Approve it. Let it build.**
|
||||
|
||||
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.
|
||||
- **The app.** A desktop window with the dashboard and your agent's terminal side by side, for Windows, macOS and Linux.
|
||||
- **The Loop.** It builds every remaining phase of a spec, one fresh agent per phase, while you do something else.
|
||||
- **Plain files in your repo.** What you decide lands as specs, so the next session, agent and engineer start from the same plan.
|
||||
|
||||
One command opens it, every step is a card, and the terminal is always there if you prefer it.
|
||||
<img src="docs/banner.jpg" alt="Plan2Code: Planny walking the steps from Pathfinder to Finalize" width="1024">
|
||||
|
||||
Version 3.1.0 · MIT · 📖 [plan2code.jparkerweb.com](https://plan2code.jparkerweb.com)
|
||||
Plan2Code is a spec-driven workflow for AI coding agents. You work through it 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. An approved plan becomes phase documents, and the agent builds to them one phase at a time.
|
||||
|
||||
Version 3.1.1 · Apache 2.0 · 📖 [plan2code.jparkerweb.com](https://plan2code.jparkerweb.com)
|
||||
|
||||
---
|
||||
|
||||
## Contents
|
||||
|
||||
- [See it](#see-it)
|
||||
- [Install and start](#install-and-start)
|
||||
- [A session on the page](#a-session-on-the-page)
|
||||
- [The workflow](#the-workflow)
|
||||
- [The skills](#the-skills)
|
||||
- [The four rules](#the-four-rules-that-do-most-of-the-work)
|
||||
- [What lands in your repo](#what-lands-in-your-repo)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Dive deeper](#dive-deeper)
|
||||
|
||||
---
|
||||
|
||||
@@ -26,6 +40,12 @@ Version 3.1.0 · MIT · 📖 [plan2code.jparkerweb.com](https://plan2code.jparke
|
||||
|
||||
The dashboard, in a project halfway through a build. It suggests the next step for the spec you pick.
|
||||
|
||||
```bash
|
||||
npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git#release
|
||||
```
|
||||
|
||||
Needs Node.js 18+ and Git (details under [Before you start](#before-you-start)). Then `cd` into your project and run `plan2code`.
|
||||
|
||||
---
|
||||
|
||||
## Install and start
|
||||
@@ -38,10 +58,10 @@ The dashboard, in a project halfway through a build. It suggests the next step f
|
||||
- **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.
|
||||
|
||||
Installation needs network access and runs through the [skills CLI](https://skills.sh). To update, run `plan2code update` (or re-run the install command). To remove everything, run `plan2code uninstall`: it asks first, then asks whether your own data in `~/.plan2code/` (notebooks, handoffs, settings) goes too. `--yes` skips the questions and keeps your data; add `--purge` to delete it.
|
||||
Installation needs network access and runs through the [skills CLI](https://skills.sh). The command installs the newest release: `#release` is a branch that moves to each release as it is published, so you never get unfinished work from `main`. To update, run `plan2code update`: it installs the newest release too, prints `Updating <old> -> <new>` (or `Already on <new>` and stops; `plan2code update --force` reinstalls anyway), and `plan2code update --main` takes the newest work on `main` instead. **Go back to a release** with `plan2code update --tag v3.0.2` (any release tag works). To remove everything, run `plan2code uninstall`: it asks first, then asks whether your own data in `~/.plan2code/` (notebooks, handoffs, settings) goes too. `--yes` skips the questions and keeps your data; add `--purge` to delete it.
|
||||
|
||||
```bash
|
||||
npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git
|
||||
npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git#release
|
||||
```
|
||||
|
||||
This fetches the installer to a temp directory, builds the workflow as Agent Skills, delegates
|
||||
@@ -76,74 +96,15 @@ The installer opens this menu (cloning and running `node install.js`, below, ope
|
||||
|
||||
Already inside your agent? Type `/plan2code` instead (`$plan2code` in Codex).
|
||||
|
||||
<details>
|
||||
<summary>About the plan2code command</summary>
|
||||
Run `plan2code` from any project to open the dashboard in Claude Code, Devin or Codex (it asks which when more than one is installed). Flags, permission prompts, the desktop shortcut, other agent CLIs and the setup page for a missing agent are in [.readme/launcher.md](.readme/launcher.md).
|
||||
|
||||
Install (`I`) adds `plan2code` as a global command (Advanced `A` → `D` adds just the command). Run it from any project and the Plan2Code
|
||||
dashboard opens right there, in **Claude Code**, **Devin** or **Codex**. With more than one installed it asks which and
|
||||
remembers your pick; `plan2code --cli claude`, `--cli devin` or `--cli codex` skips the question, and `--model <name>`
|
||||
chooses the model. It works in cmd, PowerShell, Git Bash, macOS and Linux shells, and needs the
|
||||
Claude Code, Devin or Codex CLI on your `PATH`. After you pick the agent it asks whether to turn its
|
||||
permission prompts off (Yes by default; `--permission-mode bypassPermissions` in Claude Code, `--permission-mode bypass`
|
||||
in Devin, `--dangerously-bypass-approvals-and-sandbox` in Codex, a custom agent's bypass arguments, and no question for a
|
||||
custom agent that has none; for Codex the question names its sandbox, which that flag turns off too). It asks on every
|
||||
launch and remembers no answer. `plan2code --keep-permissions` keeps the prompts without asking, and
|
||||
`plan2code --bypass-permissions` turns them off without asking. With no terminal to ask on (a script or a pipe) the
|
||||
prompts stay on unless `--bypass-permissions` is given. The installer then offers a desktop shortcut (answer `y`),
|
||||
which opens a folder menu first: Choose a folder, with the project folders you opened lately under it (with none yet, it goes straight to the folder dialog). In a terminal, `plan2code` offers the same recent folders as a numbered menu. Uninstalling (`U`, or `plan2code uninstall` from any terminal) removes both.
|
||||
</details>
|
||||
### The desktop app
|
||||
|
||||
<details>
|
||||
<summary>Using another agent CLI, or none yet</summary>
|
||||
<img src="docs/screenshots/app-terminal-dark.webp" alt="The desktop app: the Plan2Code dashboard on the left and the agent's terminal docked on the right.">
|
||||
|
||||
Plan2Code runs inside an AI coding agent CLI. With no agent it can run (none of Claude Code,
|
||||
Devin or Codex, and no working custom agent),
|
||||
`plan2code` opens a setup page in your browser (the web console runs it, so no agent is needed).
|
||||
The page lists each agent as **Found**, **Found outside PATH** or **Not found**, with its install
|
||||
commands for your system, a Copy button per command and an **Install page** link. Install one and
|
||||
press **Check again**: no restart needed. An agent found outside `PATH` gets **Use it from here**,
|
||||
which saves where it was found so you never touch `PATH` yourself. Below the list sit five starter
|
||||
templates (GitHub Copilot CLI, OpenCode, Gemini CLI, Pi and Cursor CLI) for agents Plan2Code does not ship.
|
||||
**Start with this agent** carries the run straight on in the same tab, onto the new agent's
|
||||
dashboard. Naming a built-in that is missing with `--cli <name>` opens the same page on that agent
|
||||
(a missing custom agent prints its own steps and exits 127). In the
|
||||
desktop app a **Set up an agent** button opens the same page in the window and returns to the
|
||||
launch card with the found agent picked. Where no page can open, such as over SSH or with no
|
||||
display, `plan2code` prints the install commands and install pages and exits with code 127.
|
||||
The installer also offers the **Plan2Code desktop app**: one window with the dashboard and your agent's terminal side by side, docked right or bottom. A launch card asks which agent, model and effort to start on, and once it is installed `plan2code` opens the app (`plan2code --classic` keeps the terminal flow). `plan2code update` updates the skills, the command and the app together.
|
||||
|
||||
Once an agent is running, to use a different agent CLI, open the web console's **User Preferences → Agents & models** and add it: a name, the
|
||||
command, and (optionally) its arguments, the start prompt, arguments for skipping permission prompts, and
|
||||
how it takes a model. Custom agents are saved in `~/.plan2code/agents.json` and used by both the
|
||||
`plan2code` command (listed after the built-ins; `--cli <id>` picks one) and the desktop app's picker. The
|
||||
`/plan2code` start prompt only does something in an agent that loads the installed Plan2Code skills; for
|
||||
any other, leave the start prompt blank and start a skill yourself. Details in
|
||||
[.readme/web-console.md](.readme/web-console.md#agents--models).
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>About the desktop app</summary>
|
||||
|
||||
The installer also offers the **Plan2Code desktop app**: one window with the dashboard and your agent's
|
||||
terminal side by side, docked right (or bottom) and collapsible. Every console page, not only the
|
||||
dashboard, opens inside it. A launch card asks which agent, model and effort to start on, with
|
||||
permission checks off as its own tick (on by default, matching the terminal flow; untick it to keep
|
||||
the agent's approval prompts). A **New Session** button in the top bar replaces the agent with a fresh
|
||||
one on a brief built from the session, and the console's own Session meter points at it when a
|
||||
session is getting long. Once it is installed, `plan2code` opens the app instead of running the agent
|
||||
in your terminal. `plan2code --classic` keeps the terminal flow, and so does a Linux machine with no
|
||||
display (over SSH, say) or any machine over an SSH session. `plan2code update` updates the skills, the
|
||||
command and the app together; run it in a terminal outside the app when the bar says **Update
|
||||
available**, then reopen the app. The bar also offers **Update skills** when the app and the installed
|
||||
skills disagree. `plan2code uninstall` removes all three.
|
||||
|
||||
The app can also build a whole spec unattended with the Implementation Loop; see [docs/desktop-app.md](docs/desktop-app.md#implementation-loop).
|
||||
|
||||
The first release is unsigned, so macOS (**Open Anyway** in System Settings, Privacy & Security) or
|
||||
Windows (**More info**, then **Run anyway**) may ask you to allow it once. The app starts the agent
|
||||
with its normal approval prompts unless you tick the launch card's permission-checks-off option (the
|
||||
plain `plan2code` command above, without the app, asks instead, with prompts off by default too). Details:
|
||||
[docs/desktop-app.md](docs/desktop-app.md).
|
||||
</details>
|
||||
The app is not code-signed (signing is not planned for now), so your system may ask you to allow it once. More about the app, a manual download and the Implementation Loop: [docs/desktop-app.md](docs/desktop-app.md).
|
||||
|
||||
**Supported tools** (the agents the skills CLI can install into): every agent it supports, including Claude Code · Cursor ·
|
||||
GitHub Copilot · Windsurf · Codex · Continue · Codeium · Zed · Amp · OpenCode · Devin · Crush · Pi ·
|
||||
@@ -192,7 +153,7 @@ worked on right now.
|
||||
</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.
|
||||
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">
|
||||
@@ -210,7 +171,7 @@ next check-in, and it never holds up your answers.
|
||||
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 **Notebook** in the top bar is a private pad of your own for the
|
||||
folder, in Markdown with pictures, that the agent reads only when you start a workflow from one of its tabs on
|
||||
folder, in Markdown with pictures, that the agent reads only when you start a skill from one of its tabs on
|
||||
the dashboard and send the box it fills. The **die** beside it opens **Activities**,
|
||||
thirteen small games to play through a long wait, which pause the moment it is your turn. 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
|
||||
@@ -239,31 +200,7 @@ Each box is a card on the dashboard. Chaining a couple of small steps in one ses
|
||||
start a fresh session before a big plan or build step: planning context leaking into implementation
|
||||
is where most agent drift starts.
|
||||
|
||||
The dashboard's cards, and when each one lights up for the spec you pick:
|
||||
|
||||
| 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, a drafted plan or a bug diagnosis |
|
||||
| Revise the plan | Requirements changed mid-build? Adjust the plan without starting over. | The spec is written up into phases, built or not |
|
||||
| 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 (suggested when the spec is a diagnosed bug or an upgrade brief) |
|
||||
| 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. Any skill's **Stop with a handoff** writes one too, and the dashboard lists them to pick up. | Always |
|
||||
| Codebase X-ray | Explain how and why an area works, or find the rough spots worth fixing. | Always |
|
||||
| Diagnose a bug | Find a bug's cause and write it up, without fixing it. | Always |
|
||||
| Get a PR ready | Runs the checks your branch needs, says if it is ready, and writes the PR description to copy. Never commits, pushes or opens the PR. | Always |
|
||||
| Write missing tests | Finds code with no tests and writes unit and integration tests in your project's own style. Never changes source code. | Always |
|
||||
| Clear out dead code | Finds code nothing uses, says how safe each piece is to remove, and removes only what you pick. Uses the dead-code tools your project already has, and never commits. | Always |
|
||||
| Update dependencies | Scans every manifest, labels each update Safe, Check first or Warning, applies only what you pick in batches with your checks after each, and puts back whatever breaks. A ticked Warning becomes an upgrade brief for Quick task or Plan. Never commits. | Always |
|
||||
| Prototype a screen | Several versions of a screen on one page, tuned with live dials, and your pick brought back by Copy and paste. Saved into a spec only when you say, and never changes your code. | Always (takes the picked spec as the save folder) |
|
||||
| Changelog | Checks the CHANGELOG version against the main branch and suggests entries for what is new. | Always |
|
||||
| Git | Branches, pull, push and commits on one board, asking before anything leaves your machine. | Always (offers to start a repository outside one) |
|
||||
Every box is a card, and so is every other skill. They are all in [The skills](#the-skills), with the command for each.
|
||||
|
||||
Pathfinder, Plan, Revise the plan and Quick task can each offer a prototype when a decision is about how a screen looks or flows, and run it right there in the same session; nothing is drawn without your yes.
|
||||
|
||||
@@ -305,145 +242,45 @@ keep the two out of each other's way.
|
||||
|
||||
## The six steps in detail
|
||||
|
||||
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)
|
||||
|
||||
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.
|
||||
|
||||
1. **Name the destination** — one or two lines fixing what this effort is finding its way to. Settled
|
||||
first, because it fixes scope. It also asks where the map should live: **local files** under
|
||||
gitignored `specs/` (private, solo — the default), or **GitHub Issues** (a map issue with one
|
||||
sub-issue per decision, native blocking, so your team can see and work the frontier in the tracker).
|
||||
2. **Chart the map** — a breadth-first grilling surfaces the open decisions. Anything you can phrase
|
||||
*sharply* becomes a question file; anything you can only sense stays listed as fog.
|
||||
3. **Clear the questions one at a time** — resolving one burns off the fog behind it, graduating
|
||||
whatever just became sharp into new questions. After each decision it offers a menu: take the next
|
||||
question here, or start fresh — recommended after about three, to keep the agent sharp.
|
||||
Ask for a **brief** at any point and you get a dated, plain-English summary of what has been
|
||||
decided, what is still open, and what is next — meeting minutes, with no jargon in them.
|
||||
4. **Hand off** — when nothing is left to decide, it writes a `PLAN-DRAFT` that
|
||||
`/plan2code-1-plan` resumes from at Phase 4, with requirements, context, and scope already
|
||||
answered.
|
||||
|
||||
**Question types:** `grill` (a decision only you can make — the default) · `research` (a fact gates
|
||||
it; background agents resolve these, several in parallel) · `sketch` (you need something concrete to
|
||||
react to) · `legwork` (manual work that has to happen before a decision is possible).
|
||||
|
||||
It never answers its own questions, and it **plans, it never builds.** When the urge to just build it
|
||||
arrives, the map is done. Skip Step 0 entirely when you already know what you're building.
|
||||
|
||||
**Out:** `specs/<feature>/pathfinder/map.md` + `questions/` (or a `pathfinder:map` issue and its
|
||||
sub-issues) → `PLAN-DRAFT-<date>.md`. The draft is always a local file — that is what Step 1 reads.
|
||||
|
||||
### 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 seven phases, stopping for you after each: requirements
|
||||
analysis · system context (reading your actual codebase) · scope assessment (a large project saves and
|
||||
resumes in a fresh session) · tech stack (needs your explicit sign-off) · architecture design ·
|
||||
technical specification · transition decision.
|
||||
|
||||
It won't finalize below **90% confidence**, and every assumption it makes is written into the draft.
|
||||
|
||||
**In:** a description of the feature. **Out:** `PLAN-DRAFT-<date>.md` + `PLAN-CONVERSATION-<date>.md`
|
||||
|
||||
### 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.
|
||||
|
||||
The overview also identifies the **parallel execution groups**: phases with no shared files or
|
||||
dependencies, safe to run in separate agents at once.
|
||||
|
||||
**In:** the `PLAN-DRAFT`. **Out:** `overview.md` + `phase-1…N.md`
|
||||
|
||||
### 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.
|
||||
|
||||
One phase per conversation. It won't run tests unless the phase says to.
|
||||
|
||||
**In:** `specs/<feature>/overview.md`. **Out:** working code, and updated checkboxes.
|
||||
|
||||
Want a second pair of eyes before you sign off? `/plan2code-3-implement-review` builds the phase the
|
||||
same way, runs a focused review and the fixes you pick, and only then asks for approval.
|
||||
|
||||
### 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 —
|
||||
and the review pass is read-only. It fixes things only if you ask, and verifies each fix afterwards.
|
||||
|
||||
Spec-aware when `specs/` exists, and works fine without it. Most useful right after a planning or
|
||||
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
|
||||
like this.
|
||||
|
||||
**In:** `specs/<feature>/overview.md`. **Out:** archived specs.
|
||||
Each step is its own run, and the specs on disk are the only thing carried from one to the next. What each step asks, writes and hands on is in [.readme/steps.md](.readme/steps.md).
|
||||
|
||||
---
|
||||
|
||||
## Prefer the terminal?
|
||||
## The skills
|
||||
|
||||
Each one is a card on the dashboard and a command in your agent. Which cards light up for the spec you pick, the inputs and outputs, and the decision tree are on the [quick reference](QUICK-REFERENCE.md).
|
||||
|
||||
| Command | What it does |
|
||||
|---------|--------------|
|
||||
| `/plan2code` | Open the dashboard: every skill below as a card, launched on the page |
|
||||
| `/plan2code-init` | Set up this project: reads it and writes AGENTS.md, the guide every later step works from |
|
||||
| `/plan2code-init-update` | Refresh AGENTS.md with what the project has learned lately |
|
||||
| `/plan2code-0-pathfinder` | Pathfinder: turn a foggy idea into decisions, one question at a time, and hand a plan draft to Plan |
|
||||
| `/plan2code-1-plan` | Plan: requirements, technical design and your approval |
|
||||
| `/plan2code-2-document` | Document: turn the plan into phase files of small tasks |
|
||||
| `/plan2code-3-implement` | Implement: build the next phase, with a report and your sign-off |
|
||||
| `/plan2code-3-implement-review` | Implement + Review: build the phase, review it, then ask for sign-off |
|
||||
| `/plan2code-4-finalize` | Finalize: check the work, summarize, archive the specs, suggest the commit |
|
||||
| `/plan2code-1b-revise-plan` | Revise the plan: requirements moved mid-build, so change the specs, not the code |
|
||||
| `/plan2code-quick-task` | Quick task: a small change with a quick plan, then it builds it |
|
||||
| `/plan2code-review` | Review: a second opinion on your changes, problems ranked, you pick what gets fixed |
|
||||
| `/plan2code-handoff` | Handoff: pack this conversation into a document a fresh session picks up cold |
|
||||
| `/plan2code-xray` | Codebase X-ray: explain how and why an area works, or rank the rough spots; never edits code |
|
||||
| `/plan2code-diagnose` | Diagnose a bug: find the cause and write it up without fixing it |
|
||||
| `/plan2code-pr-prep` | PR Prep: run the checks your branch needs, say if it is ready, write the PR description |
|
||||
| `/plan2code-test` | Write missing tests: find untested code and write tests in your project's style |
|
||||
| `/plan2code-dead-code` | Clear out dead code: find what nothing uses, remove only what you pick |
|
||||
| `/plan2code-deps` | Update dependencies: label each update Safe, Check first or Warning, apply what you pick in batches |
|
||||
| `/plan2code-ui-prototype` | Prototype a screen: several versions on one page with live dials; never changes your code |
|
||||
| `/plan2code-changelog` | Changelog: check the CHANGELOG version against the default branch, suggest entries |
|
||||
| `/plan2code-git` | Git: branches, pull, push and commits on one board, asking before anything leaves your machine |
|
||||
|
||||
### 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, saved in `~/.plan2code/handoffs/` and listed on the dashboard to pick up |
|
||||
| `/plan2code-xray` | Explain how and why an area of the code works (citing files, commits and PRs), or rank the rough spots worth fixing into a brief for Pathfinder or Plan; never edits code |
|
||||
| `/plan2code-diagnose` | Find a bug's cause and write it up as `specs/<bug-name>/DIAGNOSIS-<date>.md` without fixing it, then offer `/plan2code-quick-task` to fix it, or `/plan2code-1-plan` when the fix is big |
|
||||
| `/plan2code-pr-prep` | Before you open a pull request. Picks the checks the branch's changes need from the project's `## Test map` (or its config files), runs the ones you keep, says Ready, Ready with notes or Not ready, and writes a PR description to copy with the create-a-PR link; never commits, pushes or opens the PR |
|
||||
| `/plan2code-test` | Parts of the code have no tests. Asks where to look, finds the untested files (plus real coverage when the project already has a coverage tool), shows a plan in the project's own style, then writes and runs unit and integration tests; never changes source code, hands a real bug to `/plan2code-diagnose` |
|
||||
| `/plan2code-dead-code` | Code nothing calls anymore. Uses the project's own dead-code tools, one per language (Knip, vulture, cargo check and others), or searches by itself, checks every item for callers across the project, labels each Safe to remove, Check first or Warning, removes only what you pick, then runs the tests and build and puts back anything that breaks them; never commits, never installs anything |
|
||||
| `/plan2code-deps` | Clear a dependency backlog in one sitting. Scans every manifest (npm, pnpm, Yarn, Cargo, pip, uv, Go, .NET), labels each update Safe, Check first or Warning with a reason, applies the ones you pick in batches, runs the install and your checks after each batch and puts back whatever breaks; a ticked Warning writes `specs/<package>-upgrade/UPGRADE-<date>.md`, which the dashboard shows as *Upgrade ready* for `/plan2code-quick-task` or `/plan2code-1-plan`; never commits; installs a scanner or fixes a small break in your code only after you approve that exact change |
|
||||
| `/plan2code-ui-prototype` | See a screen before it gets built. Draws several versions of a screen or flow on one page that opens in your browser, with live dials for fonts, colors, spacing and feel; Copy and paste brings your pick back for the next round, and a yes saves it as `specs/<spec>/prototypes/<name>.html` and `.md`; never changes your code |
|
||||
| `/plan2code-changelog` | Check the CHANGELOG version against the default branch, suggest entries for new work you can edit, keep `package.json` aligned, then hand off to Git to commit |
|
||||
| `/plan2code-git` | Branches, pull, push and commits on one board (or plain instructions in the terminal); asks before every push, publish and delete |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
@@ -493,7 +330,8 @@ 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, including the private Notebook and Activities in the top bar
|
||||
- **[.readme/](.readme/README.md)**: the index of the long guides
|
||||
- **[.readme/web-console.md](.readme/web-console.md)**: the guide to the web console, from the dashboard to the last sign-off, including the private Notebook, with [Activities](.readme/activities.md) and the [internals](.readme/web-console-internals.md) in their own files
|
||||
- **[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
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
# Security
|
||||
|
||||
## Reporting a vulnerability
|
||||
|
||||
Please report a vulnerability privately, not as a public issue. Use GitHub's private reporting: open the repository's **Security** tab and choose **Report a vulnerability** (or go to <https://github.com/jparkerweb/plan2code/security/advisories/new>).
|
||||
|
||||
Include what you found, the version (`version.json`, or the bottom of the web console's Help dialog), your system, and the steps to reproduce it. You can expect a first reply within a few days. Once a fix is released, the report is published with credit to you if you want it.
|
||||
|
||||
## What is in scope
|
||||
|
||||
Plan2Code runs on your own machine: the installer, the `plan2code` command, the local web console (served on `127.0.0.1` with a per-session token) and the desktop app. Reports about any of these are welcome, in particular anything that lets a web page or another local user reach the console, read or write files outside the project, or run a command the person did not approve.
|
||||
|
||||
The desktop app is not code-signed; that is documented in [docs/desktop-app.md](docs/desktop-app.md#the-app-is-not-code-signed) and is not a vulnerability report.
|
||||
@@ -9,16 +9,25 @@
|
||||
<meta name="theme-color" content="#0b2150">
|
||||
<meta property="og:title" content="Plan2Code: plan it, approve it, let it build">
|
||||
<meta property="og:description" content="A spec-driven workflow for AI coding agents, and a desktop app that puts the plan, your agent and every sign-off in one window.">
|
||||
<meta property="og:image" content="https://plan2code.jparkerweb.com/banner.jpg">
|
||||
<meta property="og:type" content="website">
|
||||
<meta property="og:url" content="https://plan2code.jparkerweb.com/">
|
||||
<meta property="og:image" content="https://plan2code.jparkerweb.com/social-card.png">
|
||||
<meta property="og:image:width" content="1200">
|
||||
<meta property="og:image:height" content="630">
|
||||
<meta property="og:image:alt" content="Plan2Code: Plan it. Approve it. Let it build. Beside it, the Approve this phase card from the web console.">
|
||||
<meta name="twitter:card" content="summary_large_image">
|
||||
<link rel="canonical" href="https://plan2code.jparkerweb.com/">
|
||||
<link rel="icon" href="favicon.ico" sizes="32x32">
|
||||
<link rel="icon" type="image/png" sizes="32x32" href="favicon.png">
|
||||
<link rel="icon" href="favicon.svg" type="image/svg+xml">
|
||||
<link rel="apple-touch-icon" href="apple-touch-icon.png">
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Archivo:wdth,wght@62..125,300..900&family=Martian+Mono:wght@300..600&display=swap" rel="stylesheet">
|
||||
<link rel="preload" href="fonts/archivo-latin.woff2" as="font" type="font/woff2" crossorigin>
|
||||
<link rel="preload" href="fonts/martian-mono-latin.woff2" as="font" type="font/woff2" crossorigin>
|
||||
<script>document.documentElement.className += " js"</script>
|
||||
<style>
|
||||
/* Self-hosted, subset to Latin (see scripts/ and the Phase 11 notes): no blocking request to a font host. */
|
||||
@font-face { font-family: "Archivo"; font-style: normal; font-weight: 300 900; font-stretch: 62% 125%; font-display: swap; src: url("fonts/archivo-latin.woff2") format("woff2"); }
|
||||
@font-face { font-family: "Martian Mono"; font-style: normal; font-weight: 300 800; font-stretch: 75% 112.5%; font-display: swap; src: url("fonts/martian-mono-latin.woff2") format("woff2"); }
|
||||
/* The page is a blueprint: cyanotype blue, chalk-white line work, one highlighter
|
||||
yellow for the moments that are yours (your move, your sign-off). The app window
|
||||
keeps the product's own warm dark palette, so it reads as the built thing lying
|
||||
@@ -74,7 +83,7 @@ body {
|
||||
img { max-width: 100%; height: auto; }
|
||||
a { color: var(--chalk); text-underline-offset: 4px; text-decoration-color: var(--chalk-3); }
|
||||
a:hover { text-decoration-color: var(--mark); }
|
||||
code, kbd { font-family: var(--mono); font-size: 0.8em; }
|
||||
code, kbd { font-family: var(--mono); font-size: max(0.8em, 12.5px); }
|
||||
:focus-visible { outline: 2px solid var(--mark); outline-offset: 3px; border-radius: 3px; }
|
||||
h1, h2, h3 { margin: 0; font-family: var(--sans); }
|
||||
h2 {
|
||||
@@ -94,7 +103,7 @@ p { margin: 0; }
|
||||
.sr { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
|
||||
.sheet { padding: 120px 0; border-top: 1px solid var(--line-2); background: var(--bp-900); }
|
||||
.sheet.deep { background: var(--bp-950); }
|
||||
.fig-note { margin-top: 14px; color: var(--chalk-3); font: 400 11.5px/1.6 var(--mono); }
|
||||
.fig-note { margin-top: 14px; color: var(--chalk-3); font: 400 12.5px/1.6 var(--mono); }
|
||||
|
||||
/* Planny. The star eye is always the highlight color. */
|
||||
.planny { display: block; width: 44px; height: 60px; overflow: visible; flex: none; color: var(--chalk); --shell: var(--bp-800); --star: var(--mark); }
|
||||
@@ -147,6 +156,8 @@ p { margin: 0; }
|
||||
.hero-foot { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 24px 48px; align-items: end; margin-top: 32px; }
|
||||
.hero-foot .lede { margin-top: 0; }
|
||||
.cta { display: flex; flex-wrap: wrap; gap: 12px; }
|
||||
.hero-cmd { max-width: 880px; margin: 22px auto 0; }
|
||||
.cmd.hero-cmd pre { font-size: 15px; }
|
||||
|
||||
/* The stage: dimension lines, the app window, the four moments of a session. */
|
||||
.stage { position: relative; max-width: 1320px; margin: 64px auto 0; padding: 0 var(--gutter); }
|
||||
@@ -175,7 +186,7 @@ p { margin: 0; }
|
||||
.surface img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; object-position: top left; opacity: 0; transition: opacity 0.5s ease; }
|
||||
.surface img.on { opacity: 1; }
|
||||
.stamp { position: absolute; right: 9%; top: 40%; padding: 10px 20px 8px; border: 3px solid var(--mark); border-radius: 6px; color: var(--mark); font: 800 clamp(15px, 2.2vw, 28px)/1.1 var(--sans); font-stretch: 122%; letter-spacing: 0.02em; background: rgba(23, 21, 19, 0.82); transform: rotate(-7deg) scale(1.6); opacity: 0; pointer-events: none; }
|
||||
.stamp small { display: block; font: 400 11px/1.6 var(--mono); letter-spacing: 0; color: var(--a-ink-2); }
|
||||
.stamp small { display: block; font: 400 12.5px/1.6 var(--mono); letter-spacing: 0; color: var(--a-ink-2); }
|
||||
.stamp.on { opacity: 1; transform: rotate(-7deg) scale(1); transition: transform 0.22s cubic-bezier(0.2, 1.4, 0.4, 1), opacity 0.12s; }
|
||||
.term { display: flex; flex-direction: column; min-width: 0; min-height: 0; background: var(--a-term); border-left: 1px solid var(--a-rule); }
|
||||
.stage[data-dock="bottom"] .term { border-left: 0; border-top: 1px solid var(--a-rule); height: 190px; }
|
||||
@@ -186,7 +197,7 @@ html.js .seg { display: inline-flex; }
|
||||
.seg button + button { border-left: 1px solid rgba(255, 255, 255, 0.22); }
|
||||
.seg button[aria-pressed="true"] { background: var(--a-accent); color: #0c1117; }
|
||||
.seg button:focus-visible { outline-offset: -2px; }
|
||||
.tb { flex: 1; min-height: 0; margin: 0; padding: 12px; overflow: hidden; font: 400 11.5px/1.75 var(--mono); white-space: pre-wrap; word-break: break-word; display: flex; flex-direction: column; justify-content: flex-end; color: var(--a-ink); }
|
||||
.tb { flex: 1; min-height: 0; margin: 0; padding: 12px; overflow: hidden; font: 400 12.5px/1.75 var(--mono); white-space: pre-wrap; word-break: break-word; display: flex; flex-direction: column; justify-content: flex-end; color: var(--a-ink); }
|
||||
.tb .d { color: #a39b8e; }
|
||||
.tb .g { color: #7fd29a; }
|
||||
.tb .b { color: #8fb8f0; }
|
||||
@@ -231,7 +242,7 @@ html:not(.js) .moments button { cursor: default; }
|
||||
.details svg .hi { stroke: var(--mark); }
|
||||
.details svg .hi-fill { fill: var(--mark); stroke: none; }
|
||||
.details svg .soft { stroke-dasharray: 3 4; stroke: var(--chalk-3); }
|
||||
.details svg text { fill: var(--chalk-2); stroke: none; font: 400 8px var(--mono); }
|
||||
.details svg text { fill: var(--chalk-2); stroke: none; font: 400 12.5px var(--mono); }
|
||||
.details p { color: var(--chalk-2); font-size: 15.5px; margin-top: 8px; }
|
||||
|
||||
/* The Implementation Loop. */
|
||||
@@ -248,7 +259,7 @@ html:not(.js) .moments button { cursor: default; }
|
||||
.banner .pips i.done { background: var(--a-ok); }
|
||||
.banner .pips i.now { background: var(--a-accent); animation: pulse 1.2s ease-in-out infinite alternate; }
|
||||
@keyframes pulse { to { opacity: 0.45; } }
|
||||
.banner .el { margin-left: auto; color: var(--a-ink-2); font: 400 12px var(--mono); }
|
||||
.banner .el { margin-left: auto; color: var(--a-ink-2); font: 400 12.5px var(--mono); }
|
||||
.banner .stop { padding: 4px 10px; border: 1px solid var(--a-rule-2); border-radius: 6px; font-size: 12.5px; color: var(--a-ink-2); }
|
||||
.ledger-scroll { overflow-x: auto; }
|
||||
.ledger th:first-child { padding-left: 16px; }
|
||||
@@ -257,7 +268,7 @@ html:not(.js) .moments button { cursor: default; }
|
||||
.ledger thead th { font-weight: 500; font-size: 12.5px; color: var(--a-ink-2); background: var(--a-panel); }
|
||||
.ledger tbody th { font-weight: 600; white-space: nowrap; }
|
||||
.ledger tbody th small { display: block; font-weight: 400; color: var(--a-ink-2); font-size: 12.5px; }
|
||||
.ledger td { font-family: var(--mono); font-size: 11.5px; line-height: 1.7; color: var(--a-ink-2); white-space: nowrap; }
|
||||
.ledger td { font-family: var(--mono); font-size: 12.5px; line-height: 1.7; color: var(--a-ink-2); white-space: nowrap; }
|
||||
.ledger td[data-s="done"] { color: #7fd29a; }
|
||||
.ledger td[data-s="done"]::before { content: "\2713\00a0"; }
|
||||
.ledger td[data-s="now"] { color: var(--a-ink); }
|
||||
@@ -283,21 +294,21 @@ html:not(.js) .moments button { cursor: default; }
|
||||
.pipe .n { position: relative; display: grid; place-items: center; width: 36px; height: 36px; border: 1.5px solid var(--chalk); border-radius: 50%; background: var(--bp-950); font: 600 13px var(--mono); }
|
||||
.pipe li.opt .n { border-style: dashed; border-color: var(--chalk-3); color: var(--chalk-2); }
|
||||
.pipe h3 { margin-top: 18px; }
|
||||
.pipe h3 small { font: 400 11.5px var(--mono); color: var(--chalk-3); margin-left: 4px; }
|
||||
.pipe h3 small { font: 400 12.5px var(--mono); color: var(--chalk-3); margin-left: 4px; }
|
||||
.pipe p { color: var(--chalk-2); font-size: 14.5px; line-height: 1.5; margin-top: 6px; }
|
||||
.pipe code { display: block; margin-top: 12px; color: var(--mark); font-size: 10.5px; line-height: 1.6; }
|
||||
.pipe .out { display: block; margin-top: 4px; color: var(--chalk-3); font: 400 10.5px/1.6 var(--mono); }
|
||||
.pipe code { display: block; margin-top: 12px; color: var(--mark); font-size: 12.5px; line-height: 1.6; }
|
||||
.pipe .out { display: block; margin-top: 4px; color: var(--chalk-3); font: 400 12.5px/1.6 var(--mono); }
|
||||
.under { display: grid; grid-template-columns: minmax(0, 5fr) minmax(0, 7fr); gap: 48px 64px; margin-top: 88px; }
|
||||
.under h3 { font-size: 1.45rem; font-weight: 800; font-stretch: 115%; letter-spacing: -0.01em; }
|
||||
.under h3 + p { color: var(--chalk-2); margin-top: 10px; font-size: 15.5px; }
|
||||
.tree { margin: 22px 0 0; padding: 20px 22px; border: 1px solid var(--line-2); border-radius: 6px; background: rgba(7, 22, 52, 0.6); font: 400 12px/1.95 var(--mono); color: var(--chalk-2); overflow-x: auto; white-space: pre; }
|
||||
.tree { margin: 22px 0 0; padding: 20px 22px; border: 1px solid var(--line-2); border-radius: 6px; background: rgba(7, 22, 52, 0.6); font: 400 12.5px/1.95 var(--mono); color: var(--chalk-2); overflow-x: auto; white-space: pre; }
|
||||
.tree b { color: var(--chalk); font-weight: 500; }
|
||||
.tree .x { color: var(--ok); }
|
||||
.tree .w { color: var(--mark); }
|
||||
.tree .c { color: var(--chalk-3); }
|
||||
.skills { margin: 22px 0 0; padding: 0; list-style: none; display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 40px; border-top: 1px solid var(--line-2); }
|
||||
.skills li { padding: 12px 0; border-bottom: 1px solid var(--line-2); font-size: 14.5px; line-height: 1.45; color: var(--chalk-2); }
|
||||
.skills code { display: block; color: var(--chalk); font-size: 11.5px; margin-bottom: 3px; }
|
||||
.skills code { display: block; color: var(--chalk); font-size: 12.5px; margin-bottom: 3px; }
|
||||
.agents { margin-top: 28px; color: var(--chalk-2); font-size: 15.5px; max-width: 72ch; }
|
||||
|
||||
/* The rules. */
|
||||
@@ -313,6 +324,7 @@ html:not(.js) .moments button { cursor: default; }
|
||||
.shots img { display: block; width: 100%; border-radius: 8px; box-shadow: 0 0 0 1px rgba(238, 244, 255, 0.22), 0 24px 60px rgba(2, 8, 24, 0.6); }
|
||||
.shots figcaption { margin-top: 16px; color: var(--chalk-2); font-size: 15.5px; max-width: 56ch; }
|
||||
.shots figcaption strong { color: var(--chalk); }
|
||||
.loop-shots { grid-template-columns: minmax(0, 1fr); gap: 28px; margin-top: 36px; }
|
||||
.aside { margin-top: 56px; display: flex; gap: 18px; align-items: center; color: var(--chalk-2); max-width: 70ch; }
|
||||
.aside .planny { width: 34px; height: 46px; }
|
||||
|
||||
@@ -320,12 +332,17 @@ html:not(.js) .moments button { cursor: default; }
|
||||
.install { padding: 120px 0 104px; border-top: 1px solid var(--line-2); }
|
||||
.install-grid { display: grid; grid-template-columns: minmax(0, 5fr) minmax(0, 7fr); gap: 48px 64px; align-items: start; }
|
||||
.before { border: 1px solid var(--line-2); border-radius: 6px; background: rgba(7, 22, 52, 0.7); padding: 22px 24px; font-size: 15.5px; }
|
||||
.before h3 { margin-bottom: 10px; }
|
||||
.needs { margin: 16px 0 0; color: var(--chalk-2); font-size: 15.5px; }
|
||||
.needs strong { color: var(--chalk); }
|
||||
.before { margin-top: 16px; padding: 14px 24px; }
|
||||
.before summary { cursor: pointer; font-weight: 700; color: var(--chalk); min-height: 28px; }
|
||||
.before summary:focus-visible { outline: 2px solid var(--mark); outline-offset: 4px; }
|
||||
.before[open] summary { margin-bottom: 10px; }
|
||||
.before ul { margin: 0; padding-left: 20px; color: var(--chalk-2); }
|
||||
.before li { margin: 8px 0; }
|
||||
.before strong { color: var(--chalk); }
|
||||
.cmd { display: flex; align-items: center; gap: 12px; margin-top: 20px; padding: 10px 10px 10px 16px; background: var(--bp-950); border: 1.5px solid var(--chalk); border-radius: 6px; }
|
||||
.cmd pre { flex: 1; min-width: 0; margin: 0; overflow-x: auto; font: 400 11.5px/1.6 var(--mono); white-space: pre; color: var(--chalk); }
|
||||
.cmd pre { flex: 1; min-width: 0; margin: 0; overflow-x: auto; font: 400 12.5px/1.6 var(--mono); white-space: pre; color: var(--chalk); }
|
||||
.cmd pre span { color: var(--mark); user-select: none; }
|
||||
.copy { flex: none; min-height: 40px; padding: 0 16px; border: 0; border-radius: 4px; background: var(--mark); color: var(--bp-950); font: 700 14px var(--sans); cursor: pointer; }
|
||||
.copy:hover { background: #ffe08a; }
|
||||
@@ -373,7 +390,7 @@ footer .brand { margin-right: auto; }
|
||||
.details li:first-child { border-top: 0; }
|
||||
.moments button { padding: 12px 12px 10px; font-size: 13.5px; }
|
||||
.cmd { flex-direction: column; align-items: stretch; padding: 14px; }
|
||||
.cmd pre { font-size: 11.5px; }
|
||||
.cmd pre { font-size: 12.5px; }
|
||||
.brand span { display: none; }
|
||||
}
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
@@ -398,6 +415,11 @@ footer .brand { margin-right: auto; }
|
||||
.light { position: absolute; left: -3%; right: -3%; top: -110px; height: 560px; background: radial-gradient(ellipse 50% 50% at 50% 50%, var(--light-1), var(--light-2) 40%, transparent 72%); filter: blur(46px); pointer-events: none; }
|
||||
.win { transform-origin: 50% 100%; transform: rotateX(var(--tilt, 0deg)); box-shadow: 0 0 0 1px var(--line-2), 0 -18px 70px -10px color-mix(in srgb, var(--light-2) 55%, transparent), 0 40px 90px rgba(0, 0, 0, 0.6); }
|
||||
.moments, .stage .fig-note { position: relative; }
|
||||
.pause { display: block; margin: 16px auto 0; min-height: 40px; padding: 0 18px; border: 1px solid var(--line-2); border-radius: 6px; background: transparent; color: var(--chalk); font: 600 14px var(--sans); cursor: pointer; }
|
||||
html:not(.js) .pause { display: none; }
|
||||
.pause[aria-pressed="true"] { background: rgba(238, 244, 255, 0.1); }
|
||||
.pause:hover { background: rgba(238, 244, 255, 0.07); }
|
||||
.pause:focus-visible { outline: 2px solid var(--mark); outline-offset: 2px; }
|
||||
.tree, .before { background: color-mix(in srgb, var(--bp-950) 70%, transparent); }
|
||||
.install { position: relative; overflow: hidden; }
|
||||
.install::before { content: ""; position: absolute; left: 10%; right: 10%; bottom: -330px; height: 460px; background: radial-gradient(ellipse 50% 50% at 50% 50%, var(--light-1), var(--light-2) 40%, transparent 72%); filter: blur(60px); opacity: .5; pointer-events: none; }
|
||||
@@ -454,6 +476,10 @@ footer .brand { margin-right: auto; }
|
||||
<a class="btn solid" href="#install">Install Plan2Code</a>
|
||||
<a class="btn line" href="#workflow">See the workflow</a>
|
||||
</div>
|
||||
<div class="cmd hero-cmd">
|
||||
<pre><span aria-hidden="true">$ </span>npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git#release</pre>
|
||||
<button class="copy" type="button" aria-label="Copy the install command">Copy</button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@@ -487,10 +513,10 @@ footer .brand { margin-right: auto; }
|
||||
</div>
|
||||
<div class="wbody">
|
||||
<div class="surface" id="surface">
|
||||
<img class="on" src="screenshots/dashboard-plan-dark.webp" width="2560" height="1600" alt="The Plan2Code dashboard for a new task API project: the steps in order as cards, with the Plan card marked Suggested.">
|
||||
<img src="screenshots/question-dark.webp" width="2560" height="1600" alt="A Plan question card, How tasks are paged, with three options, the first marked Suggested, each with its trade-off underneath.">
|
||||
<img src="screenshots/build-dark.webp" width="2560" height="1600" alt="Phase 3 of the task API being built: 5 of 11 done on the progress bar, and the phase's task list with the first five ticked.">
|
||||
<img src="screenshots/signoff-dark.webp" width="2560" height="1600" 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.">
|
||||
<img class="on" src="screenshots/dashboard-plan-dark.webp" srcset="screenshots/dashboard-plan-dark-1280.webp 1280w, screenshots/dashboard-plan-dark.webp 2560w" sizes="(min-width: 1240px) 900px, 100vw" width="2560" height="1600" fetchpriority="high" aria-hidden="false" alt="The Plan2Code dashboard for a new task API project: the steps in order as cards, with the Plan card marked Suggested.">
|
||||
<img src="screenshots/question-dark.webp" srcset="screenshots/question-dark-1280.webp 1280w, screenshots/question-dark.webp 2560w" sizes="(min-width: 1240px) 900px, 100vw" width="2560" height="1600" loading="lazy" aria-hidden="true" alt="A Plan question card, How tasks are paged, with three options, the first marked Suggested, each with its trade-off underneath.">
|
||||
<img src="screenshots/build-dark.webp" srcset="screenshots/build-dark-1280.webp 1280w, screenshots/build-dark.webp 2560w" sizes="(min-width: 1240px) 900px, 100vw" width="2560" height="1600" loading="lazy" aria-hidden="true" alt="Phase 3 of the task API being built: 5 of 11 done on the progress bar, and the phase's task list with the first five ticked.">
|
||||
<img src="screenshots/signoff-dark.webp" srcset="screenshots/signoff-dark-1280.webp 1280w, screenshots/signoff-dark.webp 2560w" sizes="(min-width: 1240px) 900px, 100vw" width="2560" height="1600" loading="lazy" aria-hidden="true" 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.">
|
||||
<div class="stamp" id="stamp" aria-hidden="true">Approved<small>phase 3 of 4, by you</small></div>
|
||||
</div>
|
||||
<div class="term">
|
||||
@@ -521,6 +547,7 @@ footer .brand { margin-right: auto; }
|
||||
<li><button type="button" aria-pressed="false"><strong>Sign off</strong>Nothing is marked complete until you approve it.</button></li>
|
||||
</ol>
|
||||
<p class="fig-note">Illustration: the app's window drawn around real screenshots of its pages. The terminal lines are an example.</p>
|
||||
<button class="pause" id="pause" type="button" aria-pressed="false">Pause the tour</button>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
@@ -552,6 +579,16 @@ footer .brand { margin-right: auto; }
|
||||
<p>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.</p>
|
||||
</li>
|
||||
</ul>
|
||||
<div class="shots">
|
||||
<figure>
|
||||
<img loading="lazy" src="screenshots/app-launch-dark.webp" width="2560" height="1600" alt="The desktop app's launch card, asking which agent, model and effort to start on.">
|
||||
<figcaption><strong>Pick the agent first.</strong> The launch card asks which agent, model and effort to start on, with permission checks as their own tick.</figcaption>
|
||||
</figure>
|
||||
<figure>
|
||||
<img loading="lazy" src="screenshots/app-terminal-dark.webp" width="2560" height="1600" alt="The desktop app with the dashboard on the left and the agent's terminal docked on the right.">
|
||||
<figcaption><strong>The plan beside the agent.</strong> The dashboard and the agent's terminal share one window, docked where you like.</figcaption>
|
||||
</figure>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
@@ -591,6 +628,16 @@ footer .brand { margin-right: auto; }
|
||||
<div class="ping"><div><b>✅ Phase complete</b><span>Plan2Code 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.</span></div></div>
|
||||
</div>
|
||||
<p class="fig-note">Illustration with example data. The message is the one the loop sends to your chat.</p>
|
||||
<div class="shots loop-shots">
|
||||
<figure>
|
||||
<img loading="lazy" src="screenshots/loop-setup-dark.webp" width="2560" height="1600" alt="The Implementation Loop setup screen in the desktop app.">
|
||||
<figcaption><strong>Set it up once.</strong> Pick the phases, a model strength for each and the quick check.</figcaption>
|
||||
</figure>
|
||||
<figure>
|
||||
<img loading="lazy" src="screenshots/loop-banner-dark.webp" width="2560" height="1600" alt="The Implementation Loop banner while a phase builds, with Stop after this phase.">
|
||||
<figcaption><strong>Watch it run.</strong> The banner shows the phase, the time and a way to stop after this phase.</figcaption>
|
||||
</figure>
|
||||
</div>
|
||||
<div class="stops">
|
||||
<h3>It would rather stop than guess. The loop ends on a stop screen, with the evidence, when:</h3>
|
||||
<ul>
|
||||
@@ -627,7 +674,7 @@ footer .brand { margin-right: auto; }
|
||||
<h3>The checkboxes are the state</h3>
|
||||
<p>Progress lives in the spec files, not in the chat. Close the window mid-phase and nothing is lost.</p>
|
||||
<pre class="tree" aria-label="Example spec folder"><b>specs/task-api/</b>
|
||||
├─ PLAN-DRAFT-2026-11-02.md
|
||||
├─ PLAN-DRAFT-YYYYMMDD.md
|
||||
├─ overview.md <span class="c">phases 1 and 2 done</span>
|
||||
├─ phase-1.md <span class="x">[x] 4 of 4</span>
|
||||
├─ phase-2.md <span class="x">[x] 5 of 5</span>
|
||||
@@ -647,6 +694,7 @@ footer .brand { margin-right: auto; }
|
||||
<li><code>/plan2code-xray</code>Explains how and why an area of the code works.</li>
|
||||
<li><code>/plan2code-pr-prep</code>Runs the checks your branch needs and writes the PR description.</li>
|
||||
<li><code>/plan2code-test</code>Finds code with no tests and writes them in your project's style.</li>
|
||||
<li><code>/plan2code-deps</code>Finds outdated packages, says how safe each update is, and applies only what you pick.</li>
|
||||
<li><code>/plan2code-dead-code</code>Finds code nothing uses and removes only what you pick.</li>
|
||||
<li><code>/plan2code-1b-revise-plan</code>Requirements moved mid-build: revise the specs, not the code.</li>
|
||||
<li><code>/plan2code-handoff</code>Packs a session into a document a fresh one resumes from.</li>
|
||||
@@ -655,7 +703,7 @@ footer .brand { margin-right: auto; }
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<p class="agents">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.</p>
|
||||
<p class="agents">The skills install into every agent the skills CLI supports, including Claude Code, Cursor, GitHub Copilot, Windsurf, Codex, Devin, OpenCode, Gemini CLI, Cline, Goose, Zed and more. 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.</p>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
@@ -687,7 +735,7 @@ footer .brand { margin-right: auto; }
|
||||
<figcaption><strong>Ask, beside the cards.</strong> A chat for anything you want to know, answered at the agent's next check-in. It never holds up your answers.</figcaption>
|
||||
</figure>
|
||||
<figure>
|
||||
<img loading="lazy" src="screenshots/notepad-dark.webp" width="2560" height="1600" alt="The Notebook open over a question: two named tabs, and a heading, bullets and bold styled in place as they are typed.">
|
||||
<img loading="lazy" src="screenshots/notebook-dark.webp" width="2560" height="1600" alt="The Notebook open over a question: two named tabs, and a heading, bullets and bold styled in place as they are typed.">
|
||||
<figcaption><strong>A private notebook.</strong> Markdown and pictures, one pad per folder. The agent reads a tab only when you start a workflow from it.</figcaption>
|
||||
</figure>
|
||||
<figure>
|
||||
@@ -695,15 +743,23 @@ footer .brand { margin-right: auto; }
|
||||
<figcaption><strong>A clear next step.</strong> Every ending says what happened and what to run next, with one button to carry on in the same session.</figcaption>
|
||||
</figure>
|
||||
<figure>
|
||||
<img loading="lazy" src="screenshots/dashboard-utilities-dark.webp" width="2560" height="1600" alt="The dashboard's utility cards: Get a PR ready, Write missing tests, Clear out dead code, Changelog, Git and Handoff, each with a line on what it does and its command.">
|
||||
<img loading="lazy" src="screenshots/dashboard-utilities-dark.webp" width="2560" height="1600" alt="The dashboard's utility cards: Diagnose a bug, Get a PR ready, Write missing tests, Clear out dead code, Update dependencies, Prototype a screen, Changelog, Git (noting the folder is not a git repository yet) and Handoff, each with a line on what it does and its command.">
|
||||
<figcaption><strong>Every skill is a card.</strong> The any-time skills sit on the dashboard beside the steps, each with what it does and the command behind it.</figcaption>
|
||||
</figure>
|
||||
<figure>
|
||||
<img loading="lazy" src="screenshots/git-dark.webp" width="2560" height="1600" alt="The git board on feature/task-endpoints: the Changes tab opens on a Next step card reading Commit 3 files, above the three changed files ticked for the commit.">
|
||||
<figcaption><strong>A git board.</strong> Changes, Branches and Sync, opening on your likely next step. It asks before anything is pushed, published or deleted, and it never force-pushes.</figcaption>
|
||||
</figure>
|
||||
<figure>
|
||||
<img loading="lazy" src="screenshots/signoff-changes-dark.webp" width="2560" height="1600" alt="The Changes tab beside the Approve this phase card: three changed files listed on the left, and the diff of paginate.js on the right with added and removed lines marked.">
|
||||
<figcaption><strong>Read the diff before you sign.</strong> The Changes tab lists every file the phase touched, with the diff beside the approval, so you see the code before you say yes.</figcaption>
|
||||
</figure>
|
||||
<figure>
|
||||
<img loading="lazy" src="screenshots/lessons-dark.webp" width="2560" height="1600" alt="The Lessons to keep card: three lessons about the task API, each with Keep, Reword and Drop.">
|
||||
<figcaption><strong>It remembers what it learned about your code.</strong> Lessons are offered at the end of a run, kept only when you say so, and saved with the repo for the next session.</figcaption>
|
||||
</figure>
|
||||
</div>
|
||||
<p class="aside"><svg class="planny" viewBox="0 0 22 30" aria-hidden="true" focusable="false"><use href="#pl-body"/><use href="#pl-up"/></svg><span>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.</span></p>
|
||||
<p class="aside"><svg class="planny" viewBox="0 0 22 30" aria-hidden="true" focusable="false"><use href="#pl-body"/><use href="#pl-up"/></svg><span>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. <a href="https://github.com/jparkerweb/plan2code/blob/main/.readme/walkthrough.md">Read the walkthrough</a> for a whole feature, start to finish.</span></p>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
@@ -711,26 +767,27 @@ footer .brand { margin-right: auto; }
|
||||
<div class="wrap install-grid">
|
||||
<div>
|
||||
<h2 id="install-title">One line installs all of it.</h2>
|
||||
<p class="lede">The skills, the <code>plan2code</code> command and, if you say yes, the desktop app. Run it again any time to update. MIT licensed.</p>
|
||||
<p class="lede">The skills, the <code>plan2code</code> command and, if you say yes, the desktop app. Run it again any time to update. Apache 2.0 licensed.</p>
|
||||
</div>
|
||||
<div>
|
||||
<div class="before">
|
||||
<h3>Before you start</h3>
|
||||
<div class="cmd">
|
||||
<pre><span aria-hidden="true">$ </span>npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git#release</pre>
|
||||
<button class="copy" type="button" aria-label="Copy the install command">Copy</button>
|
||||
</div>
|
||||
<p class="needs"><strong>Needs Node 18+ and Git.</strong> Includes the desktop app for Windows, macOS and Linux (<a href="https://github.com/jparkerweb/plan2code/releases/latest">latest release</a>).</p>
|
||||
<details class="before">
|
||||
<summary>Before you start</summary>
|
||||
<ul>
|
||||
<li><strong>Node.js 18 or newer.</strong> Check with <code>node --version</code>. No Node? Get it from <a href="https://nodejs.org/">nodejs.org</a> (the LTS download), or run <code>winget install OpenJS.NodeJS.LTS</code> on Windows, <code>brew install node</code> on macOS, or use <code>nvm</code> on Linux. Then open a new terminal.</li>
|
||||
<li><strong>Node.js 18 or newer</strong> (22 or newer if you install Claude Code with npm). Check with <code>node --version</code>. No Node? Get it from <a href="https://nodejs.org/">nodejs.org</a> (the LTS download), or run <code>winget install OpenJS.NodeJS.LTS</code> on Windows, <code>brew install node</code> on macOS, or use <code>nvm</code> on Linux. Then open a new terminal.</li>
|
||||
<li><strong>Git.</strong> Check with <code>git --version</code>. The installer is fetched from GitHub with Git, and without it npm stops with <code>spawn git ENOENT</code>. No Git? Get it from <a href="https://git-scm.com/downloads">git-scm.com</a>, or run <code>winget install Git.Git</code> on Windows, <code>brew install git</code> on macOS, or use your package manager on Linux. Then open a new terminal.</li>
|
||||
<li><strong>Start from your project.</strong> Open your terminal in the project you want to work on (<code>cd</code> into it) before you run anything. Plan2Code works on the folder you start it in.</li>
|
||||
<li><strong>Ways in.</strong> <code>plan2code</code> (Claude Code, Devin or Codex), or type <code>/plan2code</code> in your agent (<code>$plan2code</code> in Codex).</li>
|
||||
<li><strong>No agent yet?</strong> Install Claude Code, Codex or Devin first, or let the <code>plan2code</code> command's setup page walk you through it.</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="cmd">
|
||||
<pre><span aria-hidden="true">$ </span>npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git</pre>
|
||||
<button class="copy" type="button" aria-label="Copy the install command">Copy</button>
|
||||
</div>
|
||||
</details>
|
||||
<ul class="after">
|
||||
<li><strong>Then, from your project, run <code>plan2code</code>.</strong> With the app installed it opens the app, and <code>plan2code --classic</code> keeps the agent in your terminal. Already inside your agent? Type <code>/plan2code</code> (<code>$plan2code</code> in Codex).</li>
|
||||
<li><strong>The app is checked before it is kept.</strong> 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. <a href="https://github.com/jparkerweb/plan2code/blob/main/docs/desktop-app.md">Read the app guide</a>.</li>
|
||||
<li><strong>The app is checked before it is kept.</strong> 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. The app is not code-signed (signing is not planned for now), so your system may ask you to allow it once. <a href="https://github.com/jparkerweb/plan2code/blob/main/docs/desktop-app.md">Read the app guide</a>.</li>
|
||||
<li><strong>Back at your prompt with nothing printed?</strong> The installer always opens a menu, so no output at all means npm could not reach the repository and hid the reason. <code>git ls-remote https://github.com/jparkerweb/plan2code.git</code> shows why.</li>
|
||||
</ul>
|
||||
</div>
|
||||
@@ -746,23 +803,23 @@ footer .brand { margin-right: auto; }
|
||||
<a href="https://github.com/jparkerweb/plan2code#readme">README</a>
|
||||
<a href="https://github.com/jparkerweb/plan2code/releases">Releases</a>
|
||||
<a href="https://github.com/jparkerweb/plan2code/blob/main/CHANGELOG.md">Changelog</a>
|
||||
<span>MIT license</span>
|
||||
<span>Apache 2.0 license</span>
|
||||
</div>
|
||||
</footer>
|
||||
|
||||
<script>
|
||||
(function () {
|
||||
var CMD = 'npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git';
|
||||
var CMD = 'npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git#release';
|
||||
var $ = function (i) { return document.getElementById(i); };
|
||||
var calm = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
|
||||
|
||||
/* Copy the install command. */
|
||||
var copy = document.querySelector('.copy');
|
||||
var copyTimer;
|
||||
var copies = document.querySelectorAll('.copy');
|
||||
var copyTimer, copy;
|
||||
function copied() {
|
||||
copy.textContent = 'Copied';
|
||||
[].forEach.call(copies, function (c) { c.textContent = 'Copied'; });
|
||||
clearTimeout(copyTimer);
|
||||
copyTimer = setTimeout(function () { copy.textContent = 'Copy'; }, 1800);
|
||||
copyTimer = setTimeout(function () { [].forEach.call(copies, function (c) { c.textContent = 'Copy'; }); }, 1800);
|
||||
}
|
||||
function copyFallback() {
|
||||
var ta = document.createElement('textarea');
|
||||
@@ -775,9 +832,11 @@ footer .brand { margin-right: auto; }
|
||||
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();
|
||||
[].forEach.call(copies, function (c) {
|
||||
c.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. */
|
||||
@@ -831,7 +890,10 @@ footer .brand { margin-right: auto; }
|
||||
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 < imgs.length; k++) {
|
||||
imgs[k].classList.toggle('on', k === i);
|
||||
imgs[k].setAttribute('aria-hidden', String(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');
|
||||
@@ -852,8 +914,24 @@ footer .brand { margin-right: auto; }
|
||||
}, calm ? 0 : 3000);
|
||||
if (auto) later(function () { show((i + 1) % MOMENTS.length); }, BEAT);
|
||||
}
|
||||
/* A visible, keyboard-reachable pause for the rotation. */
|
||||
var pauseBtn = $('pause');
|
||||
function syncPause() {
|
||||
/* One fixed label; aria-pressed carries the state. */
|
||||
pauseBtn.setAttribute('aria-pressed', String(!auto));
|
||||
}
|
||||
pauseBtn.addEventListener('click', function () {
|
||||
auto = !auto;
|
||||
syncPause();
|
||||
if (auto) show(at);
|
||||
else {
|
||||
while (timers.length) clearTimeout(timers.pop());
|
||||
moments.classList.remove('auto');
|
||||
}
|
||||
});
|
||||
syncPause();
|
||||
[].forEach.call(btns, function (b, i) {
|
||||
b.addEventListener('click', function () { auto = false; show(i); });
|
||||
b.addEventListener('click', function () { auto = false; syncPause(); show(i); });
|
||||
});
|
||||
[].forEach.call(document.querySelectorAll('.seg button'), function (b) {
|
||||
b.addEventListener('click', function () {
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
User-agent: *
|
||||
Allow: /
|
||||
|
||||
Sitemap: https://plan2code.jparkerweb.com/sitemap.xml
|
||||
|
After Width: | Height: | Size: 121 KiB |
|
After Width: | Height: | Size: 128 KiB |
|
After Width: | Height: | Size: 30 KiB |
|
After Width: | Height: | Size: 36 KiB |
|
Before Width: | Height: | Size: 99 KiB After Width: | Height: | Size: 107 KiB |
|
Before Width: | Height: | Size: 107 KiB After Width: | Height: | Size: 115 KiB |
|
After Width: | Height: | Size: 48 KiB |
|
Before Width: | Height: | Size: 119 KiB After Width: | Height: | Size: 121 KiB |
|
Before Width: | Height: | Size: 122 KiB After Width: | Height: | Size: 124 KiB |
|
Before Width: | Height: | Size: 90 KiB After Width: | Height: | Size: 89 KiB |
|
Before Width: | Height: | Size: 95 KiB After Width: | Height: | Size: 95 KiB |
|
After Width: | Height: | Size: 34 KiB |
|
Before Width: | Height: | Size: 89 KiB After Width: | Height: | Size: 87 KiB |
|
Before Width: | Height: | Size: 97 KiB After Width: | Height: | Size: 91 KiB |
|
Before Width: | Height: | Size: 121 KiB After Width: | Height: | Size: 158 KiB |
|
Before Width: | Height: | Size: 132 KiB After Width: | Height: | Size: 170 KiB |
|
After Width: | Height: | Size: 104 KiB |
|
After Width: | Height: | Size: 110 KiB |
|
Before Width: | Height: | Size: 117 KiB After Width: | Height: | Size: 123 KiB |
|
Before Width: | Height: | Size: 122 KiB After Width: | Height: | Size: 128 KiB |
|
Before Width: | Height: | Size: 97 KiB After Width: | Height: | Size: 99 KiB |
|
Before Width: | Height: | Size: 101 KiB After Width: | Height: | Size: 104 KiB |
|
Before Width: | Height: | Size: 73 KiB After Width: | Height: | Size: 68 KiB |
|
Before Width: | Height: | Size: 78 KiB After Width: | Height: | Size: 72 KiB |
|
After Width: | Height: | Size: 146 KiB |
|
After Width: | Height: | Size: 156 KiB |
|
After Width: | Height: | Size: 110 KiB |
|
After Width: | Height: | Size: 118 KiB |
|
After Width: | Height: | Size: 28 KiB |
|
After Width: | Height: | Size: 32 KiB |
|
After Width: | Height: | Size: 32 KiB |
|
After Width: | Height: | Size: 66 KiB |
|
After Width: | Height: | Size: 74 KiB |
|
Before Width: | Height: | Size: 62 KiB |
|
Before Width: | Height: | Size: 67 KiB |
|
After Width: | Height: | Size: 62 KiB |
|
After Width: | Height: | Size: 67 KiB |
|
After Width: | Height: | Size: 46 KiB |
|
Before Width: | Height: | Size: 109 KiB After Width: | Height: | Size: 111 KiB |
|
Before Width: | Height: | Size: 119 KiB After Width: | Height: | Size: 119 KiB |
|
After Width: | Height: | Size: 124 KiB |
|
After Width: | Height: | Size: 132 KiB |
|
After Width: | Height: | Size: 40 KiB |
|
Before Width: | Height: | Size: 97 KiB After Width: | Height: | Size: 103 KiB |
|
Before Width: | Height: | Size: 105 KiB After Width: | Height: | Size: 110 KiB |
@@ -0,0 +1,6 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
|
||||
<url>
|
||||
<loc>https://plan2code.jparkerweb.com/</loc>
|
||||
</url>
|
||||
</urlset>
|
||||
|
After Width: | Height: | Size: 247 KiB |
@@ -1,7 +1,11 @@
|
||||
{
|
||||
"name": "plan2code",
|
||||
"version": "3.1.0",
|
||||
"version": "3.1.1",
|
||||
"private": true,
|
||||
"license": "Apache-2.0",
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
},
|
||||
"bin": {
|
||||
"plan2code-install": "./install.js"
|
||||
},
|
||||
|
||||
@@ -20,7 +20,7 @@
|
||||
"plan2code",
|
||||
"contributor-tooling"
|
||||
],
|
||||
"license": "MIT",
|
||||
"license": "Apache-2.0",
|
||||
"scripts": {
|
||||
"build": "tsup",
|
||||
"dev": "tsup --watch",
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
#!/usr/bin/env node
|
||||
// Writes the 1280px-wide variants of the landing page's hero pictures next to
|
||||
// the 2560px originals (`<name>-1280.webp`), for the page's srcset. Dev-only.
|
||||
//
|
||||
// node scripts/make-site-images.mjs [--browser <path>]
|
||||
//
|
||||
// Rerun it after capture-screenshots.mjs. Playwright has no WebP encoder of
|
||||
// its own, so the browser's canvas does the resize and the WebP export.
|
||||
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { launchBrowser } from "./browser.mjs";
|
||||
|
||||
const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
|
||||
const DIR = path.join(ROOT, "docs", "screenshots");
|
||||
const HERO = ["dashboard-plan-dark", "question-dark", "build-dark", "signoff-dark"];
|
||||
|
||||
const flag = process.argv.indexOf("--browser");
|
||||
const browser = await launchBrowser(flag > 0 ? { executablePath: process.argv[flag + 1] } : {});
|
||||
try {
|
||||
const page = await browser.newPage();
|
||||
for (const name of HERO) {
|
||||
const src = "data:image/webp;base64," + fs.readFileSync(path.join(DIR, `${name}.webp`)).toString("base64");
|
||||
const data = await page.evaluate(async (url) => {
|
||||
const img = new Image();
|
||||
img.src = url;
|
||||
await img.decode();
|
||||
const c = document.createElement("canvas");
|
||||
c.width = 1280;
|
||||
c.height = Math.round((img.naturalHeight * 1280) / img.naturalWidth);
|
||||
const g = c.getContext("2d");
|
||||
g.imageSmoothingQuality = "high";
|
||||
g.drawImage(img, 0, 0, c.width, c.height);
|
||||
return c.toDataURL("image/webp", 0.85).split(",")[1];
|
||||
}, src);
|
||||
const out = path.join(DIR, `${name}-1280.webp`);
|
||||
fs.writeFileSync(out, Buffer.from(data, "base64"));
|
||||
console.log(`${path.basename(out)} ${Math.round(fs.statSync(out).size / 1024)} KB`);
|
||||
}
|
||||
} finally {
|
||||
await browser.close();
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
#!/usr/bin/env node
|
||||
// Renders scripts/social-card.html to docs/social-card.png (1200x630), the
|
||||
// image the landing page's og:image points at (twitter:card falls back to it). Dev-only.
|
||||
//
|
||||
// node scripts/make-social-card.mjs [--browser <path>]
|
||||
//
|
||||
// Rerun it after docs/screenshots/signoff-dark.webp changes. Needs
|
||||
// playwright-core (a root devDependency) and a local Chrome or Edge.
|
||||
|
||||
import path from "node:path";
|
||||
import { fileURLToPath, pathToFileURL } from "node:url";
|
||||
import { launchBrowser } from "./browser.mjs";
|
||||
|
||||
const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
|
||||
const flag = process.argv.indexOf("--browser");
|
||||
const browser = await launchBrowser(flag > 0 ? { executablePath: process.argv[flag + 1] } : {});
|
||||
try {
|
||||
const page = await browser.newPage({ viewport: { width: 1200, height: 630 }, deviceScaleFactor: 1 });
|
||||
await page.goto(pathToFileURL(path.join(ROOT, "scripts", "social-card.html")).href);
|
||||
await page.evaluate(() => document.fonts.ready);
|
||||
await page.waitForFunction(() => [...document.images].every((i) => i.complete && i.naturalWidth > 0));
|
||||
const out = path.join(ROOT, "docs", "social-card.png");
|
||||
await page.screenshot({ path: out, clip: { x: 0, y: 0, width: 1200, height: 630 } });
|
||||
console.log(`wrote ${path.relative(ROOT, out)}`);
|
||||
} finally {
|
||||
await browser.close();
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
<!doctype html>
|
||||
<meta charset="utf-8">
|
||||
<title>Plan2Code social card</title>
|
||||
<style>
|
||||
@font-face { font-family: "Archivo"; src: url("../docs/fonts/archivo-latin.woff2") format("woff2"); font-weight: 300 900; font-stretch: 62% 125%; }
|
||||
* { box-sizing: border-box; margin: 0; }
|
||||
html, body { width: 1200px; height: 630px; overflow: hidden; }
|
||||
body {
|
||||
background: radial-gradient(900px 500px at 85% 10%, #1a4596 0%, #0b2150 55%, #071634 100%);
|
||||
font-family: "Archivo", system-ui, sans-serif;
|
||||
color: #eef4ff;
|
||||
position: relative;
|
||||
}
|
||||
.grid { position: absolute; inset: 0; background-image: linear-gradient(rgba(170,200,255,.08) 1px, transparent 1px), linear-gradient(90deg, rgba(170,200,255,.08) 1px, transparent 1px); background-size: 40px 40px; }
|
||||
.copy { position: absolute; left: 64px; top: 120px; width: 500px; }
|
||||
.brand { font-size: 26px; font-weight: 700; letter-spacing: .02em; color: #b9cbee; margin-bottom: 28px; }
|
||||
h1 { font-size: 76px; line-height: 1.02; font-weight: 800; font-stretch: 100%; letter-spacing: -.01em; }
|
||||
h1 span { display: block; }
|
||||
h1 .mark { color: #ffd45e; }
|
||||
p { margin-top: 28px; font-size: 26px; line-height: 1.35; color: #b9cbee; }
|
||||
.shot { position: absolute; left: 620px; top: 150px; width: 700px; border-radius: 14px; border: 1px solid rgba(170,200,255,.35); box-shadow: 0 30px 80px rgba(0,0,0,.5); }
|
||||
</style>
|
||||
<div class="grid"></div>
|
||||
<div class="copy">
|
||||
<div class="brand">Plan2Code</div>
|
||||
<h1><span>Plan it.</span><span>Approve it.</span><span class="mark">Let it build.</span></h1>
|
||||
<p>Plan, approve and build with your AI agent, on one page.</p>
|
||||
</div>
|
||||
<img class="shot" src="../docs/screenshots/signoff-dark.webp" alt="">
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "3.1.0",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"version": "3.1.1",
|
||||
"description": "A structured workflow of six steps (Pathfinder, Plan, Document, Implement, Review, Finalize) for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
"workflow",
|
||||
@@ -11,12 +11,12 @@
|
||||
"plan"
|
||||
],
|
||||
"author": "Justin Parker",
|
||||
"license": "MIT",
|
||||
"license": "Apache-2.0",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-11-15",
|
||||
"releaseDate": "2026-11-17",
|
||||
"mode": "utility"
|
||||
}
|
||||