Compare commits

..
6 Commits
27 changed files with 672 additions and 258 deletions

No files matched your search

+9 -7
View File
@@ -50,7 +50,7 @@ plan2code/
│ ├── check-skill-table.mjs # src/plan2code.md "What each skill reads and writes" table vs each skill's prompt and references
│ ├── parse-check.mjs # Imports every shipped browser module as real ESM
│ ├── screenshots/ # JSON payloads posted per shot (`ask` reuses `question.json`; `finish` follows `signoff.json`)
│ ├── test-web-console.mjs, test-launcher.mjs # node --test suites
│ ├── test-web-console.mjs, test-launcher.mjs, test-getting-started.mjs # node --test suites (the last keeps the newcomer docs in step)
│ ├── test-skill-scripts.mjs, test-script-<skill>.mjs, skill-script-helpers.mjs # Skill script suites and fixtures
│ └── validate-char-count.js # Pre-commit character count validator
├── skills/ # Generated, gitignored build output — one Agent Skill per src/ prompt
@@ -85,7 +85,7 @@ plan2code/
| `version.json` | Version metadata (name, version, description) |
| `QUICK-REFERENCE.md` | User quick-reference card |
| `src/statusline-claude/` | Claude CLI status bar (see Status Line below) |
| `src/launcher/plan2code.js` | Global `plan2code` command that opens the dashboard skill in Claude Code or Devin (installed by `I` and `A`; also via Custom → D) |
| `src/launcher/plan2code.js` | Global `plan2code` command that opens the dashboard skill in Claude Code, Devin or Codex (installed by `I` and Advanced → `E`; also via Advanced → `D`) |
## Workflow Prompts (in `src/`)
@@ -245,9 +245,10 @@ Key design points:
- **`validate()` in `lib.mjs` enforces four workflow rules mechanically**: max three open required questions, no internal vocabulary in a title, one recommended option, and no loop markers or metrics-scraper bait.
- **The palette is written twice for dark, and that duplication is the mechanism.** `@media (prefers-color-scheme: dark) :root:not([data-theme="light"])` follows the system; `:root[data-theme="dark"]` is the explicit choice from the colors panel. Drop the `:not()` and a system-dark browser overrides someone who asked for light. A chosen accent is applied as an inline custom property on `:root` (CSSOM, which the CSP allows), and the default is applied by REMOVING that override so the stylesheet's own per-theme values win. The server's `data-looks-accent` stand-in only lasts until `applyLooks()` runs, which removes it first thing — left on, its rule would beat "Back to default".
- **Help is in the page, built on first open.** The **?** button (`#btn-about`) opens `<dialog id="help-modal">`, which replaced the old "What this page is" About dialog. Its 17 panels and their icon sheet are hand-written HTML and SVG in `<template id="help-content">` in `index.html` (after `#start-poses`), cloned into `#help-panels` the first time **?** is pressed, so first load builds nothing and Help still reads fully once the server is gone. `help.js` supplies the tab list and rules, `app.js` the wiring (tab buttons, roving focus, `renderAbout()` for the live connection line on tab 1, `lightDismiss()`, and a Ctrl/⌘+Enter guard scoped to this dialog). SVG is styled by class and CSS variables only — a `style=` attribute is dropped by the CSP, and a test fails on one — and every number the prose quotes sits in a `data-fact` span a test checks against the constant it comes from.
- **Stuck sessions are explained twice, in Help and on the status line.** `stuck` ("When something looks stuck") is the second tab in `HELP_TABS`; its panel opens with a `help-callout` ("Check this first": Plan2Code often waits for a permission in the terminal, which the page cannot see) and four You see / Likely cause / Do this rows before the diagram. The quiet and Not running status lines carry a "What to check" button (`openHelpOn("stuck")`) inside the existing `role="status"` element, so it exists only while the symptom shows. Every finished and paused screen gets a "Before you close this" panel from `renderCloseGuide()` in `renderHandoff()` (Safe to close, Start fresh, Carry on). Tests in `scripts/test-web-console.mjs` check the tab order, the callout and rows, and the `renderCloseGuide` call.
- **Markdown is rendered to DOM nodes, never to an HTML string** (`public/render.js`), so agent-authored text that quotes a hostile source cannot execute. Only `marked.lexer()` is used.
Tests: `npm test` runs, in order, `validate-char-count.js`, `install.js --build-skills`, `parse-check.mjs`, `check-skill-table.mjs`, then `node --test scripts/test-web-console.mjs scripts/test-launcher.mjs scripts/test-skill-scripts.mjs scripts/test-script-pathfinder.mjs scripts/test-script-finalize.mjs scripts/test-script-handoff.mjs scripts/test-script-git-commit.mjs scripts/test-script-changelog.mjs`. The parse check exists because `node --check` parses a `.js` file as a CommonJS script and has already let a browser-fatal string literal through; it imports each shipped module as a real ES module instead. They live in `scripts/`, not `src/web-console/`, because everything under the latter ships into every skill.
Tests: `npm test` runs, in order, `validate-char-count.js`, `install.js --build-skills`, `parse-check.mjs`, `check-skill-table.mjs`, then `node --test scripts/test-web-console.mjs scripts/test-launcher.mjs scripts/test-getting-started.mjs scripts/test-skill-scripts.mjs scripts/test-script-pathfinder.mjs scripts/test-script-finalize.mjs scripts/test-script-handoff.mjs scripts/test-script-git-commit.mjs scripts/test-script-changelog.mjs`. The parse check exists because `node --check` parses a `.js` file as a CommonJS script and has already let a browser-fatal string literal through; it imports each shipped module as a real ES module instead. They live in `scripts/`, not `src/web-console/`, because everything under the latter ships into every skill.
**Adding a file under `public/` needs three edits, not one:** the file itself, the `SERVABLE` allow-list in `server.mjs`, and (for a module the page imports) a `<link rel="modulepreload">` in `index.html`. The set is hardcoded rather than a directory lookup so there is nothing to traverse; a new module missing from it 404s and the page dies at import with no useful error (a test fetches every import and fails naming the file). A module missing its preload still works, but loads serially after `app.js` and slows the first paint.
@@ -273,18 +274,19 @@ src/statusline-claude/
**Adaptive plan-usage display:** the formatter auto-selects between `5h/7d` rate-limit percentages (Pro/Max/Teams — when `rate_limits` present in stdin) and `Nk in · Nk out` session-token counts (Bedrock/Vertex/PAYG — when `rate_limits` absent). Segment is hidden when neither shape is available.
**Installer integration** lives in `install.js` under the `STATUS LINE INSTALLATION` section (`installStatusLine`, `uninstallStatusLine`). Included in `A` (Install All + dev tools); also available individually via Custom → `S`.
**Installer integration** lives in `install.js` under the `STATUS LINE INSTALLATION` section (`installStatusLine`, `uninstallStatusLine`). Included in Advanced → `E` (Everything); also available individually via Advanced → `S`.
## Global `plan2code` Command
Typing `plan2code` in any directory opens the dashboard skill against the current project, **in that directory**, in one of two CLIs (the `CLIS` table in the launcher):
Typing `plan2code` in any directory opens the dashboard skill against the current project, **in that directory**, in one of three CLIs (the `CLIS` table in the launcher):
| CLI | Runs |
| --- | --- |
| Claude Code | `claude /plan2code --permission-mode bypassPermissions [args]` |
| Devin | `devin --permission-mode bypass [args] -- /plan2code` |
| Codex | `codex --dangerously-bypass-approvals-and-sandbox [args] $plan2code` (Codex starts a skill with `$name`; the launch line follows Codex's documentation) |
On a terminal it first prints a Planny banner (`renderBanner()`). With both on `PATH` it asks `Plan2Code opens inside an AI coding agent. Pick which one to use:` as a numbered menu, the last pick pre-selected and marked `(last used)` (Enter keeps it; a number, `claude` or `devin` also work); with one installed it uses that without asking, printing `Opening with <CLI>…` (as does a `--cli` pick); with neither it exits 127 naming both. `--cli claude` / `--cli devin` (or `--cli=<name>`) skips the menu and is never forwarded; an unknown name exits 2, an uninstalled one 127. The pick is saved as `lastCli` in `~/.plan2code/launcher.json`, merged beside `lastFolder`. Before spawning, unless the forwarded args carry `--model` / `--model=`, it asks `Which model should <CLI> use?` from the curated `src/launcher/models.json` (copied to `~/.plan2code/bin/models.json`, overwritten by every install) merged with the user's additions in `~/.plan2code/models.json` (edited in the console's User Preferences → Models). Enter keeps the model the CLI last used; a pick appends `--model <id>`. Ctrl+C at any launcher prompt exits 130. With no TTY on stdin there is no menu (last pick, else the first installed) and no model question: it prints that the CLI will use the model last used in it (switch it in that CLI on its own, or pass `--model <name>`). Headings, numbers, defaults, retry lines and the `plan2code:` error prefixes are colored with `paint()` (the escape values of `install.js`'s `COLORS`, copied), stdout only when stdout is a TTY and stderr only when stderr is, and never when `NO_COLOR` is set; piped runs print plain text and no banner. Other arguments are forwarded to the CLI (`plan2code --model opus`), and its exit code is passed back. Tests: `scripts/test-launcher.mjs` (run by `npm test`) spawns the launcher against stand-in `claude`/`devin` commands and a temp home.
On a terminal it first prints a Planny banner (`renderBanner()`). With more than one on `PATH` it asks `Plan2Code opens inside an AI coding agent. Pick which one to use:` as a numbered menu, the last pick pre-selected and marked `(last used)` (Enter keeps it; a number or a CLI id also works); with one installed it uses that without asking, printing `Opening with <CLI>…` (as does a `--cli` pick); with none it exits 127 and prints `SKILL_STEPS`: how to install an agent, `cd` into the project, and type `/plan2code` (`$plan2code` in Codex). An uninstalled `--cli` pick prints the same steps after its error. `--cli claude` / `devin` / `codex` (or `--cli=<name>`) skips the menu and is never forwarded; an unknown name exits 2, an uninstalled one 127. The pick is saved as `lastCli` in `~/.plan2code/launcher.json`, merged beside `lastFolder`. Before spawning, unless the forwarded args carry `--model` / `--model=`, it asks `Which model should <CLI> use?` from the curated `src/launcher/models.json` (copied to `~/.plan2code/bin/models.json`, overwritten by every install) merged with the user's additions in `~/.plan2code/models.json` (edited in the console's User Preferences → Models). Enter keeps the model the CLI last used; a pick appends `--model <id>`. Ctrl+C at any launcher prompt exits 130. With no TTY on stdin there is no menu (last pick, else the first installed) and no model question: it prints that the CLI will use the model last used in it (switch it in that CLI on its own, or pass `--model <name>`). Headings, numbers, defaults, retry lines and the `plan2code:` error prefixes are colored with `paint()` (the escape values of `install.js`'s `COLORS`, copied), stdout only when stdout is a TTY and stderr only when stderr is, and never when `NO_COLOR` is set; piped runs print plain text and no banner. Other arguments are forwarded to the CLI (`plan2code --model opus`), and its exit code is passed back. Tests: `scripts/test-launcher.mjs` (run by `npm test`) spawns the launcher against stand-in `claude`/`devin` commands and a temp home.
**Design constraints:**
- **Stable copy, not the package dir** — the installer normally runs from an npx cache directory npm may delete, so `installLauncher()` copies `src/launcher/plan2code.js` to `~/.plan2code/bin/plan2code.js` and the shims point there. (The loop/metrics/bot wrappers point into `__dirname` and don't have this protection.)
@@ -304,4 +306,4 @@ On a terminal it first prints a Planny banner (`renderBanner()`). With both on `
The macOS and Linux shortcuts carry the `plan2code-launcher` marker as a comment line. A `.lnk` has nowhere to hide one (its Description is the hover tooltip), so it's recognized by what it runs: the UTF-16 strings `plan2code.ps1` and `--pick-folder` stored in the file (`plan2code.cmd` also matches, so shortcuts from before the PowerShell switch get refreshed). `uninstallLauncher()` removes only a recognized shortcut, plus the icons (`plan2code.ico`, `plan2code.png`), `bin/models.json` and `launcher.json` (never the user's `~/.plan2code/models.json`). A shortcut failure prints a warning and never fails the command install.
**Installer integration** lives in `install.js` under the `PLAN2CODE COMMAND` section (`installLauncher`, `uninstallLauncher`, plus the shortcut helpers). `install()` awaits it after a successful skills install (so both `I` and `A` get it), `U` removes it, and Custom → `D` installs it alone.
**Installer integration** lives in `install.js` under the `PLAN2CODE COMMAND` section (`installLauncher`, `uninstallLauncher`, plus the shortcut helpers). `install()` awaits it after a successful skills install (so `I` and Advanced → `E` get it), `U` removes it, and Advanced → `D` installs it alone. After an install, `printGettingStarted()` prints the three steps (cd into the project, start Plan2Code, pick a card) and, when no agent CLI is on `PATH`, how to get one.
+6 -6
View File
@@ -15,7 +15,7 @@ node install.js
npm run build:skills
# Full check (about 70s): char limits, skills/ build, browser-module parse check,
# dashboard skill-table check, web console + launcher node:test suites
# dashboard skill-table check, web console + launcher + getting-started node:test suites
npm test
# One web console or launcher test
@@ -64,13 +64,12 @@ The root `npm test` does not run the metrics or bot vitest suites; run them in t
| Option | Action |
|--------|--------|
| `I` | Install the Plan2Code skills globally via the `skills` CLI, plus the global `plan2code` command (opens the dashboard in Claude Code or Devin) — no dev tools |
| `A` | Everything in `I` plus every dev tool: `plan2code-loop`, `plan2code-bot`, `plan2code-metrics`, and the Claude Code status line |
| `I` | Install the Plan2Code skills globally via the `skills` CLI, plus the global `plan2code` command (opens the dashboard in Claude Code, Devin or Codex), then print the getting-started steps. No dev tools |
| `U` | Uninstall Plan2Code: skills + `plan2code` command + `plan2code-loop` + `plan2code-metrics` + `plan2code-bot` + Claude Code status line (confirmation required) |
| `C` | Open CUSTOM sub-menu |
| `A` | Open the ADVANCED sub-menu |
| `Q` | Quit |
**CUSTOM sub-menu (`C`):**
**ADVANCED sub-menu (`A`):**
| Option | Action |
|--------|--------|
@@ -80,6 +79,7 @@ The root `npm test` does not run the metrics or bot vitest suites; run them in t
| `S` | Install Claude Code status line only |
| `B` | Install plan2code-bot CLI only |
| `D` | Install the global `plan2code` command only |
| `E` | Everything: the skills, the `plan2code` command and every dev tool (`plan2code-loop`, `plan2code-bot`, `plan2code-metrics`, the Claude Code status line) |
| `Q` | Return to main menu |
## Non-Interactive Flags
@@ -97,7 +97,7 @@ The root `npm test` does not run the metrics or bot vitest suites; run them in t
2. **Checks the skills CLI is reachable** with `npx --yes skills --version`.
3. **Sweeps pre-2.2 install paths** and removes installed `plan2code-*` skills so renamed or retired prompts cannot survive as orphans.
4. **Delegates installation** to `npx --yes skills add "<repo>/skills" -g -s <skill names> -y`.
5. **Installs the global `plan2code` command** (only when step 4 succeeded). Custom → `L` runs the same flow without `-g` and without the launcher.
5. **Installs the global `plan2code` command** (only when step 4 succeeded). Advanced → `L` runs the same flow without `-g` and without the launcher.
The skills CLI owns distribution from step 4 onward. It stores canonical skills under `~/.agents/skills/` and links them into agents that maintain their own skill directory. Plan2Code no longer maintains platform-specific output formats.
+1 -1
View File
@@ -25,7 +25,7 @@ hand, or the reverse — the checkboxes are the only handoff.
```bash
# From the plan2code root directory
node install.js # A (everything + dev tools) — or C → O (loop only)
node install.js # A → E (everything + dev tools) or A → O (loop only)
```
## Run
+1 -1
View File
@@ -16,7 +16,7 @@ One thing to remember: **collect after every finished spec.** Everything else is
```bash
# Install once, from the plan2code root
node install.js # A (everything + dev tools) — or C → M (metrics only)
node install.js # A → E (everything + dev tools) or A → M (metrics only)
# After finishing a spec (steps 1–4)
cd your-project
+1 -1
View File
@@ -36,7 +36,7 @@ The icons down the left are Planny, the project mascot.
## Install
```bash
node install.js # A (everything + dev tools) — or C → S (status line only)
node install.js # A → E (everything + dev tools) or A → S (status line only)
```
That copies the script to `~/.claude/plan2code-statusline.js`, writes a default config to
+1 -1
View File
@@ -19,7 +19,7 @@ Built for **maintainers**. If you're using Plan2Code to ship features, you don't
## Install
```bash
node install.js # A (everything + dev tools) — or C → B (bot only)
node install.js # A → E (everything + dev tools) or A → B (bot only)
```
## Run
+11
View File
@@ -7,6 +7,17 @@ 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.
- **Start from your project.** Open your terminal in the project you want to work on (`cd` into it) before you run anything. Plan2Code works on the folder you start it in.
- **Ways in.** `plan2code` (Claude Code, Devin or Codex), or type `/plan2code` in your agent (`$plan2code` in Codex).
- **No agent yet?** Install Claude Code, Codex or Devin first.
Not installed yet? The install steps are in the [README](../README.md#install-and-start).
---
## Session 1: Plan
Run `plan2code` in the project (or `/plan2code` inside your agent). The dashboard opens in your
+2
View File
@@ -10,6 +10,8 @@ Plan2Code is a structured 4-step workflow methodology for AI-assisted software d
**Author:** Justin Parker
**License:** MIT
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.
## How to Use This File
This file is an index — each section below contains a brief summary and a link to a detail file in `.agents-docs/`. Read only the sections relevant to your current task. Full details (commands, tables, file lists) are in the linked files. The sections "Project Overview", "How to Use This File", "Mascot", and "Keeping this file current" / "Failure log" are fully inline here and are never split into `.agents-docs/`.
+7
View File
@@ -13,9 +13,16 @@ All notable changes to Plan2Code will be documented in this file.
- **web-console**: the Commit this? question in Git commit has a collapsed **Show the N files** table of every path and its state, so "15 files" can be read before you say yes.
- **web-console**: a finished quick task or phase build gets a **Commit it now** button beside the printed git command. It starts Git commit in the same session, as if you had clicked its dashboard card.
- **web-console**: the dashboard scan reports `isGit`, found from the filesystem without spawning git (linked worktrees count). The Git commit card stays clickable outside a repository and says "Not a git repository yet: it offers to start one". The skill has its own Planny pose and a Help entry.
- **installer**: after an install it prints getting-started steps: how to start Plan2Code from the project you want to work in, and what to do if no agent CLI is installed yet.
- **launcher**: the `plan2code` command can start Codex as well as the other agent CLIs. The Codex launch line follows Codex's documentation and has not been tried by hand.
- **launcher**: when no agent CLI is installed, `plan2code` now explains how to get one and how to run the skill from it, instead of printing one line and exiting.
- **docs**: the README, quick reference, docs site and package READMEs open with a "Before you start" block: Node.js 18+ is needed, start Plan2Code from your project, and the ways in. `scripts/test-getting-started.mjs` keeps them in step.
- **web-console**: Help's "When something looks stuck" tab is now second, opens with a "Check this first" callout about a permission prompt waiting in the terminal, and lists four symptoms with a likely cause and what to do. The quiet and Not running status lines carry a "What to check" button that opens it.
- **web-console**: every finished and paused screen shows a "Before you close this" panel: the tab is safe to close, why to restart the agent or start a new session, and the two ways to carry on.
### 🔧 Changed
- **installer**: the menu is now Install, Uninstall, Advanced and Quit. The former Custom choices live under Advanced.
- **web-console**: Subagents is now on by default for the skills that offer it, until you turn it off for a project and skill. A saved Off is kept.
- **commits**: every commit Plan2Code suggests is now `<subject>`, a blank line, then `AI Assisted`. `commit-msg.mjs` no longer reads a ticket from the branch name and rejects `--ticket`.
- **build**: `skills/` is no longer tracked. It is gitignored build output, rebuilt by the installer and `npm run build:skills`, as upstream does. `npm test` now runs `install.js --build-skills` instead of `--verify-skills`, so it fails on a broken source entry rather than on drift. `--verify-skills` stays as a diagnostic.
+9 -2
View File
@@ -1,13 +1,20 @@
# Plan2Code Quick Reference
## 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.
- **Start from your project.** Open your terminal in the project you want to work on (`cd` into it) before you run anything. Plan2Code works on the folder you start it in.
- **Ways in.** `plan2code` (Claude Code, Devin or Codex), or type `/plan2code` in your agent (`$plan2code` in Codex).
- **No agent yet?** Install Claude Code, Codex or Devin first.
## Launch
The web console is the main way in: a local page where questions, documents, build progress and sign-offs live.
| How | Command | What happens |
| ------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
| From your project (shell) | `plan2code` | Opens Claude Code or Devin on the dashboard (`--cli claude` / `--cli devin` to choose) |
| Inside any agent | `/plan2code` | Opens the dashboard: a card for every skill, launched on the same page |
| 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 / update | `npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git` | Installs the skills and the `plan2code` command; re-run it to update |
| Straight into a skill | `/plan2code-1-plan --web` (any step) | Skips the "web console or terminal?" question and opens the page |
+19 -14
View File
@@ -30,8 +30,14 @@ The dashboard, in a project halfway through a build. It suggests the next step f
## Install and start
Requires [Node.js](https://nodejs.org/) 18 or later and network access — installation runs through
the [skills CLI](https://skills.sh). To update, re-run the install command.
### 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.
- **Start from your project.** Open your terminal in the project you want to work on (`cd` into it) before you run anything. Plan2Code works on the folder you start it in.
- **Ways in.** `plan2code` (Claude Code, Devin or Codex), or type `/plan2code` in your agent (`$plan2code` in Codex).
- **No agent yet?** Install Claude Code, Codex or Devin first.
Installation needs network access and runs through the [skills CLI](https://skills.sh). To update, re-run the install command.
```bash
npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git
@@ -47,33 +53,32 @@ The installer opens this menu (cloning and running `node install.js`, below, ope
╔═════════════════════════════════════════════════════════╗
║ INSTALL PLAN2CODE ║
╠═════════════════════════════════════════════════════════╣
║ I. INSTALL Install Plan2Code skills everywhere ║
║ A. ALL Install Plan2Code + dev tools ║
║ U. UNINSTALL Remove Plan2Code skills and dev tools ║
║ C. CUSTOM Advanced options ║
║ I. INSTALL Install skills + the plan2code command ║
║ U. UNINSTALL Remove everything Plan2Code installed ║
║ A. ADVANCED Project install, dev tools, and more ║
║ Q. QUIT Exit ║
╚═════════════════════════════════════════════════════════╝
```
### Start
1. In any project, run `plan2code`. It starts Claude Code or Devin on the dashboard, and the
dashboard opens in your browser.
1. `cd` into your project, then run `plan2code`. It starts Claude Code, Devin or Codex on the dashboard,
and the dashboard opens in your browser.
2. In a project without an `AGENTS.md`, pick **Set up this project** first: Plan and Quick task
need it.
3. Pick a card.
Already inside your agent? Type `/plan2code` instead.
Already inside your agent? Type `/plan2code` instead (`$plan2code` in Codex).
<details>
<summary>About the plan2code command</summary>
The installer adds `plan2code` as a global command (Custom `C` → `D` adds just the command). Run it from any project and the Plan2Code
dashboard opens right there, in **Claude Code** or **Devin**. With both installed it asks which and
remembers your pick; `plan2code --cli claude` or `--cli devin` skips the question, and `--model <name>`
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 or Devin CLI on your `PATH`. It starts the agent with permission prompts off
(`--permission-mode bypassPermissions` in Claude Code, `--permission-mode bypass` in Devin); run
Claude Code, Devin or Codex CLI on your `PATH`. It starts the agent with permission prompts off
(`--permission-mode bypassPermissions` in Claude Code, `--permission-mode bypass` in Devin, `--dangerously-bypass-approvals-and-sandbox` in Codex); run
`claude /plan2code` yourself if you want prompts. The installer then offers a desktop shortcut (answer `y`),
which opens a folder picker first. Uninstalling (`U`) removes both.
</details>
+24 -3
View File
@@ -112,6 +112,11 @@ h3 { font-size: 1.45rem; margin: 8px 0; }
.copy .tick { display: none; }
.copy.-done .clip { display: none; }
.copy.-done .tick { display: block; }
.before { margin: 0 auto 20px; max-width: 640px; text-align: left; background: var(--panel); border: 1px solid var(--rule-2); border-radius: var(--radius); padding: 14px 18px; font-size: 15px; }
.before h3 { font-size: 1.05rem; margin: 0 0 8px; }
.before ul { margin: 0; padding-left: 20px; color: var(--ink-2); }
.before li { margin: 4px 0; }
.before strong { color: var(--ink); }
.then { margin: 12px 0 0; color: var(--ink-2); font-size: 15px; }
/* Hero: centered headline, then the dashboard at full width. */
@@ -215,6 +220,14 @@ footer a { color: inherit; }
</svg>
<h1 id="hero-title">Plan and build with your AI agent, on one page.</h1>
<p class="lede">Plan2Code asks the questions, drafts the plan and builds it one phase at a time. You answer and approve in your browser, and the specs land in your repo.</p>
<div class="before" id="before-start">
<h3>Before you start</h3>
<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>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>No agent yet?</strong> Install Claude Code, Codex or Devin first.</li>
</ul>
</div>
<div class="cmd">
<pre id="install-cmd"><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">
@@ -223,7 +236,7 @@ footer a { color: inherit; }
<span class="label">Copy</span>
</button>
</div>
<p class="then">then run <code>plan2code</code> in any project.</p>
<p class="then">then, from your project, run <code>plan2code</code> (Claude Code, Devin or Codex), or type <code>/plan2code</code> in your agent (<code>$plan2code</code> in Codex).</p>
</div>
</section>
@@ -356,7 +369,15 @@ footer a { color: inherit; }
<section class="s alt close" id="install" aria-labelledby="install-title">
<div class="narrow">
<h2 id="install-title">Install</h2>
<p class="muted">Needs Node.js 18 or later. Run it again any time to update.</p>
<p class="muted">Run it again any time to update.</p>
<div class="before" id="before-start-2">
<h3>Before you start</h3>
<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>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>No agent yet?</strong> Install Claude Code, Codex or Devin first.</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">
@@ -365,7 +386,7 @@ footer a { color: inherit; }
<span class="label">Copy</span>
</button>
</div>
<p class="then">then run <code>plan2code</code> in any project.</p>
<p class="then">then, from your project, run <code>plan2code</code> (Claude Code, Devin or Codex), or type <code>/plan2code</code> in your agent (<code>$plan2code</code> in Codex).</p>
</div>
</section>
Binary file not shown.

Before

Width:  |  Height:  |  Size: 96 KiB

After

Width:  |  Height:  |  Size: 94 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 102 KiB

After

Width:  |  Height:  |  Size: 100 KiB

+81 -48
View File
@@ -976,12 +976,11 @@ async function install() {
return 1;
}
// Point at the dashboard first: the `plan2code` command when it installed, the skill otherwise.
const dashboardWhere = launcherFailed ? 'Open the dashboard in your agent:' : 'Open the dashboard from any project:';
const dashboardCommand = launcherFailed ? '/plan2code' : LAUNCHER_COMMAND;
// The steps come first: where to start, the ways in, and what to do without an agent.
printGettingStarted({ commandInstalled: !launcherFailed });
console.log(`${COLORS.GREEN} ╭───╮${COLORS.RESET} ${COLORS.BRIGHT}All done! Happy coding!${COLORS.RESET}`);
console.log(`${COLORS.GREEN} ╲│ ${COLORS.CYAN}★${COLORS.GREEN} │╱${COLORS.RESET} ${COLORS.BRIGHT}${dashboardWhere}${COLORS.RESET}`);
console.log(`${COLORS.GREEN} │ ${COLORS.BRIGHT}◡${COLORS.GREEN} │${COLORS.RESET} ${COLORS.BRIGHT}${COLORS.CYAN}${dashboardCommand}${COLORS.RESET}`);
console.log(`${COLORS.GREEN} ╲│ ${COLORS.CYAN}★${COLORS.GREEN} │╱${COLORS.RESET}`);
console.log(`${COLORS.GREEN} │ ${COLORS.BRIGHT}◡${COLORS.GREEN} │${COLORS.RESET}`);
console.log(`${COLORS.GREEN} ╰┬─┬╯${COLORS.RESET} ${COLORS.DIM}Docs:${COLORS.RESET} ${COLORS.BRIGHT}https://github.com/jparkerweb/plan2code${COLORS.RESET}`);
console.log('');
console.log(`${COLORS.DIM} Update later with:${COLORS.RESET} ${COLORS.CYAN}npx skills update -g${COLORS.RESET}`);
@@ -990,6 +989,42 @@ async function install() {
return launcherFailed ? 1 : 0;
}
/**
* Print what to do after installing: where to start, the ways in, and what to do when no AI
* agent is installed. Used at the end of every install route so they all end the same way.
*/
function printGettingStarted({ commandInstalled }) {
const agents = ['claude', 'devin', 'codex'].filter((name) => isCommandOnPath(name));
const line = (text = '') => console.log(` ${text}`);
console.log(`${COLORS.CYAN}╔═══════════════════════════════════════════════════════════════════════════╗${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}HOW TO USE PLAN2CODE${COLORS.RESET}`, 76) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(`${COLORS.CYAN}╚═══════════════════════════════════════════════════════════════════════════╝${COLORS.RESET}`);
console.log('');
line(`${COLORS.BRIGHT}1. Open a terminal IN the project you want to work on${COLORS.RESET}`);
line(' Plan2Code works on the folder you start it in.');
line(` ${COLORS.CYAN}cd path/to/your-project${COLORS.RESET}`);
console.log('');
line(`${COLORS.BRIGHT}2. Start Plan2Code${COLORS.RESET}`);
if (commandInstalled) {
line(` ${COLORS.CYAN}${LAUNCHER_COMMAND}${COLORS.RESET} opens your AI agent on the Plan2Code dashboard`);
line(` or, inside the agent itself: ${COLORS.CYAN}/plan2code${COLORS.RESET} (Claude Code, Devin) ${COLORS.CYAN}$plan2code${COLORS.RESET} (Codex)`);
} else {
line(` Inside your AI agent, type ${COLORS.CYAN}/plan2code${COLORS.RESET} (Claude Code, Devin) or ${COLORS.CYAN}$plan2code${COLORS.RESET} (Codex)`);
}
console.log('');
line(`${COLORS.BRIGHT}3. Pick a card on the page that opens in your browser${COLORS.RESET}`);
line(' Any AI agent that reads Agent Skills can run Plan2Code the same way.');
console.log('');
if (agents.length === 0) {
console.log(` ${COLORS.YELLOW}${SYMBOLS.WARNING} NO AI AGENT FOUND ON THIS COMPUTER${COLORS.RESET}`);
line('Plan2Code runs inside an AI coding agent. Install one, open a new terminal, then follow the steps above:');
line(` Claude Code ${COLORS.CYAN}npm i -g @anthropic-ai/claude-code${COLORS.RESET}`);
line(` Codex ${COLORS.CYAN}npm i -g @openai/codex${COLORS.RESET}`);
line(' Devin https://devin.ai');
console.log('');
}
}
// ============================================================================
// UNINSTALLATION
// ============================================================================
@@ -1109,47 +1144,30 @@ function runInteractive() {
console.log(`${COLORS.CYAN}╔═════════════════════════════════════════════════════════╗${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}INSTALL PLAN2CODE${COLORS.RESET}`, 58) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(`${COLORS.CYAN}╠═════════════════════════════════════════════════════════╣${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}I.${COLORS.RESET} ${COLORS.GREEN}INSTALL${COLORS.RESET} Install Plan2Code skills everywhere`, 58) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}A.${COLORS.RESET} ${COLORS.MAGENTA}ALL${COLORS.RESET} Install Plan2Code + dev tools`, 58) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}U.${COLORS.RESET} ${COLORS.RED}UNINSTALL${COLORS.RESET} Remove Plan2Code skills and dev tools`, 58) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}C.${COLORS.RESET} ${COLORS.BLUE}CUSTOM${COLORS.RESET} Advanced options`, 58) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}I.${COLORS.RESET} ${COLORS.GREEN}INSTALL${COLORS.RESET} Install skills + the plan2code command`, 58) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}U.${COLORS.RESET} ${COLORS.RED}UNINSTALL${COLORS.RESET} Remove everything Plan2Code installed`, 58) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}A.${COLORS.RESET} ${COLORS.BLUE}ADVANCED${COLORS.RESET} Project install, dev tools, and more`, 58) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}Q.${COLORS.RESET} ${COLORS.DIM}QUIT${COLORS.RESET} Exit`, 58) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(`${COLORS.CYAN}╚═════════════════════════════════════════════════════════╝${COLORS.RESET}`);
console.log('');
// Input prompt
console.log('');
const answer = await question(`${COLORS.CYAN}${SYMBOLS.SELECT} SELECT OPTION${COLORS.RESET} (I, A, U, C, Q) [I]: `);
const answer = await question(`${COLORS.CYAN}${SYMBOLS.SELECT} SELECT OPTION${COLORS.RESET} (I, U, A, Q) [I]: `);
const input = answer.trim().toUpperCase() || 'I';
// I path — skills only. The loop remains optional via A or Custom → O.
// I path: skills and the plan2code command. The dev tools stay optional under Advanced.
if (input === 'I') {
rl.close();
process.exit(await install());
}
// A path — Install Everything (skills + loop + bot + metrics + Claude status line)
if (input === 'A') {
rl.close();
const loopResult = installPlan2CodeLoop();
console.log('');
const botResult = installPlan2CodeBot();
console.log('');
const metricsResult = installPlan2CodeMetrics();
console.log('');
const statusLineResult = await installStatusLine();
console.log('');
const installResult = await install();
const exitCode = loopResult !== 0 ? loopResult : botResult !== 0 ? botResult : metricsResult !== 0 ? metricsResult : statusLineResult !== 0 ? statusLineResult : installResult;
process.exit(exitCode);
}
// U path — Uninstall All
if (input === 'U') {
console.log('');
console.log(`${COLORS.RED} ╭───╮${COLORS.RESET}`);
console.log(`${COLORS.RED} ╲│ ${COLORS.YELLOW}★${COLORS.RED} │╱${COLORS.RESET} ${COLORS.YELLOW}!${COLORS.RESET}`);
console.log(`${COLORS.RED} │ ${COLORS.YELLOW}~${COLORS.RED} │${COLORS.RESET} ${COLORS.DIM}Are you sure? This will remove Plan2Code from all platforms.${COLORS.RESET}`);
console.log(`${COLORS.RED} │ ${COLORS.YELLOW}~${COLORS.RED} │${COLORS.RESET} ${COLORS.DIM}Are you sure? This removes everything Plan2Code installed: skills, the plan2code command and any dev tools.${COLORS.RESET}`);
console.log(`${COLORS.RED} ╰┬─┬╯${COLORS.RESET}`);
console.log('');
const confirmAnswer = await question(`${COLORS.RED}${SYMBOLS.SELECT} CONFIRM UNINSTALL${COLORS.RESET} (Y/N) [N]: `);
@@ -1172,11 +1190,11 @@ function runInteractive() {
}
}
// C path — CUSTOM sub-menu
if (input === 'C') {
// A path: ADVANCED sub-menu
if (input === 'A') {
console.log('');
console.log(`${COLORS.CYAN}╔════════════════════════════════════════════════════════════════╗${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}CUSTOM OPTIONS${COLORS.RESET}`, 65) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}ADVANCED OPTIONS${COLORS.RESET}`, 65) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(`${COLORS.CYAN}╠════════════════════════════════════════════════════════════════╣${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}L.${COLORS.RESET} ${COLORS.BLUE}LOCAL${COLORS.RESET} Install skills into the current project only`, 65) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}O.${COLORS.RESET} ${COLORS.GREEN}LOOP CLI${COLORS.RESET} Install plan2code-loop CLI only`, 65) + `${COLORS.CYAN}║${COLORS.RESET}`);
@@ -1184,53 +1202,70 @@ function runInteractive() {
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}S.${COLORS.RESET} ${COLORS.GREEN}STATUS${COLORS.RESET} Install Claude Code status line`, 65) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}B.${COLORS.RESET} ${COLORS.GREEN}BOT${COLORS.RESET} Install plan2code-bot CLI only`, 65) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}D.${COLORS.RESET} ${COLORS.GREEN}P2C CMD${COLORS.RESET} Install the plan2code command only`, 65) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}E.${COLORS.RESET} ${COLORS.MAGENTA}EVERYTHING${COLORS.RESET} Install Plan2Code + all dev tools`, 65) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(padEndVisible(`${COLORS.CYAN}║${COLORS.RESET} ${COLORS.BRIGHT}Q.${COLORS.RESET} ${COLORS.DIM}BACK${COLORS.RESET} Return to main menu`, 65) + `${COLORS.CYAN}║${COLORS.RESET}`);
console.log(`${COLORS.CYAN}╚════════════════════════════════════════════════════════════════╝${COLORS.RESET}`);
console.log('');
const customAnswer = await question(`${COLORS.CYAN}${SYMBOLS.SELECT} SELECT OPTION${COLORS.RESET} (L, O, M, S, B, D, Q) [Q]: `);
const customAnswer = await question(`${COLORS.CYAN}${SYMBOLS.SELECT} SELECT OPTION${COLORS.RESET} (L, O, M, S, B, D, E, Q) [Q]: `);
const customInput = customAnswer.trim().toUpperCase() || 'Q';
// C > L — install skills into the current project
// A > E: install everything (skills + loop + bot + metrics + Claude status line)
if (customInput === 'E') {
rl.close();
const loopResult = installPlan2CodeLoop();
console.log('');
const botResult = installPlan2CodeBot();
console.log('');
const metricsResult = installPlan2CodeMetrics();
console.log('');
const statusLineResult = await installStatusLine();
console.log('');
const installResult = await install();
const exitCode = loopResult !== 0 ? loopResult : botResult !== 0 ? botResult : metricsResult !== 0 ? metricsResult : statusLineResult !== 0 ? statusLineResult : installResult;
process.exit(exitCode);
}
// A > L: install skills into the current project
if (customInput === 'L') {
rl.close();
process.exit(installProjectSkills());
}
// C > O — install loop CLI only
// A > O: install loop CLI only
if (customInput === 'O') {
rl.close();
const result = installPlan2CodeLoop();
process.exit(result);
}
// C > M — install metrics CLI only
// A > M: install metrics CLI only
if (customInput === 'M') {
rl.close();
const result = installPlan2CodeMetrics();
process.exit(result);
}
// C > S — install status line
// A > S: install status line
if (customInput === 'S') {
rl.close();
const result = await installStatusLine();
process.exit(result);
}
// C > B — install bot CLI only
// A > B: install bot CLI only
if (customInput === 'B') {
rl.close();
const result = installPlan2CodeBot();
process.exit(result);
}
// C > D — install the global `plan2code` command (opens the dashboard in Claude Code or Devin)
// A > D: install the global `plan2code` command (opens the dashboard in Claude Code, Devin or Codex)
if (customInput === 'D') {
rl.close();
process.exit(await installLauncher());
}
// C > Q — back to main menu
// A > Q: back to main menu
return main();
}
@@ -1242,7 +1277,7 @@ function runInteractive() {
}
// Invalid input — loop back
console.log(`\n${COLORS.RED}${SYMBOLS.ERROR} Invalid option. Please choose I, A, U, C, or Q.${COLORS.RESET}\n`);
console.log(`\n${COLORS.RED}${SYMBOLS.ERROR} Invalid option. Please choose I, U, A, or Q.${COLORS.RESET}\n`);
return main();
}
@@ -2209,7 +2244,7 @@ function uninstallPlan2CodeBot() {
}
// ============================================================================
// PLAN2CODE COMMAND (global `plan2code` → dashboard in Claude Code or Devin)
// PLAN2CODE COMMAND (global `plan2code` → dashboard in Claude Code, Devin or Codex)
// ============================================================================
/**
@@ -2444,7 +2479,7 @@ function installDesktopShortcut(binDir, file) {
P2C_FILE: file,
P2C_SCRIPT: `${shim}.ps1`,
P2C_ARGS: LAUNCHER_PICK_FOLDER_FLAG,
P2C_DESCRIPTION: 'Open the Plan2Code dashboard in Claude Code or Devin',
P2C_DESCRIPTION: 'Open the Plan2Code dashboard in Claude Code, Devin or Codex',
P2C_ICON: icon,
}
);
@@ -2464,7 +2499,7 @@ function installDesktopShortcut(binDir, file) {
`# ${LAUNCHER_MARKER}`,
'Type=Application',
`Name=${SHORTCUT_NAME}`,
'Comment=Open the Plan2Code dashboard in Claude Code or Devin',
'Comment=Open the Plan2Code dashboard in Claude Code, Devin or Codex',
`Exec="${shim}" ${LAUNCHER_PICK_FOLDER_FLAG}`,
...(icon ? [`Icon=${icon}`] : []),
'Terminal=true',
@@ -2559,14 +2594,12 @@ async function installLauncher({ quiet = false } = {}) {
if (!isDirOnPath(binDir)) {
console.log(` ${COLORS.YELLOW}${SYMBOLS.WARNING}${COLORS.RESET} ${binDir} is not on your PATH — add it to use ${COLORS.BRIGHT}${LAUNCHER_COMMAND}${COLORS.RESET} from any directory`);
}
if (!isCommandOnPath('claude') && !isCommandOnPath('devin')) {
console.log(` ${COLORS.YELLOW}${SYMBOLS.WARNING}${COLORS.RESET} Neither the ${COLORS.BRIGHT}claude${COLORS.RESET} nor the ${COLORS.BRIGHT}devin${COLORS.RESET} CLI is on your PATH — install one before running ${COLORS.BRIGHT}${LAUNCHER_COMMAND}${COLORS.RESET}`);
}
// The shortcut is a convenience on top of the command, so a failure here only warns.
await offerDesktopShortcut(binDir);
console.log(` ${COLORS.DIM}Run '${LAUNCHER_COMMAND}' in any project to open the Plan2Code dashboard in Claude Code or Devin${COLORS.RESET}`);
console.log(` ${COLORS.YELLOW}${SYMBOLS.WARNING}${COLORS.RESET} It starts the agent with permission prompts off (${COLORS.CYAN}--permission-mode bypassPermissions${COLORS.RESET} in Claude Code, ${COLORS.CYAN}bypass${COLORS.RESET} in Devin). Run ${COLORS.CYAN}claude /plan2code${COLORS.RESET} yourself if you want prompts.`);
console.log(` ${COLORS.YELLOW}${SYMBOLS.WARNING}${COLORS.RESET} The ${LAUNCHER_COMMAND} command starts the agent with permission prompts off (${COLORS.CYAN}--permission-mode bypassPermissions${COLORS.RESET} in Claude Code, ${COLORS.CYAN}bypass${COLORS.RESET} in Devin, ${COLORS.CYAN}--dangerously-bypass-approvals-and-sandbox${COLORS.RESET} in Codex). Run ${COLORS.CYAN}claude /plan2code${COLORS.RESET} yourself if you want prompts.`);
console.log('');
// Inside install() the final summary prints the steps once, after everything else.
if (!quiet) printGettingStarted({ commandInstalled: true });
return 0;
}
+1 -1
View File
@@ -8,7 +8,7 @@
"scripts": {
"prepare": "husky",
"build:skills": "node install.js --build-skills",
"test": "node scripts/validate-char-count.js && node install.js --build-skills && node scripts/parse-check.mjs && node scripts/check-skill-table.mjs && node --test scripts/test-web-console.mjs scripts/test-launcher.mjs scripts/test-skill-scripts.mjs scripts/test-script-pathfinder.mjs scripts/test-script-finalize.mjs scripts/test-script-handoff.mjs scripts/test-script-git-commit.mjs scripts/test-script-changelog.mjs"
"test": "node scripts/validate-char-count.js && node install.js --build-skills && node scripts/parse-check.mjs && node scripts/check-skill-table.mjs && node --test scripts/test-web-console.mjs scripts/test-launcher.mjs scripts/test-getting-started.mjs scripts/test-skill-scripts.mjs scripts/test-script-pathfinder.mjs scripts/test-script-finalize.mjs scripts/test-script-handoff.mjs scripts/test-script-git-commit.mjs scripts/test-script-changelog.mjs"
},
"devDependencies": {
"husky": "^9.0.0"
+1 -1
View File
@@ -13,7 +13,7 @@ From the plan2code root:
```bash
node install.js
# Select C > B to install bot only, or I to install everything
# Select A > B to install the bot only, or A > E to install everything
```
Or manually:
+2 -2
View File
@@ -6,8 +6,8 @@ Recursive self-improvement toolchain for plan2code contributors. Collects metric
```bash
# Install (one-time, from the plan2code root)
node install.js # → "A" (Install All + dev tools) includes metrics
# → or "M" (Metrics only) under the CUSTOM sub-menu
node install.js # → "A" then "E" (Everything) includes metrics
# → or "M" (Metrics only) under the ADVANCED sub-menu
# After finishing any project spec (steps 1-4):
cd your-project
+46
View File
@@ -0,0 +1,46 @@
// Keeps the "Before you start" guidance identical in meaning across the newcomer docs.
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
const DOCS = ['README.md', 'docs/index.html', 'QUICK-REFERENCE.md'];
const EM_DASH = String.fromCharCode(0x2014);
function read(file) {
return readFileSync(join(ROOT, file), 'utf8');
}
// The first "Before you start" block: from its heading to the next heading (Markdown)
// or the end of its container (HTML).
function blockOf(file) {
const text = read(file);
const start = text.search(/^#{2,3} Before you start$|<h3>Before you start<\/h3>/m);
assert.ok(start >= 0, `${file} has no "Before you start" block`);
const rest = text.slice(start);
const body = rest.indexOf('\n') + 1;
const next = file.endsWith('.html') ? rest.indexOf('</div>') : rest.slice(body).search(/^#{1,3} /m);
const end = file.endsWith('.html') ? next : next < 0 ? -1 : body + next;
return end > 0 ? rest.slice(0, end) : rest;
}
for (const file of DOCS) {
test(`${file} tells a newcomer how to get started`, () => {
const text = read(file);
const block = blockOf(file);
for (const needle of ['Node.js 18', 'node --version', 'nodejs.org', '/plan2code', '$plan2code']) {
assert.ok(text.includes(needle), `${file} is missing "${needle}"`);
}
assert.match(block, /project you want to (work on|work in)/, `${file} does not say to start from your project`);
assert.ok(!block.includes(EM_DASH), `${file} has an em dash in its "Before you start" block`);
});
test(`${file} puts the guidance before the install command`, () => {
const text = read(file);
const guide = text.indexOf('Before you start');
const install = text.indexOf('npx --allow-git');
assert.ok(guide >= 0 && install >= 0 && guide < install, `${file}: "Before you start" must come before the npx line`);
});
}
+30 -3
View File
@@ -77,6 +77,29 @@ test("launcher: Devin keeps its args ahead of the -- and the prompt", (t) => {
assert.deepEqual(box.argsOf("devin"), ["--permission-mode", "bypass", "--verbose", "--", "/plan2code"]);
});
test("launcher: Codex gets the bypass flag, the forwarded args, then the $plan2code prompt", (t) => {
const box = sandbox(["codex"]);
t.after(box.cleanup);
const result = box.run(["--verbose"]);
assert.equal(result.status, 0, result.stderr);
assert.deepEqual(box.argsOf("codex"), ["--dangerously-bypass-approvals-and-sandbox", "--verbose", "$plan2code"]);
});
test("launcher: --cli codex picks Codex when it is installed beside another CLI", (t) => {
const box = sandbox(["claude", "codex"]);
t.after(box.cleanup);
const result = box.run(["--cli", "codex"]);
assert.equal(result.status, 0, result.stderr);
assert.equal(box.argsOf("claude"), null);
assert.ok(box.argsOf("codex"));
});
test("launcher: the shipped models.json lists every CLI, and every entry has an id and a label", () => {
const shipped = JSON.parse(fs.readFileSync(path.join(path.dirname(LAUNCHER), "models.json"), "utf8"));
assert.ok(Array.isArray(shipped.codex));
for (const { id, label } of shipped.codex) assert.ok(id && label);
});
test("launcher: a forwarded --model skips the model notice", (t) => {
const box = sandbox(["claude"]);
t.after(box.cleanup);
@@ -119,11 +142,12 @@ test("launcher: an unknown --cli exits 2, a missing CLI 127, and nothing is star
const unknown = box.run(["--cli", "bogus"]);
assert.equal(unknown.status, 2);
assert.match(unknown.stderr, /--cli takes claude or devin, not "bogus"/);
assert.match(unknown.stderr, /--cli takes claude, devin, codex, not "bogus"/);
const missing = box.run(["--cli", "devin"]);
assert.equal(missing.status, 127);
assert.match(missing.stderr, /the `devin` CLI was not found/);
assert.ok(missing.stderr.includes("$plan2code"));
assert.equal(box.argsOf("claude"), null);
});
@@ -150,12 +174,15 @@ test("launcher: the shipped models.json is curated Devin at low/medium/high only
}
});
test("launcher: with neither CLI installed it exits 127 naming both", (t) => {
test("launcher: with no CLI installed it exits 127 and says how to run the skill from an agent", (t) => {
const box = sandbox([]);
t.after(box.cleanup);
const result = box.run([]);
assert.equal(result.status, 127);
assert.match(result.stderr, /neither `claude` nor `devin` was found/);
assert.match(result.stderr, /none of `claude`, `devin` or `codex` was found/);
assert.ok(result.stderr.includes("type /plan2code"));
assert.ok(result.stderr.includes("$plan2code (Codex)"));
assert.match(result.stderr, /cd into the project/);
});
test("launcher: a forwarded argument with a space and a cmd metacharacter arrives unchanged", (t) => {
+55 -2
View File
@@ -1050,7 +1050,7 @@ test("help: every number the help quotes matches the code", () => {
const panels = new Map(
[...tpl.matchAll(/<section class="help-panel" data-tab="([^"]+)">([\s\S]*?)<\/section>/g)].map((m) => [m[1], m[2]])
);
const firstSeven = HELP_TABS.slice(0, 7).map((t) => panels.get(t.id)).join("\n");
const firstEight = HELP_TABS.slice(0, 8).map((t) => panels.get(t.id)).join("\n");
const used = [
"closedTabMinutes",
"maxLifeHours",
@@ -1062,7 +1062,7 @@ test("help: every number the help quotes matches the code", () => {
"maxUploadMb",
"cleanupDays",
];
for (const key of used) assert.ok(firstSeven.includes(`data-fact="${key}"`), `tabs 1 to 7 quote ${key}`);
for (const key of used) assert.ok(firstEight.includes(`data-fact="${key}"`), `tabs 1 to 8 quote ${key}`);
});
/* ---------------------------------------------------------- image uploads */
@@ -7048,3 +7048,56 @@ test("the Changelog card comes just before Git commit and is always on", () => {
assert.equal(cardAvailability(entry, scan, null).on, true);
}
});
/* ------------------------------------------- getting started: stuck help and the finished screen */
const EM = String.fromCharCode(0x2014);
const publicSource = (name) => fs.readFileSync(path.join(ROOT, "src", "web-console", "public", name), "utf8");
test("help: the stuck tab is second, with a callout and four symptom rows before the diagram", () => {
assert.equal(HELP_TABS[0].id, "about");
assert.equal(HELP_TABS[1].id, "stuck");
const tpl = helpTemplate();
const panel = tpl.match(/<section class="help-panel" data-tab="stuck">([\s\S]*?)<\/section>/)[1];
assert.match(panel, /<div class="help-callout" role="note">/);
assert.match(panel, /Check this first/);
assert.match(panel, /look at your terminal/);
assert.equal((panel.match(/class="help-row"/g) || []).length, 4, "four symptom rows");
for (const part of ["You see", "Likely cause", "Do this"]) {
assert.equal((panel.match(new RegExp(`<dt>${part}</dt>`, "g")) || []).length, 4, `each row has "${part}"`);
}
assert.ok(panel.indexOf("help-rows") < panel.indexOf("help-figure"), "the rows come before the diagram");
assert.match(panel, /<svg class="help-callout-icon"[^>]*aria-hidden="true"/, "the icon is decoration");
});
test("status line: the quiet and Not running lines offer What to check, opening Help on the stuck tab", () => {
const app = publicSource("app.js");
assert.match(app, /help\.textContent = "What to check"/);
assert.match(app, /openHelpOn\("stuck"\)/);
// Exactly the three lines that carry it: the approval hint, the stale line and the Not running line.
const render = app.slice(app.indexOf("function renderStatus()"), app.indexOf("/* ---------------------------------------------------------------- brief */"));
assert.match(render, /Boolean\(hint\)/);
assert.equal((render.match(/^\s+true\n\s+\);/gm) || []).length, 2, "the stale and Not running lines pass check");
});
test("finished screen: every shape shows Before you close this, with three rows", () => {
const app = publicSource("app.js");
const handoff = app.slice(app.indexOf("function renderHandoff("));
assert.match(handoff.slice(0, handoff.indexOf("\n}\n")), /card\.appendChild\(renderCloseGuide\(shape\)\)/);
const guide = app.slice(app.indexOf("function renderCloseGuide("), app.indexOf("function renderHandoff("));
for (const label of ["Safe to close", "Start fresh", "Carry on", "Before you close this"]) {
assert.ok(guide.includes(label), `the guide says "${label}"`);
}
assert.match(guide, /shape === "paused"/, "a pause changes the Start fresh sentence");
assert.match(guide, /resume command/);
});
test("getting started: the new help, status and finished-screen strings carry no em dash", () => {
const app = publicSource("app.js");
const guide = app.slice(app.indexOf("const GUIDE_ICONS"), app.indexOf("function renderHandoff("));
assert.ok(!guide.includes(EM), "the close guide has no em dash");
const tpl = helpTemplate();
const stuck = tpl.match(/<section class="help-panel" data-tab="stuck">([\s\S]*?)<\/section>/)[1];
const fresh = stuck.slice(0, stuck.indexOf("<h4>Not running, or not connected?</h4>"));
assert.ok(!fresh.includes(EM), "the callout and rows have no em dash");
});
+3 -2
View File
@@ -1,5 +1,5 @@
{
"_note": "Curated model menu for the plan2code launcher. Maintained by the Plan2Code authors; every install overwrites this file. Users add models in User Preferences (kept in ~/.plan2code/models.json). Devin entries are explicit ids at Low, Medium and High effort only, verified against `devin models list`.",
"_note": "Curated model menu for the plan2code launcher. Maintained by the Plan2Code authors; every install overwrites this file. Users add models in User Preferences (kept in ~/.plan2code/models.json). Devin entries are explicit ids at Low, Medium and High effort only, verified against `devin models list`. Codex has no curated entries yet (its docs name none to verify): the launcher skips the model question for it. Pass --model <name> to choose one.",
"claude": [
{
"id": "default",
@@ -111,5 +111,6 @@
"id": "glm-5-3-high",
"label": "GLM-5.3 High"
}
]
],
"codex": []
}
+31 -6
View File
@@ -2,14 +2,15 @@
'use strict';
/**
* `plan2code` — open the Plan2Code dashboard skill in Claude Code or Devin, in the current
* directory.
* `plan2code`: open the Plan2Code dashboard skill in Claude Code, Devin or Codex, in the
* current directory.
*
* Runs one of:
* claude /plan2code --permission-mode bypassPermissions [extra args]
* devin --permission-mode bypass [extra args] -- /plan2code
* codex --dangerously-bypass-approvals-and-sandbox [extra args] $plan2code
*
* When both CLIs are installed it asks which one, with the last pick as the default; with only
* Codex starts a skill with `$name` rather than `/name`. When more than one CLI is installed it asks which one, with the last pick as the default; with only
* one installed it uses that. `--cli claude` / `--cli devin` skips the question. Before starting
* it asks which model to run, from the curated list in models.json (shipped with every
* install) plus any models the user added in User Preferences; Enter keeps the model the CLI
@@ -107,8 +108,28 @@ const CLIS = [
label: 'Devin',
args: (extra) => ['--permission-mode', 'bypass', ...extra, '--', '/plan2code'],
},
{
id: 'codex',
label: 'Codex',
// Codex mentions a skill with `$name`; the prompt is its one positional argument.
args: (extra) => ['--dangerously-bypass-approvals-and-sandbox', ...extra, '$plan2code'],
},
];
/** What to do when no agent is installed: how to get one and how to run the skill from it. */
const SKILL_STEPS = [
'Plan2Code runs inside an AI coding agent. To use it:',
' 1. Install one: Claude Code (npm i -g @anthropic-ai/claude-code), Codex (npm i -g @openai/codex) or Devin (https://devin.ai).',
' 2. Open a new terminal and cd into the project you want to work on.',
' 3. Start your agent there, then type /plan2code (Claude Code, Devin) or $plan2code (Codex).',
];
/** The CLI ids as prose: "`claude`, `devin` or `codex`". */
function cliIdList() {
const ids = CLIS.map((cli) => '`' + cli.id + '`');
return `${ids.slice(0, -1).join(', ')} or ${ids[ids.length - 1]}`;
}
// The curated menu ships beside this file (models.json, overwritten by every install); models
// the user adds in User Preferences live in ~/.plan2code/models.json and are merged in.
const SHIPPED_MODELS_FILE = path.join(__dirname, 'models.json');
@@ -341,21 +362,25 @@ async function chooseCli(requested) {
if (requested !== undefined) {
const known = CLIS.find((cli) => cli.id === requested);
if (!known) {
console.error(`${ce.red('plan2code:')} --cli takes ${CLIS.map((cli) => cli.id).join(' or ')}${requested ? `, not "${requested}"` : ''}.`);
console.error(`${ce.red('plan2code:')} --cli takes ${CLIS.map((cli) => cli.id).join(', ')}${requested ? `, not "${requested}"` : ''}.`);
return { code: 2 };
}
const found = installed.find((cli) => cli.id === requested);
if (!found) {
console.error(`${ce.red('plan2code:')} the \`${known.id}\` CLI was not found on your PATH.`);
console.error(`Install ${known.label}, open a new terminal, and run \`plan2code\` again.`);
for (const step of SKILL_STEPS) console.error(step);
}
if (found) announceCli(found);
return found ? { cli: found } : { code: 127 };
}
if (installed.length === 0) {
console.error(`${ce.red('plan2code:')} neither ${CLIS.map((cli) => `\`${cli.id}\``).join(' nor ')} was found on your PATH.`);
console.error(`Install ${CLIS.map((cli) => cli.label).join(' or ')}, open a new terminal, and run \`plan2code\` again.`);
console.error(`${ce.red('plan2code:')} none of ${cliIdList()} was found on your PATH.`);
console.error('');
for (const step of SKILL_STEPS) console.error(step);
console.error('');
console.error('Already have an agent? Open it in your project and type /plan2code ($plan2code in Codex), or install it and run `plan2code` again.');
return { code: 127 };
}
if (installed.length === 1 || !process.stdin.isTTY) {
+49
View File
@@ -1376,6 +1376,26 @@ h1 {
.presets { margin-top: 12px; gap: 8px; }
.presets-label { font-size: 12.5px; color: var(--ink-3); }
/* "Before you close this": three rows on every finished screen. The icon sits
in a coloured circle and the label says the same thing, so no meaning rests
on colour alone. */
.handoff-guide {
margin: 20px 0 0; padding: 14px 16px;
background: var(--panel-2); border: 1px solid var(--rule-2); border-radius: var(--radius);
}
.handoff-guide-title { margin: 0 0 10px; font: 600 15px/1.3 var(--serif); color: var(--ink); }
.handoff-guide-rows { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 10px; }
.handoff-guide-row { display: flex; align-items: flex-start; gap: 12px; font-size: 14px; color: var(--ink-2); }
.handoff-guide-text { min-width: 0; overflow-wrap: anywhere; }
.handoff-guide-label { color: var(--ink); }
.handoff-guide-icon {
flex: none; display: inline-flex; align-items: center; justify-content: center;
width: 28px; height: 28px; border-radius: 50%; border: 1.5px solid currentColor;
}
.handoff-guide-icon svg { fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round; }
.handoff-guide-icon.is-safe { color: var(--ok); background: var(--ok-soft); }
.handoff-guide-icon.is-fresh { color: var(--accent-ink); background: var(--accent); border-color: var(--accent); }
.handoff-guide-icon.is-carry { color: var(--accent); background: var(--accent-soft); }
.handoff-close { margin: 16px 0 0; color: var(--ink-2); }
.handoff-tools { margin-top: 16px; }
.handoff-unsent {
@@ -2361,6 +2381,26 @@ a.icon-btn { box-sizing: border-box; text-decoration: none; }
padding: 1px 5px;
overflow-wrap: anywhere;
}
/* Help, "When something looks stuck": a calm callout and a symptom / cause / action list. */
.help-panel .help-callout {
display: flex; align-items: flex-start; gap: 12px;
margin: 0 0 16px; padding: 12px 14px;
background: var(--stage-soft); border: 1px solid var(--stage); border-left-width: 4px; border-radius: var(--radius);
}
.help-callout-icon { flex: none; width: 22px; height: 22px; margin-top: 1px; fill: none; stroke: var(--stage); stroke-width: 1.8; stroke-linecap: round; stroke-linejoin: round; }
.help-panel .help-callout-label { display: block; margin-bottom: 2px; font-size: 14px; color: var(--ink); }
.help-panel .help-callout p { margin: 0; color: var(--ink); }
.help-panel ol.help-rows { list-style: none; margin: 0 0 12px; padding: 0; }
.help-row { margin: 0 0 8px; padding: 10px 12px; background: var(--panel-2); border: 1px solid var(--rule); border-radius: var(--radius); }
.help-panel .help-row:last-child { margin-bottom: 0; }
.help-row dl { display: grid; grid-template-columns: max-content 1fr; gap: 3px 12px; margin: 0; }
.help-row dt { font-size: 12px; font-weight: 700; letter-spacing: 0.02em; text-transform: uppercase; color: var(--ink-2); padding-top: 1px; }
.help-row dd { margin: 0; font-size: 13.5px; color: var(--ink); min-width: 0; overflow-wrap: anywhere; }
@media (max-width: 520px) {
.help-row dl { grid-template-columns: 1fr; gap: 0; }
.help-row dt { margin-top: 6px; }
.help-row dt:first-child { margin-top: 0; }
}
.help-panel .handoff-command { margin: 0 0 12px; }
.help-panel .handoff-command:last-child { margin-bottom: 0; }
.help-panel .handoff-code {
@@ -3567,3 +3607,12 @@ a.icon-btn { box-sizing: border-box; text-decoration: none; }
color: var(--accent);
font-weight: 700;
}
/* "What to check", beside the quiet and Not running lines. A link in a button's clothes. */
.status-help {
font: inherit; font-size: 0.92em; font-weight: 600;
color: var(--accent); background: none; border: 0; padding: 0 2px;
text-decoration: underline; text-underline-offset: 2px; cursor: pointer;
}
.status-help:hover { text-decoration-thickness: 2px; }
.status-help:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; border-radius: 3px; }
+97 -17
View File
@@ -1637,23 +1637,32 @@ function renderStatus() {
// end right now, and it flies too: the ring and the stars mean the same
// thing. Never on the stale or adrift lines: a turning ring beside
// "has not checked in" would contradict the sentence it sits next to.
const say = (mood, line, count, spin) => {
// `check` adds a "What to check" button that opens Help on the stuck tab.
const say = (mood, line, count, spin, check) => {
if (mood !== moodNow) {
moodNow = mood;
moodVar = Math.floor(Math.random() * MOOD_VARIANTS[mood]);
}
bot.setAttribute("class", `planny is-${mood} v${moodVar}`);
if (text.dataset.line !== line) {
text.dataset.line = line;
text.replaceChildren(
...line.split(/\*\*(.+?)\*\*/).map((part, i) => {
if (i % 2 === 0) return document.createTextNode(part);
const key = document.createElement("strong");
key.className = "agent-key";
key.textContent = part;
return key;
})
);
const shown = check ? `${line}|check` : line;
if (text.dataset.line !== shown) {
text.dataset.line = shown;
const parts = line.split(/\*\*(.+?)\*\*/).map((part, i) => {
if (i % 2 === 0) return document.createTextNode(part);
const key = document.createElement("strong");
key.className = "agent-key";
key.textContent = part;
return key;
});
if (check) {
const help = document.createElement("button");
help.type = "button";
help.className = "status-help";
help.textContent = "What to check";
help.addEventListener("click", () => openHelpOn("stuck"));
parts.push(document.createTextNode(" "), help);
}
text.replaceChildren(...parts);
}
tick.textContent = count || "";
$("agent-spin").hidden = !spin;
@@ -1710,13 +1719,16 @@ function renderStatus() {
if (agentStale()) {
return say(
"work",
"Still working on it. Longer tasks can go a few minutes between updates. Your answers are saved. If it stays quiet for a long while, check your terminal (it may be waiting on a permission approval)."
"Still working on it. Longer tasks can go a few minutes between updates. Your answers are saved. If it stays quiet for a long while, check your terminal (it may be waiting on a permission approval).",
"",
false,
true
);
}
// Same clock as agentStale(), so the soft line at 30 s hands over to the
// stale message at two minutes on one timeline.
const hint = agentLastSeen ? approvalHint(S.agent, Date.now() - Date.parse(agentLastSeen)) : "";
return say("work", hint || activity() || "Plan2Code is thinking…", fmtMs(workingMs()), true);
return say("work", hint || activity() || "Plan2Code is thinking…", fmtMs(workingMs()), true, Boolean(hint));
}
// Between pressing Send and the agent picking it up, the agent's own status
// is still "waiting" because it has not started yet. Reading that as "your
@@ -1729,7 +1741,10 @@ function renderStatus() {
"adrift",
stranded()
? "Plan2Code is not running. Your answers are saved and waiting for it. If the terminal is idle, type **continue** there and it will pick them up; it may also be waiting for your permission approval."
: "Plan2Code is not running right now. Anything you answer here is saved. If the terminal is idle, type **continue** there to wake it; it may also be waiting for your permission approval."
: "Plan2Code is not running right now. Anything you answer here is saved. If the terminal is idle, type **continue** there to wake it; it may also be waiting for your permission approval.",
"",
false,
true
);
}
@@ -2312,6 +2327,69 @@ function paintMain(main) {
// in prose and useless for the single action a screen exists to offer. A
// finish with nothing left to run skips the last two beats: it gets a quiet
// pointer at the dashboard instead of a Next step block.
// "Before you close this": the three things someone looking at a finished
// screen wonders. Every finish shape gets it; a pause says where the place is
// kept, and a session with nothing left to run points at the dashboard alone.
const GUIDE_ICONS = {
safe: ["M5 12.5 10 17.5 19 7"],
fresh: ["M19.5 12a7.5 7.5 0 1 1-2.4-5.5", "M19.5 4v4.5H15"],
carry: ["M5 12h13", "M13 6.5 18.5 12 13 17.5"],
};
function guideIcon(kind) {
const wrap = el("span", `handoff-guide-icon is-${kind}`);
wrap.setAttribute("aria-hidden", "true");
const svg = document.createElementNS(SVG_NS, "svg");
svg.setAttribute("viewBox", "0 0 24 24");
svg.setAttribute("width", "16");
svg.setAttribute("height", "16");
for (const d of GUIDE_ICONS[kind]) {
const path = document.createElementNS(SVG_NS, "path");
path.setAttribute("d", d);
svg.appendChild(path);
}
wrap.appendChild(svg);
return wrap;
}
function renderCloseGuide(shape) {
const panel = el("section", "handoff-guide");
panel.setAttribute("aria-labelledby", "handoff-guide-title");
const title = el("h3", "handoff-guide-title", "Before you close this");
title.id = "handoff-guide-title";
panel.appendChild(title);
const rows = [
["safe", "Safe to close", "This tab is only a window. Everything is saved on disk, and nothing here needs you."],
[
"fresh",
"Start fresh",
shape === "paused"
? "Restart your agent window, or close the old session and start a new one. Your saved place is picked up by the resume command above."
: "Restart your agent window, or close the old session and start a new one. A new session starts from clean context. This one is full of this step's instructions, so continuing in it is slower and can confuse the next step.",
],
[
"carry",
"Carry on",
shape === "all-done"
? `In the new session, start from the dashboard with \`${DASHBOARD_COMMAND}\`.`
: `Paste the command above in the new session, or start from the dashboard with \`${DASHBOARD_COMMAND}\`.`,
],
];
const list = el("ul", "handoff-guide-rows");
for (const [kind, label, text] of rows) {
const row = el("li", "handoff-guide-row");
row.appendChild(guideIcon(kind));
const body = el("div", "handoff-guide-text");
body.appendChild(el("strong", "handoff-guide-label", label));
body.appendChild(document.createTextNode(" "));
body.appendChild(textWithCode("span", "handoff-guide-line", text));
row.appendChild(body);
list.appendChild(row);
}
panel.appendChild(list);
return panel;
}
function renderHandoff(fin) {
const card = el("article", "card handoff");
card.appendChild(el("p", "card-kicker", "Session ended"));
@@ -2402,13 +2480,15 @@ function renderHandoff(fin) {
}
}
card.appendChild(renderCloseGuide(shape));
card.appendChild(
el(
"p",
"handoff-close",
reviewPending() === "open"
? "The review is optional. Skip it and you can close this tab: nothing else here needs you."
: "Then you can close this tab. Nothing here needs you any more."
? "The review is optional. Skip it and nothing else here needs you."
: "That is everything on this page."
)
);
+1 -1
View File
@@ -9,6 +9,7 @@ const tab = (id, label, diagram) => Object.freeze({ id, label, diagram });
export const HELP_TABS = Object.freeze([
tab("about", "What this page is", true),
tab("stuck", "When something looks stuck", true),
tab("around", "Finding your way around", true),
tab("workspace", "Your workspace", false),
tab("planny", "Reading Planny", true),
@@ -22,7 +23,6 @@ export const HELP_TABS = Object.freeze([
tab("subagents", "Helpers (subagents)", false),
tab("ask", "Ask a quick question", false),
tab("finishing", "Stopping and finishing", false),
tab("stuck", "When something looks stuck", true),
tab("prefs", "Keyboard and preferences", false),
tab("privacy", "Privacy and where things are saved", false),
]);
+184 -139
View File
@@ -602,6 +602,10 @@
<path d="M12 11v6" />
<path d="M12 7.5v.5" />
</symbol>
<symbol id="hi-stuck" viewBox="0 0 24 24" fill="none">
<path d="M12 4l9 16H3z" />
<path d="M12 10v4.5M12 17v.5" />
</symbol>
<symbol id="hi-around" viewBox="0 0 24 24" fill="none">
<circle cx="12" cy="12" r="9" />
<path d="M15.5 8.5l-2 5-5 2 2-5z" />
@@ -660,10 +664,6 @@
<path d="M6 21V4" />
<path d="M6 4h11l-2 4 2 4H6" />
</symbol>
<symbol id="hi-stuck" viewBox="0 0 24 24" fill="none">
<path d="M12 4l9 16H3z" />
<path d="M12 10v4.5M12 17v.5" />
</symbol>
<symbol id="hi-prefs" viewBox="0 0 24 24" fill="none">
<path d="M4 7h16M4 12h16M4 17h16" />
<circle cx="9" cy="7" r="1.8" />
@@ -757,7 +757,174 @@
</p>
</section>
<!-- Tab 2: Finding your way around -->
<!-- Tab 2: When something looks stuck -->
<section class="help-panel" data-tab="stuck">
<h3>When something looks stuck</h3>
<p class="help-lead">
This page and Plan2Code in your terminal are two programs, and either
can stop without the other. Nothing you have typed is lost either way.
</p>
<div class="help-callout" role="note">
<svg class="help-callout-icon" viewBox="0 0 24 24" aria-hidden="true">
<path d="M12 3.5 22 20.5H2Z" />
<path d="M12 10v5" />
<path d="M12 17.8v.4" />
</svg>
<div>
<strong class="help-callout-label">Check this first</strong>
<p>
If nothing seems to be happening, look at your terminal. Plan2Code
often stops there to ask your permission, and this page cannot see it.
</p>
</div>
</div>
<h4>What you might see</h4>
<ol class="help-rows">
<li class="help-row">
<dl>
<dt>You see</dt><dd>The line beside Planny stays quiet for a minute or two while it is working.</dd>
<dt>Likely cause</dt><dd>A permission prompt is waiting in your terminal.</dd>
<dt>Do this</dt><dd>Switch to the terminal and answer it.</dd>
</dl>
</li>
<li class="help-row">
<dl>
<dt>You see</dt><dd><strong>Not running</strong> (Planny grey and still).</dd>
<dt>Likely cause</dt><dd>Plan2Code has not checked in for a few minutes.</dd>
<dt>Do this</dt><dd>Look at the terminal. If it is idle, type <code>continue</code> there.</dd>
</dl>
</li>
<li class="help-row">
<dl>
<dt>You see</dt><dd><strong>Not connected</strong> (Planny faded, his star shut).</dd>
<dt>Likely cause</dt><dd>The program behind this page shut itself down.</dd>
<dt>Do this</dt><dd>Ask Plan2Code to resume the session, and use the new link.</dd>
</dl>
</li>
<li class="help-row">
<dl>
<dt>You see</dt><dd>Nothing on the page changes after you press Send.</dd>
<dt>Likely cause</dt><dd>The agent is busy, or has finished its turn.</dd>
<dt>Do this</dt><dd>Your answer is saved. Check the terminal.</dd>
</dl>
</li>
</ol>
<figure class="help-figure" data-figure="stuck">
<svg class="help-diagram" viewBox="0 0 560 262" role="img" aria-labelledby="hd-stuck-title hd-stuck-desc">
<title id="hd-stuck-title">What to check when something looks stuck</title>
<desc id="hd-stuck-desc">
A decision flow. First: does Planny say Not connected? If yes, run
the command again and use the new link. If no: does he say Not
running? If yes, look at the terminal, which may be waiting for
your permission, finished or errored. Either way, and in every
other case, answering anyway is safe, because what you send is
held until Plan2Code collects it.
</desc>
<defs>
<marker id="hd-stuck-arrow" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="5" markerHeight="5" orient="auto-start-reverse">
<path class="hd-arrow" d="M0 0 L8 4 L0 8 z" />
</marker>
</defs>
<path class="hd-box" d="M20 50 L110 16 L200 50 L110 84 Z" />
<text class="hd-label" x="110" y="46" text-anchor="middle">Says Not</text>
<text class="hd-label" x="110" y="63" text-anchor="middle">connected?</text>
<rect class="hd-box" x="260" y="26" width="284" height="48" rx="8" />
<text class="hd-label" x="402" y="46" text-anchor="middle">Run the command again,</text>
<text class="hd-label" x="402" y="63" text-anchor="middle">use the new link</text>
<path class="hd-line" d="M202 50 H256" marker-end="url(#hd-stuck-arrow)" />
<text class="hd-label small" x="228" y="43" text-anchor="middle">yes</text>
<path class="hd-line" d="M110 86 V112" marker-end="url(#hd-stuck-arrow)" />
<text class="hd-label small" x="118" y="103">no</text>
<path class="hd-box" d="M20 150 L110 116 L200 150 L110 184 Z" />
<text class="hd-label" x="110" y="146" text-anchor="middle">Says Not</text>
<text class="hd-label" x="110" y="163" text-anchor="middle">running?</text>
<rect class="hd-box" x="260" y="120" width="284" height="60" rx="8" />
<text class="hd-label" x="402" y="144" text-anchor="middle">Look at the terminal: waiting</text>
<text class="hd-label" x="402" y="162" text-anchor="middle">for permission, finished, errored?</text>
<path class="hd-line" d="M202 150 H256" marker-end="url(#hd-stuck-arrow)" />
<text class="hd-label small" x="228" y="143" text-anchor="middle">yes</text>
<path class="hd-line" d="M110 186 V206" marker-end="url(#hd-stuck-arrow)" />
<text class="hd-label small" x="118" y="200">no</text>
<path class="hd-line" d="M402 182 V206" marker-end="url(#hd-stuck-arrow)" />
<path class="hd-line" d="M546 50 H554 V231 H474" marker-end="url(#hd-stuck-arrow)" />
<rect class="hd-accent" x="90" y="210" width="380" height="44" rx="8" />
<text class="hd-label hd-accent" x="280" y="229" text-anchor="middle">Answering anyway is safe:</text>
<text class="hd-label" x="280" y="246" text-anchor="middle">what you send is held until it is collected</text>
<path class="hd-flow" d="M202 50 H256 M546 50 H554 V231 H474" />
</svg>
<figcaption>Whatever you find, nothing you have typed is lost.</figcaption>
</figure>
<h4>Not running, or not connected?</h4>
<ul>
<li>
<strong>Not running</strong> (Planny grey and still): this page is
fine, but Plan2Code in the terminal has not checked in for
<span data-fact="adriftMinutes">3</span> minutes. It may have finished
its turn, hit an error, or be waiting on you there.
</li>
<li>
<strong>Not connected</strong> (Planny faded, arms hanging, his star shut in red):
this page cannot reach its own program, after
<span data-fact="goneSeconds">8</span> seconds without contact.
Usually it has shut itself down; see "Getting a new link" below.
</li>
</ul>
<p>"Reading Planny" shows every mood side by side.</p>
<h4>It may be waiting for you in the terminal</h4>
<p>
Plan2Code sometimes stops in the terminal to ask your permission
before it runs a command or changes a file, and this page cannot see
that. After about 30 seconds of silence while it is working, the line
beside Planny asks "Still working, or waiting on an approval in your
terminal?" Have a look at the terminal: answering there sets it going
again.
</p>
<p>
If it stays quiet a couple of minutes longer, the line changes to
"Still working on it. Longer tasks can go a few minutes between
updates", with Planny still
in his working pose. It may be busy, or still waiting on you in the
terminal; the terminal is where to look. A build that said a task may
take longer gets that long before the line changes.
</p>
<p>
Hands-off modes, such as <code>auto</code> mode in Claude Code or
<code>smart</code> mode in Devin, cut down on those stops, though some
may still need you.
</p>
<h4>Answering anyway</h4>
<p>
You can keep answering and press Send while Plan2Code is not running.
What you send is written to disk and held until something collects it,
so starting Plan2Code again picks it up where you left off.
</p>
<h4>Getting a new link</h4>
<p>The program behind this page shuts itself down:</p>
<ul>
<li>
<span data-fact="closedTabMinutes">2</span> minutes after the last tab
showing it closes,
</li>
<li>
after <span data-fact="idleMinutes">30</span> minutes without hearing
from anyone, or
</li>
<li>
after <span data-fact="maxLifeHours">4</span> hours, whatever is
happening.
</li>
</ul>
<p>
To get it back, ask Plan2Code in the terminal to resume the session,
or run the step's command again, and use the new link it gives you.
Everything you typed, sent or not, is still there.
</p>
<div class="handoff-command" data-copy>
<code class="handoff-code">resume the session and print the web console address here</code>
</div>
</section>
<!-- Tab 3: Finding your way around -->
<section class="help-panel" data-tab="around">
<h3>Finding your way around</h3>
<p class="help-lead">
@@ -891,7 +1058,7 @@
</ul>
</section>
<!-- Tab 3: Your workspace -->
<!-- Tab 4: Your workspace -->
<section class="help-panel" data-tab="workspace">
<h3>Your workspace</h3>
<p class="help-lead">
@@ -982,7 +1149,7 @@
</ul>
</section>
<!-- Tab 4: Reading Planny -->
<!-- Tab 5: Reading Planny -->
<section class="help-panel" data-tab="planny">
<h3>Reading Planny</h3>
<p class="help-lead">
@@ -1030,7 +1197,7 @@
</p>
</section>
<!-- Tab 5: Answering questions -->
<!-- Tab 6: Answering questions -->
<section class="help-panel" data-tab="answering">
<h3>Answering questions</h3>
<p class="help-lead">
@@ -1099,7 +1266,7 @@
</p>
</section>
<!-- Tab 6: Sending and what happens next -->
<!-- Tab 7: Sending and what happens next -->
<section class="help-panel" data-tab="sending">
<h3>Sending and what happens next</h3>
<p class="help-lead">
@@ -1185,7 +1352,7 @@
</ol>
</section>
<!-- Tab 7: Notes and attachments -->
<!-- Tab 8: Notes and attachments -->
<section class="help-panel" data-tab="notes">
<h3>Notes and attachments</h3>
<p class="help-lead">
@@ -1253,7 +1420,7 @@
</p>
</section>
<!-- Tab 8: Documents and printing -->
<!-- Tab 9: Documents and printing -->
<section class="help-panel" data-tab="docs">
<h3>Documents and printing</h3>
<p class="help-lead">
@@ -1312,7 +1479,7 @@
</p>
</section>
<!-- Tab 9: The dashboard -->
<!-- Tab 10: The dashboard -->
<section class="help-panel" data-tab="dashboard">
<h3>The dashboard</h3>
<p class="help-lead">
@@ -1435,7 +1602,7 @@
</p>
</section>
<!-- Tab 10: Session meter -->
<!-- Tab 11: Session meter -->
<section class="help-panel" data-tab="meter">
<h3>Session meter</h3>
<p class="help-lead">
@@ -1483,7 +1650,7 @@
</p>
</section>
<!-- Tab 11: Watching a build -->
<!-- Tab 12: Watching a build -->
<section class="help-panel" data-tab="build">
<h3>Watching a build</h3>
<p class="help-lead">
@@ -1551,7 +1718,7 @@
</p>
</section>
<!-- Tab 12: Helpers (subagents) -->
<!-- Tab 13: Helpers (subagents) -->
<section class="help-panel" data-tab="subagents">
<h3>Helpers (subagents)</h3>
<p>
@@ -1606,7 +1773,7 @@
</ul>
</section>
<!-- Tab 13: Ask a quick question -->
<!-- Tab 14: Ask a quick question -->
<section class="help-panel" data-tab="ask">
<h3>Ask a quick question</h3>
<p class="help-lead">
@@ -1697,7 +1864,7 @@
</p>
</section>
<!-- Tab 14: Stopping and finishing -->
<!-- Tab 15: Stopping and finishing -->
<section class="help-panel" data-tab="finishing">
<h3>Stopping and finishing</h3>
<p class="help-lead">
@@ -1779,128 +1946,6 @@
</p>
</section>
<!-- Tab 15: When something looks stuck -->
<section class="help-panel" data-tab="stuck">
<h3>When something looks stuck</h3>
<p class="help-lead">
This page and Plan2Code in your terminal are two programs, and either
can stop without the other. Nothing you have typed is lost either way.
</p>
<figure class="help-figure" data-figure="stuck">
<svg class="help-diagram" viewBox="0 0 560 262" role="img" aria-labelledby="hd-stuck-title hd-stuck-desc">
<title id="hd-stuck-title">What to check when something looks stuck</title>
<desc id="hd-stuck-desc">
A decision flow. First: does Planny say Not connected? If yes, run
the command again and use the new link. If no: does he say Not
running? If yes, look at the terminal, which may be waiting for
your permission, finished or errored. Either way, and in every
other case, answering anyway is safe, because what you send is
held until Plan2Code collects it.
</desc>
<defs>
<marker id="hd-stuck-arrow" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="5" markerHeight="5" orient="auto-start-reverse">
<path class="hd-arrow" d="M0 0 L8 4 L0 8 z" />
</marker>
</defs>
<path class="hd-box" d="M20 50 L110 16 L200 50 L110 84 Z" />
<text class="hd-label" x="110" y="46" text-anchor="middle">Says Not</text>
<text class="hd-label" x="110" y="63" text-anchor="middle">connected?</text>
<rect class="hd-box" x="260" y="26" width="284" height="48" rx="8" />
<text class="hd-label" x="402" y="46" text-anchor="middle">Run the command again,</text>
<text class="hd-label" x="402" y="63" text-anchor="middle">use the new link</text>
<path class="hd-line" d="M202 50 H256" marker-end="url(#hd-stuck-arrow)" />
<text class="hd-label small" x="228" y="43" text-anchor="middle">yes</text>
<path class="hd-line" d="M110 86 V112" marker-end="url(#hd-stuck-arrow)" />
<text class="hd-label small" x="118" y="103">no</text>
<path class="hd-box" d="M20 150 L110 116 L200 150 L110 184 Z" />
<text class="hd-label" x="110" y="146" text-anchor="middle">Says Not</text>
<text class="hd-label" x="110" y="163" text-anchor="middle">running?</text>
<rect class="hd-box" x="260" y="120" width="284" height="60" rx="8" />
<text class="hd-label" x="402" y="144" text-anchor="middle">Look at the terminal: waiting</text>
<text class="hd-label" x="402" y="162" text-anchor="middle">for permission, finished, errored?</text>
<path class="hd-line" d="M202 150 H256" marker-end="url(#hd-stuck-arrow)" />
<text class="hd-label small" x="228" y="143" text-anchor="middle">yes</text>
<path class="hd-line" d="M110 186 V206" marker-end="url(#hd-stuck-arrow)" />
<text class="hd-label small" x="118" y="200">no</text>
<path class="hd-line" d="M402 182 V206" marker-end="url(#hd-stuck-arrow)" />
<path class="hd-line" d="M546 50 H554 V231 H474" marker-end="url(#hd-stuck-arrow)" />
<rect class="hd-accent" x="90" y="210" width="380" height="44" rx="8" />
<text class="hd-label hd-accent" x="280" y="229" text-anchor="middle">Answering anyway is safe:</text>
<text class="hd-label" x="280" y="246" text-anchor="middle">what you send is held until it is collected</text>
<path class="hd-flow" d="M202 50 H256 M546 50 H554 V231 H474" />
</svg>
<figcaption>Whatever you find, nothing you have typed is lost.</figcaption>
</figure>
<h4>Not running, or not connected?</h4>
<ul>
<li>
<strong>Not running</strong> (Planny grey and still): this page is
fine, but Plan2Code in the terminal has not checked in for
<span data-fact="adriftMinutes">3</span> minutes. It may have finished
its turn, hit an error, or be waiting on you there.
</li>
<li>
<strong>Not connected</strong> (Planny faded, arms hanging, his star shut in red):
this page cannot reach its own program, after
<span data-fact="goneSeconds">8</span> seconds without contact.
Usually it has shut itself down; see "Getting a new link" below.
</li>
</ul>
<p>"Reading Planny" shows every mood side by side.</p>
<h4>It may be waiting for you in the terminal</h4>
<p>
Plan2Code sometimes stops in the terminal to ask your permission
before it runs a command or changes a file, and this page cannot see
that. After about 30 seconds of silence while it is working, the line
beside Planny asks "Still working, or waiting on an approval in your
terminal?" Have a look at the terminal: answering there sets it going
again.
</p>
<p>
If it stays quiet a couple of minutes longer, the line changes to
"Still working on it. Longer tasks can go a few minutes between
updates", with Planny still
in his working pose. It may be busy, or still waiting on you in the
terminal; the terminal is where to look. A build that said a task may
take longer gets that long before the line changes.
</p>
<p>
Hands-off modes, such as <code>auto</code> mode in Claude Code or
<code>smart</code> mode in Devin, cut down on those stops, though some
may still need you.
</p>
<h4>Answering anyway</h4>
<p>
You can keep answering and press Send while Plan2Code is not running.
What you send is written to disk and held until something collects it,
so starting Plan2Code again picks it up where you left off.
</p>
<h4>Getting a new link</h4>
<p>The program behind this page shuts itself down:</p>
<ul>
<li>
<span data-fact="closedTabMinutes">2</span> minutes after the last tab
showing it closes,
</li>
<li>
after <span data-fact="idleMinutes">30</span> minutes without hearing
from anyone, or
</li>
<li>
after <span data-fact="maxLifeHours">4</span> hours, whatever is
happening.
</li>
</ul>
<p>
To get it back, ask Plan2Code in the terminal to resume the session,
or run the step's command again, and use the new link it gives you.
Everything you typed, sent or not, is still there.
</p>
<div class="handoff-command" data-copy>
<code class="handoff-code">resume the session and print the web console address here</code>
</div>
</section>
<!-- Tab 16: Keyboard and preferences -->
<section class="help-panel" data-tab="prefs">
<h3>Keyboard and preferences</h3>