mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-16 04:45:33 -08:00
13 KiB
13 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
COLORSconstant, 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)
- External deps (metrics):
- File operations: Synchronous fs by default; the web console's fire-and-forget sweeps and
readOverview()usefs.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 undersrc/web-console/ships to users — put tests inscripts/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(innpm 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: thegreyedfield onskills.jsentries,{ cancelled: true }from the folder picker and/workspace/browse, the"cancelled"eventroutes.mjsbroadcasts. Rename one only together with every reader.aria-labelledbyis HTML and stays; vendored files (public/vendor/) stay as shipped.
Gotchas / Pitfalls
- Version sync: When adding a new version to
CHANGELOG.md, runnode scripts/set-version.mjs <x.y.z>(the one writer of every carrier; it never edits the changelog), which updatesversion.jsonandpackage.json(root) to match.README.md(theVersion X.Y.Zline near the top) also carries the version, andversion.json'sreleaseDatemoves with it.version.jsonis copied into every skill'sreferences/web-console/(the console's Help shows it), so after a bump runnpm run build:skillsornpm test(--verify-skills) fails. The installer displays the version fromversion.jsonin its header. All three files (CHANGELOG.md,version.json,package.json) must always show the same version number. The desktop app carries it too (underplan2code-app/:package.json,package-lock.jsonwith two lines,src-tauri/tauri.conf.json,src-tauri/Cargo.toml,fake-agent/Cargo.toml, andCargo.lock'splan2code-appandfake-agententries):node scripts/check-versions.mjs [--tag vX.Y.Z]compares those,version.json,package.json,CHANGELOG.mdand README's line (twelve places in all),npm testruns it first on this tree, and the release workflow runs it before building. - CHANGELOG ordering: Entries in
CHANGELOG.mdmust 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 avprefix and no date. The release date is recorded only inversion.json'sreleaseDate. 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-Stringrender the###heading emoji as?under the default Windows console encoding, so a heading audit done that way reports garbage. ReadCHANGELOG.mdwith a file-read or grep tool instead. .claude/skills/is tracked: a new repo-local skill only needsgit 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-*.mdfiles (and the dashboard promptsrc/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, andplan2code-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:
.gitattributespinseol=lfbecausevalidate-char-count.jscounts the characters on disk, and a CRLF checkout adds about one per line to every prompt. Measure withnode scripts/validate-char-count.jsbefore trusting a near-limit prompt. Git never writes CRLF here, but tools do (Python writing in text mode on Windows, some editors and generators), soscripts/fix-line-endings.mjsputs every text file git sees back to LF:npm run fix:eolby hand,--checkto only list, and it runs by itself as npm'spretest, 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 withnewline="\n"(or write bytes) anyway. - The pre-commit hook runs the LF fix, then the char-count check:
.husky/pre-commitisnode scripts/fix-line-endings.mjsfollowed bynode 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 fullnpm testfor 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): editsrc/only. The installer rebuildsskills/on every run, so it is always up to date at install time.npm testrunsinstall.js --build-skillsso a brokenSOURCE_PROMPTSentry or unreadable source fails CI. Never hand-editskills/;install.js --verify-skillscan diff a stale tree againstsrc/when diagnosing.- Metrics internal prompts have no char limit: Files in
plan2code-metrics/src/prompts/are NOT subject to the 20,000 char limit — onlysrc/plan2code-*.mdconsumer-facing prompts are. - User Feedback table format: The
## User Feedbackmarkdown table inoverview.mdhas a strict format the collector regex depends on. Field names are matched case-insensitively; the house form isRating,Reason,Went Well,Went Poorly, andRatingmust 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.tsscrapes the latestspecs/<feature>/PLAN-DRAFT-*.mdprose. Overall confidence falls back to prose only when<!-- METRICS_JSON ... -->lacksconfidence(collector.ts:186-196):Confidence: 95%, or a table row| Confidence | 95with 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-planPhase 7 must keepConfidencefollowed by a number (with%, or as a table row) and bareRequirements/Feasibility/Integration/Riskfollowed 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-pathfinderworks around this by hyphenating the labels (Requirements-clarity 22/25), which breaks the character class. - Web console result-handoff invariant:
result.jsonholds answers a person pressed Send on. An uncollected result (noconsumedAt) is never overwritten and never deleted./submitand/cancelreturn 409 while one is pending,openclears the file only when it is already consumed, andwaitstampsconsumedAtafter printing the result, never before, and exits by settingprocess.exitCoderather than callingprocess.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", andprocess.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 touchesresult.jsonmust preserve the invariant, andscripts/test-web-console-lifecycle.mjsguards it (its "result handoff (regressions)" tests). Related: the server writes each submitted answer onto its item assubmitted, andvalidate()inpatches.mjsmust keep excluding that field from the completion-marker and metrics-scraper scans, which are meant for agent-authored text only. A person who typedTASK_COMPLETEinto an answer would otherwise make every later patch unpostable. - Web console oversized bodies:
readBody()andreadRaw()(thePOST /uploadreader) inroutes.mjsdrain the rest of the body pastMAX_BODYinstead of callingreq.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
openran in:console.mjsfinds a running server through a handle file under a hash of the project directory (handleFile(project, sid)→runtimeDirFor(project)→<RUNTIME_DIR>/<cwdHash(project)>/<sid>.jsoninsessions.mjs, withRUNTIME_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 ofopen/open --resume. Runstatus,chat,waitandstopfrom that same directory. From anywhere elsestatussayslive: false,chat/waitreportserver-gone(exit 20) andstopstops 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; checkserver.logandevents.ndjson(a real exit writes anexitevent 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\...), whileserver.mjscanonicalizes its session dir withfs.realpathSync.nativeto the long form. Any test comparing a server-returned path (e.g. an upload'spath) against the test'ssessionmust pass the test side throughfs.realpathSync.native()first, and compare case-insensitively on Windows. - Web console assets:
computeExpectedSkills()copies references asBuffers, so binary files are fine. Adding apublic/file needs the three edits in Architecture → Web Console. The vendoredmarked.esm.jssha256 is in.readme/web-console.md. - The default highlight color lives in two places: changing it means editing
DEFAULT_ACCENTinpublic/palette.jsand the light, system-dark and explicit-dark--accent*values inpublic/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 checkssrc/plan2code-*.mdflat 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>.mdline 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>.cmdand<name>.ps1intonpm config get prefix, each runningnode <package>/dist/bin/<name>.js(the metrics and bot installers both do this). After a source change,npm run buildin the package is enough; no reinstall. - plan2code-metrics only runs from a repo checkout:
analyzer.tsandimprover.tsloadsrc/prompts/analyze.md/improve.mdat runtime throughnew URL('../src/prompts/...', import.meta.url), resolved relative todist/(analyzer.ts:11,improver.ts:13). A packed or copieddist/withoutsrc/prompts/fails.