Files
plan2code/.agents-docs/AGENTS-architecture.md
T

111 KiB
Raw Blame History

Architecture

Part of AGENTS.md — project guidance for AI coding agents.

Directory Structure

plan2code/
├── src/                        # Source workflow prompts (14 markdown files)
│   ├── plan2code-0-pathfinder-references/ # Reference files for pathfinder skill
│   │   ├── brief.md                        # Dated plain-English decision briefs
│   │   ├── chart.md                        # MODE A: destination + frontier grills, templates
│   │   ├── github-issues.md                # Issue-backed map (loaded only when Backend is github)
│   │   ├── grilling.md                     # Folded-in grilling + domain-modeling
│   │   ├── questions.md                    # On-disk question-file format + markers
│   │   ├── resolve.md                      # Per-type resolution + graduating the fog
│   │   ├── handoff.md                      # Clearing gate + PLAN-DRAFT handoff
│   │   └── trail.md                        # Every-response map visual + pathed resume command
│   ├── shared-references/              # Reference files shared across skills
│   │   ├── building-habits.md              # Find the cause, test first, pin behavior (quick-task, implement, implement-review)
│   │   └── helper-strength.md              # How strong a model and how much effort each helper gets (pathfinder, plan, revise-plan, quick-task, implement, implement-review, review)
│   ├── plan2code-review-references/     # Reference files for review skill
│   │   ├── verification-protocol.md        # Deep verification + confidence calibration
│   │   ├── dimensions.md                   # 11 dimensions with detailed checklists
│   │   ├── false-positives.md              # Known false-positive patterns
│   │   ├── reviewer-brief.md               # Fill-in brief for the one fresh helper that runs the analysis
│   │   └── session-end.md                  # Next-step routing at review session end
│   ├── plan2code-init-update-references/ # Reference files for init-update skill
│   │   └── ai-agent-file-sync.md           # Step 7: replace AI configs with AGENTS.md refs
│   └── plan2code-4-finalize-references/ # Reference files for finalize skill
│       └── community-feedback-submission.md # STEP 6.5 payload schema + submission tiers
├── plan2code-loop/           # Autonomous loop CLI tool (Node.js/TypeScript)
│   ├── src/                    # TypeScript source
│   └── dist/                   # Built output (tsup)
├── plan2code-bot/            # Autonomous end-to-end workflow test runner (TypeScript, tsup, Claude Agent SDK, vitest); user docs in .readme/test-bot.md
├── plan2code-metrics/        # Recursive self-improvement toolchain
│   ├── src/                    # TypeScript source
│   │   └── prompts/            # Internal AI prompt templates (no char limit)
│   └── dist/                   # Built output (tsup)
├── src/statusline-claude/       # Claude CLI status line (Node.js, zero deps, single file)
│   ├── statusline.js           # Self-contained: config, git, formatters, render
│   └── statusline-config.json  # Default config template
├── src/launcher/               # Global `plan2code` command (Node.js, zero deps)
│   ├── plan2code.js            # Opens /plan2code in Claude Code or Devin in the cwd (or a picked folder)
│   ├── models.json             # Curated model menu, copied to ~/.plan2code/bin/ on install
│   └── plan2code.ico           # Desktop shortcut icon (Windows)
├── src/web-console/            # Local browser UI bundled into every skill (Node.js, zero deps, no build)
│   ├── console.mjs             # CLI the agent drives: open, post, wait, chat, keep, status, stop, help
│   ├── server.mjs, routes.mjs, static.mjs, cmd-*.mjs, picker.mjs, and the by-job files (files, sessions, patches, scan, inbox, workspace, settings)
│   ├── console.md, console-*.md, notes/, building*.md # Agent-facing contract (console.md read once, the rest on demand)
│   └── public/                 # Page assets served to the browser
├── scripts/                    # Development scripts
│   ├── bench-web-console.mjs   # Start-path timing
│   ├── capture-screenshots.mjs # Stages web console screens and saves the docs screenshots (needs a local Chrome or Edge, through `playwright-core`)
│   ├── browser.mjs             # The one place a browser is launched (Chrome, then Edge, through `playwright-core`; `PLAN2CODE_TEST_BROWSER` forces one); page tests, the screenshots and the bench use it
│   ├── css-snapshot.mjs        # Dev-only: every element's computed style on every screen, both themes; take one before a stylesheet move and `--compare` after
│   ├── vendor-codemirror.mjs   # Dev-only: bundles the pinned CodeMirror 6 packages with esbuild into `public/vendor/codemirror.esm.js` (installed in a temp folder from `vendor-codemirror-lock.json`, never in the repo)
│   ├── 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, web-console-test-helpers.mjs  # Web console suites, split by area (the page tests are `-page-*`, the source shape `-shape`), and their shared setup
│   ├── test-launcher.mjs, test-getting-started.mjs  # Launcher suite; newcomer docs kept in step
│   ├── test-skill-scripts.mjs, test-script-<skill>.mjs, test-git-repo.mjs, skill-script-helpers.mjs, fixture-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
│   └── plan2code-<name>/       # SKILL.md plus references/ and scripts/ where present
│                               # Generated by npm run build:skills; consumed by skills add
├── .husky/                     # Git hooks (husky)
│   └── pre-commit              # Runs character count validation
├── .claude/                    # Repo-local Claude Code config (NOT installed by install.js)
│   └── skills/                 # Maintainer-only dev skills, e.g. plan2code-publish/, plan2code-model-update/
├── .github/ISSUE_TEMPLATE/      # bug.yml, idea.yml, config.yml (target of the console's feedback button)
├── .readme/                    # User guides linked from README (web-console.md, web-console-design.md, walkthrough.md, autonomous-loop.md, metrics.md, status-line.md, test-bot.md)
├── docs/                       # Landing page `index.html` served at plan2code.jparkerweb.com (GitHub Pages, `CNAME`) and assets
│   └── screenshots/            # Web console screenshots, <shot>-light.webp and <shot>-dark.webp (generated)
├── specs/                      # Feature specs (if any in-progress)
├── install.js                  # Interactive installer (Node.js)
├── package.json                # Root package (husky only, private: true)
├── version.json                # Version metadata
├── CHANGELOG.md, QUICK-REFERENCE.md, LICENSE
├── .gitattributes, .editorconfig  # Pin LF (see Code Style & Gotchas)
├── prototypes/, specs--completed/, dist/  # Local only, gitignored: design prototypes, archived specs, stale pre-2.2 build output. Ignore root dist/.
└── README.md                   # User documentation

Key Files

