Files
plan2code/.agents-docs/AGENTS-development-commands.md
T

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

  1. Builds skills/ from src/ — one Agent Skill per source prompt, including uncommitted source edits.
  2. Checks the skills CLI is reachable with npx --yes skills@1.7.6 --version (the version is pinned: SKILLS_CLI_VERSION in install.js).
  3. Sweeps pre-2.2 install paths and removes installed plan2code-* skills so renamed or retired prompts cannot survive as orphans.
  4. Delegates installation to npx --yes skills@1.7.6 add "<repo>/skills" -g -s <skill names> -y.
  5. Installs the global plan2code command (only when step 4 succeeded). Advanced → L runs the same flow without -g and without the launcher.

The skills CLI owns distribution from step 4 onward. It stores canonical skills under ~/.agents/skills/ and links them into agents that maintain their own skill directory. Plan2Code no longer maintains platform-specific output formats.

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.

  1. Edit the source file under src/.
  2. Run npm run build:skills.
  3. Test the workflow in an AI tool.
  4. skills/ is gitignored, so only the src/ change is committed.
  5. Never edit skills/ by hand because the next build overwrites it.

Adding a New Workflow Prompt / Skill

  1. Create src/plan2code-<name>.md with body content only and keep it under 20,000 characters.

  2. Register it in SOURCE_PROMPTS in install.js (with the web-console additionalReferences entry every skill carries); add a generateStepLabel() case when needed. List any shared scripts it runs in scripts: [...], and put its own scripts in src/plan2code-<name>-scripts/ (with a scripts/test-script-<name>.mjs added to package.json's test list).

  3. 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 from skills.js, so the edits are skills.js, install.js (step 2), the skill's prompt (step 1), its pose and its notes; npm test names anything else left out:

    • src/web-console/public/skills.js: one entry (workflow, label, start pose, flags, subagents line, the meter's weight, started and ran, and resume) with its card (plus help when Help's line should differ from the blurb), and the card's states and grayed. 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 in public/styles/poses.css), unless its pose borrows 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 a HELP_TOPICS alias in src/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 (the open --workflow list and the notes/<workflow>.md row).
    • Optional: STARTER_SET_FOR in public/starters.js (unlisted gets "general").

    Adding a spec state is shorter: one entry in src/web-console/public/spec-states.js, the detection in classifySpec() in src/web-console/scan.mjs, the states of each card in skills.js that takes it, and a line in the dashboard skill (src/plan2code.md); then npm test.

  4. 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), and CHANGELOG.md. Update docs/index.html for core pipeline steps, and for a utility only when it is a headline change (its .utils block).

  5. Run npm run build:skills and npm test.