Files
plan2code/.agents-docs/AGENTS-code-style.md
T

9.7 KiB

Code Style & Gotchas

Part of AGENTS.md — project guidance for AI coding agents.

Code Style

  • install.js: CommonJS, Node.js built-ins only (no external deps), ANSI colors via COLORS constant, readline-based prompts
  • plan2code-loop & plan2code-metrics: TypeScript + ESM, built with tsup (target ES2022, moduleResolution: bundler)
    • External deps: @inquirer/prompts, chalk, execa, ora
    • Interactive CLI via @inquirer/prompts (select, input, confirm)
  • File operations: Synchronous fs in all packages
  • src/web-console: ESM, Node built-ins only, no build step. It is bundled into every skill, so it must stay dependency-free and runnable as a plain node console.mjs. Anything added under src/web-console/ ships to users — put tests in scripts/ instead.

Gotchas / Pitfalls

  • Version sync: When adding a new version to CHANGELOG.md, also update version.json and package.json (root) to match. Check README.md for any version badges or references that need updating. The installer displays the version from version.json in its header. All three files (CHANGELOG.md, version.json, package.json) must always show the same version number.
  • CHANGELOG ordering: Entries in CHANGELOG.md must be in reverse-chronological order — newest version at the top, oldest at the bottom. New entries are always inserted immediately after the file header.
  • CHANGELOG house format is not Keep a Changelog: version headings are ## vX.Y.Z — with a v prefix and no date. The release date is recorded only in version.json's releaseDate. Category headings carry emoji: ### ✨ Added, ### 🔧 Changed, ### 🐛 Fixed, ### 💥 Breaking, ### 🗑️ Removed, ### 📚 Documentation. Older entries contain one-off variants (🎁 Added, 📦 Updated, 📝 Documentation, 🏎️ Improved, 🧪 Testing) — do not introduce new ones. The .claude/skills/plan2code-changelog/ skill automates version selection and formatting; use it rather than hand-rolling an entry.
  • PowerShell mangles the CHANGELOG emoji: Get-Content / Select-String render the ### heading emoji as ? under the default Windows console encoding, so a heading audit done that way reports garbage. Read CHANGELOG.md with a file-read or grep tool instead.
  • .claude/skills/ is tracked, not ignored: repo-local skills (plan2code-changelog, plan2code-publish, sync-repo) live there and are committed. Nothing in .gitignore touches .claude/, so a new skill only needs git add. Per the Failure Log convention in AGENTS.md, a correction that is a workflow rather than a rule belongs here as a skill, linked from AGENTS.md — not as a Failure log line.
  • Loop .gitignore setup: ensureGitignore() runs at startup in Controller.run() as a pre-flight step, not just inside createTaskCommit(). This is critical for phase mode where the Node controller doesn't handle commits — without it, git add -A would stage spec files.
  • Workflow file character limit: All src/plan2code-*.md files must be ≤ 11,500 characters. A husky pre-commit hook enforces this, and plan2code-metrics (improver.ts, applier.ts) applies the same number to proposed prompt edits, so change them together. The limit predates v2.2.0's single-format build (it left buffer for the largest platform-specific YAML header to stay under Windsurf's 12,000 char limit) and is retained as a prompt-size discipline — the generated SKILL.md header is ~180 chars, so 11,500 still clears 12,000. It was raised from 11,000 in v2.4.0 so the web console's Interface lines could be added to Pathfinder and Planning without cutting any of their rules; when a prompt runs short of room, move detail into a reference file rather than compressing rules.
  • skills/ is a committed build artifact: edit src/, run npm run build:skills, and commit the regenerated skills in the same change. npm test runs install.js --verify-skills and fails on missing, unexpected, or stale files. Never edit skills/ by hand.
  • Metrics internal prompts have no char limit: Files in plan2code-metrics/src/prompts/ are NOT subject to the 11,500 char limit — only src/plan2code-*.md consumer-facing prompts are.
  • User Feedback table format: The ## User Feedback markdown table in overview.md has a strict format the collector regex depends on. Field names must be exactly Rating, Reason, Went Well, Went Poorly. Pipe characters in values must be escaped as \|.
  • PLAN-DRAFT confidence numbers are scraped by regex: when a specs/<feature>/PLAN-DRAFT-*.md contains no <!-- METRICS_JSON ... --> comment, collector.ts falls back to prose scraping (collector.ts:186-241). The overall-confidence pattern requires a literal %, but the four breakdown patterns (collector.ts:201-204) do not — /[Rr]equirements?[:\s|]+(\d{1,2})/ and its siblings match a bare dimension word followed by whitespace, a colon, or a pipe and then digits. So a PLAN-DRAFT written by anything other than /plan2code-1-plan Phase 7 must keep both the % sign and bare Requirements / Feasibility / Integration / Risk followed by a number off the page — including innocent table rows like | Requirements | 11 |. Otherwise the metrics pipeline records a planning-step confidence that no planning step produced. /plan2code-0-pathfinder works around this by hyphenating the labels (Requirements-clarity 22/25), which breaks the character class.
  • Web console result-handoff invariant: result.json holds answers a person pressed Send on. An uncollected result (no consumedAt) is never overwritten and never deleted. /submit and /cancel return 409 while one is pending, open clears the file only when it is already consumed, and wait stamps consumedAt after printing the result, never before, and exits by setting process.exitCode rather than calling process.exit(). That ordering is deliberate: an agent harness that kills a long shell command must not be able to land between "marked collected" and "handed over", and process.exit() can truncate an unflushed pipe. A repeat delivery is recoverable, a lost one is not. Two separate data-loss bugs came from breaking this in different places, and both were silent: the person sees "Sent", the agent never receives it. Any new code path that touches result.json must preserve the invariant, and scripts/test-web-console.mjs guards it. Related: the server writes each submitted answer onto its item as submitted, and validate() in lib.mjs must keep excluding that field from the completion-marker and metrics-scraper scans, which are meant for agent-authored text only. A person who typed TASK_COMPLETE into an answer would otherwise make every later patch unpostable.
  • Web console oversized bodies: readBody() in server.mjs calls req.destroy() past MAX_BODY, so an oversized JSON body gets no response at all: the client sees a connection reset, never a status code. A route that must answer 413 has to stop buffering and drain the rest of the body instead, as readRaw() (the POST /upload reader) does; memory still stays capped.
  • Web console commands are tied to the directory open ran in: console.mjs finds a running server through a handle file under a hash of the project directory (handleFile(project, sid) → runtimeDirFor(cwdHash(project)) in lib.mjs), and the project is the working directory of open / open --resume. Run status, chat, wait and stop from that same directory. From anywhere else status says live: false, chat / wait report server-gone (exit 20) and stop stops nothing, while the server is in fact still running. It is easy to mistake for a crash when a scratch session is opened from the repo and then driven from its session folder; check server.log and events.ndjson (a real exit writes an exit event or a stack) before chasing one.
  • Windows temp paths in web console tests: os.tmpdir() can be an 8.3 short path (C:\Users\JUSTIN~1.PAR\...), while server.mjs canonicalises its session dir with fs.realpathSync.native to the long form. Any test comparing a server-returned path (e.g. an upload's path) against the test's session must pass the test side through fs.realpathSync.native() first, and compare case-insensitively on Windows.
  • Web console assets require build and serving coverage: computeExpectedSkills() copies references as Buffers, so binary files are supported and the bundled MP3 chimes exercise that path. Any browser-served asset under src/web-console/public/ must also be added to the hardcoded SERVABLE allow-list in server.mjs and covered by a test; otherwise the generated skill contains it but the server returns 404. The vendored marked.esm.js sha256 is recorded in .readme/web-console.md.
  • Reference file sizing guideline: Files in src/plan2code-*-references/ directories target ~100-200 lines each (soft guideline; evaluate splitting above 300). They are NOT subject to the 11,500 character limit. The pre-commit hook (validate-char-count.js) only checks src/plan2code-*.md flat files — subdirectory contents are automatically excluded.
  • The splitting guideline has a hard ceiling — reference files cannot always be split: each new reference costs the orchestrator a Read references/<file>.md line plus its fallback blockquote (~150-200 chars), and orchestrators near the 11,500 limit have no room to spend. When a reference legitimately exceeds 300 lines (e.g. plan2code-0-pathfinder-references/chart.md), that is an accepted trade-off, not an oversight. (The second constraint here — that the flat-file Read path rewrite was non-recursive — went away in 2.1.0 along with the rewrite itself; references/ is now the real path on every agent, nested references included.)