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

14 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-metrics & plan2code-bot: TypeScript + ESM, built with tsup (target ES2022, moduleResolution: bundler)
    • External deps (metrics): @inquirer/prompts, chalk, execa, fs-extra, ora
    • External deps (bot): @anthropic-ai/claude-agent-sdk, chalk, fs-extra, ora
    • Interactive CLI via @inquirer/prompts (select, input, confirm)
  • File operations: Synchronous fs by default; the web console's fire-and-forget sweeps and readOverview() use fs.promises
  • 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.
  • US English everywhere: docs, comments, prompts, UI text, test names and commit messages use US spelling: color, gray, behavior, center, canceled, labeled, judgment, license, defense, and -ize / -yze verbs (normalize, analyze, summarize). scripts/test-us-english.mjs (in npm test) fails on common UK spellings in tracked files. A few names keep the UK spelling because they are data contracts read in several places, and that test allow-lists them: the greyed field on skills.js entries, { cancelled: true } from the folder picker and /workspace/browse, the "cancelled" event routes.mjs broadcasts. Rename one only together with every reader. aria-labelledby is HTML and stays; vendored files (public/vendor/) stay as shipped.

Gotchas / Pitfalls

  • Version sync: When adding a new version to CHANGELOG.md, run npm run set-version -- <x.y.z> (node scripts/set-version.mjs; with no version on a terminal it shows the current one and asks, Enter taking the next patch; the one writer of every carrier; it never edits the changelog), which updates version.json and package.json (root) to match. README.md (the Version X.Y.Z line near the top) also carries the version, and version.json's releaseDate moves with it. version.json is copied into every skill's references/web-console/ (the console's Help shows it), so after a bump run npm run build:skills or npm test (--verify-skills) fails. 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. The desktop app carries it too (under plan2code-app/: package.json, package-lock.json with two lines, src-tauri/tauri.conf.json, src-tauri/Cargo.toml, fake-agent/Cargo.toml, and Cargo.lock's plan2code-app and fake-agent entries): node scripts/check-versions.mjs [--tag vX.Y.Z] compares those, version.json, package.json, CHANGELOG.md and README's line (twelve places in all), npm test runs it first on this tree, and the release workflow runs it before building.
  • 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: a new repo-local skill only needs git add (see Architecture → Repo-Local Skills). A correction that is a workflow belongs there as a skill, linked from AGENTS.md, not as a Failure log line.
  • Workflow file character limit: All src/plan2code-*.md files (and the dashboard prompt src/plan2code.md) must be ≤ 20,000 characters (about 5k tokens, the usual Agent Skills guidance for a SKILL.md body). 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. History: 11,000 originally (headroom under Windsurf's old 12,000-char limit for platform-specific files, gone since 2.1.0's single-format build), 11,500 in 2.4.0, 20,000 in 2.4.1. The limit is now a prompt-size discipline only: the whole SKILL.md loads on every invocation while references load on demand, so situational detail still belongs in a reference file, and anything with one correct answer belongs in a script (see Skill scripts in the architecture doc).
  • Keep LF line endings: .gitattributes pins eol=lf because validate-char-count.js counts the characters on disk, and a CRLF checkout adds about one per line to every prompt. Measure with node scripts/validate-char-count.js before trusting a near-limit prompt. Git never writes CRLF here, but tools do (Python writing in text mode on Windows, some editors and generators), so scripts/fix-line-endings.mjs puts every text file git sees back to LF: npm run fix:eol by hand, --check to only list, and it runs by itself as npm's pretest, in the husky pre-commit before the char count, and after every Write or Edit through the PostToolUse hook in .claude/settings.json. In a Python script that writes repo files, open them with newline="\n" (or write bytes) anyway.
  • The pre-commit hook runs the LF fix, then the char-count check: .husky/pre-commit is node scripts/fix-line-endings.mjs followed by node scripts/validate-char-count.js. skills/ drift, parse errors and test failures are caught only by the tests, so run them before committing: the targeted suites for a change that stays in one area, the full npm test for shared code or before a PR (see "Targeted tests first" in Development Commands). Sub-package tests are separate; see Development Commands.
  • skills/ is generated build output (gitignored): edit src/ only. The installer rebuilds skills/ on every run, so it is always up to date at install time. npm test runs install.js --build-skills so a broken SOURCE_PROMPTS entry or unreadable source fails CI. Never hand-edit skills/; install.js --verify-skills can diff a stale tree against src/ when diagnosing.
  • Metrics internal prompts have no char limit: Files in plan2code-metrics/src/prompts/ are NOT subject to the 20,000 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 are matched case-insensitively; the house form is Rating, Reason, Went Well, Went Poorly, and Rating must parse to an integer from 1 to 10. Pipe characters in values must be escaped as \|.
  • PLAN-DRAFT confidence numbers are scraped by regex: collector.ts scrapes the latest specs/<feature>/PLAN-DRAFT-*.md prose. Overall confidence falls back to prose only when <!-- METRICS_JSON ... --> lacks confidence (collector.ts:186-196): Confidence: 95%, or a table row | Confidence | 95 with no %. The four breakdown patterns (collector.ts:200-203) run on every draft, METRICS_JSON or 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 Confidence followed by a number (with %, or as a table row) 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-lifecycle.mjs guards it (its "result handoff (regressions)" tests). Related: the server writes each submitted answer onto its item as submitted, and validate() in patches.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() and readRaw() (the POST /upload reader) in routes.mjs drain the rest of the body past MAX_BODY instead of calling req.destroy(), so an oversized body gets a 413 rather than a connection reset, and memory still stays capped. A new body reader must drain the same way.
  • 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(project) → <RUNTIME_DIR>/<cwdHash(project)>/<sid>.json in sessions.mjs, with RUNTIME_DIR = os.tmpdir()/plan2code-console (-<uid> on Linux and macOS, a 0700 folder with 0600 handles), or $PLAN2CODE_CONSOLE_HOME/runtime), 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 canonicalizes 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: computeExpectedSkills() copies references as Buffers, so binary files are fine. Adding a public/ file needs the three edits in Architecture → Web Console. The vendored marked.esm.js sha256 is in .readme/web-console.md.
  • The default highlight color lives in two places: changing it means editing DEFAULT_ACCENT in public/palette.js and the light, system-dark and explicit-dark --accent* values in public/styles/tokens.css. No test ties them together.
  • 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 20,000 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), which adds up across a prompt's 20,000-char budget. When a reference legitimately exceeds 300 lines (e.g. plan2code-0-pathfinder-references/chart.md), that is an accepted trade-off, not an oversight. Nested folders under -references/ work: references/ is the real path on every agent.
  • Windows global bins for metrics and bot are wrappers, not npm link: on win32 the installer writes <name>.cmd and <name>.ps1 into npm config get prefix, each running node <package>/dist/bin/<name>.js (the metrics and bot installers both do this). After a source change, npm run build in the package is enough; no reinstall.
  • plan2code-metrics only runs from a repo checkout: analyzer.ts and improver.ts load src/prompts/analyze.md / improve.md at runtime through new URL('../src/prompts/...', import.meta.url), resolved relative to dist/ (analyzer.ts:11, improver.ts:13). A packed or copied dist/ without src/prompts/ fails.