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

17 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, deps 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, deps 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, deps 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, deps 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
deps.mjs (own) deps One file in fixed sections, one adapter per ecosystem behind one interface (npm, pnpm and Yarn; Cargo; pip; uv; Go; .NET): detect (lockfiles, members, missing tools, the run folder under the OS temp folder), scan (rows, held, notScanned, stillOpen; a declared runtime it cannot cut by sets runtimeNotChecked; a missing or failed audit sets notAudited), notes (release-note slices via gh api or fetch), fit (the newest version the project's runtime runs, per adapter; a runtime hold with one becomes a pick, unknown rows go to the agent), pins (each row's exact version written in the project's own files, outside its lockfile and manifests: pins.json), label (the pure FR-6 to FR-9 rules: Safe, Check first, Warning; reasons plus reasonsPlain in plain English; a row with a pin is never Safe; a record's usedIn lists the files that import the package), checks (the checks for the baseline, or one group's targeted checks narrowed by usedIn and pins), baseline and compare (read run-check.mjs --log logs, never run checks: tests red before or flaky never blame a group), batches (--picks, --split narrowing), backup, apply (the package manager's own update; failed also on unpicked, overshot past a runtime-cut target, undoFailed or needsNewerRuntime), fix (one approved replacement in one project file after apply: never a lockfile or manifest of the batch, never under node_modules, .git or specs, never binary or over 1 MB, the text found exactly once; the file is backed up into the batch's backup first, so restore puts it back), restore --verify (byte for byte, fixed files included and named in fixed[]; a file it cannot put back is mismatched {path, reason} with verified: false, never a crash), install-tool (the exact install line of a scanner the scan listed missing; runs nothing, the prompt runs it through run-check.mjs after approval), handoff (specs/<package>-upgrade/UPGRADE-<date>.md, never outside specs/) and cleanup. Never runs --force, an audit fix or a tool install. Writes manifests and lockfiles only through apply and restore, any other project file only through fix after the person approved that exact change, and a ticked brief. Tests: scripts/test-script-deps.mjs against stub CLIs on a temp PATH and fixtures in scripts/fixtures/deps/ named with each tool's version
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
lessons.mjs dashboard, pathfinder, plan, revise-plan, document, implement(-review), review, finalize, quick-task, xray, diagnose, pr-prep, test, dead-code, ui-prototype Learning's one script. Every answer carries state (not-set-up, off, on, paused, unknown) and active, decided only by learningState() in the bundled web-console/learning.mjs, which it loads at run time through consoleModule("learning.mjs") (exit 3 no-console without it), so the dashboard and the skills never disagree. state (the state, since when Paused for you, the waiting count, whether AGENTS.md exists, whether on the default branch) / switch on|off (the team switch) / pause on|off (Paused for you, refused unless On) / read (the lessons for the named paths and the branch's changed files, marked when their About files changed since, with a run handle so a later read hands over only new areas) / note (a lesson, an area, a doubt or an AGENTS.md fix, checked, then held as waiting; nothing while Off or Paused for you; a secret exits 5) / check (the secret refusal and the email, handle and person-name flags; reads only) / list (the approval list of everything waiting, new failure log lines, the first-ask card) / decide (applies the person's choices, or --first-ask yes|no; a test map row fix carries row on its list item and is reworded with row or with after as its one table line, read back by rowFromLine() in test-map.mjs, and every row is validated and secret-checked again at Apply) / log-lines (failure log lines added since Learning was first switched on) / areas --suggest (first areas from the test map) / report (lessons per area, the oldest, marked and gone ones) / remove --confirm (deletes every saved lesson). Writes only the project's .plan2code/settings.json and .plan2code/lessons/<area>.md, the pointer line and upkeep sentence in the project's AGENTS.md, its failure log lines (moved into lessons, marked (kept in the log), or added on a first-ask no), accepted fixes to AGENTS.md or an .agents-docs/ file, and, through the core, the pause and the waiting lessons on this machine only, in ~/.plan2code/learning/<repository key>/. Never stages or commits
changes.mjs implement, implement-review, quick-task The sign-off page's Changes tab. start --session <folder> snapshots the working tree (tracked, modified and new files, never ignored ones) into a git tree object through a temporary index and git write-tree, so the real index, HEAD, branches and working tree stay as they were, and writes the tree id to <session>/changes-start.json; a rerun replaces it. diff --session <folder> [--cap 524288] snapshots the tree now, compares it with the start tree and writes <session>/changes.diff (unified, git diff --no-color -M headers; over the cap it is cut at a file boundary with a notice, every file still named; a file that may hold a secret keeps its name and counts, its lines hidden; the counts of hidden and cut files travel as # counts: <added> <removed> <path> trailer lines (tab separated fields) that the page applies to files with no lines of their own), printing { ok, files, added, removed, truncated, hidden, file }. Exit 3 for no repository, no snapshot or a snapshot git no longer has, 4 when git cannot snapshot. Work done before start never shows, and nothing has to be committed. The notes for Implement and Quick Task (notes/implement.md, notes/quick-task.md) say when to run each; the page draws the result as a diff doc block

Shared reference for lessons.mjs: src/shared-references/lessons.md ships as references/lessons.md (through additionalReferences) to the same fifteen skills and the dashboard. It is the prose half of Learning: the fixed words (Learning, lesson, waiting; Not set up, Off, On, Paused for you), when a skill runs each command (Start, While working, End, unattended runs, Learning off), and that a failed call means one "Lessons could not be read this run." and carrying on without lessons.

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, test-script-lessons.mjs, test-script-deps.mjs, test-script-changes.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/.