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

10 KiB

Architecture: skill scripts

Part of AGENTS.md and the Architecture index: project guidance for AI coding agents.

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, diagnose, dead-code list / status (the dashboard state, Phase Checklist, groups, task markers, numbering, the implement selection verdict, consistency checks) / check / check-draft / metrics / mark / tick / archive. list imports scanProject() from the bundled web-console/scan.mjs, and status calls deriveSpecState() and pickPhaseFiles() from web-console/spec-files.mjs, the one rule the scan also uses, so the dashboard and the skills never disagree on a spec's state (a phase with only blocked tasks left stays building, and finalizeReady lights Finalize once each has a written reason). mark writes the phase file's Status line on every move (--to in-progress too). check's format rules (no Status line, a checkbox under Notes, a task pointing at a line number, a bare [!]) warn, and fail only a spec whose overview.md carries <!-- plan2code-format: 2 -->. archive that has to copy removes the source only once every file name and size at the target matches (PLAN2CODE_ARCHIVE_FAULT is its test seam)
commit-msg.mjs implement(-review), review, quick-task, finalize, init-update, git, dead-code The <subject> / AI Assisted commit command (two -m flags), with an optional git add -- <files> from --files. There is no add-everything option: --add-all was retired, and scripts/test-script-git.mjs fails if it returns anywhere in src/
review-scope.mjs review, implement(-review), quick-task, finalize, pr-prep, test, dead-code Review Mode's git fallback: files, lines, doc share, base branch
glob.mjs init, init-update, implement(-review), quick-task, finalize, pr-prep, test, dead-code The glob subset (**, *, ?, {a,b}) as a RegExp, and forward-slash path normalizing; imported by test-map.mjs and test-match.mjs
test-map.mjs init, init-update, implement(-review), quick-task, finalize, pr-prep, test, dead-code read / write the project test map (one | Area | Paths | Run | Shared | table under ## Test map in AGENTS.md, or behind one link to .agents-docs/); every line outside the table stays byte-identical
test-match.mjs implement(-review), quick-task, finalize, pr-prep, test covers (changed files to the map rows and tests that cover them, plus shared-ground hints), gaps (source files no test covers, ranked by recent change) and nearest (existing tests to read for style)
test-commands.mjs init, init-update, pr-prep, test, dead-code discover: the whole-suite command, per-folder runners, lint/types/build checks, coverage commands already present and the language's built-in runner, from config files only
run-check.mjs implement(-review), quick-task, finalize, pr-prep, test, dead-code Run one command with a timeout, kill its process tree on timeout, and classify it passed, failed, timeout or not-started with the output's tail
pr-prep.mjs (own) pr-prep template (the PR template and its headings), pr-url (the create-a-PR link through git-repo.mjs) and spec (the branch's spec folder for the save offer). Read-only
coverage.mjs (own) test read --lcov / --go-func: coverage output as per-file lines, hits and percent, plus the total. Read-only, runs no tool
dead-code.mjs (own) dead-code detect (the dead-code tools the project already has, languages, file counts), run --tool (a tool's output as candidates), narrow (folders ranked by candidates), keep list|filter|add|remove (the shared keep list, .plan2code-dead-code/keep.md; rows matched by file, name and the hash of the item's declaration line, #n for the n-th identical line, file: for a whole file; remove takes --hash or --line and exits 2 ambiguous-entry when two rows share a name), backup and restore --verify (copies outside the project and a checked put-back), report write (.plan2code-dead-code/reports/DEAD-CODE-<date>.md; tool one id or a list of ids) and gitignore-check / gitignore-add. Writes only code removals the agent makes, keep.md and, on a yes, a report and the .gitignore line
agents-md.mjs init, init-update AGENTS.md structure, budget, orphans, broken links, always-inline sections. With no AGENTS.md yet (Init's run, so said once), notices warns when .gitignore keeps specs--completed/ out of git, since archived specs are then not backed up
agent-files.mjs init, init-update Detect and replace other agents' config files with AGENTS.md pointers
pathfinder.mjs (own) 0-pathfinder init (the map in its Step 5 state from --destination, --scores and --fog; refuses an existing map) and add (the next questions/NN-<slug>.md plus its map row), with the references' templates kept as the fallback, then reconcile, frontier, claim, resolve, rule-out, trail, gate (which also prints the exact PLAN-DRAFT status line specs.mjs reads), lint, brief-data. Writes rows as [Name](link): tail with no em dash, and still reads maps written the old way
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
ui-prototype.mjs (shared, with ui-prototype-round.mjs, ui-prototype-page.mjs, ui-prototype-drafts.mjs, ui-prototype-block.mjs) ui-prototype, pathfinder, plan, revise-plan, quick-task (ride-along) sweep (drafts older than 30 days), new-round, assemble (the page from round.json, the variant files and the shell in references/ui-prototype-shell/, images and fonts embedded; exit 4 round-mismatch when a drafts round's round.json names another name or round than its folder), check (the contract's rules, the three image rules image-type, image-size and image-missing, and the size ceiling), open (the default browser), read-block (a pasted choice block from stdin into fields) and save (the pair specs/<spec>/prototypes/<name>.html and .md, then that prototype's drafts removed). Writes only under ~/.plan2code/prototypes/<project key>/ and, on save, the spec's prototypes/; never writes project code, never opens a page outside the drafts or specs/, never fetches anything over the network. The helper modules are imported only by ui-prototype.mjs

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, and the newer shared scripts: test-script-test-map.mjs, test-script-test-match.mjs, test-script-test-commands.mjs, test-script-run-check.mjs, test-script-pr-prep.mjs, test-script-coverage.mjs), 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/.