10 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
# Full check (about 70s): char limits, skills/ build, browser-module parse check,
# dashboard skill-table check, web console + launcher + getting-started node:test suites
npm test
# 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 Loop
cd plan2code-loop && npm install # First time setup
cd plan2code-loop && npm run build # Build the CLI
# 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)
# Plan2Code Bot (end-to-end workflow runner, Claude Agent SDK)
cd plan2code-bot && npm install && npm run build
cd plan2code-bot && npm test # vitest
The root npm test does not run the metrics or bot vitest suites; run them in their package. npm run dev in loop, 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.
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 cancelled). |
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-loop + plan2code-metrics + plan2code-bot + Claude Code status line (confirmation required) |
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 |
O |
Install plan2code-loop CLI only |
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-loop, 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, statusline, loop, metrics, bot), never uninstalling; with no record, the skills and the plan2code command. plan2code update 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 --version. - 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 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/ plus a copy of 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 (a short list;
npm testnames anything missed):src/web-console/public/skills.js: one entry (workflow, label, start pose, flags, subagents line) with its card, and the card'sstatesandgreyed. Utilities go in group"extra"before Changelog.src/web-console/public/meter.js: aWEIGHTSentry if its launch scores.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).- 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) and theconsole.mjsusage text.- 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.md(prompt table, own-script rows, 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.