File Purpose
install.js Interactive installer — builds skills/ from src/, then delegates installation to the skills CLI
src/plan2code-*.md Source workflow prompts (the "source of truth")
skills/ Generated Agent Skills, gitignored build output regenerated by the installer (and npm run build:skills) before every skills add
scripts/validate-char-count.js Pre-commit validator ensuring all source prompts ≤ 20,000 chars
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, Devin or Codex (installed by I and Advanced → E; also via Advanced → D). When the desktop app is installed (~/.plan2code/app/plan2code-app[.exe], or the file PLAN2CODE_APP names) and a display exists (Windows and macOS always; Linux needs DISPLAY or WAYLAND_DISPLAY), it opens the app after the agent and model questions with --project <folder> --agent <id> [--model <id>] and exits; --classic (never forwarded to the CLI) and a failed spawn keep the terminal flow. The app reads all three (project::launch_choice): the picker starts on --agent, and --model applies to that agent on every start and Restart (AgentManager::set_model); a model never applies to another agent
plan2code-app/ Tauri desktop app (Rust host, xterm panel, the console's dashboard in a frame; its own README). RELEASE-CHECKLIST.md lists the by-hand checks before each release. src-tauri/src/versions.rs compares the app's version (tauri.conf.json) with the installed skills' (~/.plan2code/bin/version.json) for the bar's Update skills line, which runs node ~/.plan2code/bin/plan2code.js update only when pressed
plan2code-app/src-tauri/src/attention.rs The taskbar signal's rules, pure and knowing nothing about Tauri: Signal (busy, ready, attention, plain), badge_for(signal, os, enabled) (Windows: green dot on ready, red on attention; macOS: red ! on attention only; Linux: count 1 on attention), should_flash(prev, next, focused, enabled) (once, only on a change into ready or attention while unfocused) and dot_rgba() (the dot's pixels, in the favicon's colors, which a test checks against public/favicon.js). main.rs applies the result through set_attention, set_taskbar_signal and clear_attention_cmd; the page asks with the attention and taskbar messages (public/app-bridge.js) and the switch is taskbarSignal in the app's own ~/.plan2code/app.json.
plan2code-app/src-tauri/src/agents.rs Custom agents in the app: CustomAgent, the Agent handle over built-ins and custom entries, load_custom_agents, reading the Agents file below; the console side is src/web-console/agents.mjs
Desktop app install (install.js) installDesktopApp() downloads plan2code-app-<version>-<windows|macos|linux>-<x64|arm64>[.exe] and plan2code-app-<version>-SHA256SUMS.txt from the GitHub release (PLAN2CODE_RELEASE_BASE replaces the URL; the tests serve a stand-in), checks the SHA-256 and places the file in ~/.plan2code/app/ (the old file is renamed aside first, since Windows cannot overwrite a running exe). app is an install piece (INSTALL_PIECES, after launcher), so plan2code update updates it with the rest. install() asks for it after the command (default yes; a no is kept as skipped in install.json); unattended it installs it unless it is already recorded or was declined. A failed app never fails the install. .github/workflows/release-app.yml builds one file per system (tauri build --no-bundle) and the checksum list on a published release, after scripts/check-versions.mjs --tag

Agents file

~/.plan2code/agents.json holds the person's custom agent CLIs. The web console is its only writer (User Preferences → Agents, through POST /agents); the plan2code launcher and the desktop app only read it. Each reader carries its own copy of the rules (src/web-console/agents.mjs for the console, a copy in src/launcher/plan2code.js, agents.rs in the app), and scripts/fixtures/agents-cases.json is the contract all three readers' tests load: file normalization with its warnings, buildArgs command lines and makeId ids. Change a rule in the fixture first.

  • File: { "schema": 1, "agents": [...] }. Any other schema, text that is not JSON, or agents that is not a list gives no custom agents and one warning. A missing file is an empty list with no warning. More than 50 entries: the first 50 are used. Unknown keys, in the file and in an entry, are kept when the console saves.
  • Entry: id, name and command are required; args (default []), prompt (default "/plan2code", blank allowed), bypassArgs ([]), modelArgs (["--model", "{model}"]) and models ([], each { id, label? }) are optional. The three argument fields are lists of text, one list item per argument.
  • Rules: id matches ^[a-z0-9][a-z0-9-]{0,31}$, is not claude, devin or codex, and is unique; name is at most 60 characters and unique ignoring case; command is not blank. makeId(name, taken) makes the id from the name in kebab case (agent when nothing is left), with -2, -3 on a clash, at most 32 characters.
  • Bad entries: a bad entry is skipped with a warning naming it (agents[i], 0-based) and the rest still load, in all three readers. POST /agents instead refuses the save with { error, index, field }, and answers 409 while the file holds something GET /agents could not read, unless the body says replace: true.
  • Command line: buildArgs returns args with {prompt} filled (the prompt is appended when no argument holds it, and a blank prompt drops an argument that is exactly {prompt}), then modelArgs with {model} filled when a model is chosen, then bypassArgs when checks are off. Arguments travel as a list, never through a shell; the Windows cmd wrapper for a .cmd or .bat belongs to the launcher and the app.

Workflow Prompts (in src/)

File Step Purpose
plan2code.md — The dashboard: opens the web console's skill menu and launches the picked skill into its own session
plan2code-init.md Init Generate AGENTS.md as index + .agents-docs/ section files (progressive discovery)
plan2code-init-update.md Update Update AGENTS.md with learnings; detects and routes edits to .agents-docs/ files
plan2code-0-pathfinder.md 0 Chart a foggy idea as a map (local files, or GitHub Issues) of decision questions under specs/<idea>/pathfinder/, resolve them one at a time, hand a seeded PLAN-DRAFT to Step 1
plan2code-quick-task.md quick Lightweight planning for small tasks (standalone — not a pipeline step)
plan2code-1-plan.md 1 Requirements analysis & architecture
plan2code-1b-revise-plan.md 1b Mid-implementation revisions
plan2code-2-document.md 2 Create implementation specs
plan2code-3-implement.md 3 Execute implementation (phase by phase)
plan2code-3-implement-review.md 3 Execute one phase, run focused review and fixes, then request approval
plan2code-review.md review Post-implementation comprehensive review, analyzed by one fresh helper when the tool has one (verified in session; the report says who reviewed)
plan2code-4-finalize.md 4 Validate, summarize, feedback, archive (steps 1–7, +optional 6.5)
plan2code-handoff.md handoff Compact the conversation into a self-contained handoff document for a fresh session
plan2code-xray.md xray Explain how and why an area works (files, commits, PRs via gh when present), or rank the rough spots worth fixing into ARCHITECTURE-BRIEF-<date>.md for Pathfinder or Plan; never edits code
plan2code-diagnose.md diagnose Find a bug's cause under the find-the-cause-first habit (references/building-habits.md) and write it up as specs/<bug-name>/DIAGNOSIS-<YYYYMMDD>.md without fixing it, then offer Quick Task to fix it, or Plan when the fix is big. The dashboard scan reports such a folder as spec state diagnosed ("Bug diagnosed"), which lights Quick Task (suggested) and Plan. Once Quick Task marks the diagnosis Fixed (nothing past it in the folder) the state is fixed ("Bug fixed"): no pipeline card lights, the picker never pre-selects it, and Quick Task offers to archive it with specs.mjs archive
plan2code-changelog.md changelog Check the CHANGELOG version against the default branch, suggest editable entries for new work, keep package.json aligned, offer to commit the result through Git
plan2code-git.md git Branches, pull (with conflict help), push, publish and commits (clear message, suggested splits) on the web console's git board, or plain instructions in the terminal (switch to main, commit and push); asks before every push, publish and delete

Naming Convention

Workflow files follow a strict naming pattern:

  • The hub: plan2code.md (bare name — bare: true in SOURCE_PROMPTS, no suffix; it is the dashboard the rest hang off, not a step)
  • Utilities: plan2code-<name>.md (single dash)
  • Numbered steps: plan2code-<N>-<name>.md (single dash, number, single dash)

Examples:

  • plan2code-init.md (utility)
  • plan2code-1-plan.md (step 1)
  • plan2code-1b-revise-plan.md (step 1b)

Reference Files

Some workflows use companion reference files for depth that does not need to load on every invocation. The orchestrator (main workflow file) loads them via Read directives during execution.

Pattern: src/<source-filename-without-extension>-references/ (e.g., plan2code-review-references/). A file several skills read lives in src/shared-references/ instead and ships to each through additionalReferences (e.g., building-habits.md into Quick Task, Implement and Implement + Review).

How the installer handles them: the directory is copied verbatim to skills/<skill-name>/references/, so Read references/<file>.md resolves consistently for every agent. There is one output format, with no flat-file sibling directory or path rewrite.

Reference files are NOT subject to the 20,000 character limit. The review workflow pioneered this pattern (verification-protocol, dimensions, false-positives, session-end); the init-update workflow also uses it (ai-agent-file-sync for its Step 7), plan2code-4-finalize.md uses it for STEP 6.5 (community-feedback-submission), and plan2code-0-pathfinder.md leans on it hardest (brief, chart, github-issues, grilling, questions, resolve, handoff, trail — the orchestrator is a dispatcher, the depth lives in the references). Other workflows can adopt it when a source file carries detail that is only needed some of the time. The implement-review skill is a generated composition: additionalReferences in SOURCE_PROMPTS packages the canonical implement prompt, review prompt, and review reference directory into its own references/ directory so those workflows are reused without source duplication.

Skill Scripts

Anything a workflow step decides with one correct answer (parsing a spec's checkboxes, rebuilding Pathfinder's map markers, the commit message, which AI config files exist) lives in a script the agent runs, not in prose it follows. Prose keeps the judgment.

Source Ships to How
src/skill-scripts/<name>.mjs skills/<skill>/scripts/<name>.mjs Shared: a skill lists the ones it runs in scripts: [...] on its SOURCE_PROMPTS entry. Skills install independently, so each gets its own copy
src/skill-scripts/common.mjs every skill that has scripts SHARED_SCRIPTS_ALWAYS in install.js
src/<source>-scripts/<name>.mjs skills/<skill>/scripts/<name>.mjs A skill's own scripts, mirroring -references/. A name that collides with a shared script is a build error
version.json (repo root) skills/<skill>/scripts/version.json Copied at build, so an installed skill can report its version
Script Skills Does
specs.mjs plan, revise-plan, document, implement, implement-review, review, quick-task, finalize, handoff list / status (Phase Checklist, groups, task markers, numbering, the implement selection verdict, consistency checks) / metrics / mark / archive. Imports scanProject() from the bundled web-console/scan.mjs, so the dashboard and the skills share one spec classifier
commit-msg.mjs implement(-review), review, quick-task, finalize, init-update, git The <subject> / AI Assisted commit command (two -m flags), with optional git add
review-scope.mjs review, implement(-review), quick-task Review Mode's git fallback: files, lines, doc share, base branch
agents-md.mjs init, init-update AGENTS.md structure, budget, orphans, broken links, always-inline sections
agent-files.mjs init, init-update Detect and replace other agents' config files with AGENTS.md pointers
pathfinder.mjs (own) 0-pathfinder reconcile, frontier, claim, resolve, rule-out, trail, gate, lint, brief-data
feedback-payload.mjs (own) 4-finalize STEP 6.5's payload (real sha256 prompt hashes) and the gh / browser / print submission tiers
xray.mjs (own) xray hotspots (churn, files changed together, often-changed files with no test, from git log over a capped window) and history <path> (commits following renames, a blame summary, PR titles and first paragraphs through gh when signed in, and which sources were used). Read-only
changelog-state.mjs (own) changelog state, bump, set-package-version: the default branch's version, whether the branch's entry can be extended (not released, not on another branch), the file's heading style, the gap since the entry was last touched; only set-package-version writes, and only the version field
git.mjs (own) git state, plan, branch-check, init-check, delete-check, cleanup-list, conflicts, pr-url, classify-error: the repo snapshot, each action's exact command and confirm text (shared by the terminal and the board), branch-name, delete, cleanup and git init checks, a stopped rebase's conflicts, the pull-request link and git's errors sorted into kinds with a next step. Read-only: the agent runs every command it prints, and guard() refuses force push, hook skipping, amend, remote delete and blanket add

Conventions (common.mjs): Node 18+ built-ins only; one JSON object on stdout (ok: false plus error, message, next on a handled failure, the same line on stderr); exit 0 ok, 1 crash, 2 bad arguments, 3 not found, 4 invalid or check failed, 5 refused; --help documents commands and exit codes; writes take --dry-run; PLAN2CODE_NOW pins the clock for tests. A SKILL.md names a script as node "<S>/<name>.mjs", where <S> is scripts/ beside it.

Tests: scripts/test-skill-scripts.mjs (installer plumbing and the shared scripts), scripts/test-script-<skill>.mjs (a skill's own), with fixtures from scripts/skill-script-helpers.mjs. Importing that module rebuilds skills/ unless npm_lifecycle_event is test (npm test has just built it). Git fixtures go through copyFixture() (scripts/fixture-helpers.mjs): built once per test file, copied per test, since every git process costs a few hundred milliseconds on Windows; a remote inside the fixture is added with slashed() so the copy's .git/config can be pointed at its own origin. They run the built skills/ tree, and one test fails if any SKILL.md or shipped reference names a <S>/<name>.mjs that skill does not ship. The per-skill scripts import ./common.mjs, which only sits beside them in the built tree, so run them from skills/, not src/.

Repo-Local Skills (.claude/skills/)

Maintainer-only skills committed to the repo but deliberately excluded from the generated skills/ product artifact:

  • plan2code-publish/ — publishes a GitHub Release after version files agree.
  • plan2code-changelog/ — validates release classification and keeps version files synchronized.
  • plan2code-model-update/ — refreshes the launcher's curated model menu (src/launcher/models.json) from devin models list and Claude Code's documented model aliases: shows a diff, applies only the changes the maintainer approves, validates the file and runs npm test. Terminal only, and it never commits.
  • sync-repo/ — decrypts the protected upstream-sync workflow in memory.

Do not run skills add against the repository root: recursive discovery also finds these maintainer skills. install.js targets skills/ and passes explicit workflow names instead. Global install/uninstall cleanup removes plan2code-* workflow skills from user skill directories; it never operates on this repository's .claude/skills/ directory, and sync-repo intentionally has no plan2code- prefix.

Web Console

Optional local browser UI shipped with every skill. Source lives in src/web-console/ and is fanned into each skill by an additionalReferences: [{ source: 'web-console', target: 'web-console' }] entry in SOURCE_PROMPTS, landing at skills/<skill>/references/web-console/. The bare plan2code skill is the hub: it opens the console as --workflow dashboard, the page draws the skill menu itself (from each SKILLS entry's card in public/skills.js, through SKILL_CATALOG in public/answers.js, kept in sync with the install set by a test), and a card click reaches the agent as a { "i": "__launch", "skill": ..., "workflow": ... } send — the dashboard then resumes its own session under the launched skill's workflow (open --resume <sid> --workflow <w> restates workflow/title/specDir on the live server) and runs that skill's file. plan2code-review now has a console of its own AND still runs inside builds on the page (a review verdict on Implementation's sign-off card, or the Review it now button on a finished quick task), so plan2code-3-implement and plan2code-quick-task also carry review.md and the review references, the same way implement-review does. CONSOLE_WORKFLOWS in public/answers.js, built from the same SKILLS list, decides whether a copied hand-off asks the next session for the console.

File Role
console.mjs the CLI the agent drives: open, post, wait, chat (the instant Quick question check), keep (copy a cited note attachment into specs/<idea>/attachments/), delete-spec, handoff new, delete-handoff (both on handoffs.mjs), status, stop, help (a compact summary for an agent that found the binary but not console.md; help <topic> prints one contract file, help topics lists them). post --wait <N> posts and waits in one command
server.mjs HTTP server, spawned detached by open (never as a harness background task, which get killed on compaction and at assorted timeouts)
public/ (other files) index.html, favicon.svg (Planny peeking up from the tab bar, served as image/svg+xml) with favicon.png (the same icon at 192 px, served as image/png) as the fallback, vendor/marked.esm.js, the chimes (start-skill.mp3, bootup.mp3, start-stop.mp3, next.mp3, insert.mp3, sleeping.mp3; which moment plays which is SOUND_EVENTS in palette.js, one switch per event saved in looks.json), and a package.json that only says "type": "module", so Node (the server and the tests import the pure modules) parses them as ES modules without a reparse warning. The stylesheet is the files in public/styles/, joined by the server into the one /app.css the page asks for
cmd-chat.mjs the chat command: hand over Quick questions now, never waiting
cmd-help.mjs the help command: the CLI's usage and the contract's topic files; the usage's workflow list and its build sessions come from WORKFLOWS and isBuild() in skills.js
cmd-open.mjs the open command: start or resume a session, its server and the browser; refuses a --workflow that isWorkflow() does not know (exit 2, naming the valid ones), and asks startsClean() (public/hops.js) whether a resume blanks the page
in-app.mjs the desktop app's signal to open: inAppSignal() reads PLAN2CODE_IN_APP, PLAN2CODE_CONSOLE_SID, PLAN2CODE_APP_ANNOUNCE and PLAN2CODE_APP_TOKEN; announcePage() POSTs the page to that window's loopback endpoint. Under the app open never starts a browser, resumes the app's session and announces the page; with the variables unset nothing here runs. Imported by cmd-open.mjs
open-link.mjs the desktop app's webview opens no new windows, so the page there sends links off the console (linkLeavesPage() in public/app-bridge.js: http or https on another origin, caught in wireChrome()) to POST /open-link. linkToOpen() takes http and https only (400 otherwise); openLink() starts the default browser with the link as one argument, never through a shell (rundll32 url.dll,FileProtocolHandler on Windows, open on macOS, $BROWSER or xdg-open elsewhere) and skips it under PLAN2CODE_NO_BROWSER. When that fails the page shows the link with a Copy button to paste into a browser
cmd-post-wait.mjs post and wait: publish a patch, then collect what the person sent
cmd-small.mjs the small commands: keep, forget, delete-spec, handoff, delete-handoff, status and stop; handoff new refuses an unknown --workflow the same way open does
files.mjs where the console's files live, how they are written safely, and the argument parser both command lines share
agents.mjs the rules of ~/.plan2code/agents.json (see Agents file above), console side: normalizeAgents() reads the file into clean entries and warnings, never throwing; validateForSave() checks what User Preferences sends and names the first bad entry and field; makeId(), buildArgs() (the command line from an entry) and resolveCommand() (where a command runs from, never running it). Served by GET / POST /agents and POST /agents/test in routes.mjs
inbox.mjs the Quick question chat's inbox beside the card slot
patches.mjs checking and merging an agent's patch into the session state: validate() (the house rules; allows templates only as "idea" on a text item, anything else exits 3), the patch merge, resolveDocFiles() and applyPatch()
routes.mjs every URL the page can call, in one ordered list (ROUTES, walked by handle()); server.mjs hands each request to it
scan.mjs what the dashboard knows about the repo: scanProject(), classifySpec() (a folder's files to a spec state), TASK_LINE_RE (re-exported from spec-files.mjs) and removeSpec()
sessions.mjs a session's roots and handle files (repoRoots(), healthOk(), attachmentName(): the kept-file name <slug>-<id8>.<ext>, the same upload always gets the same name, readOverview()) and the console folder's housekeeping: the three sweeps open runs fire-and-forget after it prints (sweepUploads(), staleSessions() / removeSessions(), staleScratch() / removeScratch()) and cleanupFindings() / removeCleanup() for User Preferences → Cleanup
settings.mjs the person's saved console settings: Subagents and pull-request hosts
spec-files.mjs no imports: how a spec's markdown files are read, MARKERS, TASK_LINE_RE, TASK_ID_RE, CHECKBOX_RE, STATUS_RE, statusOf() and countTasks(); shared by scan.mjs, patches.mjs and src/skill-scripts/specs.mjs (through consoleModule())
static.mjs serving the page's own files: SERVABLE (the allow-list), TYPES, caching and ETags, the accent colors, and CSS_ORDER + joinedStyles(), the one place the cascade order is stated
workspace.mjs the session's extra folders, and the folders remembered per project and spec
public/app.js the page's entry and the only page file that starts anything: the start-up block. index.html loads it; it imports screens/core.js and the screens beside it
public/doc-files.js a document as the page shows it, and as a file: blocks, Markdown and HTML download
public/hops.js no imports: the hop rule, startsClean(from, to), which says whether a hop from one workflow to another starts the new skill on a clean page (to or from the dashboard, into Git, or from one skill into another off a finished screen, but never out of Git or into Review); shared by cmd-open.mjs, server.mjs (its Ask reset) and screens/core.js
public/looks.js how the page looks and sounds: the saved looks, their sync, and the preferences dialog's swatches
public/mention-box.js the @name suggestions popover under a text box
public/net.js the page talking to its own server
public/palette.js the highlight colors, the sound events and the card widths, as data (importable by Node so a test can check every shade in both themes)
public/render.js Markdown to DOM, safely: no HTML string is ever produced, only nodes built with createElement and textContent; also the shared page helpers (el, md, copyButton, lightDismiss)
public/selectors.js what the page reads off its state: the questions, the finish, the scan, who has the ball
public/send-state.js whether Send is available, and what its button says
public/skills.js the skill list: every per-skill fact the console uses (card, order, start pose, launch scoring, subagent opt-in, which spec states light its card), data only, imported by the page and by Node; the older tables (SKILL_CATALOG, START_POSES, CONSOLE_WORKFLOWS and the rest, in answers.js) are lookups on it. Each entry also carries weight (what its launch and run score on the meter, or null), started and ran (the meter's labels for them, or null), resume ("overview", "folder" or null: what the resume command takes after the skill's command) and an optional card.help (Help's line for the card when it differs from blurb). WORKFLOWS (every entry's workflow, in order) and isWorkflow() are what the CLI checks a --workflow against. The meter's WEIGHTS, LAUNCH_LABELS and RUN_LABELS, resumeCommand(), Help's card list and cmd-help's workflow list are all derived from it, so a new skill is one entry here, not an edit to each of those
public/sound.js the sound cues: which plays, one at a time, held until the first click
public/spec-states.js the spec states (diagnosed, fixed, exploring, mapped, planned, documented, building, built, unrecognized): each one's picker label, the card it is the natural next step for and its recommendation, data only; which cards a state lights lives in skills.js, how a folder maps to a state in classifySpec() in scan.mjs
public/state.js the page's shared state (page.S the server's truth, page.local what is staged) and the redraw() / save hooks every screen calls; defines only
public/uploads.js pictures and documents attached to a note: chips, trays, re-encoding, upload, retry
public/screens/ask.js the Ask chat, the Subagents tab, and attaching files to notes
public/screens/cards.js question cards: every kind, the pager, settled and in-flight records
public/screens/cleanup.js User Preferences, Cleanup tab
public/screens/core.js the core every screen sits inside: connection, the render loop, the page chrome and Send; the only file that imports the screens, and only app.js imports it
public/screens/dashboard.js the dashboard: cards, the spec picker, handoff chips, delete, and the first-open wake-up
public/screens/docs.js documents: tabs, blocks, print and download, and the brief button
public/screens/ending.js how a session ends: the finished screen, its offers, Stop and the way home
public/screens/git-host.js hosts the git board: tabs, panels and what each click sends
public/screens/help-dialog.js the Help dialog and the first-run Welcome (named so it is never confused with the pure help.js). Help reads right in both modes: a phrase that differs under the desktop app carries its app wording in data-app (swapped in by renderAppWording()), and a paragraph that differs is a .for-browser / .for-app sibling pair, switched by :root.in-app (set in core.js from page.inApp, rule in help.css). The older render*Help() functions patch a few ids the same way. scripts/test-web-console-page-help.mjs sweeps every topic's visible text in each mode for the other mode's wording
public/screens/looks.js User Preferences: looks, sounds and the launcher's model menus
public/screens/starting.js the launching, starting and waiting screens, with Planny's poses
public/screens/workspace.js the read-only Workspace of extra folders, and @mentions
public/styles/ask.css The Ask pane and its Quick question chat
public/styles/dashboard.css The dashboard: the menu, the spec picker, its confirm and the launching pane
public/styles/docs.css Documents and the doc tools
public/styles/ending.css The end of a session: the hand-off and the stopping screen
public/styles/git.css The git board
public/styles/help.css The help dialog, its diagrams and its tabs
public/styles/looks.css The looks button and the highlight swatches
public/styles/pieces.css Shared pieces: cards, options, settled answers, pager, forms, checklist, markdown and the modal
public/styles/planny.css Planny the mascot: the flight, his moods and variants, and the wake-up
public/styles/poses.css The start-screen poses, one per skill. After the dashboard on purpose: its narrow-window rules override the dashboard's
public/styles/responsive.css Print, then the narrow-window rules: last, so its overrides come after everything they override
public/styles/shell.css The page shell: banner, top bar and meter, layout, sidebar, aside, footer, waiting and arrival
public/styles/tokens.css Colors, type, sizes and the light and dark themes: the variables every other file reads
public/help.js the Help dialog's PURE rules: HELP_TABS (18 tabs: ids, order, labels, diagram flags; every tab uses the chosen highlight color; The git board sits right after Watching a build), helpTabFor() (which tab opens, FR-8 order, first match wins: finished → Stopping and finishing, server gone or agent adrift → When something looks stuck, opened from the Workspace dialog → Your workspace, then Ask, the Subagents tab → Helpers (subagents), a red-meter dashboard → Session meter, dashboard, a doc or the Overview, a git session → The git board, a build, else What this page is) and helpKeyTarget() (roving arrow keys, Home, End, wrapping). No module-scope DOM, so node --test covers it
git-repo.mjs the one read-only reader of a git repository: the worktree status (countPending(), behind pendingFiles()), the branch table, the default branch, a merge or rebase in progress, the remotes and their web addresses, the last fetch and the pull-request link; snapshot() is what open and every reread store as state.git. Every git call carries GIT_OPTIONAL_LOCKS=0, so a background look never takes the index lock. Imported by cmd-open.mjs, cmd-post-wait.mjs and sessions.mjs; the git skill's git.mjs reaches it through common.mjs
public/git-board.js PURE, one import (pr-url.js): the git board's rules from a state.git snapshot: branch order and the Remote only fold at REMOTE_FOLD 50, whether a new branch name is free, which buttons show and are enabled, whether the board still waits on the agent (boardAwaiting(): from a click until the agent's next post, not just until wait collects it), the plain sentence each click sends as reply, the "Last refreshed" line, which files start ticked in the commit dialog, and the pull-request link; the next step (ten rules, nextStep()), the tab that owns it, per-tab badges (tabBadges()), the busy mode and per-control gate (busyMode(), controlAllowed()), the tab to show (pickTab()), and the create-panel sources and clean-up groups. app.js only renders what it says
public/git-board-view.js No DOM access of its own: drawGitBoard(ctx) draws the tabbed board (header, tab strip with Done with git, the card slot, step strip, Changes / Branches / Sync) from the helpers it is handed (el, md, copyButton), every control through one gate; screens/git-host.js hosts it, and scripts/test-web-console-git-board.mjs drives it with a recording fake el
public/pr-url.js PURE, no imports: prUrl(), the "open a pull request" link for the GitHub, GitLab, Azure DevOps and Bitbucket shapes (null for an unknown kind, no web address, or a non-https result). git-repo.mjs re-exports it, and the board's base picker rebuilds the link in the browser with the same code
public/workspace.js PURE, no imports: the Workspace's name rules (nameProblem(), NAME_MAX, defaultName(), freeName() for the -2 suggestion), the footer label and its width tiers (footerLabel(), FOOTER_TIERS) and changeLine(), the Workspace: … reply line an agent is handed per change. Imported by the server, cmd-chat.mjs, cmd-post-wait.mjs, workspace.mjs and the page
public/meter.js PURE, imports only skills.js: the session meter. WEIGHTS (the events that are not a skill's own launch, merged with each skill's weight from skills.js; its keys are also RUN_EVENTS, the run events post accepts), LAUNCH_COUNTED (workflows whose launch itself scores), the built-phase sizing (TASK_EVENTS, the keys of TASK_BONUS: implement-phase +0 and implement-review-phase +1; isTaskCount() accepts a whole tasks from 1 to MAX_TASKS 999; runPoints() scores such a run ceil(tasks / TASKS_PER_POINT) (3) plus its bonus, and any other run its WEIGHTS value), ANSWERS_PER_POINT 2 (answer entries score per skill run, floor(count / 2)), breakdownFrom() (the click-the-ring list: one row per scoring entry plus one answers row per skill run), pointsFrom() (the count, its sum, folded from ledger.ndjson and deduplicated by id, never stored), levelFor() with YELLOW_AT 5 / RED_AT 10, ringFraction() (full at RING_FULL 15), WORDS, tooltipFor(), RED_BANNER and meterView()
public/mentions.js PURE, no imports: the @name popover's logic — mentionAt() finds an @partial at the caret, matchNames() filters the workspace names, applyMention() splices a pick in and returns the new caret. Used by the Ask box, notes and text answers
public/favicon.js The tab icon's status bar. faviconState({ mood, spin, finished }) (PURE) maps the call renderStatus() makes for Planny's line to busy (the spinning ring), ready (point), attention (adrift, gone, or work without the ring — the stale line) or plain (finished, happy); faviconSvg() is FAVICON_BODY (kept equal to favicon.svg by a test) plus a bar along the bottom edge in the FAVICON_COLORS color (busy dashed on a white strip, so the states differ by pattern; the rest solid); setFavicon() swaps both <link rel=icon> hrefs only on a change — the SVG as a data URL, the PNG link drawn through a canvas. Called from say() in renderStatus(), which runs every second
public/app-bridge.js The messages the page posts to the desktop app that frames it. framed() is true inside a frame; tellApp(kind, extra) posts { plan2code: kind }, a named request with no free text: looks (the highlight's dark shades, from applyLooks(), for the app bar's buttons), agent-continue (the in-app continue button on the Not running line: the app types the keystrokes continueKeys() in plan2code-app/ui/meter.js names into the agent's terminal, continue and Enter, then under Claude Code its send-now chord ctrl+x ctrl+s, so a word queued behind a stuck turn is delivered) and new-session (the meter popover's New Session: the app presses its own bar button, confirm and all). Nothing outside a frame
public/subagents.js PURE, no imports: the Subagents switch. SUBAGENT_WORKFLOWS / offered() (the opt-in table: implement, implement-review, quick-task, review, pathfinder, plan, revise-plan, each with its default instruction), cleanSetting() ({ on, instruction, max, strength } or { error }: bad, too-long past 2,000 characters, max outside 1-20, strength not one of STRENGTHS; strength is balanced, thrifty, best or session, missing reads as balanced, saved per project and skill in each subagents.json entry and sent as a Helper strength: line in the "on" block), FRAME_LINES, blockFor(setting, told) (the Subagents: lines and subagents field an agent is owed, given the session setting and its cursor; never says "off" to an agent not told "on"), checkHelper() / checkHelpers() (the helpers house rule) and the page's view rules showSwitch(), switchLabel(), helperRows(), showTab(), CHECKIN_LINE. Imported by the server, the cmd-*.mjs files, patches.mjs, settings.mjs, the page and the tests; in SERVABLE and preloaded
handoffs.mjs the handoff store, the only code that names, lists, marks, deletes and sweeps handoffs, all in ~/.plan2code/handoffs/ (PLAN2CODE_HANDOFFS_DIR for tests; PLAN2CODE_NOW pins its clock): newHandoff() claims YYYY-MM-DD-HHmm-handoff (-2, -3 on a clash, the .json created exclusively) and writes only <id>.json ({ v: 1, id, title, worktree, project, spec, workflow, skill, written, fromStop, usedAt }), the agent writing <id>.md; listHandoffs(worktree) (unused, same worktree, .md present, newest first, title and Next task read off the document); readHandoffMeta(), markHandoffUsed(); removeHandoff() (HANDOFF_ID only, regular files, never a link, realpath inside the folder, throws on any refusal); staleHandoffs() / removeHandoffs() for the sweep
notepads.mjs the notebook store (the feature is named Notebook; its code, routes and storage folder keep the name notepad), the only code that names, reads, writes and removes notebooks, one per folder Plan2Code runs in, in ~/.plan2code/notepads/<folder-name>-<12 hex>/ (PLAN2CODE_NOTEPADS_DIR for tests), split into named tabs: meta.json ({ v: 2, folder, created }), tabs.json ({ v: 1, order, last, tabs: { id: { name, created } } }) and tabs/<id>/note.md with tabs/<id>/images/. notepadKey() (the folder's basename slug and the first 12 hex of sha256(foldKey(folder))), listTabs() / defaultTabId(), readNotepad(folder, tab) (never creates or writes anything; { tabs, last, tab } with the tab's text, savedAt and images repeated at the top), the tab changes createTab() / renameTab() / reorderTabs() / setLastTab() / deleteTab() (index first, then the folder; names pass normalizeTabName(), TAB_NAME_MAX 40, any case compared by nameKey(), NOTEPAD_MAX_TABS 20), saveNote(folder, tab, text) (1 MB cap, atomic), addImage() / addThumb() / removeImage() (JPEG bytes only, 200 pictures per tab, UUID names), imagePath() (regular files whose realpath stays inside the folder), staleNotepads(now, maxAgeMs) (the real folders directly under it named like a key, never a link or a file, whose newest file is at least maxAgeMs old, as { key, folder, path } with folder from meta.json or null), removeNotepad(key) (the key checked against NOTEPAD_KEY_RE, the path kept inside the notepads folder by path.relative, a link refused, then the whole folder removed; User Preferences, Cleanup is its only caller) and NotepadError (code and status, turned into { error } by the /notepad routes). Migration: a notepad in the first shape (note.md and images/ at the top) reads as one virtual tab, Notes (LEGACY_TAB_ID), and writes nothing; its first write moves the files into tabs/<LEGACY_TAB_ID>/ and writes tabs.json last, every step safe to run again after a crash. A tabs.json that does not hold up is set aside as tabs.json.corrupt and rebuilt from the tab folders on the next write. Every write runs under a notepad.lock in the notepad's folder. The agent CLI never imports it: nothing in a notepad reaches the agent
public/notepad.js PURE, no imports: the Notebook's rules. SAVE_DEBOUNCE_MS 800, RETRY_STEPS_MS (1 s up to 30 s), NOTE_MAX_BYTES / NOTEPAD_MAX_IMAGES / TAB_NAME_MAX / NOTEPAD_MAX_TABS / IMAGE_ID_RE / TAB_ID_RE (kept equal to notepads.mjs by a test), noteBytes(), the save-state reducer nextSave(state, event) from SAVE_START (states idle, pending, saving, saved, failed, too-long; it returns the timer to arm), saveStatus() (the status line's words), unsaved() (what beforeunload asks on), keepsText() (unsaved or too long: a reopen never replaces the editor's text then), tabSwitch() (whether leaving a tab must save it first), NOT_LOADED, EDITOR_NOT_LOADED, errorSentence() (one sentence per /notepad refusal, else a lost connection), the tab rules cleanTabName(), nameTaken(), tabNameProblem(), moveTab(), dropTab() and the two-confirm delete nextDelete() / DELETE_STAGES, and step() (wrapping through the pictures)
public/screens/notepad.js the Notebook: #btn-notepad in the top bar on every screen (disabled while the server is gone, renderNotepadButton() in the render pass), #notepad-modal, the one CodeMirror editor (made on first open by a dynamic import of notepad-editor.js), the page's view of the notepad as { tabs, activeId }, the name form (New tab and Rename, never window.prompt), the in-modal two-step delete, and autosave through nextSave() to POST /notepad/text?tab=<id>, flushed on close, when the page is hidden and before a switch. The editor stays read-only until the first read lands, so nothing typed into an empty editor is saved over a note. Every save and every picture is bound to the tab it was made in: saveTab is fixed when the change is made, a picture entry carries its tab, and a switch waits for the save (settled()), stays put with "Not saved yet, so staying on this tab." when it cannot, and drops a deleted tab's unsaved text without sending it
public/notepad-tabs.js the tab bar: createTabs({ onSwitch, onChange }) with draw(tabs, activeId) (role="tab" buttons, roving tabindex, arrow keys, Alt+arrows to reorder, F2 and double-click to rename, native drag and drop with an .is-drop-before mark that only a tab drag lights, focus kept across redraws, #notepad-empty and #notepad-body toggled) and focusTab(). No fetches: it calls back, and screens/notepad.js owns every request
public/notepad-editor.js the Notebook's live-preview editor on CodeMirror 6 (makeCodeMirrorEditor(parent, { onChange, label }) returning { getValue, setValue, setReadOnly, focus, destroy }). A ViewPlugin decorates only the lines in view from the Markdown syntax tree: heading line classes cm-h1 to cm-h6, bullets drawn as a widget, the marks around bold, links, quotes and a heading hidden on every line the selection is not on. The editor sits in a shadow root (.notepad-cm-host), because CodeMirror writes its rules as a <style> element, which style-src 'self' refuses, and adopts them as a constructed stylesheet inside a shadow root. setValue() is setState(): not reported through onChange, and the undo history is cleared (so each tab starts with a clean one)
public/notepad-editor.css the one stylesheet of that shadow root, linked from notepad-editor.js (a <link> inside the root, in SERVABLE, not in CSS_ORDER): heading sizes, bullets, quote, code and link looks on the console's tokens (custom properties inherit across the boundary, so both themes work). Rules that meet CodeMirror's own base theme use div.cm-editor for the specificity
public/vendor/codemirror.esm.js CodeMirror 6 (state, view, language, commands, lang-markdown, MIT), bundled into one minified ES module by scripts/vendor-codemirror.mjs (sha256 4ff96d58fc1a5497eb933426bd2d160d2fb0cf490de8bb9302c304096c71c1d4, the six top-level versions in the script and the file's header comment, everything they pull in pinned by scripts/vendor-codemirror-lock.json and installed with npm ci, so the same lock gives the same bytes). Never edited by hand: change a version in the script and run node scripts/vendor-codemirror.mjs --update-lock (needs npm and network; the packages install in a temp folder, never in the repo), or without the flag to rebuild from the lock
public/styles/notepad.css the notebook's own rules: the top bar button, the dialog, the tab bar and its tools, the name form, the delete question, the empty state and the pictures. The editor's look is notepad-editor.css, inside its shadow root
picker.mjs the per-OS native folder picker behind Browse… (pickerCommand() → { command, args, env } or null; pickFolder() runs it with async spawn, so the server keeps serving while the dialog is open). Copied from src/launcher/plan2code.js (self-contained CommonJS, so it cannot be shared) with the prompt as a parameter; a drift test keeps the two in step
update-check.mjs the dashboard's release check, server-only (never in SERVABLE): compareVersions() (numeric X.Y.Z, null otherwise), latestTag() (the highest refs/tags/vX.Y.Z, peeled ^{} and pre-release tags skipped), checkForUpdate({ installed, cacheFile, now, run }) (never throws) and runLsRemote() (git ls-remote --tags on the repo: no shell, GIT_TERMINAL_PROMPT=0, GCM_INTERACTIVE=never, SSH BatchMode when GIT_SSH_COMMAND is unset, windowsHide, killed at 10 s; git authenticates itself, the console never touches a credential). The answer, failures included, is cached for an hour in ~/.plan2code/console/update-check.json (UPDATE_CHECK_FILE, in PROTECTED_CONSOLE_FILES so no sweep removes it). server.mjs starts it after the ready line and never awaits it; stateFrame() carries update: { installed, latest } only when a newer release exists (its latest is part of haveKey(), so a page that connected first still gets it), and GET /version returns { version, latest }. Tests seed a fresh cached failure in every console home, so no test server reaches the network. The plan2code launcher reads the same cache for its terminal release notice (a copy of this module sits in ~/.plan2code/bin/)
public/chat.js the Quick question chat's PURE rules, shared by the server and the page: CHAT_LIMIT / CHAT_MAX_CHARS / CHAT_MAX_ATTACHMENTS (the combined image + document cap; CHAT_MAX_IMAGES is kept as an alias of it), chatOffline() (the server's 409 offline guard), and the page's view model (chatView, sendState, nextAbout, contextOptions, unreadDot / shouldChime). Ask context is the { history, about } model: nextAbout() records the last 3 places visited in history and sets about only when the person picks one from + Add context (contextOptions() lists that history plus This spec); dropping it or a successful send clears it, so the page never attaches context on its own. Imports only answers.js, no module-scope DOM, so node --test covers it
public/starters.js PURE, no imports: the Role list (ROLES, ROLE_NOT_SET, normalizeRole(), needsRoleNudge(): the dashboard banner shows until looks.json carries any role), the 19 starter templates (Markdown ## heading sections, shape pinned by a test) and their per-role orders (TEMPLATES, TEMPLATE_ORDERS, templatesFor(), templateSwap() for the replace prompt), and the Ask starter sets (STARTER_SETS, STARTER_SET_FOR, startersFor()). Imported by the page's looks and screens and by the tests; in SERVABLE, preloaded by index.html and parse-checked. The page owns the wording; a skill only flags its fresh-idea text card with "templates": "idea"
public/answers.js the page's PURE answer-shaping logic (what an answer reads as, what a placeholder offers, whether a send carries an answer at all). Kept out of the page's entry because app.js cannot be imported outside a browser, so anything left in it is untestable. The scripts/test-web-console-*.mjs tests import it directly.
public/labels.js taskLabel() / activityLabel(): rewrites a build's Task 4.2 of 6 activity line to Task 2 of 6 (only for implement / implement-review; a plan's Task 2.1 is a real section number). A separate module for the same reason as answers.js: pure, so node --test can import it
public/boot.js playWake(): the dashboard's first-open wake-up. Self-contained (it owns its timers, the listeners that swallow input mid-run and the one measured glide transform; the page's stir() callback times the nudge between the click and the boot, which screens/dashboard.js fills with one snore; skipEl — the muted Skip button, and Escape — ends the run early with onSkip as the cue to silence queued sounds) and free of module-scope DOM access, so it can be imported by the tests and kept out of the screens' render paths; GLIDE_AT_MS / DONE_AT_MS are its timings
console.md the core of the agent-facing contract, read once per conversation (every skill ships the same copy, so a dashboard hop never re-reads it): starting, the turn (post --wait, the exit codes, handling a send, settle), posting, the payload and its kinds, documents (including file blocks), the house rules, and an index of the topic files below with the moment each is read. A test caps it at 24,000 characters
console-finish.md · console-stop.md · console-chat.md · console-workspace.md · console-subagents.md · console-launches.md · console-meter.md · console-attachments.md · console-trouble.md topic files, each read only when its moment first comes: finishing (the finish and its buttons), stop requests (the way home mid-workflow, stopWarning, resuming a pause), Quick questions, the Workspace, standing instructions and helper reports, dashboard launches and the menu payload, the session meter's run events (read only when a run is refused: the notes inline every run), keeping a cited note attachment, and recovery
notes/<workflow>.md per-workflow notes (init for both inits, pathfinder with Briefs, plan, revise-plan, document, implement for both builds, quick-task, review, finalize, handoff, changelog, git, xray, diagnose). Each skill's Interface line reads <D>/console.md and its own notes file right after open; a test checks every skill names one that exists
building.md · building-review.md the build half of the contract, for implement, implement-review and quick-task: progress posts (agent.activity, agent.quietMinutes, file blocks re-read with refresh), the chat check between tasks, questions mid-build and stop requests; building-review.md is the review run on the page (the sign-off's review verdict, Review it now, Implement + Review's Stage 2), read only when asked for

Key design points:

  • First-run Welcome. The first dashboard a person sees (after the wake-up finishes) opens #welcome-modal. Any close (button, Esc, backdrop) saves looks.welcomeSeen: true to looks.json, which survives "Back to default". Help's first tab has a Show the welcome again link (data-action="welcome"). Logic: maybeWelcome() / openWelcome() in screens/help-dialog.js.

  • Top-bar icons. #btn-looks (gear) opens #looks-modal, titled User Preferences: Role, Theme, Card width, Highlight color, Sounds and Models. #btn-feedback (megaphone) is a plain link to https://github.com/jparkerweb/plan2code/issues/new/choose, backed by .github/ISSUE_TEMPLATE/bug.yml and idea.yml (config.yml sets blank_issues_enabled: false). DEFAULT_ACCENT in palette.js is ocean.

  • Version in Help. GET /version reads version.json beside server.mjs, falling back to ../../version.json for a run from src/ (the /version route in routes.mjs). renderHelpVersion() in screens/help-dialog.js fills #help-version. computeExpectedSkills() in install.js injects the root version.json into every references/web-console/, so a version bump changes every skill.

  • Models in User Preferences. GET / POST /models in routes.mjs read the shipped ~/.plan2code/bin/models.json and read/write the user's ~/.plan2code/models.json (SHIPPED_MODELS_FILE / USER_MODELS_FILE in files.mjs). PLAN2CODE_MODELS_DIR relocates both for tests. The launcher reads the same two files for its model menu.

  • The wait is bounded. wait --seconds 240 exits 0 (answers), 10 (still waiting, message: "Waiting on your answer in the web console" to relay), 20 (server gone, resume it) or 30 (canceled). The agent loops. Nothing blocks for the whole time a person takes.

  • A turn is one command, and the CLI does the bookkeeping. Agent speed is model round trips and typed tokens, not the console (bench-web-console.mjs --roundtrip: Send→agent ~70 ms, post→page ~180 ms), so the CLI absorbs every step with one right answer: consume() marks the agent working when it hands over a submit (markWorking()), and wait hands the turn back (markWaiting()) when it starts with an open question, a finish, or on the dashboard or git board; post --wait <N> posts and waits in one process; settle: true | [ids] (settleItems() in patches.mjs) records the latest send's cards as answered from their submitted; a new or reopened question with no stated status sets waiting and waiting drops quietMinutes (settleAgent()); a doc whose content changed with no version moves up one (mergeDocs()); a chat reply with no id is r<re>; doc blocks with file (and select: "tasks", doc-level refresh: true) are read from the worktree by resolveDocFiles() before the merge, refusing paths outside it; and a hop (__launch, __dashboard, __commit, __pickup) comes with resume (the exact open --resume command) and skillFile (hopFor()), a pick-up also with handoffFile. The wait loop's health check runs beside the 50 ms polling instead of blocking it, and is aborted on exit. help <topic> prints any contract file; help topics lists them. token defaults to the option key in the page's tokenFor(), and nothing reads fallbackText, so the contract no longer asks for either.

  • The CLI hands the agent its terminal line. open, post and wait (exits 0 and 10) print terminalLine: "→ Look at the web console: <url>" (terminalLine() in sessions.mjs), and console.md asks the agent to end every terminal message with the latest one verbatim, so the tool builds the line rather than the model. In wait it is added to the printed result only; the collected result.json on disk never carries it. open also prints swept: { sessions, scratch, handoffs } when it found anything to clean.

  • State fields written by open, not the agent. Every open (fresh or resume) records state.worktree and state.branch from repoRoots() — the branch is read off <gitdir>/HEAD on the walk that already finds the gitdir ("" on a detached HEAD or outside git; env-relocated repos ask git, as before) — and the page shows them in the footer as the workspace label (footerLabel(): folder · branch, or folder + N folders · branch once folders are added, stepping down through narrower tiers); a click opens the Workspace dialog. state.wake = true is set only by a fresh open --workflow dashboard and deleted by every resume (server restart, launch, Back to the dashboard); the page also keeps a per-sid sessionStorage guard so a reload never replays it.

  • looks.width is a person-level preference alongside theme, accent and sounds in looks.json. CARD_WIDTHS in public/palette.js (narrow 720, comfortable 880 — default — wide 1080) is read by the page (cardWidth() validates a saved value) and by routes.mjs, which paints data-width on first load; styles/tokens.css maps data-width onto the single --card-width variable that every column rule uses.

  • GET /overview is the one route that reads a project file. It serves <spec>/overview.md as text/markdown with cache-control: no-store (so the Overview tab is always fresh), or 404 { "error": "no overview" }. A dashboard session honors ?spec= only when it equals a dir in state.scan.specs; every other workflow uses state.specDir and ignores the query. The root is state.worktree (fallback state.project), and readOverview() resolves and realpaths the file and refuses anything outside the root's realpath, so ../, absolute paths and outward symlinks all 404.

  • Month-old sessions are deleted whole. open lists staleSessions() (directories matching the session-id pattern whose state.json mtime is older than 30 days, never the sid being opened — no exceptions for paused sessions or unread sends) and staleScratch() (top-level regular .json / .mjs files in the console folder older than 30 days, never looks.json or console-dir — PROTECTED_CONSOLE_FILES — never a directory or symlink) before it prints, and removes them after; removeSessions() / removeScratch() re-check every name against the session-id pattern / the scratch-name rule before deleting — not the age, the skipped sid or the file type, which the stale* listing already decided, so never hand them names that did not come from it. console.md tells agents to write temporary payload files into the session's own folder so they go with it.

  • User Preferences → Cleanup deletes on demand, from a list the server makes. POST /cleanup (origin-checked) with { scan: true } returns cleanupFindings(): { items: [{ id, where, name, kind, bytes, folder? }], bytes } (folder on notepad: items only), ids session:<sid> (the staleSessions() rule, and every file in the folder that old too, never the serving sid), console:<name> (anything at the top of the console home but PROTECTED_CONSOLE_FILES, sessions and runtime, directories too) and root:<name> (anything at the top of ~/.plan2code but KEPT_PLAN2CODE_ENTRIES: console, bin, launcher.json, install.json, models.json, handoffs, notepads, app, app.json, agents.json), notepad:<key> (a month-old notepad, whole; see Notebook below) and completed:<name> (each folder or link directly under the session worktree's specs--completed/ whose newest mtime is older than the session age, 30 days; loose files there stay; the server passes project: sessionWorktree() || PROJECT, and without a project the archive is never scanned). Both stray kinds must be untouched for STRAY_GRACE_MS (an hour, by the newest lstat mtime anywhere inside, since rewriting a file never moves its folder's mtime; unreadable reads as fresh): the same folders hold workspaces.json.lock and writeJsonAtomic()'s <file>.<pid>.tmp, which live for milliseconds. root: is only scanned when the console home is <PLAN2CODE_MODELS_DIR or ~/.plan2code>/console, so a test or dev home never reaches the real folder. Paths never go to the page. { delete: [id] } runs removeCleanup(), which re-scans and removes only ids still on the fresh list (symlinks unlinked, never followed), returning { removed, bytes, failed }. The page always shows the list before Delete these.

  • The console's path is stated, not searched for. Each Interface line names references/web-console/ beside the SKILL.md and the ~/.plan2code/console/console-dir fallback; the prompts with room (all but pathfinder, plan, document and finalize, which sit near the char limit) also name the canonical global install path ~/.agents/skills/<skill>/references/web-console/ (the skills CLI's real store; every agent dir links into it), and every console.mjs open writes HERE to ~/.plan2code/console/console-dir (only open, so a help or dev run from src/ never repoints it) so a later session can read the path from a fixed place. Without these the agent hunts the skill install dirs on every session.

  • open needs no payload, and runs first. --file and --title are optional (the title defaults to the folder name). Every skill's Interface line puts node "<D>/console.mjs" open --workflow <w> BEFORE reading console.md or the project, and a test (every skill opens the console before it reads anything) keeps it that way; a blank session renders a starting screen ("Starting Pathfinder", Planny in flight) until the first post. Every skill replaces the flight with its own animated pose (init — init-update borrows it — pathfinder, plan — revise-plan borrows it — document, implement — implement-review borrows it — finalize, quick-task, review, handoff; only the dashboard keeps the flight), cloned by startStage() in screens/starting.js from <template id="start-poses"> in index.html and animated under .pose in styles/poses.css; each SKILLS entry's pose in skills.js is the list (START_POSES/startPose() in answers.js read it), and a test keeps the template in sync with it and every catalog workflow mapped to a pose. The same pose stands above the waiting pane (.waiting-pane, agent working with an activity and nothing to ask). posePane() keeps the pane on screen across renders when the pose is unchanged — renderMain() holds any :scope > [data-pose] child back from the clear — so the SVG never leaves the DOM, its animations never restart on a state frame, and Planny carries unbroken from launching → starting → waiting. The dashboard's launch hand-off resumes first and reads the launched skill's file after.

  • The dashboard scan knows whether the folder is a git repository. scanProject() returns { hasAgents, isGit, pending, specs }; isGit comes from insideGitRepo(), the same filesystem walk findRoots() does (no git process, linked worktrees and submodules count, a set GIT_DIR / GIT_WORK_TREE / GIT_COMMON_DIR counts as a repo). The Git card is never grayed, since a clean tree still has branches to switch, pull and push. When isGit is false the card shows GIT_INIT_NOTE ("Not a git repository yet: it offers to start one") as its detail line; a scan with no isGit counts as a repo. In a repo, pending is pendingFiles() in sessions.mjs, which calls countPending() in git-repo.mjs: one bounded git status --porcelain -z under GIT_OPTIONAL_LOCKS=0 (null when git cannot say) counting modified, staged, deleted and untracked paths. Above 0 the detail line is pendingNote(n) ("3 files to commit"); 0 and null show no note. A finish with commit: true puts a Commit it now button on the finished screen (commitOffer(), renderCommitOffer()); its __commit press makes the agent resume as git in the same session and run the commit flow above the board. open --resume treats any switch into git (this press, or Changelog's "Commit this now?") as a hop, like a dashboard launch: switchWorkflow() blanks the page, finish and the last run's state.git included, and draft.json goes. Without that, the old finish outlived the switch, and the page sat on the old ending above the new questions and the board. A confirm item may carry files: [{ path, state }], drawn as a collapsed table by filesTable(). Subagents is on by default for the seven opted-in skills (defaultSetting()); a saved Off stays off.

  • The start path is timed, and open is built around it. Measure with node scripts/bench-web-console.mjs (--browser-delay 900 for a real Chrome launch, --roundtrip for Send→agent and post→page, PLAN2CODE_CONSOLE_TRACE=1 on open for a step timeline). Four things make it fast, and each is load-bearing:

    • No git process. repoRoots() in sessions.mjs finds the common dir and worktree top by walking to .git (following gitdir: and commondir files) — each git rev-parse cost 150ms+ on Windows. It asks git only when GIT_DIR/GIT_WORK_TREE/GIT_COMMON_DIR relocate the repo, and uses the native realpath so an 8.3 short name keys the same project git would.
    • The socket handover. open spawns the server first, then binds the loopback port itself (the first listen() blocks ~50ms on Windows, overlapped with the server's boot), launches the browser on that URL immediately (Chrome via start takes ~900ms to its first request, the longest step of all), and hands the listening socket to the server over IPC (bindLoopback()/handOff() in sessions.mjs, --handoff in server.mjs). Requests queue in the socket until the server takes it; one open already accepted is passed across as a socket and acknowledged (conn-held) before the channel is closed. No channel, or no socket within 3s, and the server binds its own port; open then opens the real URL.
    • The first paint needs no fetch. routes.mjs (renderIndex()) renders index.html with the session's title, badge and saved theme (data-theme, data-looks-accent, matched by accent rules generated from palette.js and appended to the joined stylesheet by static.mjs) and the whole first state as an inline <script type="application/json" id="boot"> (every < escaped; data blocks are not executed, so the CSP is unchanged). modulepreload hints fetch every module in parallel, the page draws in the same task as the script runs, and /events?have=<key> skips the opening frame when the page already holds that exact state. The chimes load on first use, not at start-up.
    • Reads are stat-gated. fileStamp() (mtime:size:ino) decides whether state.json, result.json and looks.json changed before anything reads or parses them — per request, per heartbeat and in the 1s poll; the parsed state is cached (readState() returns it; /submit clones before editing). wait stats result.json every 50ms instead of parsing it every 400ms. Static assets are held in memory for the server's life and revalidate by ETag.
  • The Workspace and the session meter live beside state.json, one writer each, and outlive every hop. Three session files, none of which switchWorkflow() ever touches, so both survive dashboard → skill → dashboard (a new console session starts with a count of 0, and with the folders remembered for its folder and spec, below):

    File Writer Holds
    workspace.json the server (workspace.mjs) the folders (id, path, name, description, original, nested), version, the changes log, missing ids, and remote (remoteWarning() in sessions.mjs, computed by the server at boot)
    ledger.ndjson console.mjs append-only, one JSON line per entry. Meter events: launch (every fresh open and every resume into another workflow), run (a post's run, id scoped by launch, with tasks when a built phase reports one) and answer (one per item the person answered in a collected send, written by ledgerAnswers(), id <launch>:answer:<send stamp>:<item>). Also folder-issue reports
    workspace-cursor.json console.mjs the last workspace version handed to the agent; advanced after the print, never backwards

    The page changes the workspace only through five routes: GET /workspace (?check=1 re-stats every folder first), POST /workspace/add (path resolved against state.worktree, ~ expanded, case-insensitive duplicate check on win32/darwin; not-a-folder, duplicate, bad-name, name-taken + suggest), POST /workspace/edit, POST /workspace/remove (the original folder refuses) and POST /workspace/browse (one picker at a time, 409 busy; 404 no-picker when remote is set or no picker exists; PLAN2CODE_PICKER_ECHO stands in for the dialog in tests). stateFrame() carries workspace (folders, missing, remote, the current launch's folder issues) and meter (meterView() over the ledger), and both files are on the 1s poll; it also carries an optional update once the boot-time release check (update-check.mjs) finds a newer release. The agent hears of the workspace through open output (workspace: { folders, missing? }, which also seeds the cursor) and then each change once, as workspace: [...] plus Workspace: … reply lines on wait exit 0 or chat; a change alone never ends a wait slice (pendingWorkspace on exit 10). post and open --file lift run and folderIssue out of the patch into the ledger, never into state.json; an unknown event or a malformed issue is exit 3. Remembered workspaces. workspace.mjs keeps ~/.plan2code/console/workspaces.json (WORKSPACES_FILE, under PLAN2CODE_CONSOLE_HOME in tests): projects[<case-folded worktree>] = { path, project, specs: { "specs/<name>": … } }, each entry { original: { name, description }, folders: [{ path, name, description, nested? }], at }. rememberedWorkspace() answers spec, else project, else nothing; initialWorkspace(worktree, entry) builds from it, both in the server's first workspaceNow() and in open's read-only workspaceOnOpen(), so they agree. workspace.json carries scope (the spec key or ""). Every user change (bumpWorkspace, not missing/found) calls rememberWorkspace(). setScope() swaps the list, logging removed/added/renamed/described changes so the cursor stays truthful; POST /workspace/scope { spec } (the dashboard picker, on selection and before a launch) seeds an unsaved spec from the project's list, and followSpecDir() (state poll, boot) moves the scope to a posted specDir, saving the current list as an unsaved spec's. Two writers, each a read-modify-write of one key: the server and console.mjs forget --spec (Finalize Step 6). The contract is in console-workspace.md and console-meter.md, and building.md (per-phase run), so the skill prompts stay unchanged.

  • The Subagents switch is a standing instruction, injected only on change. The page's icon button (#btn-subagents, after Write a brief) and #subagents-modal show only when the frame's subagents block says offered && supported. offered comes from public/subagents.js; supported means the latest { "type": "open" } line in events.ndjson carries caps: ["subagents"] (latestOpenCaps()), so an older skill copy's open hides the button. Four places hold it, one writer each:

    File Writer Holds
    ~/.plan2code/console/subagents.json server.mjs per project folder → workflow: { on, instruction, max }, instruction: null being the shipped default; on PROTECTED_CONSOLE_FILES
    <session>/subagents-setting.json the server (settings.mjs) { workflow, on, instruction, max, revision }: synced from the store at boot and on any workflow change (serverSubagents().sync in settings.mjs), revision bumped only by a real change
    <session>/subagents-cursor.json console.mjs { revision, state }, the last block handed over; open resets it, and it moves only after the print
    state.json → helpers console.mjs post the helpers the agent reports, merged by id, checked by checkHelpers() plus the prose scan; dropped by switchWorkflow() on a dashboard hop

    POST /subagents (origin-checked; 400 not-offered / bad / too-long / max) saves the store and bumps the session setting. consume(), cmdChat(), deliverChat() and open append blockFor()'s lines last in reply and the subagents field; a change alone never ends a wait slice. The page's Subagents tab (before Ask) draws state.helpers through helperRows(). Helpers never reach the meter ledger. Contract: console-subagents.md.

  • The filesystem is the transport. Sessions live in ~/.plan2code/console/sessions/<sid>/, deliberately not under specs/, so the console cannot trip the metrics scraper or the loop's marker parser, and survives git clean. A result written after the agent dies is picked up by the next session.

  • Attachments on notes and quick questions live in <sid>/uploads/, never in the project: images as <uuid>.jpg, documents as <uuid>.<ext> with ext from DOC_TYPES in answers.js (text, code, PDF). The browser re-encodes images to JPEG and sends raw bytes to POST /upload as image/jpeg; documents go as-is as application/octet-stream, the extension taken by docExt() from the uncut x-p2c-name. readRaw(req, limit, cb) in routes.mjs caps images at MAX_BODY (4 MB) and documents at MAX_DOC_BYTES (10 MB), and drains rather than destroys so the client gets its 413. Images need the FF D8 FF magic; documents pass checkDocument() in sessions.mjs (%PDF- for PDF, strict UTF-8 with no NUL for text), else 415. The server names the file with crypto.randomUUID(). GET /uploads/<id>.<ext> serves images as image/jpeg and documents under a fixed type (application/pdf, else text/plain) with nosniff and, on text, CSP sandbox (a sandboxed PDF cannot open in the viewer), so a browser can show but never run one; recordSubmitted() writes every send's note onto its item as sentNote { at, text, images, files } (paths and names only), which noteAwaiting() in answers.js turns into the Sent box's attachment links and the Notes pane's pending note until the agent's next thread message; DELETE /uploads/<id>.<ext> takes any allowed extension; both stay contained under uploads/. isOwnUpload() returns the kind ("image" / "file" / false), and attachmentsOk() makes /submit comments and /chat messages carry images only in images[] and documents only in files[], this session's uploads only, at most 5 together (MAX_ATTACHMENTS). A comment's reply gains one Image: <path> (<name>) or File: <path> (<name>) line per attachment, in attach order; a chat entry's lines come from chatReplyLines(), its images first, then its files. sweepUploads() bounds disk growth, and the session sweep removes the whole session a month after that. A note attachment a spec file cites is copied out first by console.mjs keep (--session --upload --name --spec [--from]): it checks both paths (the upload must sit under the session's uploads/, and the spec folder under state.project, real paths included, so a symlinked folder cannot carry the copy outside), copies with COPYFILE_EXCL and reuses an existing copy, prints { ok, path, link, image, reused } with a forward-slash link relative to --from, and logs a keep event. It is the agent's hand, not the server's: it runs in the agent's shell only when the agent decides to cite a file, so the server still never writes into a project.

  • Answers carry their terminal token. Each item ships fallbackText and token, so a click resolves to the literal word the prompt already expects (approved, a, skip). No workflow needs a second code path, and declining the console degrades to prose with nothing lost.

  • A build tells the page how long silence is normal. The page calls a working agent stuck after two minutes without a post, which is right for a conversation and wrong for a twenty-minute build task. agent.quietMinutes (1 to 60, counted only while working) stretches the stuck, adrift and Send-grace thresholds; quietLimitMs() in answers.js is the one rule.

  • A finished quick task's review button is a request through the wait loop, like the brief: { "i": "__review" } or { "i": "__done" }. The agent keeps waiting after posting a finish that carries review, and takes the review up by posting "finish": null, which puts the session back to work. Implementation's review needs no such machinery: it is a verdict on the sign-off card, asked before approval, so the session never left work to take it up.

  • Back to the dashboard is the same kind of post-finish request. A finish with finish.dashboard: true shows the button; a press arrives as { "i": "__dashboard", "type": "dashboard" }, and the agent runs open --resume <sid> --no-open --workflow dashboard then posts "finish": null with a fresh menu. The agent waits ~10 minutes after the finish for it (alongside __review / __done on a quick task); after that the page swaps the button for the /plan2code command. finish.command is optional — without one the page shows the "All done" line — and validate() rejects a <placeholder> command and a non-boolean dashboard. The session-level actions are therefore __brief, __stop, __launch, __review, __done and __dashboard; a new post-finish button should copy this precedent.

  • Continue here, Update CHANGELOG first and Ask prompt blocks. Three small additions on the same pattern. Continue here is page-only: continueOffer(fin) (public/answers.js) reads finish.command, and when it starts with a Plan2Code skill (and the finish is not a pause) screens/ending.js draws a button beside the Next step block, hidden when the session meter is red; the press is the dashboard's own { "i": "__launch", ... } through sendAfterBuild("launch", offer), so the agent writes nothing new (startsClean() cleans the page for the hop, except out of Git and into Review; a same-skill next step keeps the workflow, so the agent posts "finish": null). Update CHANGELOG first is finish.changelog: true, accepted by validate() only on quick-task and finalize (a paused finish is exempt from that check and the page ignores the flag), and it belongs with commit: true; the press is __changelog, a HOP_ACTIONS entry in cmd-post-wait.mjs that resumes as changelog, whose "Commit this now?" yes carries on to Git. Ask prompt blocks are contract only (console-chat.md → Prompts to carry away): the page already draws a Copy button on every fenced block.

  • __dashboard also arrives mid-workflow. A left-pointing triangle (#btn-home, filled with --accent) sits left of Stop session on every non-dashboard page. Its state comes from the pure homeButtonState() in answers.js: hidden on the dashboard, on a finish and during a stop, and otherwise gated by the same turnGate() Stop now uses (the person's turn, unless the agent has gone adrift). The confirm (#home-modal) reuses stopWarning(), and the submit carries the staged answers plus __dashboard, with HOME_REPLY. With no finish on the page, the agent treats it as a stop that lands on the menu: it saves its place as for __stop, then resumes as the dashboard with "finish": null + menu, with no finish and no stop in between (console-stop.md → "Back to the dashboard, mid-workflow"; building.md for builds). local.homeward drives Planny's "Saving your place and opening the dashboard…" line until the through-the-dashboard reset clears it.

  • Handoffs live outside every repo, in ~/.plan2code/handoffs/, and the console owns them (handoffs.mjs; the console ships in every skill, so the Stop flow, the Handoff skill and the dashboard all reach it through console.mjs). handoff new --workflow <w> --skill <s> [--spec specs/<x>] [--title <t>] [--from-stop] claims one for this checkout and prints { ok, id, path, meta } (exit 2 bad usage, 3 a bad value). Off the dashboard the Stop modal offers Stop with a handoff (#stop-handoff, suggested) above Just stop and save (#stop-go); the first sends __stop with handoff: true and STOP_HANDOFF_REPLY, and wait adds handoffSkill (the built Handoff skill's SKILL.md, handoffFor()); console-stop.md gives the order (answers, save, handoff new --from-stop, write, paused finish naming the file, stop). On a dashboard, cmdOpen() adds scan.handoffs (listHandoffs(worktree)) and scan.handoffsDir after scanProject(), which stays handoff-free because specs.mjs list shares it. The picker draws them as dashed .spec-chip.is-handoff chips after the specs (specSel = "handoff:<id>"); a picked one replaces the skill cards with renderHandoffPreview(): Pick it up here, Read it all (GET /handoff?id=, served only for an id in the dashboard's own state.scan.handoffs), Copy for a new conversation (handoffCopyText()) and Delete (openHandoffDelete(), one step). Pick it up sends { "i": "__pickup", "type": "pickup", "handoff": <id> }; HOP_ACTIONS.pickup (pickupHop()) reads the stored .json only, never the page, and falls back to Quick Task with fallback: true when the record, its skill or its spec is gone, or the Handoff skill wrote it (resuming that skill would only write another handoff); markPickedUp() stamps usedAt as the hop is printed, so the next scan drops the chip. Delete sends __delete with handoff in place of spec, and the agent runs delete-handoff --handoff <id> (removeHandoff(), exit 3 on a refusal, nothing touched). open sweeps handoffs untouched for 30 days (staleHandoffs(), the .json's mtime, else the .md's), picked up or not, and reports them in swept.handoffs; Cleanup never lists the folder (KEPT_PLAN2CODE_ENTRIES).

  • Notebook: the person's, one per folder, in ~/.plan2code/notepads/, in named tabs, and never the agent's. notepads.mjs is the store's one owner (PLAN2CODE_NOTEPADS_DIR moves it for tests). The folder is the session's worktree, else its project (notepadRoot() in routes.mjs), keyed <folder-name>-<12 hex> by notepadKey() (the hash over foldKey(), so case-only path differences match on Windows and macOS, and two worktrees get two notepads). Layout: meta.json ({ v: 2, folder, created }), tabs.json ({ v: 1, order: [id], last, tabs: { id: { name, created } } }, the index and the only place order and the last tab live) and, per tab, tabs/<id>/note.md with tabs/<id>/images/<uuid>.jpg and <uuid>.thumb.jpg; a tab id is 12 hex. Every write takes the folder's notepad.lock; a read never creates a file, so only the person's edits age a notepad. A delete removes the tab from the index first, then its folder, and the next write sweeps away a tab folder the index no longer names (a delete that crashed half way). Migration: the first shape (v: 1, one note.md and images/ at the top) reads as one virtual tab, Notes, with the fixed id LEGACY_TAB_ID, and a read writes nothing; the first write moves the files into tabs/<LEGACY_TAB_ID>/ and writes tabs.json last, so a crash in the middle is finished by the next write and never loses a file. A tabs.json that does not hold up is set aside as tabs.json.corrupt and rebuilt from the tab folders. Routes: eleven, placed after /upload in ROUTES (the shape test pins the order): GET /notepad[?tab=<id>] ({ tabs, last, tab: { id, text, savedAt, images } }, with the tab's text, savedAt and images repeated at the top), POST /notepad/text?tab= ({ text }, 1 MB, 413 too-long), POST /notepad/image?tab= and POST /notepad/thumb?id=<uuid>&tab= (raw image/jpeg the page re-encoded with reencode(), 4 MB, 200 pictures per tab: 415 not-jpeg, 413 too-large, 409 too-many), POST /notepad/image/delete?tab= ({ id }), POST /notepad/tab ({ name }), /notepad/tab/rename ({ id, name }), /notepad/tab/delete ({ id }), /notepad/tab/order ({ order }, every id once) and /notepad/tab/last ({ id }), and GET /notepad/images/<tab>/<uuid>[.thumb].jpg (matched on the raw request line like /uploads/, served through imagePath()'s realpath containment, no-store). A text or picture request with no ?tab means the last tab used (and makes Notes when there is none), so an unchanged client keeps working. The ten POSTs are origin-checked, and every refusal is a NotepadError turned into { error } (bad-name, duplicate-name, too-many-tabs, no-such-tab beside the picture and text codes). None of them writes to the session folder or events.ndjson, and console.mjs never imports notepads.mjs, so nothing in a notepad reaches state.json or anything wait prints. The editor, and the CSP. CodeMirror 6 replaced OverType 2.6.1 after a spike (typing at 200 KB measured about 24 ms a key against about 99 ms, and real heading sizes): public/vendor/codemirror.esm.js is one minified file (about 500 KB) made by the dev-only scripts/vendor-codemirror.mjs from scripts/vendor-codemirror-lock.json, never installed in the repo, and loaded by a dynamic import only when the Notebook first opens. CodeMirror writes its rules as a <style> element, which style-src 'self' refuses, so the editor lives in the open shadow root of .notepad-cm-host where it adopts them as a constructed stylesheet, and its own look is public/notepad-editor.css, a <link> inside the root. Custom properties inherit across the boundary, so both themes work; page tests reach the editor with Playwright's CSS locators (they pierce open shadow roots) and read its text from EditorView.findFromDOM(), since lines the cursor is not on draw without their Markdown marks. CodeMirror's own rules win a tie in specificity (they are adopted after the linked sheet), so notepad-editor.css writes div.cm-editor .cm-scroller for the few it overrides. scripts/test-web-console-page-notepad.mjs fails on any securitypolicyviolation with the notepad open. Upgrading CodeMirror: change a version in scripts/vendor-codemirror.mjs, run node scripts/vendor-codemirror.mjs --update-lock (npm and network; it installs in a temp folder), update the sha256 in the files-table row, then run the two notepad test files. Tabs on the page: screens/notepad.js binds every save and picture to the tab it was made in (a switch waits for the save, and stays put when it cannot), public/notepad-tabs.js draws the bar, and public/notepad.js holds the name, order and delete rules as pure code. Cleanup. No sweep at open touches a notepad, and notepads is in KEPT_PLAN2CODE_ENTRIES, so the folder is never a stray. cleanupFindings() lists a notepad as one notepad:<key> item (with folder from meta.json, labeled "Notebook for " by screens/cleanup.js, the key when it is missing) only when staleNotepads() finds the newest file in it (newestMtime() in files.mjs, which recurses to any depth, so tab folders count) SESSION_MAX_AGE_MS (30 days) old or more; removeCleanup() removes the whole folder through removeNotepad() (key checked against NOTEPAD_KEY_RE, contained in notepadsDir(), a link refused).

  • A Bug fixed spec deletes in one step. Its chip shows a visible Delete (.spec-chip-del-label) instead of the hover ✕, openDeleteConfirm() gives it a fixed-bug warning and a Delete it button, and deleteStep() sends __delete on the first press, with no name to type. chipDetail() drops the scan's repeated "bug fixed" detail under the label.

  • The Quick question chat is a second, append-only channel beside the card slot. The page's Ask tab (always last, every workflow, still there after a finish) posts to POST /chat (a message, or { reset: true } for New conversation) and POST /chat/decision (Approve / Decline on an edit the agent proposed). The server is the only writer of <sid>/chat.ndjson (one JSON line per message / decision / reset, each with a seq; appendChat() in inbox.mjs); console.mjs is the only writer of <sid>/chat-cursor.json (the last seq handed over, advanced only after printing) and of the agent's replies in state.json → chat.replies (merged by id, checked by validateChat(): real re, proposal paths outside the running specs/<idea>/). The server never writes chat into state.json — post read-modify-writes it under withStateLock() — and stateFrame() merges inbox and replies into the frame's chat block (conversation, messages, typed, limit, offline) in memory. /chat never checks pendingResult(), so neither channel can block the other. wait keeps its exit codes 0/10/20/30: exit 0 gains chat (or is type: "chat" with no actions), and the instant console.mjs chat answers 0/10/20 without touching result.json, which builds run after every task. Guards: 10 typed messages per conversation (409 limit), 4,000 characters (400 too-long), own uploads only, of the right kind (400 image, 400 file), 409 offline when chatOffline() says no agent is there, 409 stale for an old conversation. A hop through the dashboard (checked on every state change and at server start, so a restart still sees it) appends a reset and starts a new conversation. A lone reset never ends a wait slice (deliverableChat()); it rides along with the next message.

  • validate() in patches.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 18 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 (except the dashboard topic's card list: buildHelp() fills its .help-cards from SKILL_CATALOG and CATALOG_GROUPS at that moment, in the dashboard's order), so first load builds nothing and Help still reads fully once the server is gone. help.js supplies the tab list and rules, screens/help-dialog.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-source.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 one node --test over the skill-script tests (test-skill-scripts.mjs, test-script-*.mjs, test-git-repo.mjs), test-launcher.mjs, test-getting-started.mjs and the web console's test-web-console-*.mjs, so they run in parallel, one process each. The console tests are split by area (-session, -lifecycle, -logic, -server, -chat, -chat-stress, -workspace, -subagents, -concurrency, -source, -git, -qa, -speed, -hardening). Their shared setup is scripts/web-console-test-helpers.mjs: importing it gives the file its own console home (so workspaces.json, subagents.json, looks.json and sessions never collide across files) and registers the stop --all cleanup. -session and -lifecycle each run an ordered chain of tests on one session of their own; everything else opens a session per test. A new test goes in the file for its area, after the tests it depends on. 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/: a page module needs SERVABLE in static.mjs and a <link rel="modulepreload"> in index.html. The set is hardcoded rather than a directory lookup so there is nothing to traverse; a module missing from it 404s and the page dies at import with no useful error (the import-fetch 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. A screen goes in public/screens/, imports only state.js and the pure modules (never another screen), and is imported by screens/core.js; the import guard in scripts/test-web-console-shape.mjs fails naming a screen that breaks either rule. A stylesheet goes in public/styles/ and on CSS_ORDER in static.mjs, never on SERVABLE; the joined-stylesheet test fails when the folder and the list disagree. Every new file also needs its row in the files table above, which the docs-table test (same file) checks.

Status Line

Optional Claude Code status bar living in src/statusline-claude/. Three-line bar beside a Planny icon: two content lines with a dashed rule between, showing model (+ effort), project/worktree, branch, uncommitted diff stats, session duration + cost, context window usage, and plan/quota usage.

Design constraints:

  • Zero runtime dependencies — statusline.js is self-contained (config loader, git helpers, formatters, render). Copied verbatim to ~/.claude/plan2code-statusline.js on install; no bundler step.
  • Stdin-driven — all data comes from Claude Code's stdin JSON (model, workspace, context_window, rate_limits, cost). No API calls, no auth, no background processes.
  • Silent failure — outer try/catch around main() plus process.exit(0) on missing stdin guarantees the script never crashes the CLI. All git ops are timeout-bounded (1.5s) and non-git workspaces short-circuit via isGitRepo() (walks up to 10 parent dirs looking for .git).
  • Atomic settings writes — installer writes ~/.claude/settings.json via temp file + rename so a crash never leaves the file truncated.
  • Custom-config respect — installer detects non-plan2code statusLine entries, prompts before replacing, and backs up to statusline-previous.json. Uninstall only removes settings.statusLine if it points to the plan2code bundle.

Layout:

src/statusline-claude/
├── statusline.js           # Self-contained: config, git, formatters, render
├── statusline-config.json  # Default config template
└── README.md               # User docs: install, config, debugging

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 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 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 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 that CLI's own steps after its error (its install command, cd into the project, then plan2code --cli <id> or its prompt). --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= (or, for Codex, -m), it asks Which model should <CLI> use? from models.json plus the user's additions, Enter keeping the model the CLI last used — 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. plan2code update is the one subcommand: it is never forwarded and opens no agent, it runs npx --yes --allow-git=all git+https://github.com/jparkerweb/plan2code.git --update, so install.js --update reinstalls what ~/.plan2code/install.json lists. On every other start, before spawning the CLI, it prints one line when a newer release is out (Plan2Code v<latest> is out (you have v<installed>). Run: plan2code update), compared against ~/.plan2code/bin/version.json and read from the console's cached release check (~/.plan2code/console/update-check.json); it never waits on the network, and when the cache is missing or stale it refreshes it in a detached background process so the next start knows. Tests: scripts/test-launcher.mjs (run by npm test) spawns the launcher against stand-in claude/devin/codex 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. Beside it go update-check.mjs (the web console's release check, for the terminal notice) and a version.json (the installed version). (The loop/metrics/bot wrappers point into __dirname and don't have this protection.)
  • npm-style shims — written into npm's global bin (npm config get prefix; <prefix>/bin off Windows): an sh shim everywhere, plus .cmd and .ps1 on Windows, so cmd.exe, PowerShell and Git Bash all resolve it. On macOS/Linux, when the npm bin isn't writable (system Node), it falls back to ~/.local/bin.
  • Marker-based ownership — every shim contains plan2code-launcher; uninstallLauncher() removes only files carrying it, leaving any other plan2code bin alone.
  • Resolving the CLI — the launcher walks PATH (+ PATHEXT on Windows) itself. An .exe is spawned directly; a .cmd/.bat wrapper goes through cmd.exe /d /s /c with quoted args, since Node refuses to spawn batch files without a shell. The installer warns only when neither claude nor devin is on PATH.
  • No bin-name overlap — the installer's own bin in package.json is plan2code-install (→ install.js), so plan2code belongs to the launcher alone. npx runs a package's only bin whatever it's named, so the README's npx … plan2code.git command is unaffected; keep it the only bin, or npx will need -c plan2code-install.
  • --pick-folder is shortcut-only — the launcher strips it before building the CLI's args. The shortcut runs the CLI menu, then the folder picker, then the model menu. With it, a native folder picker chooses the cwd instead: on Windows, the Explorer-style IFileOpenDialog (FOS_PICKFOLDERS) via powershell -STA -EncodedCommand, its C# interop (WINDOWS_PICKER_SOURCE) passed in an env var and compiled with Add-Type (~0.5s), with a TopMost owner form so it doesn't open behind the console — Windows PowerShell's FolderBrowserDialog is the old tree-only dialog, and is kept only as the fallback when Add-Type is blocked (Constrained Language Mode, AppLocker); osascript choose folder on macOS, and zenity then kdialog on Linux (only when DISPLAY/WAYLAND_DISPLAY is set). If there's no picker, or the picker fails, it falls back to a typed Project folder [last]: prompt. A picker that exits 0/1 with nothing printed means the person canceled, so the launcher exits 0. The picker starts on the last pick, stored in ~/.plan2code/launcher.json. From the shortcut, a non-zero exit other than Ctrl+C (130 / 0xC000013A) waits for Enter so the error doesn't vanish with the window. Typed in a terminal, plan2code behaves exactly as before.

Desktop shortcut — after the shims are written, installLauncher() (now async) calls offerDesktopShortcut(). It asks Also add a Plan2Code shortcut to your desktop? (y/N), skips the question when stdin isn't a TTY, and refreshes an existing marked shortcut without asking. installDesktopShortcut() writes it to the real desktop ([Environment]::GetFolderPath('Desktop') on Windows, which covers OneDrive redirection; xdg-user-dir DESKTOP on Linux; ~/Desktop otherwise):

OS File Runs
Windows Plan2Code.lnk (written by WScript.Shell) pwsh.exe (else Windows PowerShell) -NoLogo -ExecutionPolicy Bypass -File "<bin>\plan2code.ps1" --pick-folder, icon src/launcher/plan2code.ico (the web console's Peek-a-boo favicon, 16–256 px) copied to ~/.plan2code/bin/plan2code.ico
macOS Plan2Code.command (0755) exec "<bin>/plan2code" --pick-folder in Terminal
Linux plan2code.desktop (0755, Terminal=true, gio … metadata::trusted) "<bin>/plan2code" --pick-folder, Icon= the web console's favicon.png copied to ~/.plan2code/bin/plan2code.png

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 I and Advanced → E get it), U removes it, and Advanced → D installs it alone. Every global install writes ~/.plan2code/install.json, the install record listing the pieces installed (skills, launcher, statusline, loop, metrics, bot); install.js --update (what plan2code update runs) reinstalls exactly those, with no menu and never uninstalling, or with no record the skills and the plan2code command. 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.