mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-17 04:45:33 -08:00
203 lines
17 KiB
Markdown
203 lines
17 KiB
Markdown
# Development Commands
|
|
> Part of [AGENTS.md](../AGENTS.md) — project guidance for AI coding agents.
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# 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](./AGENTS-test-map.md), 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](./AGENTS-code-style.md).
|
|
|
|
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`.
|