17 KiB
Development Commands
Part of AGENTS.md — project guidance for AI coding agents.
Common Commands
# Install dev dependencies (sets up husky pre-commit hooks only; each sub-package
# below needs its own npm install. Running `npm test` needs Node 20+; users of
# the installed skills still need only Node 18+)
npm install
# Run the interactive installer
node install.js
# Regenerate skills/ from src/ (non-interactive)
npm run build:skills
# Try the Activities games from src/: opens the console in the browser, served
# fresh from disk, so a saved game file shows on the next page reload
npm run play
# Fast lane (about 2 minutes on a 24-core machine, measured outside the desktop app):
# the files listed under "fast" in scripts/test-lanes.json, none of which start a
# console server, run a console page suite or play a game (test-app-meter.mjs opens one
# static page in a browser and skips when none is installed). CI runs it on Ubuntu for
# every pull request, and on all three systems for a push to main or a pull request
# labeled `full-matrix`.
npm run test:fast
# Full check (takes minutes; every page suite drives a browser): list check, char limits,
# skills/ build, browser-module parse check, dashboard skill-table check, web console +
# launcher + getting-started node:test suites
npm test
# Put every text file git sees back to LF (also runs by itself as pretest and in
# the pre-commit hook); --check only lists
npm run fix:eol
# One web console or launcher test
node --test --test-name-pattern "<regex>" scripts/test-web-console-<area>.mjs
# Web console start-up benchmark (the paint columns use a local Chrome or Edge through
# playwright-core, which `npm install` already provides)
node scripts/bench-web-console.mjs [--runs 7] [--workflow dashboard]
# Refresh the web console screenshots in docs/screenshots/ (needs a local Chrome or Edge).
# Rerun after any change a person would see on the console page, and open every image
# before committing: right screen, both themes, no username or home path in frame.
# PLAN2CODE_TEST_BROWSER=chrome|msedge forces which browser the page tests and these scripts use
node scripts/capture-screenshots.mjs # every screen
node scripts/capture-screenshots.mjs --only dashboard # one screen (dashboard-utilities scrolls to the utility cards)
# Compare every element's computed style on every screen before and after a stylesheet change
# (dev-only, not in npm test): take a baseline first, then compare after each move
node scripts/css-snapshot.mjs --out before.json
node scripts/css-snapshot.mjs --compare before.json
# Plan2Code Metrics
cd plan2code-metrics && npm install # First time setup
cd plan2code-metrics && npm run build # Build the CLI
cd plan2code-metrics && npm test # vitest (aggregator, community, improver)
# Desktop app (plan2code-app/, Rust + Tauri). CI's `app` workflow runs all three on Ubuntu
# for every pull request and push to main, and on Windows and macOS too for a manual run or a
# pull request labeled `full-matrix`. It fails on any rustfmt difference or clippy warning, so run
# them before pushing, not only cargo test (see plan2code-app/README.md "Tests").
# First time: rustup component add rustfmt clippy (for the toolchain in rust-toolchain.toml)
cd plan2code-app && node scripts/vendor.mjs && cargo fmt --check
cd plan2code-app && cargo clippy --workspace --all-targets -- -D warnings
cd plan2code-app && cargo test --workspace
# Plan2Code Bot (end-to-end workflow runner, Claude Agent SDK)
cd plan2code-bot && npm install && npm run build
cd plan2code-bot && npm test # vitest
Targeted tests first
The full npm test takes minutes and drives a browser per page suite. When a change stays inside one part of the project, run that part's suites instead (with the PLAN2CODE_* app variables unset, as for npm test), and leave the full run for when a change reaches shared code.
The fast lane is npm run test:fast (scripts/test-fast.mjs): it runs the files in scripts/test-lanes.json's fast array through node-test.mjs. Two-list rule: every scripts/test-*.mjs is named in exactly one of fast and skipFast. A new test file that starts a console server, runs a console page suite or plays a game goes in skipFast; anything else goes in fast. node scripts/check-test-lanes.mjs fails (and runs first in npm test) when a file is in neither list, in both, or named but missing. test-fast.mjs itself is a runner and sits in skipFast. .github/workflows/fast-tests.yml runs the lane on Ubuntu for every pull request, and on all three systems for pushes to main and pull requests labeled full-matrix.
The same areas as one-command rows live in the Test map, which PR Prep and Test read; keep both in step.
| What changed | Run |
|---|---|
An Activities game (public/activities/*), public/tones.js or public/music.js |
node --test scripts/test-web-console-tones.mjs scripts/test-web-console-activities.mjs, plus the game's own scripts/test-web-console-activities-<game>*.mjs when it has one; add test-web-console-page-activities.mjs when the Activities window or its switches changed |
A music prototype (prototypes/music/<game>/) |
node prototypes/music/check.cjs <game> (nothing in npm test reads prototypes/) |
| One web console area (server routes, chat, git board, workspace, notepad, Implementation Loop...) | that area's scripts/test-web-console-<area>.mjs (the loop's is test-web-console-loop.mjs), and its test-web-console-page-<area>.mjs when the page changed; node scripts/parse-check.mjs after editing any browser module under public/ |
The launcher (src/launcher/) |
node --test scripts/test-launcher.mjs |
| A skill's script | npm run build:skills, then node --test scripts/test-script-<skill>.mjs (and test-skill-scripts.mjs for the shared plumbing) |
Dead Code (src/plan2code-dead-code-scripts/, scripts/fixtures/dead-code/) |
npm run build:skills, then node scripts/node-test.mjs scripts/test-script-dead-code.mjs |
UI Prototype (src/skill-scripts/ui-prototype*.mjs, src/plan2code-ui-prototype-references/, scripts/fixtures/ui-prototype/) |
npm run build:skills, then node scripts/node-test.mjs scripts/test-script-ui-prototype.mjs scripts/test-ui-prototype-page.mjs |
A workflow prompt (src/plan2code-*.md) |
node scripts/validate-char-count.js and node scripts/check-skill-table.mjs |
| A new skill or console workflow | First update the hand-written tables that list every workflow: the SUBAGENT_WORKFLOWS count and the meter's WEIGHTS, LAUNCH_LABELS and RUN_LABELS in test-web-console-logic.mjs, notesFor in test-web-console-speed.mjs, the event list in src/web-console/console-meter.md (checked by test-web-console-chat-stress.mjs) and a BUDGETS.notes entry in test-console-wire-budgets.mjs. Then run those four suites plus test-web-console-skills.mjs and test-web-console-spec-states.mjs; the PR Prep and Test build missed all five tables and only the full suite caught them |
| Docs or comments only | node --test scripts/test-us-english.mjs scripts/test-line-endings.mjs |
Run the full npm test when the change touches something many suites lean on: web-console-test-helpers.mjs or page-test-helpers.mjs, looks.js / prefs.js / static.mjs (the SERVABLE list), skills.js, install.js, the server's shared modules (console.mjs, routes.mjs); after a sync merge or a version bump; before opening a PR or cutting a release; and whenever you cannot say which suites a change reaches.
The root npm test does not run the metrics or bot vitest suites; run them in their package. npm run dev in metrics and bot is tsup --watch. The web console and launcher suites isolate themselves with PLAN2CODE_CONSOLE_HOME, PLAN2CODE_MODELS_DIR and PLAN2CODE_NO_BROWSER=1 (scripts/web-console-test-helpers.mjs), so they never open a browser or touch your real console home. The web console suites are split by area so node --test runs them in parallel. npm test runs them through scripts/node-test.mjs, which caps the files run at once at one per spare core (8 at most): each page test file drives a browser, and more at once than the cores can carry fails page tests at random (a flat 8 did on 3 and 4 core CI runners). Page tests (test-web-console-page-*.mjs) read styles and set scrolls only through styleOf(), stylesOf() and scrollCard() from page-test-helpers.mjs, which retry until the element is still on the page; test-web-console-shape.mjs fails a raw locator.evaluate that does either.
Test/Dev Env Vars
| Variable | Effect |
|---|---|
PLAN2CODE_CONSOLE_HOME |
Replaces ~/.plan2code/console: sessions, looks.json and the runtime handle dir all move under it (src/web-console/files.mjs). Always set it for scratch runs so stop --all cannot reach real sessions. |
PLAN2CODE_NO_BROWSER |
open does not launch a browser (NO_BROWSER also works). |
PLAN2CODE_BROWSER |
Browser command line to run with the link appended, instead of the system default. |
PLAN2CODE_MODELS_DIR |
Moves the launcher model menus (bin/models.json, models.json) away from ~/.plan2code, for tests. |
PLAN2CODE_PICKER_ECHO |
Tests only: /workspace/browse returns this as the picked folder instead of opening a picker (- means canceled). |
PLAN2CODE_CONSOLE_DEV |
Set to 1 (by npm run play) and the server reads every page file from disk on each request instead of once, so a reload shows edits (src/web-console/static.mjs). |
PLAN2CODE_CONSOLE_TRACE |
Set to 1 on open to print a start-up step timeline to stderr. |
Installer Menu Options
Main menu:
| Option | Action |
|---|---|
I |
Install the Plan2Code skills globally via the skills CLI, plus the global plan2code command (opens the dashboard in Claude Code, Devin or Codex), then print the getting-started steps. No dev tools |
U |
Uninstall Plan2Code: skills + plan2code command + plan2code-metrics + plan2code-bot + Claude Code status line + desktop app (confirmation required; plan2code uninstall runs the same removal, see --uninstall below) |
A |
Open the ADVANCED sub-menu |
Q |
Quit |
ADVANCED sub-menu (A):
| Option | Action |
|---|---|
L |
Install the skills into the current project instead of globally |
M |
Install plan2code-metrics CLI only |
S |
Install Claude Code status line only |
B |
Install plan2code-bot CLI only |
D |
Install the global plan2code command only |
E |
Everything: the skills, the plan2code command and every dev tool (plan2code-bot, plan2code-metrics, the Claude Code status line) |
Q |
Return to main menu |
Non-Interactive Flags
install.js takes no arguments for normal use, but exposes two build hooks and the non-interactive update. Any argument other than these three (when none is present) exits 1 with usage; extra arguments beside --build-skills or --verify-skills are ignored, while --update must be the only argument.
| Flag | Action |
|---|---|
--build-skills |
Regenerate skills/ from src/, pruning stale skills and reference files |
--verify-skills |
Diff local skills/ against src/; exits 1 on drift. Diagnostic only, the installer rebuilds anyway |
--update |
No menu: reinstall what ~/.plan2code/install.json lists (skills, launcher, app, statusline; metrics and bot only when run from a git checkout, since they run from the install folder, which npx's cache is not), never uninstalling; with no record, the skills and the plan2code command. plan2code update runs it through npx |
--uninstall [--yes] [--purge] |
No menu: confirm y/N (--yes skips it), run uninstallAll() (the menu's U sequence: skills, dev tools, status line, plan2code command, desktop app), then ask whether to also delete ~/.plan2code (purgeData(); --purge says yes without asking, --yes alone keeps the data). plan2code uninstall [--yes] [--purge] runs it through npx |
How the Installer Works
- Builds
skills/fromsrc/— one Agent Skill per source prompt, including uncommitted source edits. - Checks the skills CLI is reachable with
npx --yes skills@1.7.6 --version(the version is pinned:SKILLS_CLI_VERSIONininstall.js). - Sweeps pre-2.2 install paths and removes installed
plan2code-*skills so renamed or retired prompts cannot survive as orphans. - Delegates installation to
npx --yes skills@1.7.6 add "<repo>/skills" -g -s <skill names> -y. - Installs the global
plan2codecommand (only when step 4 succeeded). Advanced →Lruns the same flow without-gand without the launcher.
The skills CLI owns distribution from step 4 onward. It stores canonical skills under ~/.agents/skills/ and links them into agents that maintain their own skill directory. Plan2Code no longer maintains platform-specific output formats.
Invocation choices:
| Choice | Reason |
|---|---|
Explicit space-separated -s <names> |
Avoids shell expansion and prevents unrelated directories under skills/ from being installed. |
No -a / --agent '*' |
Uses the CLI's supported default agent set instead of requesting incompatible scope/agent combinations. |
| Captured output | Suppresses the CLI's duplicated banners while preserving real failures; unsupported-scope noise is filtered. |
Skill Format
| Item | Value |
|---|---|
| Path | skills/<skill-name>/SKILL.md |
| Skill name | generateSkillName(prompt), such as plan2code-1-plan or plan2code-init |
| Frontmatter | name, description, disable-model-invocation: true |
| Reference files | skills/<skill-name>/references/<path>, copied from src/<prompt>-references/ and additionalReferences (any file type; every skill bundles web-console/, and a skill with scripts also gets scripts/version.json) |
| Scripts | skills/<skill-name>/scripts/<file>.mjs, plus common.mjs and a generated version.json (see Skill Scripts in the architecture doc) |
disable-model-invocation: true is unconditional because these workflows are user-initiated. Agents that do not recognize the field ignore it.
Editing Workflow Prompts
See the skills/ build-artifact gotcha in Code Style & Gotchas.
- Edit the source file under
src/. - Run
npm run build:skills. - Test the workflow in an AI tool.
skills/is gitignored, so only thesrc/change is committed.- Never edit
skills/by hand because the next build overwrites it.
Adding a New Workflow Prompt / Skill
-
Create
src/plan2code-<name>.mdwith body content only and keep it under 20,000 characters. -
Register it in
SOURCE_PROMPTSininstall.js(with the web-consoleadditionalReferencesentry every skill carries); add agenerateStepLabel()case when needed. List any shared scripts it runs inscripts: [...], and put its own scripts insrc/plan2code-<name>-scripts/(with ascripts/test-script-<name>.mjsadded topackage.json'stestlist). -
Register it with the web console. The meter's points and labels, the resume command, Help's card list and
console.mjs help's workflow list are all derived fromskills.js, so the edits areskills.js,install.js(step 2), the skill's prompt (step 1), its pose and its notes;npm testnames anything else left out:src/web-console/public/skills.js: one entry (workflow, label, start pose, flags, subagents line, the meter'sweight,startedandran, andresume) with its card (plushelpwhen Help's line should differ from the blurb), and the card'sstatesandgrayed. Utilities go in group"extra"before Changelog.src/web-console/public/index.html: its start pose, an<svg class="pose pose-<workflow>" data-pose="<workflow>">in<template id="start-poses">(pose CSS inpublic/styles/poses.css), unless itsposeborrows an existing one (as Implement + Review borrows Implement's).- Its help topic: a
src/web-console/notes/<workflow>.md(named in the skill's Interface line) or aHELP_TOPICSalias insrc/web-console/cmd-help.mjs. src/plan2code.md: the skill/workflow table and "What each skill reads and writes" (scripts/check-skill-table.mjs: every backticked token must appear in the skill's prompt).console.md(theopen --workflowlist and thenotes/<workflow>.mdrow).- Optional:
STARTER_SET_FORinpublic/starters.js(unlisted gets "general").
Adding a spec state is shorter: one entry in
src/web-console/public/spec-states.js, the detection inclassifySpec()insrc/web-console/scan.mjs, thestatesof each card inskills.jsthat takes it, and a line in the dashboard skill (src/plan2code.md); thennpm test. -
Update command inventories in
README.md(dashboard-card and command tables),QUICK-REFERENCE.md,.agents-docs/AGENTS-architecture-install.md(prompt table),.agents-docs/AGENTS-architecture-skill-scripts.md(own-script rows) and.agents-docs/AGENTS-architecture-console.md(notes list), andCHANGELOG.md. Updatedocs/index.htmlfor core pipeline steps, and for a utility only when it is a headline change (its.utilsblock). -
Run
npm run build:skillsandnpm test.