# Architecture: skill scripts > Part of [AGENTS.md](../AGENTS.md) and the [Architecture index](./AGENTS-architecture.md): 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/.mjs` | `skills//scripts/.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/-scripts/.mjs` | `skills//scripts/.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//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 ``. `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 `` / `AI Assisted` commit command (two `-m` flags), with an optional `git add -- ` 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-.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/-upgrade/UPGRADE-.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-.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 ` (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//prototypes/.html` and `.md`, then that prototype's drafts removed). Writes only under `~/.plan2code/prototypes//` 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/.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//`. Never stages or commits | | `changes.mjs` | implement, implement-review, quick-task | The sign-off page's Changes tab. `start --session ` 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 `/changes-start.json`; a rerun replaces it. `diff --session [--cap 524288]` snapshots the tree now, compares it with the start tree and writes `/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: ` 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 "/.mjs"`, where `` is `scripts/` beside it. **Tests:** `scripts/test-skill-scripts.mjs` (installer plumbing and the shared scripts), `scripts/test-script-.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 `/.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/`.