Compare commits

..
104 Commits
Author SHA1 Message Date
jparkerweb 342da7c353 Merge pull request #8 from jparkerweb/sync/upstream-v2.5.0
Sync upstream v2.5.0: Subagents switch and tab, standalone review scope (v2.5.0)
2026-10-06 17:59:07 -07:00
jparkerweb da105160a8 Replace the landing page footer's version number with a Releases link to the GitHub releases page, so the page no longer shows a stale version 2026-10-06 17:58:33 -07:00
jparkerweb 977e462e76 Sync upstream web console updates into v2.5.0: a Subagents switch that tells the agent to use helpers (per project and skill, sent as a standing instruction only when it changes), a Subagents tab listing the helpers the agent reports, a standalone review that asks what to review instead of assuming the branch diff, a refusal for doc patches that move a version backwards, and the project name in the footer and browser tab title 2026-10-06 17:57:22 -07:00
jparkerweb 57134cf36e Merge pull request #7 from jparkerweb/sync/upstream-v2.4.5
v2.4.2: upstream web console updates (Cleanup, update banner, launcher banner, Notes threads)
2026-10-05 19:11:56 -07:00
jparkerweb c19a072a3a Sync upstream web console updates into v2.4.2: on-demand Cleanup of unused ~/.plan2code files, an UPDATE AVAILABLE banner from the release tags, a colored launcher with a Planny banner, Notes threads that keep the person's notes and read older reply shapes, the repo-local plan2code-model-update maintainer skill, and review fixes (413 for oversize bodies, notes kept on skip, scoped reconnect banner, live Overview tab, busy state on 409, menu keyboard focus, case-insensitive mentions) 2026-10-05 19:10:45 -07:00
jparkerweb cd8a1be568 Change image alt text for banner in README
Updated image alt text in README.md.
2026-10-05 18:56:03 -07:00
jparkerweb f968aeded8 Show a small spinner left of the web console's Questions and Ask tab names while Plan2Code is on it: Questions spins from Send until the answers are picked up, Ask while a picked-up question has no answer yet, and neither turns once the agent goes quiet or offline 2026-10-04 20:14:53 -07:00
jparkerweb fb71a02756 Hoist the Phase Checklist and Parallel Execution Groups to directly under the Summary in Document's overview.md template, so the phases are found without scrolling
AI Assisted
2026-10-04 18:44:23 -07:00
jparkerweb c8e65f12a6 Count a build on the web console's session meter while it runs, and score Implement + Review's built-in review once instead of twice
AI Assisted
2026-10-04 18:44:23 -07:00
jparkerweb 739e56c5cf Make the web console waiting screen's tasks pointer clickable: while a build runs, Task and the tasks tab's own name (Phase N tasks) show bold in the highlight color and open that phase's tasks tab 2026-10-04 15:52:20 -07:00
jparkerweb ade74cd636 Merge pull request #6 from jparkerweb/develop
Let Send through when an agent asks a question mid-build while still …
2026-10-04 14:24:23 -07:00
jparkerweb 48830c1afb Let Send through when an agent asks a question mid-build while still marked working: once an open question has an answer or note staged the web console unlocks Send at once instead of waiting out quietMinutes, and building.md now says a question stops the build (set waiting in the same post and wait) 2026-10-04 14:12:52 -07:00
jparkerweb b65481cb24 Merge pull request #5 from jparkerweb/develop
update web console, dashboard, implement-review, global launcher
2026-10-04 12:20:55 -07:00
jparkerweb 7d54941b75 Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
AI Assisted
2026-10-04 12:17:05 -07:00
jparkerweb 5cbc6edce2 Add the session meter rescale to the v2.4.1 CHANGELOG 2026-10-04 07:40:29 -07:00
jparkerweb 6b93bcb4c5 Scale the web console session meter with the work done: built phases score one point per 3 completed tasks (reported as run.tasks), every 2 answered questions add a point to their skill run, each Pathfinder research question adds 1 via the new pathfinder-research event, and thresholds move to yellow at 5, red at 10, ring full at 15 2026-10-03 22:31:14 -07:00
jparkerweb d49f2d5792 Keep Pathfinder from ending a session while its research subagents are still running: wait for every one, show a running count in the web console, mark finished research with a completion line, and re-run interrupted research on resume
AI Assisted
2026-10-03 10:23:38 -07:00
jparkerweb bfb47f3a8e Refresh agent docs, README and quick reference for v2.4.x: document plan2code-bot, launcher model menu, test/dev env vars, full npm test pipeline, GitHub-issues pathfinder backend, and dedupe command lists in favor of the README
AI Assisted
2026-10-03 09:38:55 -07:00
jparkerweb cb86034de9 Sync upstream v2.4.0 into v2.4.1: welcome dialog, bug/idea button with issue templates, version in Help, gear preferences and ocean default accent, plus web console screenshots, new landing page and web-console-first docs
AI Assisted
2026-10-02 20:51:34 -07:00
jparkerweb 0d7c2e140b Sync upstream v2.4.0 (web console, dashboard skill, implement-review, global launcher) with 24 review fixes and a look-around wake-up for Planny
AI Assisted
2026-09-28 19:37:41 -07:00
jparkerweb eefa7082ed Add pathfinder BRIEF mode, resolved-date tracking, and decide-menu-checkpoint cadence (v2.3.0)
AI Assisted
2026-09-03 07:18:34 -07:00
jparkerweb 8acd7b9d9f Modify image tag in README for better display
Updated image tag to include 'object-fit' style.
2026-08-26 22:24:02 -07:00
jparkerweb f026d3eebc Change banner image source to direct URL
Updated image source in README to use a direct URL.
2026-08-26 22:18:20 -07:00
jparkerweb 1b3360dc99 Add clipboard copy functionality for installation command in index.html 2026-08-22 10:10:06 -07:00
jparkerweb 16a736a2a9 Change alt text for banner image in README
Updated image alt text in README.
2026-08-22 09:58:20 -07:00
jparkerwebandDevin 8663eba113 Update the protected repository sync workflow
Keep the encrypted maintainer instructions current without mixing the opaque payload into the installer migration commits.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-08-20 13:42:56 -07:00
jparkerwebandDevin f40ddf5f8e Document the v2.2.0 skills-based distribution
Align release notes, version metadata, installation guidance, and maintainer documentation with the canonical skills workflow.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-08-20 13:42:43 -07:00
jparkerwebandDevin 57e32ab64f Delegate workflow installation to the skills CLI
Replace per-tool distribution generation with a canonical committed skills build so installation and updates share one format.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-08-20 13:42:31 -07:00
jparkerweb 483c3055b2 v2.1.1 - Failure Log convention in the init prompts 2026-08-12 13:54:43 -07:00
jparkerweb ca1e137a54 update init instructions 2026-08-12 13:15:50 -07:00
jparkerweb a7506952c8 Add a GitHub Issues backend to Pathfinder
Chart Step 1 now asks where the map should live: local files under
gitignored specs/ (the default) or a pathfinder:map issue whose decision
questions are its sub-issues, driven by gh. The pick is recorded as the
first Ground rules bullet and never re-asked; Auto-Discovery resolves
either backend, and an issue URL routes straight to github.

On github the local model maps onto the tracker's own primitives rather
than being simulated in issue bodies: sub-issues, native issue
dependencies for blocking, the assignee as the claim, one
pathfinder:<type>-<mode> label so type and mode cannot drift, and an
Answer comment plus a close reason that distinguishes a decision from a
question ruled out of scope. Both wiring calls key on the database id,
not the number. The map body therefore carries no checklist at all.

Sketches, secrets and the PLAN-DRAFT stay on local disk regardless --
plan2code-1-plan discovers its input with ls specs/ and has no notion of
a tracker. github is only offered after a five-check preflight, and the
offer names the repo's visibility, because a map on a public tracker
publishes the destination and the codebase recon. The Step 3 recon is
held until Step 6 so the no-fog off-ramp leaves no litter.

Depth lives in a seventh reference file; the orchestrator was
recompressed to absorb the new section within the 11,000 char limit by
removing duplication with its references. Adapted from the GitHub
tracker doc behind Matt Pocock's wayfinder skill (MIT).

AI Assisted
2026-08-08 19:00:26 -07:00
jparkerweb dd7d8eff2d Point plan2code-bot at the GitHub repo URL
AI Assisted
2026-08-08 12:39:52 -07:00
jparkerweb b9c6d87a2d Release v2.0.0
Ports upstream v1.17.0 and v2.0.0. Breaking: Gemini CLI is no longer an
install target. Adds Pathfinder Step 0, community feedback submission and
ingestion, and Devin CLI as an agent backend.

AI Assisted
2026-08-08 12:39:37 -07:00
jparkerweb 94d53d1152 Update the Claude Code status line
AI Assisted
2026-08-08 12:39:29 -07:00
jparkerweb 0037bde2aa Document Pathfinder and community feedback across the contributor docs
Moves the README's deep material into .readme/ (walkthrough, autonomous
loop, status line, metrics, test bot) and brings AGENTS.md, the .agents-docs
set and QUICK-REFERENCE.md in line with Step 0 and the metrics ingestion
flow.

AI Assisted
2026-08-08 12:39:29 -07:00
jparkerweb 1d88d787a3 Ingest community feedback submissions in plan2code-metrics
Adds a CLI flow that lists open community-feedback issues via gh, validates
and parses each METRICS_JSON payload, imports them deduped by run_id,
re-aggregates and closes the issue. Community runs cohort by Plan2Code
version rather than prompt fingerprint, and local cohorts stay preferred so
ingested feedback never displaces the maintainer's current generation. Adds
Devin CLI as an AI backend.

AI Assisted
2026-08-08 12:39:28 -07:00
jparkerweb 987f7b8b04 Add Devin CLI as a selectable agent backend in plan2code-loop
Upstream replaced GitHub Copilot CLI with Devin; Plan2Code keeps both, so
Claude Code, Copilot CLI and Devin are all selectable and existing Copilot
selections keep working.

AI Assisted
2026-08-08 12:39:28 -07:00
jparkerweb 9bc0cfe652 Drop Gemini CLI as an install target and register Pathfinder
Removes the .gemini/commands/*.toml surface and the build-time inlining it
required; every remaining target resolves reference directives at runtime.
The uninstall entry is retained behind an uninstallOnly flag so .toml files
from earlier versions can still be cleaned up.

AI Assisted
2026-08-08 12:39:13 -07:00
jparkerweb 044d41ad06 Add Pathfinder as an optional Step 0 and offload prompt depth to references
Pathfinder charts an idea that is too big to plan as a map of decision
questions under specs/<idea>/pathfinder/, clearing one per session until it
can hand a PLAN-DRAFT to Step 1. Finalize now archives pathfinder/ with the
spec and revise-plan no longer deletes it — both previously described the
cleanup target in wording that pointed at questions/. Init-update Step 7 and
review Session End move to reference files with inline fallbacks.

AI Assisted
2026-08-08 12:39:13 -07:00
jparkerweb b08b385e76 Pin LF line endings and renormalize the working tree
scripts/validate-char-count.js measures characters on disk, so a CRLF
checkout added ~1 char per line and pushed the 11k-budget prompt files over
the limit depending on how the repo was cloned. Pins eol=lf, marks binaries,
and renormalizes the files that had CRLF.

AI Assisted
2026-08-08 12:38:58 -07:00
jparkerweb 61b3050174 Redesign docs site and README around an airmail postcard theme
Adds a postage-stamp favicon set and banner, removes three orphaned images,
and records the site and README as protected divergences so an upstream sync
can't revert them.

AI Assisted
2026-08-08 12:32:17 -07:00
jparkerweb 7b57d70e31 URL updates 2026-08-01 13:04:39 -07:00
jparkerweb 832cb1637b update URLs 2026-08-01 12:56:52 -07:00
jparkerweb 6290f66d03 Merge pull request #3 from jparkerweb/statusline-worktree
Add git worktree awareness to status line (v1.16.1)
2026-07-31 22:24:02 -07:00
jparkerweb f8f9896d38 Bump to v1.16.1 for status line git worktree awareness 2026-07-31 22:20:38 -07:00
jparkerweb be24b0a8dc Add git worktree awareness to status line
Sessions in a linked worktree previously showed only the worktree's
directory name, so the underlying repository was unidentifiable and the
session looked like an unrelated project.

The project segment now renders as "repo | worktree". Repo identity comes
from git rev-parse --git-common-dir, so it is correct regardless of how the
worktree directory was named. A leading repo prefix is stripped from the
worktree name, and the name collapses to a bare marker when it merely
restates the branch already on screen -- matched across / _ . - separators
and type prefixes like feature/, and only when the branch is displayed.

Gated behind the new items.worktree config flag (default on). Costs one
extra timeout-bounded git call, skipped entirely outside git repos.
2026-07-31 22:20:38 -07:00
jparkerweb 34204d9993 Merge pull request #2 from jparkerweb/handoff
Release v1.16.0: install handoff skill, add publish skill, sync upstream
2026-07-20 22:39:25 -07:00
jparkerweb 3e6566af4f Address PR review feedback: update step label + release-list limit 2026-07-20 22:36:35 -07:00
jparkerweb 1183919964 Set v1.16.0 releaseDate to 2026-07-20 2026-07-20 22:33:24 -07:00
jparkerweb f0a60da2e2 Release v1.16.0: install handoff skill, add publish skill, sync upstream
- Make plan2code-handoff an installed workflow prompt: move to src/,
  register in install.js SOURCE_PROMPTS, remove repo-local-only copy
- Add repo-local maintainer /plan2code-publish skill (cuts GitHub Releases;
  excluded from install.js)
- Review workflow next-step suggestion made context-aware (upstream v1.15.4)
- Doc updates: list handoff in README, QUICK-REFERENCE, architecture table;
  add "Adding a New Workflow Prompt / Skill" checklist to dev-commands
- Fix broken AGENTS.md index links: rename .agents-docs loop/metrics files
  to plan2code-* to match references
- Bump version.json to 1.16.0 to align with package.json and CHANGELOG
2026-07-20 22:31:37 -07:00
jparkerweb 5d0f2c6380 Merge pull request #1 from jparkerweb/handoff
Add plan2code-handoff skill for conversation handoff documents
2026-07-20 22:09:45 -07:00
jparkerweb 495f0cc3f6 Add plan2code-handoff skill for conversation handoff documents
AI Assisted
2026-07-20 22:07:21 -07:00
jparkerweb ed220c3c7d Bump to v1.15.4 for status line reasoning effort and context token count
AI Assisted
2026-07-19 21:22:54 -07:00
jparkerweb 8e700d485c Add reasoning effort label and context token count to status line
AI Assisted
2026-07-19 21:18:10 -07:00
jparkerweb 8f87dcce67 Sync upstream workflow improvements (v1.15.3): session-end summaries, Sync & Maintain in init-update, plan research steps, ls-based spec discovery, revision/commit guardrails; bump version to v1.15.3
AI Assisted
2026-06-28 11:46:40 -07:00
jparkerweb 9e6949ec60 sync update 2026-06-01 20:44:05 -07:00
jparkerweb 36ee3343a0 Stop ignoring CLAUDE.md
AI Assisted
2026-06-01 19:42:19 -07:00
jparkerweb f1e0de5f2d Add password-protected sync-repo skill with encrypted body
Adds a project-local /sync-repo skill whose real instructions are encrypted
at rest (AES-256-GCM + scrypt) in sync-repo.enc and only revealed in-session
after the user supplies the correct passphrase. Plaintext SYNC.md is gitignored
and never committed; *.enc is marked binary to protect the ciphertext bytes.

AI Assisted
2026-06-01 19:41:34 -07:00
jparkerweb b941c3fdb8 v1.15.2 — add Claude CLI status line, Zed support, rename 3b-review to review
- Status line: new src/statusline-claude/ (Planny box-star mascot icon),
  install/uninstall wiring in install.js, Install All (A) + Custom (S)
- Zed agent support across README, AGENTS, docs, init prompt, installer
- Rename /plan2code-3b-review to /plan2code-review (now a standalone
  utility workflow); update file, reference dir, and all cross-references
- install.js: fs.rmSync simplifications, async install, summary cleanup
- Bump to v1.15.2; CHANGELOG entries for v1.15.0/1/2
2026-06-01 16:39:35 -07:00
jparkerweb b79aed8569 v1.14.0 — add Step 3b review workflow, unify file naming, resilient code references
- Add /plan2code-3b-review: 5-step post-implementation review with adaptive
  scope, 11 dimensions, reference-file architecture, and Plan/Apply/Verify fixes
- Unify workflow/skill file naming to single-dash (drop -- and --- conventions)
- Add Devin platform support and CLAUDE.md MANDATORY FIRST STEP template
- Guide agents to use semantic anchors over line numbers in workflow prompts
- Bump version to 1.14.0
2026-05-23 06:58:20 -07:00
jparkerweb ec61e9c2ca v1.11.1 — installer 'A' option and bot evaluation notes
- install.js: split into 'I' (prompts + loop) and new 'A' (everything
  including bot + metrics); update prompt to (I, A, U, C, Q).
- CHANGELOG: document complexity check (1.11.1) and expand 1.11.0
  notes for the LLM-as-judge evaluation system.
- version.json: 1.10.0 -> 1.11.1.
2026-05-11 13:14:35 -07:00
jparkerweb 1d75934e45 plan2code-bot: replace auto-responder with LLM-as-judge evaluation
Bot now acts as an authentic QA agent instead of rubber-stamping every
question and step.

- intelligent-responder answers AskUserQuestion via LLM using current
  observations (tools used, files created, errors) instead of keyword
  matching; auto-responder removed.
- evaluator runs after each step with step-specific criteria
  (prompts/evaluation-criteria.ts), produces 0-100 score plus
  strengths/weaknesses/critical issues. Avg <60 blocks finalization.
- observation-collector captures tool_use, file writes, errors, and
  question reasoning; session-runner falls back to scraping tool_use
  blocks when canUseTool doesn't fire and dedupes both sources.
- Bot writes BOT-EVALUATION.md and BOT-NOTES.md for metrics analysis.
- Idea generator: 12 categories instead of CLI/web-app coin flip,
  stronger seed adherence, less developer-tool bias.
- Init step now writes a minimal AGENTS.md stub instead of running
  the full init skill, avoiding hallucinated architecture before plan.
- Implement step uses Read/Write/Edit/Glob/Grep directly instead of
  a Skill sub-session that produced no visible tool observations.
- bin: add --help, accept --idea="value" form, strip surrounding
  quotes; evaluator maxTurns 3 -> 30; warn when parser misses SCORE.
2026-05-11 13:14:28 -07:00
jparkerweb 882caa1d12 metrics: adopt METRICS_JSON HTML comment as primary format
Plan, document, and finalize prompts now emit a single
<!-- METRICS_JSON {...} --> block with all structured fields. Collector
parses these directly and keeps the old prose/table parsing as fallback.

Also adds a per-task complexity check to the document prompt:
split tasks with 3+ complexity signals (5+ logic branches, 2+
integration points, shared interface mutation, etc.), combine
adjacent trivial tasks.
2026-05-11 13:14:15 -07:00
jparkerweb 1301aa1b40 prompts: drop Git Commit Messages section from AGENTS.md and init flows
Project-specific commit conventions don't belong in the generic init
templates. AGENTS.md, init, and init-update no longer mention or audit
a Git Commit Messages section.
2026-05-11 13:14:08 -07:00
jparkerweb e3ed8e80f2 v1.11.0 — add plan2code-bot to root changelog 2026-03-01 21:33:57 -08:00
jparkerweb 7b3266e7d8 feat: add plan2code-bot with --resume capability and state cleanup
Add the autonomous workflow test runner (plan2code-bot) that uses the
Claude Agent SDK to run plan2code end-to-end. Includes --resume flag
to continue incomplete runs from saved state, and automatic state file
cleanup on successful completion.
2026-03-01 21:30:45 -08:00
jparkerweb bc6e2863dc v1.10.0 2026-03-01 12:24:11 -08:00
jparkerweb da51a8b7fa Planny hit the gym and lost some weight
Trimmed the mascot ASCII art across all prompts and installer.
Planny is now more aerodynamic and 40% less chunky.
2026-02-22 21:48:13 -08:00
jparkerweb 46f96f7fc8 docs: update AGENTS.md with plan2code-metrics section and corrections
- Add plan2code-metrics to architecture tree, dev commands, installer menu
- Add full metrics section (data flow, CLI menu, key files, feedback format, metric targets)
- Fix Code Style: split install.js (CommonJS) vs loop/metrics (TypeScript+ESM)
- Update finalize prompt description to reflect 7 steps
- Add metrics-specific gotchas (internal prompts, feedback table format)
2026-02-22 21:47:45 -08:00
jparkerweb 0e3651b475 v1.8.1 — add user feedback collection to plan2code-metrics 2026-02-22 21:41:16 -08:00
jparkerweb b228f2f9fe feat: add user feedback collection to plan2code-metrics
- Add UserFeedback type (rating 1-10, reason, went well, went poorly)
- Collector parses ## User Feedback table from overview.md
- Aggregator computes avg_user_rating and feedback_count per cohort
- CLI offers interactive feedback collection with pipe-safe escaping
- Finalize prompt collects optional feedback as Step 5 (before archival)
- Analysis/improvement prompts reference avg_user_rating metric target
2026-02-22 21:38:58 -08:00
jparkerweb 9d5dc75eca v1.8.0 — add plan2code-metrics recursive self-improvement toolchain
New package for contributors to collect, aggregate, analyze, and improve
workflow prompts based on real project data. Includes unit tests (vitest),
installer integration, and loop/finalize hints.
2026-02-22 19:57:40 -08:00
jparkerweb 7cb3e81890 v1.7.0 2026-02-22 12:58:08 -08:00
jparkerweb 968bad2548 v1.6.1 2026-02-18 15:16:11 -08:00
jparkerweb b942b2b9f0 v1.5.4 2026-02-17 09:13:23 -08:00
jparkerweb 725af08c90 spacing 2026-02-03 20:32:18 -08:00
jparkerweb c10354abff v1.5.2 2026-01-27 12:11:00 -08:00
jparkerweb b1502edfb2 v1.3.3: Learning Capture Protocol and improved session instructions 2025-12-31 13:07:27 -08:00
jparkerweb 87b6b643f0 naming and prompt cleanup 2025-12-25 22:02:24 -08:00
jparkerweb d6354099a9 docs 2025-12-25 21:45:41 -08:00
jparkerweb 582cfccdf5 docs
Updated README to include new workflow details and installation instructions.
2025-12-25 21:45:05 -08:00
jparkerweb b3369e5f76 docs 2025-12-23 17:23:23 -08:00
jparkerweb 0cbacb2a37 improved build and install process 2025-12-23 15:42:35 -08:00
jparkerweb 1eeab9cbb3 Delete .windsurf directory 2025-12-22 09:11:18 -08:00
jparkerweb 7ec47ba7b1 Delete .github directory 2025-12-22 09:11:10 -08:00
jparkerweb 61bad114ec Delete .cursor directory 2025-12-22 09:11:00 -08:00
jparkerweb d8369a0b8c Delete .continue directory 2025-12-22 09:10:49 -08:00
jparkerweb bdebbe30ae Delete .claude directory 2025-12-22 09:10:40 -08:00
jparkerweb bb76590667 Delete .agent directory 2025-12-22 09:10:27 -08:00
jparkerweb e88f467b40 v1.0.4 - Added explicit transition check to Planning Phase 6 2025-12-07 17:52:40 -08:00
jparkerweb 6c04256274 v1.0.3 2025-12-05 21:44:21 -08:00
jparkerweb b2a2ddfc43 v1.0.2 2025-12-05 15:41:23 -08:00
jparkerweb ef30ff0858 - Added Initial Context Check to Planning Phase 1 - Model now asks about additional files, reference materials, and external integrations before
analyzing requirements
- Added user verification checklist and git checkpoint to `Implementation Phase 3` - Phase completion reports now guide users through verification and git checkpointing before starting the next phase
2025-12-05 10:43:58 -08:00
jparkerweb 06f8f78e89 docs 2025-12-04 21:30:41 -08:00
jparkerweb 3dc6681151 docs 2025-12-04 20:51:05 -08:00
jparkerweb 0727988616 docs 2025-12-04 20:28:25 -08:00
jparkerweb 5703ecf8bd update website 2025-12-04 20:23:33 -08:00
jparkerweb fb945f3084 Revise README for Plan2Code workflow updates
Updated the README to reflect changes in the Plan2Code workflow, including new file references and installation instructions.
2025-12-04 18:10:42 -08:00
jparkerweb 47574f78cb docs 2025-12-04 18:09:23 -08:00
jparkerweb 7888f06f11 Create CNAME 2025-12-04 17:47:20 -08:00
jparkerweb 38bd676afa Update and rename plan2code.html to index.html 2025-12-04 17:42:27 -08:00
jparkerweb 7bca4bf9b7 docs 2025-12-04 17:36:20 -08:00
jparkerweb 1bd05b2fe5 v1.0.0 2025-12-04 17:34:22 -08:00
jparkerweb 89437d36b4 Initial commit 2025-12-02 20:59:19 -08:00
132 changed files with 1190 additions and 4039 deletions

No files matched your search

+1 -1
View File
@@ -183,7 +183,7 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
| `picker.mjs` | the per-OS native folder picker behind **Browse…** (`pickerCommand()` → `{ command, args, env }` or `null`; `pickFolder()` runs it with async `spawn`, so the server keeps serving while the dialog is open). Copied from `src/launcher/plan2code.js` (self-contained CommonJS, so it cannot be shared) with the prompt as a parameter; a drift test keeps the two in step |
| `update-check.mjs` | the dashboard's release check, server-only (never in `SERVABLE`): `compareVersions()` (numeric X.Y.Z, `null` otherwise), `latestTag()` (the highest `refs/tags/vX.Y.Z`, peeled `^{}` and pre-release tags skipped), `checkForUpdate({ installed, cacheFile, now, run })` (never throws) and `runLsRemote()` (`git ls-remote --tags` on the repo: no shell, `GIT_TERMINAL_PROMPT=0`, `GCM_INTERACTIVE=never`, SSH `BatchMode` when `GIT_SSH_COMMAND` is unset, `windowsHide`, killed at 10 s; git authenticates itself, the console never touches a credential). The answer, failures included, is cached for an hour in `~/.plan2code/console/update-check.json` (`UPDATE_CHECK_FILE`, in `PROTECTED_CONSOLE_FILES` so no sweep removes it). `server.mjs` starts it after the ready line and never awaits it; `stateFrame()` carries `update: { installed, latest }` only when a newer release exists (its `latest` is part of `haveKey()`, so a page that connected first still gets it), and `GET /version` returns `{ version, latest }`. Tests seed a fresh cached failure in every console home, so no test server reaches the network |
| `public/chat.js` | the Quick question chat's PURE rules, shared by the server and the page: `CHAT_LIMIT` / `CHAT_MAX_CHARS` / `CHAT_MAX_ATTACHMENTS` (the combined image + document cap; `CHAT_MAX_IMAGES` is kept as an alias of it), `chatOffline()` (the server's `409 offline` guard), and the page's view model (`chatView`, `sendState`, `nextAbout`, `contextOptions`, `unreadDot` / `shouldChime`). Ask context is the `{ history, about }` model: `nextAbout()` records the last 3 places visited in `history` and sets `about` only when the person picks one from **+ Add context** (`contextOptions()` lists that history plus *This spec*); dropping it or a successful send clears it, so the page never attaches context on its own. Imports only `answers.js`, no module-scope DOM, so `node --test` covers it |
| `public/starters.js` | PURE, no imports: the Role list (`ROLES`, `ROLE_NOT_SET`, `normalizeRole()`, `needsRoleNudge()`: the dashboard banner shows until `looks.json` carries any `role`), the 19 starter templates (Markdown `## heading` sections, shape pinned by a test) and their per-role orders (`TEMPLATES`, `TEMPLATE_ORDERS`, `templatesFor()`, `templateSwap()` for the replace prompt), and the Ask starter sets (`STARTER_SETS`, `STARTER_SET_FOR`, `startersFor()`). Imported by `app.js` and the tests; in `SERVABLE`, preloaded by `index.html` and parse-checked. The page owns the wording; a skill only flags its fresh-idea `text` card with `"templates": "idea"` |
| `public/starters.js` | PURE, no imports: the Role list (`ROLES`, `ROLE_NOT_SET`, `normalizeRole()`, `needsRoleNudge()`: the dashboard banner shows until `looks.json` carries any `role`), the 13 starter templates and their per-role orders (`TEMPLATES`, `TEMPLATE_ORDERS`, `templatesFor()`, `templateSwap()` for the replace prompt), and the Ask starter sets (`STARTER_SETS`, `STARTER_SET_FOR`, `startersFor()`). Imported by `app.js` and the tests; in `SERVABLE`, preloaded by `index.html` and parse-checked. The page owns the wording; a skill only flags its fresh-idea `text` card with `"templates": "idea"` |
| `public/answers.js` | the page's PURE answer-shaping logic (what an answer reads as, what a placeholder offers, whether a send carries an answer at all). Split out of `app.js` because `app.js` cannot be imported outside a browser, so anything left in it is untestable. `scripts/test-web-console.mjs` imports this directly. |
| `public/labels.js` | `taskLabel()` / `activityLabel()`: rewrites a build's `Task 4.2 of 6` activity line to `Task 2 of 6` (only for `implement` / `implement-review`; a plan's `Task 2.1` is a real section number). A separate module for the same reason as `answers.js`: pure, so `node --test` can import it |
| `public/boot.js` | `playWake()`: the dashboard's first-open wake-up. Self-contained (it owns its timers, the listeners that swallow input mid-run and the one measured glide transform; the page's `stir()` callback times the nudge between the click and the boot, which `app.js` fills with one snore; `skipEl` — the muted Skip button, and Escape — ends the run early with `onSkip` as the cue to silence queued sounds) and free of module-scope DOM access, so it can be imported by the tests and kept out of `app.js`'s render paths; `GLIDE_AT_MS` / `DONE_AT_MS` are its timings |
+1 -1
View File
@@ -1 +1 @@
U0VOQwGXVSGXI36GSw72BYVsi/4ONgA24308DH4YD+cAxK7y8sA5FELtBHEOS9Afj/6nBCRvL156GKEdmKfri1gtkU2XYz/x1lJBa15+a3TWTqeQrPUKLxSW0Ah0UGuPPQVxwoIBXMz9ADPlbG+qpsw/behYXr491MJC8qqRNqrQA/I0bAkLvxer4AZPz/SGohCbpQy3EmmwYOUshDm8QLEp+VjkUZfJmbjWSPXsNRhyKuMzAEHQI3OiWA/MR/qqkOzjhGHb98erQhu3Ebz3fbeR9qSDyezBoBOJN8dRb7K5HFh8IRVFhKsX5CltpO1zEcisJUN0kcI7cz6GCYDt1v+L2KVfJNFVbfveB7vZvDVUTdQ2Gu87M1GFr4bQqUjRp9TM5VpPRuUkv3IDrIcXgdc1I9lQgHki74tVmt1QBtzyOznRd4BN+8dekrE/PRlH99gPTrvCk2WRZkrddlXsBlj+qUYHOwdmldf+b2HAcFjmYu6j/585evlOvbJgMkg+Mhhbr0q7TJcSDGfF8tCRLURMA+p1bvhbZ28fRm74KKTStT85JND+4AUQQXtFxi2r98pY+1fkA8i7Gz8lNR6s0SqaJPOV0NPue0SMqeD37G7LUvmoBz7f6BhmX7O3XcTC+2ewcH4FmZH8qCSeNDGhuyMZJZxjSWyAjrCGPjBVE4IYCnLcaA8A4ZIjbAldtMNAGgfUEMNbwZpuX0ox9LzkZuOHyPICg7IIwXkP1V7HZcejYiAdmqyY8RxNdqtC4QhAjBE5GCcixqY+UwiG3tA0n4a0+Z33u9O+7wHIQ2/C22mjzwbqWoX7R8zqIcUoiY9UB69NFOb23FQTTb3nhm/KwvVlj7jE0B0Bjm+rha+KcetU6GmY3bWvfMmdSF8l2XWdlYVvSlIgHCZ9Pv/ftrBZbdf552tVOOqZgv0HOhBH+gb2DxOlFRRyfOg7BpQzUr3B1CAV2o9aZ3Q7nb02r2658HE51eIftyYfWxpmRLRlrcSkiUXhTEwFSYptH29qIhu2jgzPZ75yUXmWCNa20mddUOjwd+SOroprx7fpkiEta27UC1jBg4IabC3U4sgwd3xy3JUYd9S819bqUhjUlRqGTT89hzPdCFWOP+Ym4R6VZAcAzXgoWhFP2EANONmTRoijJs5UFYfeaazXTjJNDoDU18u1T9a9WWSY5nu5KMrON1Xwpy/uOQZ/YwyTN9PJ3mQRLr4Ohb0ZVUH/BKoNk1iuX9ex5qJlhE+PaFkOdsE1fDL1xncAdsP/Byy2MipW+J/0Bsg8Cxuudi+rL1N/ZoI2lef/zAzx20Op/fYeAL8xebbT3kNCnBC5Re4ui5ccm/n9k6RF4UO+/asNd3fPVtTVkXtETAn3yHcDdZXx37vgnEeCrPRtNUaFkVvrayuEeM2wohkKn7qriEcOrhW/bIu2BW8SKYKmNqS6oMmT4xCFLjTYcYZgzcreWlJ0PjpHYXY0SdJG5iQdPCTYyL1iAitCRnAIYKPH8gMitwcCHeibMvtfso7dncZzcoH1zxkitorzGzpTM/HUbrl+vCuG0NRSyuwlD0r0tSwnBjziK03G5zoKJ6XW4kwcZkMuucDh/W1jKyZdf30NaxlEckscWbnOcpq7pbdrOYejcWxtJaB/7tJXc0mO/LAqrRrCL3k7xoGcmVtTEZJqfwEKxPfJb3k9GWZl2UL87MbZNfTR/aVEYQKbM68/KkdmjSPlF80rJYKLP4WPGobWKEy+AwUMrHFhCQSEV+1AjU8EaWjWbO2TBytbTDC8yHXvFTUJItBpB9rAXZFT4iUCaDVarY3GuOxIiTXVWS6N6hWxz4ev/cxQep1klOhnOtS19bVQAFnmNBKGB8zi8cHxvRo+GHGed8X/k1EF9lDbtFDRIL6Z7HkPzu7qdGgCPfM5eziYafyQKps62jFYzA47+MiHvk68ngqCKihondqeHNOTr+p+QIpn8Al9W1zMETlthjpACxWyFgmVjuHsXscpsu7tOOIM87/HYqXiaybI+GmsOhsa7zTor9UGV0mrRaZvIhd5fpeTWze6pJe66KU7Yji/2swSLBn9oLjHk+x+8qCKoZybD0hVUJKftR7YUEpfZmMeeI07gCArXp48ND0D2+o/Ju2oxabsO9X5UXmhU7vkd3QwB5GwbvDV0OfMIgSvQ0BDntPmVnXFPhPqh6lr41FX0tQ5FTLtjph70QqAv6f7MCV90zS/XMH2vduOgyyuEHxeXVxeAN6QA64cns2yo+p+Xc+8oX2F6B6OUsxMMTwRpR2RHNImx0WRy/yLT342RsgCZpZgQcgglkaSIBbvFMMmaME3t+n8M3LgX7bM/7beod26A4KxZW2y/mffBnfcycoSEvvygcPqy04Dbk8j0XUOUN84VzW5MDfkR1OQmR1Ql3dwSH4d4yLljzg4WDVIC9icDAUGvTvZfK6yjTXD/4gp1IWS9J0W7P/Aeiab1b+pmJxXHi3WO9aUCDyrCkbxyPMOLSiydMFmux9JMeyMXOVQBjJYiT3hn4/U3HTWXwWYEIozauHY6/CqJmVogSGaWWLcJJBd5BANfE9DqJgDqUqoz5tC+Ger0pX1EU91OF0NE+QPWmXxdk/Ah8p2c0A0+4hKOL6xFa7wG6Sq8bJipcuqo5DnxtXhqhi00YQo3fyDG/gCOvgJjEoGaE2NI3+5krNzOqFkpT2vR2goiM2cERxi9z/uTURdqWt/H1yJup/RJUpKvr06YvgzPgm+SGLCf4IOi+VGOdOPbXjLcjmkBZ+to/7+ODKx72XYubVxToCjIf7KaIZkWWQOXwkoIa3ceFoZXaMKT/hIKy4/SXAcDcQqKwHVVl0zXaoVLXsH0qpMHOkb6iVpGGdNsVYebmaz7yWJwUIJu+vVzEs2gPrIZXD2f4c/+5t5UWDb9tybDw1XombuH2TUnmXA6v6bNzDCUU2rPfnoz3GozOOPkCLtI0Yog8MLefPMYbRGi9gKSMqdl+Uc4MMtZd89YNXvTKG1EE6t3pXio6YUoRDwPhibEvvOSszqhdm8NYitOdmRK7NRoBgEdzCJJZ9N/YoItPLXrsiGqRTx6x7x6f2IbBkK202nbRD7EM5yud8NBOm55QFmgK4X/msLNbBzAuBtQawUyOFu5fZREs0/ar7ALGM8c8gzwFp5v4sUypVVk44zTDMcR2/UjcvbAQBl3aqJkFwdATGi2zOrDJ1eeLYIh1p7p+lZB6VhKzJFxCq5s/qcptUBt/rc6jRk42BDqb8opMNJOCZdbLTX5wC8y55JZZpNX5jnesXMnXrCxVnbXe7JrsG8Ea/qneUBCejI9/qzMwS3MYB/usANyOHr2A2ctF8GXVCvE5v1wasr1om/WlFx7gjbAqQORiBNunJih1PFREuyZJUE2XB6foUJupGnbfn1cLGKJuIX32aIPI+Oy89mWcr9+RoaxVuZfL7ztGcB2a1XaCPeU+xR+t41+ArIEkW0X0dTiYV8JINmAyWzNBIHZLABtjOfs/9M1qmlOX7xjuTJZgQdHMz8vuxHtbt2pYrskMoQ4gKzhJ7uoCjChgZx4qG/JQ1iNlDYYsyX66wQiC6CcITx4xmJTX5K9/78uks/WO2H0r8/g+i126U3qy7SITEpvERkgOSfhHxP43aL2443uK67EZ9DH52mEtl4RLU5ulLzMvo1qpHbU5YVaIJYSjscIiyvPwu5onjaFp+JR5VJa7Gb9Pv7MLVR+NUBtK6DDuwxE82HTVAX6qiiOAcpLnvfbgsAXzFvrXNu+KroRxd4JYOZT9NNtiVprLPdV+g9y17iD061IcRMADggiQZY9NbO1TRCrm13JJy7xtC7K5FfBy8jA1x+Y4M7ht/lj2b4toepkfn1WyFVa4z34Zy9JOGomU5eR4cdW13KXGoufaWKp/jxD8DzTlQlb+9/rLfgIzzChvdbvZq6Kh2bHe1psgiojLbu0WXZzWke5LTA3mAt+/slGZyHGBBpxUaeFC6LGCRX548dkJHK1erjF86sfgbw22MCdQiIqR61TxFYdyQjVIvvR2qbxijhHVruwvUd7MyDeH6dA6wqaxqlUa6sNty+0RNFll9SKWsfyzeQWTu9kuD+vTE8USxPfRtWY0eEk1U4lG42XIVaOtEuC1h3RaCJuBX+B82oJL9TLirqc+zTNKU8dZACRhdtoB1y4S5U2qWfz1+wKVlWs1ru0NJiXNrn+ctyqVCAqkk1rUujtAEzYVlHCDviF99xOwF44e/OxhaaLaMO/ZagDm5EXqgdH3nkSRywQc3e6ot4WKCcyQ3+M2PVCDIVw+DvcUlTAAIsvrIfqL1C4KmrjPNVxny+UlA+39bYnIKAoN1yhiEXqV+o1BZVMtDvH2ESx5/sCjoO+cVZMUyiopOP3xYJrJeGvRLjfTV5VXBHdQ/ewzAdxxNcjCOm9iCA8RIBs4Sv5SAcBFVOcKi/YyCgH7sTVueKp3wFF3bf1Y3mKZ0z13iiqAa9N+hssNScEPtWcf1sLCj1sE5h/MBmc5b5NsoQA1nrUbj3rYQ1og9jOCOK+W1QGaRFthylTSYMdw6AEAjz+rWC2BogvfVazc8+O4ekUivkkhXoDqdb+q852KPOXI6b17/b45BK88VUO8WCGmVvtJOPiXaasLik7VOYZZr8E+HfxhCk6JddLXDrV+9Us8vT5f7n6M0RDeGAmL/8CoQy7vhMMgRuC18x8g0LRBdE3KsuGusIdX+FuvThIUQJav9W3cOovCjXnI6PtXQIs6+0WVlCBnh+neMg9OcX1lTHg81pBfKJJaNtmuUeMTz0eQ+drV8BdqDUosShP0ie0082aEcKG6yAQKmfcrEvdnqSvMJxJISYKqN8JvclavMAO22Lg9NugprLEWOjoD7gsgQg89EZihdHNbABEvJJ3HMY8xdyQXUE4iXxe4JvHLdSXIfhV0e3eVTTEXrJEn47LtDE0M90Ne/OhGEAfG44Md2J8esgEfqsmgJdoJ8CADZq3jxRmrBRzmTao1vqrnTtloPWPbvLine truncated
U0VOQwGovNAVPqFDBN7eYOJY9w4zdSme1IrzeoWpGr74/61wgcKXcBdLKhgz5v9A4iFBOH90m/q36/c3xcd/+gsiMk7U8iGD/O4kK/99yyoscIj2AvtuHV16jFqjWQGo5H0imPwjYeDJKh22S4+jL3bidIt6A2LVSNK3cevIoQl4T8Bg8ts5dkSlTbcP9ztChqSgxuGfZsETKK+eAhvgHZ+rIIkvdjMTM0oufKScatRRW/gaKHGYMdaw6fHyLr9u+lY/XJ9b1LwQnpAT6Yjj4lEOJ84h9o85RY6jLmubDHEUl6fuCMi9HD0PTzPC2s/Pni5ksX0Pw+WX3ZzfBqywuLvdEruH5DKSgktekRirr+9bSBVRdhV2YIeKZ+wsJjGG/LXSTySktAUYT9FCgO+wXX/knTzQy2zZZ07j/jcWPOeXdQ4yhhS60qHhVtvZixJG/i0Q07Vv+hSdfo8Uv4/nPyWctf2nrFEyYBHPQhLT4xWTbL86VSCnB+sCca+5xs0NkKWy6SJLp0LYDS483Bi+gIa/ZSDE8soFepIyoprNmOsNFOMjScpdZAb8Gv/7/Sc1giCS4SaIq4o8QWNxqxdxaE68IiDbKdpOcMv80s73scf8gFzIBoXL+Ta5UnhRBcOwZvNEOCEoFy18LpCwzZc3xmfhUoevaZaMsPcr/yao3tWe36zSlroaiM3A4d5Dx6qDFAlkaHllaYsGnCVlEXxVx9yMBbiFNpmy+MX5NqVT2xRYQ+FUcMhLykvFgud7HbTlFlIW4N8PEmpNWvcmG5FhOipmSUAxawmmVaEnqnsSG3ygLFgWIl3giIApGRxgH1OAUSFBxRmq5fpvYCyBrgT+I+pqKAHaOlTFCwPdaceYBqQey3kEBHe0mfbpJjxnoYpJm42Zi8ecPqkohQZ0VGPscePZ+IpoiliaNmiyIXk1AqlD7Gh9EEscuti9DHfpDbgUpCEsfeChMKjwAW8yFOia8JaaX0pfD/POZ6RU4vcM6BJppn9LLlb+7gU5hGsl8ZjT29UUcuBoU5EF6DxhOXdWmto3BYsOm+vD803xDmKKgk2x/VeHsfBezV9cusZdsja4hyd9nPMwH6qaGnkKdEkArp1mq6XNlQLw331tqEHRWiX/gWtQ31nJUhZEWgt5ewwezRQgZAE+gRjaNy9Eia/df8HEV9VNyNeUmbd3FkryB0fI/HgpIppVPt4ZIAB6KU2JSShBL5Iow3qYEvTkfYzyYZcMAsC9EQ4CpKf9m63UMPtw+NPkzvsFM+5052BiL1qmKdpCxecIeelkOOtXOKUFUg5EVqQIgZXrEHPtvERUrAFitrbowrD9ZdWiGRGAS3uZ/33l0fN/c5raZeZFdW1dZbmqAURsZdocBC0fsTQQnn/0OraSzrDJgBzyi2YAEN6+lTPoronbddrBKEOEify1XS8MXyuuJTadbyo+/4YqiyaWLglmyFsl9GHN0WMH5WFi6rjyE7+0IIKJ3i/x+rf081QiA/i+AYY9NKwtzITYJL+EHHr3+G8MzMmAnhhBkXH7yCTMAlpWLo0kX3X7z0+ne/THieIaAAYfnvsUHwolJFCfcl+OTVFhBrHblgqYu7QHuWd5Gc6iOL0LsBwnYUCritFSsAepEeFENOLkunWK7xaXtl/fIxvWGrLgjHxyok1u4iQi3HQdMeTxu29zJiLCIbAJHkNXc93/A4D+zOkZAeRKw5Wg5DVfvU4E4soiPs0j65u99E7rZhi7vsn4usTCD76Ya+nha9it6/xgnWe6h0Xh3wgGXFnJ48OlVf63k2Qyz601KqF7wPJJuYsoKt6HIwqeVWHwdsFIDyrhwcPOaJgfuS27Id0pGCtrHQ0x2zg8cbnvzdcwgy84tw7G8wQZxorqHfwYmmMJTcwi63p/OqF8iBtV38cMBplCOfIA3GMX3vHeh7N2oFbF3jg/aVI92DYsja24YqUOcMawFZlSVZxh3mmM1IHoub9E6Hf/1A5JoxeOjgRg7qFnam2oSSaQhYltx3hvj/USvuoftwm8ZPJuZGgaRdOBkTe8guCNo6Jan1jT1e/M/mnEsz3/wIrh1i2VQJ0exO0I8F+YNikm3JQBVyzdMxzYqA+IwH2YVU9G3kZitgBV3FMAOZcWEW8BTZUjtaac4Op7KrI9Y74CKEKrQbQR0R+mi5dm6aI0iiXz/0Upq+Bd28vuQljG5mygL0/ODObBj2imOsVn7z0Q4oGA3PLvh7haXEVo9Dr2+9Ishu0dsGp4K5seu5ujjhykYpN9PCTGUIYnMGImH38hluI5Y8rFlJJLYbU+DjGcOQpCmvuwGbOmexwZ/xkH9d+6+C+q1wv/hpsCZGzHiLoT0/WjB06mayDxOIBP5PZV4tzx2hFK+IuPaub/d0LcCHmw2BzcJ85WajYl9G9pKCkDWg5sDIdnqP4QNWVVxIV6N75/gGDmpT3oOEx8c3eUGMT0usz9mlgPBIPP8ZkTD69P2T9t8BLCUtM+sgGWZDBPxzRkdVjcLWHI/7r3DwsWW8eovZuBrjGorzNYR9QIYlEpAYQRZdiz2JQ0mXlT0Si/KexXT8SPMywa0eEp5DqWAzZcYo5g5OAsB7xriOzoRBXcwkXPxx1V9V9aHMguAAQ+yHQohVjquQhL+dWIzR95hC/7vIctKm9UfrTWn1xdYRl7n3UHAXERKxGdMR96i4pJbrWLRbRkSvJZZ1fxvGCf2MaQCLOgTD33pVpxJWc65QW62ugnF2R4UdJcFiC/Lk6d2rrrsYZKzwy5j6Sv647V+oHAASlpB6/9lVRUQpgqKLKIixFCeuq5R78qFA5iA7PkEwK2gXJGrBO+Mcs1EPHj6f9sXgiAjhjYCOTdyHi0+9VP326TULJqEL5AxqUThYBqsMz0/rQoE58IxSJ45M8863sKuFkWHXvqJ/HutFv/7GfFSec7KIr0Mr8g5dkrfzSso766KpmSKDXgJM5L/7/GkDHcZIccA4/xD+eOzel8cnKztecp1+NwiablsGCJy/nXMFrhlAkvXoHWyEuAS13TM4omGrBWxgLRFsqL3V1d6sRrQfd4fUIeIr+VIdOblPRbVGqECMhfZVf1olh++wQT8Iy7Gniekz9YMejGFJmopIk04lFLHdxg85bGP51wVcb1xVAWxkp55/4nPmMJ/XpP/2qYDVGIqnuT0GxF/KHk/Ts9Ddo9IDDlw5kAeIDNVGBOVUlYK802MU8b33y+BBX8WlEfFxYhgh7u7Tzckc/NivJuPknMYTAPCxD7UzsdS80ZtOcmuwBP10/4M6xzV8ZTnK8Pb7Wmp2lCnvhrOElGcztEeN6he9Bxb1JftVPQ1QYkEOce9WZB/pKwBwkktKrsyMO0svFpUdMWDXYoNyqc9R+/4Woum7FB2H+6p2sqODSYfZqjnirrBjUOD1YV19Q4+ccTfk7ofmLaNGP+K/cZaZn0EOMSKLPh6exbc/QreoJdGWmCwMNk9W0T83m+iZXb69whaxPJNPJfOroXDrnc46YDr5Kt7+tjZUS1TpzeDL5h+pj1TelC3kW3e//wtuDYnvJIBXrxbeoZUrz6On1UoQDqcymNSZUQwPNE7nWXNFSuvniQ1M7ScnuMyheJvb18rkTzJhkPRGvkCb6ash4f58bmm9otN5TQucKldyzxsicMt1AORUvvFRrrGNZVNjAbXwNm67z8oyVmvxyhXmBrEdpnEUH+h+6W9wc4v88b45eagxTb60aF6ROz/LZPhEBdOKSy1Njk/i+NZ/axD2aKCqD2T3BUiz+1P1abrYemivzWiUFEv2/Djuc9+q/Zwp8rJbMuFkrn04Zk5L4i+PwfjPTSYLxePEKdlEqV+KPqnkGTFbXIUxfeKUoC0RUV5XIugjeAeQQk1HufY1v8hrPNP1+MB78QBEW5bIrlfIZGLx0gZTjky6/k9PJBxKij9J3iIpr7Lk1Qellat/Jr7PZzkknNhvrIw+xCfx2hWEdn0yXZRnPB86GPIrwJdBDrmYBB9w0BClrchACJnHSW722P/b8CFtvUQY9/51a60q4Vgvfcq6QXoEty8XNpvUSFRJqjww44zuYbdgID4sb3MlgPr4WqdfDpL7z2vhGkOYYL+4LCI/U+TazHMXVw4wQ2YI3/EXLJgN0PDKTehMSP/QPVsv4F52T1A1sCAAT3JVv3FGtSBMZxhujOdMqbleFrEHF4f0dBhB0GbaONFv0L3CjweUW40KxpxGTUizeBFWWz7UW+B6GFfkuS8D8n7hY0/K7yDTNLI263v918fm/ER36cmBHPR1GWcMe+yo8o7paC4UBN7PSxhuYK3DFElrGNUY4tV9NK1FWfm85TPB+eAJn4UtNzzzdS4j6TgFwu4kkojqhktczKUYccLfDT+THij7ju4SPeoF5yMXmOwNtsgcxtN+hu5Iq/WiJzBWfuulyCoL8mkXk9D1JivLC2MxxzJA5qOhFu9NHgCw3nB7KIGm4lnsVkiXPQYwQD5/eKG6Kw3MbcNYkJ0ZWxYn/iR8D1OcNw7X5T5GTumT4VWHxyShVdbc1iEzAk6HZ7baKZH0qejB7f2JhdnpwHxTKGRFJ9irxnvAqpxq1ezxT/7yl/8GRmBEH/NFvW+FeOJwjl15Syi46NDK1XZb4m1Z0XJ5tTpJaIj15KtJ0cDJQKzcENSIbitFtd8MFmv+EPIXHeZe+/9Nmhd84pZLlEygLNbywYNLQXmg3xBG/WtF8geQN7kEQJZn0yTGSssZYw+g/6gHgTPAW9CoACZZgGZ512gyXrIAI8q3e+5dBS6rwJ0xeb6eoDqBqiJVlpOWqV4LDpFt0gDuGtwZJNFREsL5Bs+FuXo6FE41OUwD91dcRq7OFaGQ+0rZybRkBiQqcelNRX//BkwLZBfx9Ts+gPxQjS0/7ahpI1a1taOeyTequCFL+C4p0xumh3Iqg1ijyG0X7cWIbAuFt2By/jrM5tvZilA490yITU23wRnmtpcZui4MEeRq1oRUCYVyRD2N4fL0Ld55tAh6estfA+8qTzKI+Line truncated
+1 -1
View File
@@ -15,7 +15,7 @@ background processes.** Optional, and unrelated to the workflow itself.
On Pro / Max / Teams accounts, where rate limits are available:
```
╭───╮ Opus 5 / high │ plan2code │ feature/PCWEB-11702-pathfinder │ +12 -3
╭───╮ Opus 5 / high │ plan2code │ feature/pathfinder-github-iss │ +12 -3
│ ★ │ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
╰┬─┬╯ 3h 5m ($4.62) │ ▰▰▰▰▰▱▱▱▱▱▱▱ 42% (84K) │ 5h: 28% · 7d: 61%
```
+3 -6
View File
@@ -264,12 +264,9 @@ pressing *Not now* puts it away for good.
The first "What's the idea?" box in Pathfinder, Plan and Quick Task has a row
of starter templates above it: **Blank** first, then outlines to fill in (an
engineering spec, product requirements, a design decision, a bug
investigation, a refactor, a data migration, and so on), in the order your
role puts them. With a role chosen, the first one carries a *For your role*
pill. Pick one and the box fills with editable Markdown, one `## heading` per
answer with the answer on the lines under it, and the first `[blank]` is
selected so you can type straight over it. Brackets mark only the parts you
fill in; everything else is a default you can keep or edit. If you have
investigation, and so on), in the order your role puts
them. With a role chosen, the first one carries a *For your role* pill. Pick
one and the box fills with editable text, `[blanks]` marked; if you have
already typed something, a strip asks **Replace** or **Keep mine** first.
Only what is in the box is sent, exactly as if you had typed it.
+1 -1
View File
@@ -92,4 +92,4 @@ When you make a mistake, get corrected, or discover something about this codebas
- Sync upstream only through `/sync-repo`, and verify its baseline against the real tree before porting: an earlier sync silently skipped a whole upstream release (the `3-implement-review` skill) while the recorded version froze. Update the baseline with `.claude/skills/sync-repo/set-synced.mjs`, never with a shell pipe over the decrypted body.
- After a sync merge, run `npm test` before trusting a "clean" file: when upstream and plan2code fixed the same bug, `git merge-file` keeps both copies without a conflict (a sync once left `let pattern` declared twice in `app.js`, caught only by `parse-check`).
- When extracting upstream files in Git Bash, run `git show <ref>:<path>` with `MSYS_NO_PATHCONV=1` and `C:/` style paths (never `/c/`): path conversion rewrites `origin/main:.readme/x.md` into `origin\main;.readme\x.md`, the show fails, and the merge silently runs against an empty "theirs". Check every extracted file is non-empty before merging.
- After a sync, grep for a bare `Smarsh/` owner slug as well as `github.com/smarsh/...` URLs: the rebrand map only rewrites URLs, so `gh --repo Smarsh/smarsh2code` became `Smarsh/plan2code` in `feedback-payload.mjs` (and its test) until it was fixed by hand to `jparkerweb/plan2code`.
- After a sync, grep the result for the upstream owner slug and company name in any case (the `/sync-repo` body lists them): the rebrand map only rewrites URLs, so a bare owner slug once slipped through into `feedback-payload.mjs` (and its test) until it was fixed by hand to `jparkerweb/plan2code`. No upstream name may appear in plain text anywhere in this repo.
-15
View File
@@ -2,21 +2,6 @@
All notable changes to Plan2Code will be documented in this file.
## v2.5.1
### ✨ Added
- **web-console**: six new starter templates, each slotted into every role's order. **Refactor** (Plan, Quick Task) asks what behaviour must not change. **Performance problem** (Plan, Quick Task) asks for today's number and the target. **Dependency upgrade** (Quick Task) asks for the known breaking changes. **Spike** (Pathfinder) is a time-boxed question with an "answered when". **Integration** (Pathfinder, Plan) covers the other side's auth and limits and what happens when it fails. **Data migration** (Plan) asks for a rollback plan. Pathfinder now offers 8 templates, Plan 10 and Quick Task 10, 19 in all.
### 🔧 Changed
- **web-console**: the starter templates on the fresh-idea card (Pathfinder, Plan, Quick Task) are now Markdown sections. Each one is a `## heading` with its answer on the lines under it, instead of `Label: [blank]` lines run together. You get room to write, and the agent gets clear sections. Brackets mark only the parts you fill in, so the lines already written for you (who reads it, what it should pin down) read as defaults. **Bug investigation** splits Expected and Actual into their own sections and numbers its steps. **Add a test** lists its cases. Picking a template now selects its first `[blank]`, so you type straight over it instead of starting at the end of the box. Ids, labels and which skills see the existing templates are unchanged. A new test in `scripts/test-web-console.mjs` pins the shape.
- **web-console**: template content, revised against design-doc, PRD, ADR (MADR) and bug-report guidance. **Engineering spec** gains *Out of scope* and asks for the simpler options turned down. **Product requirements** gains *Not doing* and asks for evidence and a measure of success. **Test strategy** leads with what costs most if it breaks. **Scoping and rollout** asks who sees it first and how it rolls back. **Bug investigation** gains *How often* and *Error or logs*. **Small change** gains *Leave alone*, and its *Done when* asks for a command or check. **Add a test** names the failure case. **Record a decision**'s *Why* asks what forced the choice.
### 🐛 Fixed
- **web-console**: a "working alone" report no longer hides helpers reported after it (or beside it). A real helper report now removes the marker (`applyPatch` in `lib.mjs`, `helperRows()` in `subagents.js`), the standing instruction and `console.md` say to post `alone` only when the agent's tools cannot start helpers at all, and Help's **Helpers (subagents)** topic says the note goes away once a helper shows.
## v2.5.0
### ✨ Added
+1 -1
View File
@@ -13,7 +13,7 @@ the next engineer all start from the same specs.
One command opens it, every step is a card, and the terminal is always there if you prefer it.
Version 2.5.1 · MIT · 📖 [plan2code.jparkerweb.com](https://plan2code.jparkerweb.com)
Version 2.5.0 · MIT · 📖 [plan2code.jparkerweb.com](https://plan2code.jparkerweb.com)
---
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "plan2code",
"version": "2.5.1",
"version": "2.5.0",
"private": true,
"bin": {
"plan2code-install": "./install.js"
+8 -8
View File
@@ -230,16 +230,16 @@ test("specs archive: dry-run, move, refuse to clobber", () => {
test("commit-msg: ticket from the branch, the three -m flags, subject rules", () => {
const repo = tmp("commit");
const g = gitInit(repo, "feature/PCWEB-10968-export-csv");
const g = gitInit(repo, "feature/ABC-10968-export-csv");
write(repo, "a.txt", "a");
g("add", "-A");
g("commit", "-q", "-m", "init");
const C = (...a) => runScript("plan2code-review", "commit-msg.mjs", a, { cwd: repo });
const ok = C("--subject", "Add the export endpoint", "--add-all");
assert.equal(ok.code, 0, ok.stderr);
assert.equal(ok.json.ticket, "PCWEB-10968");
assert.equal(ok.json.command, 'git add -A && git commit -m "Add the export endpoint" -m "PCWEB-10968" -m "AI Assisted"');
assert.equal(ok.json.message, "Add the export endpoint\n\nPCWEB-10968\nAI Assisted");
assert.equal(ok.json.ticket, "ABC-10968");
assert.equal(ok.json.command, 'git add -A && git commit -m "Add the export endpoint" -m "ABC-10968" -m "AI Assisted"');
assert.equal(ok.json.message, "Add the export endpoint\n\nABC-10968\nAI Assisted");
assert.equal(C("--subject", "x".repeat(101)).code, 4);
assert.equal(C("--subject", 'say "hi"').code, 4);
assert.equal(C("--subject", "costs $5").code, 4);
@@ -425,9 +425,9 @@ test("specs: --set cannot override computed fields; empty overview exists; uncou
test("commit-msg: a repo with no commits, stray arguments, and paths quoted for every shell", () => {
const repo = tmp("commit2");
gitInit(repo, "feature/PCWEB-12-x");
gitInit(repo, "feature/ABC-12-x");
const C = (...a) => runScript("plan2code-review", "commit-msg.mjs", a, { cwd: repo });
assert.equal(C("--subject", "Add x").json.ticket, "PCWEB-12", "no commits yet");
assert.equal(C("--subject", "Add x").json.ticket, "ABC-12", "no commits yet");
const stray = C("--subject", "Fix", "--files", "a.js", "b.js");
assert.equal(stray.code, 2);
assert.equal(stray.json.error, "stray-argument");
@@ -572,12 +572,12 @@ test("specs: an em dash in a group range expands like a hyphen", () => {
test("commit-msg: @ and - paths are quoted, git add ends its options, risky subjects are refused, add and commit apart", () => {
const repo = tmp("commit3");
gitInit(repo, "feature/PCWEB-12-x");
gitInit(repo, "feature/ABC-12-x");
const C = (...a) => runScript("plan2code-review", "commit-msg.mjs", a, { cwd: repo });
const files = C("--subject", "Fix", "--files", "@types/x.d.ts", "--files", "-weird.md", "--files", "src/a@b.js");
assert.equal(files.code, 0, files.stderr);
assert.equal(files.json.add, "git add -- '@types/x.d.ts' '-weird.md' src/a@b.js");
assert.equal(files.json.commit, 'git commit -m "Fix" -m "PCWEB-12" -m "AI Assisted"');
assert.equal(files.json.commit, 'git commit -m "Fix" -m "ABC-12" -m "AI Assisted"');
assert.equal(files.json.command, `${files.json.add} && ${files.json.commit}`);
assert.equal(C("--subject", "Fix", "--add-all").json.add, "git add -A");
const bare = C("--subject", "Fix").json;
+10 -41
View File
@@ -4500,7 +4500,7 @@ test("console.md and building.md teach the workspace and session meter contract"
/* ------------------------------------------------- roles and templates */
const ROLE_IDS = ROLES.map((r) => r.id);
const TEMPLATE_SET_SIZE = { pathfinder: 8, plan: 10, "quick-task": 10 };
const TEMPLATE_SET_SIZE = { pathfinder: 6, plan: 6, "quick-task": 7 };
test("normalizeRole keeps a known role and turns anything else into Not set", () => {
for (const id of ROLE_IDS) assert.equal(normalizeRole(id), id);
@@ -4514,9 +4514,9 @@ test("needsRoleNudge: only a missing role key nudges, whatever the value once it
for (const looks of [{ role: "none" }, { role: "pm" }, { role: "garbage" }]) assert.equal(needsRoleNudge(looks), false);
});
test("TEMPLATES: nineteen non-empty texts, the six Pathfinder and Plan share held once", () => {
test("TEMPLATES: thirteen non-empty texts, the five Pathfinder and Plan share held once", () => {
const ids = Object.keys(TEMPLATES);
assert.equal(ids.length, 19);
assert.equal(ids.length, 13);
for (const id of ids) {
assert.equal(TEMPLATES[id].id, id);
assert.ok(TEMPLATES[id].text.trim(), `${id} has text`);
@@ -4525,7 +4525,7 @@ test("TEMPLATES: nineteen non-empty texts, the six Pathfinder and Plan share hel
const shared = TEMPLATE_ORDERS.pathfinder.engineer.filter((id) => TEMPLATE_ORDERS.plan.engineer.includes(id));
assert.deepEqual(
[...shared].sort(),
["design-decision", "engineering-spec", "integration", "product-requirements", "scoping-rollout", "test-strategy"]
["design-decision", "engineering-spec", "product-requirements", "scoping-rollout", "test-strategy"]
);
const labels = Object.values(TEMPLATES).map((t) => t.label);
assert.equal(new Set(labels).size, labels.length, "no template is held twice under another id");
@@ -4535,24 +4535,6 @@ test("TEMPLATES: nineteen non-empty texts, the six Pathfinder and Plan share hel
}
});
test("TEMPLATES: Markdown sections, a ## heading first and an answer under every heading", () => {
for (const { id, text } of Object.values(TEMPLATES)) {
const lines = text.split("\n");
assert.ok(lines[0].startsWith("## "), `${id} opens on a ## heading`);
lines.forEach((line, i) => {
assert.equal(line, line.trimEnd(), `${id} line ${i + 1} has no trailing space`);
if (!line.startsWith("## ")) return;
assert.ok(line.slice(3).trim(), `${id} line ${i + 1} names its heading`);
assert.ok(lines[i + 1]?.trim() && !lines[i + 1].startsWith("#"), `${id}: "${line}" has its answer on the next line`);
if (i > 0) assert.equal(lines[i - 1], "", `${id}: a blank line comes before "${line}"`);
});
for (const l of lines) {
assert.ok(!/^[A-Z][\w' ]*:\s*\[/.test(l), `${id}: "${l}" is a Markdown section, not a Label: [blank] line`);
assert.ok(!/\S\s+[A-Z][\w' ]*:\s*\[/.test(l), `${id}: "${l}" puts one answer on a line`);
}
}
});
test("TEMPLATE_ORDERS: every role holds exactly its skill's set, and Quick Task never writes to specs/", () => {
assert.deepEqual([...TEMPLATE_WORKFLOWS], ["pathfinder", "plan", "quick-task"]);
for (const wf of TEMPLATE_WORKFLOWS) {
@@ -5321,11 +5303,6 @@ test("subagents: the page shows the switch only when offered and supported, and
test("subagents: helperRows labels each state, shows a result only once a helper ended, and collapses to working alone", () => {
assert.deepEqual(helperRows([{ id: "alone", alone: true }]), { alone: true, rows: [] });
assert.deepEqual(helperRows(undefined), { alone: false, rows: [] });
// A stale working-alone entry must never hide a real helper (it can survive
// in sessions written before the merge started dropping it).
const mixed = helperRows([{ id: "alone", alone: true }, { id: "h9", title: "Late", ask: "a", state: "done", result: "ok" }]);
assert.equal(mixed.alone, false);
assert.deepEqual(mixed.rows.map((r) => r.id), ["h9"]);
const { alone, rows } = helperRows([
{ id: "h1", title: "One", ask: "a", state: "running", result: "not yet" },
{ id: "h2", title: "Two", ask: "b", state: "done", result: "Found 2 call sites" },
@@ -6032,7 +6009,7 @@ test("subagents: a workflow without the switch refuses it, bad bodies name the f
const reportedHelper = (id, extra = {}) => ({ id, title: `Helper ${id}`, ask: "Find the callers of applyPatch", state: "running", ...extra });
test("helpers: post merges them by id, a real helper supersedes working alone, and null clears the list", () => {
test("helpers: post merges them by id, takes one working-alone entry, and null clears the list", () => {
const s = consoleSession(["--workflow", "implement"]);
try {
assert.equal(postPatch(s, { helpers: [reportedHelper("h1")] }).status, 0);
@@ -6040,23 +6017,15 @@ test("helpers: post merges them by id, a real helper supersedes working alone, a
assert.equal(postPatch(s, { helpers: [done, reportedHelper("h2")] }).status, 0);
assert.deepEqual(readState(s.session).helpers, [done, reportedHelper("h2")], "h1 updated in place, h2 added");
// Working alone is a claim about having no helper tool at all, so real
// helpers supersede it whichever order the two arrive in.
assert.equal(postPatch(s, { helpers: [{ id: "alone", alone: true }] }).status, 0);
assert.deepEqual(readState(s.session).helpers.map((h) => h.id), ["h1", "h2"], "alone beside real helpers is dropped");
assert.equal(postPatch(s, { helpers: null }).status, 0);
assert.equal("helpers" in readState(s.session), false);
assert.equal(postPatch(s, { helpers: [{ id: "alone", alone: true }] }).status, 0);
assert.deepEqual(readState(s.session).helpers, [{ id: "alone", alone: true }]);
assert.deepEqual(readState(s.session).helpers.map((h) => h.id), ["h1", "h2", "alone"]);
const second = postPatch(s, { helpers: [{ id: "solo", alone: true }] }, { expectFail: true });
assert.equal(second.status, 3);
assert.match(second.stderr, /helper "solo"/);
assert.deepEqual(readState(s.session).helpers, [{ id: "alone", alone: true }], "the refused entry was not written");
assert.deepEqual(readState(s.session).helpers.map((h) => h.id), ["h1", "h2", "alone"], "the refused entry was not written");
assert.equal(postPatch(s, { helpers: [reportedHelper("h1")] }).status, 0);
assert.deepEqual(readState(s.session).helpers.map((h) => h.id), ["h1"], "a real helper removes the working-alone marker");
assert.equal(postPatch(s, { helpers: null }).status, 0);
assert.equal("helpers" in readState(s.session), false);
} finally {
cli(["stop", "--session", s.sid]);
}
@@ -6146,7 +6115,7 @@ test("helpers: a dashboard hop clears them, a same-workflow or paused resume kee
const s = consoleSession(["--workflow", "implement"]);
try {
const meterBefore = (await s.get("/state")).meter;
assert.equal(postPatch(s, { helpers: [reportedHelper("h1"), reportedHelper("h2")] }).status, 0);
assert.equal(postPatch(s, { helpers: [reportedHelper("h1"), { id: "alone", alone: true }] }).status, 0);
assert.deepEqual((await s.get("/state")).meter, meterBefore, "helper reports add nothing to the meter");
assert.equal(readLedger(s.session).some((e) => JSON.stringify(e).includes("h1")), false, "nothing about helpers reaches the ledger");
@@ -667,7 +667,7 @@ your next `chat` check.
Subagents: on (revision 2) — a console setting, not typed by the person.
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
With no way to start helpers, report one "working alone" entry for this skill run instead.
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
At most 3 helpers at once.
```
@@ -716,11 +716,8 @@ page never hears from a helper directly:
- Questions for the person stay with you, never with a helper: most harnesses
give helpers no way to ask, and an answer only reaches the agent holding the
session.
- **No way to start helpers at all?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
entry for the skill run instead. The tab then says you are working alone.
It is a claim about your tools, not about the moment — post it only when no
helper mechanism exists. Reporting a real helper removes it, so an early
`alone` can never hide a later helper.
- **Pathfinder:** research questions always use helpers and are always
reported, whatever the switch says. The switch governs recon, sketches and
lookups beside the conversation.
@@ -1211,10 +1211,6 @@ export function applyPatch(state, patch) {
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
// A real helper report supersedes the working-alone marker, whether it
// arrives after one or beside one.
if (next.helpers.some((h) => isPlainObject(h) && h.alone !== true))
next.helpers = next.helpers.filter((h) => !(isPlainObject(h) && h.alone === true));
break;
case "docs":
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
@@ -4345,11 +4345,8 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,9 +1540,8 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent reported it has no
way to start helpers here. If it starts one after all, the note
goes away and the helper's row shows instead.
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,271 +36,85 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording was revised in v2.5.1 (Markdown sections); a change is a page change.
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
const template = (id, label, lines) => Object.freeze({ id, label, text: lines.join("\n") });
export const TEMPLATES = Object.freeze({
"engineering-spec": template("engineering-spec", "Engineering spec", [
"## Engineering spec",
"[the feature or change, in a sentence]",
"",
"## Who reads it",
"The engineers who will build and review it.",
"",
"## What it should pin down",
"The behaviour, the parts of the code it touches, the interfaces between them, the simpler options we're turning down, and how we'll know it works.",
"",
"## Out of scope",
"[what this deliberately won't do]",
"",
"## What I already know",
"[constraints, links, earlier attempts]",
"Engineering spec for: [the feature or change, in a sentence]",
"Who reads it: the engineers who will build and review it.",
"What it should pin down: the behaviour, the parts of the code it touches, the interfaces between them, and how we'll know it works.",
"What I already know: [constraints, links, earlier attempts]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"## Product requirements",
"[the feature, in a sentence]",
"",
"## Who it's for",
"[the users], and the product, design and engineering people deciding on it.",
"",
"## What it should pin down",
"The problem, who has it, the evidence it's real, and how we'll measure success.",
"",
"## Not doing",
"[what this release leaves out]",
"",
"## What I already know",
"[customer asks, data, deadlines]",
"Product requirements for: [the feature, in a sentence]",
"Who it's for: [the users], and the product, design and engineering people deciding on it.",
"What it should pin down: the problem, who has it, what success looks like, and what waits for later.",
"What I already know: [customer asks, data, deadlines]",
]),
"design-decision": template("design-decision", "Design decision", [
"## Design decision",
"[the choice we're facing, in a sentence]",
"",
"## Who it's for",
"The engineers and architects who will live with it.",
"",
"## What it should pin down",
"The options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"",
"## Constraints",
"[performance, compatibility, deadlines, team skills]",
"A design decision to work out: [the choice we're facing, in a sentence]",
"Who it's for: the engineers and architects who will live with it.",
"What it should pin down: the options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"Constraints: [performance, compatibility, deadlines, team skills]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"## Test strategy",
"[the feature or area]",
"",
"## Who reads it",
"QA and the engineers writing the tests.",
"",
"## What it should pin down",
'What\'s riskiest, meaning what costs most if it breaks, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"",
"## What exists today",
"[current tests, known gaps]",
"Test strategy for: [the feature or area]",
"Who reads it: QA and the engineers writing the tests.",
'What it should pin down: what\'s risky, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"What exists today: [current tests, known gaps]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"## Scoping and rollout",
"[the feature or project]",
"",
"## Who reads it",
"The engineering manager, the product lead and the team.",
"",
"## What it should pin down",
"What's in the first release and what waits, the build order, risks to the timeline, how it reaches users (flags, stages, who sees it first), and how we roll it back.",
"",
"## Constraints",
"[dates, people, dependencies]",
"Scoping and rollout for: [the feature or project]",
"Who reads it: the engineering manager, the product lead and the team.",
"What it should pin down: what's in the first release and what waits, the build order, risks to the timeline, and how it reaches users (flags, stages, who goes first).",
"Constraints: [dates, people, dependencies]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"## Brainstorm to curated notes",
"[the topic or rough idea]",
"",
"## Who reads the notes",
"[the team or people this goes to]",
"",
"## What I want out of it",
"The ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"",
"## Starting thoughts",
"[anything already on your mind]",
"Brainstorm to turn into curated notes: [the topic or rough idea]",
"Who reads the notes: [the team or people this goes to]",
"What I want out of it: the ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"Starting thoughts: [anything already on your mind]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"## Bug investigation",
"[what's going wrong, in a sentence]",
"",
"## Steps to reproduce",
"1. [first step]",
"2. [next step]",
"",
"## Expected",
"[what should happen]",
"",
"## Actual",
"[what happens instead]",
"",
"## How often",
"[every time, sometimes, once]",
"",
"## Error or logs",
"[paste the exact text]",
"",
"## Where and since when",
"[environment, version, first seen]",
"Bug to investigate: [what's going wrong, in a sentence]",
"Steps to reproduce: [1. ... 2. ...]",
"Expected: [what should happen]. Actual: [what happens instead]",
"Where and since when: [environment, version, first seen]",
]),
"small-change": template("small-change", "Small change", [
"## Small change",
"[what to change, in a sentence]",
"",
"## Where",
"[the file, screen or command, if you know it]",
"",
"## Leave alone",
"[anything that must not change]",
"",
"## Done when",
"[the command to run or the thing to check]",
"Small change: [what to change, in a sentence]",
"Where: [the file, screen or command, if you know it]",
"Done when: [how you'll tell it worked]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"## Copy or content tweak",
"[the screen, message, email or doc]",
"",
"## Current text",
"[paste it]",
"",
"## New text",
"[paste it, or describe the tone you want]",
"",
"## Who reads it",
"[the people who see it]",
"Change the wording of: [the screen, message, email or doc]",
"Current text: [paste it]",
"New text: [paste it, or describe the tone you want]",
"Who reads it: [the people who see it]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"## UI polish",
"[the screen or component]",
"",
"## What looks or feels off",
"[spacing, alignment, colour, states, small screens]",
"",
"## What good looks like",
"[a reference, screenshot or description]",
"",
"## Leave alone",
"[anything that must not move]",
"UI polish on: [the screen or component]",
"What looks or feels off: [spacing, alignment, colour, states, small screens]",
"What good looks like: [a reference, screenshot or description]",
"Leave alone: [anything that must not move]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"## Visual prototype",
"[the screen or component to mock up]",
"",
"## What to show",
"[the states or flows to click through]",
"",
"## What I want to learn",
"[the question it should answer]",
"",
"## Where it lives",
"A prototypes/ folder [or its own branch], never wired into the real code.",
"A throwaway visual prototype of: [the screen or component]",
"What to show: [the states or flows to click through]",
"What I want to learn: [the question it should answer]",
"Where it lives: a prototypes/ folder [or its own branch], never wired into the real code.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"## Add a test",
"[the function, behaviour or bug]",
"",
"## Cases to cover",
"- [the normal case]",
"- [the edge cases]",
"- [the failure or bug it guards against]",
"",
"## Where tests live",
"[the test file or folder, if you know it]",
"Add a test for: [the function, behaviour or bug]",
"Cases to cover: [the normal case, the edge cases, the bug it guards against]",
"Where tests live: [the test file or folder, if you know it]",
]),
"record-decision": template("record-decision", "Record a decision", [
"## Record a decision",
"[the decision we've already made, in a sentence]",
"",
"## Why",
"[what forced the choice, and the options we turned down]",
"",
"## What it commits us to",
"[the consequences]",
"",
"## Save it in",
"docs/adr/ [or wherever this repo keeps them]",
]),
refactor: template("refactor", "Refactor", [
"## Refactor",
"[what to restructure, in a sentence]",
"",
"## Why now",
"[what the current shape makes hard]",
"",
"## Behaviour that must not change",
"[the public API, outputs or tests that must stay the same]",
"",
"## Done when",
"[the tests that must still pass, and the shape it ends in]",
]),
"performance-problem": template("performance-problem", "Performance problem", [
"## Performance problem",
"[what's slow, in a sentence]",
"",
"## How it's measured today",
"[the number, and how you got it]",
"",
"## Target",
"[the number that counts as fixed]",
"",
"## Where",
"[the endpoint, page, query or job]",
]),
"dependency-upgrade": template("dependency-upgrade", "Dependency upgrade", [
"## Dependency upgrade",
"[the package, from version to version]",
"",
"## Why",
"[security fix, a feature we need, end of support]",
"",
"## Known breaking changes",
'[release notes link, or "not checked yet"]',
"",
"## Done when",
"[the build, tests or checks that must pass]",
]),
spike: template("spike", "Spike", [
"## Spike",
"[the question to answer, in a sentence]",
"",
"## Why it matters",
"[the decision waiting on the answer]",
"",
"## Time box",
"[how long before we stop and decide anyway]",
"",
"## Answered when",
"[the evidence that would settle it]",
]),
integration: template("integration", "Integration", [
"## Integration",
"[the system we're connecting to, and why]",
"",
"## What flows",
"[the data or events, and in which direction]",
"",
"## Their side",
"[API docs, auth method, rate limits, test sandbox]",
"",
"## When it fails",
"[what should happen if they're down or slow]",
]),
"data-migration": template("data-migration", "Data migration", [
"## Data migration",
"[what moves or changes shape]",
"",
"## Size and downtime",
"[row counts, and whether users can stay on while it runs]",
"",
"## Rollback",
"[how we undo it if it goes wrong]",
"",
"## Done when",
"[the checks that prove nothing was lost]",
"Record a decision we've already made: [the decision, in a sentence]",
"Why: [the reasons, and what we turned down]",
"What it commits us to: [the consequences]",
"Save it as an ADR in: docs/adr/ [or wherever this repo keeps them]",
]),
});
@@ -309,28 +123,28 @@ const orders = (byRole) => Object.freeze(Object.fromEntries(Object.entries(byRol
// One full order per role per skill. No "none" row: Not set reads Engineer's.
export const TEMPLATE_ORDERS = Object.freeze({
pathfinder: orders({
engineer: ["engineering-spec", "design-decision", "spike", "integration", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "spike", "engineering-spec", "design-decision", "integration", "test-strategy"],
architect: ["design-decision", "engineering-spec", "integration", "spike", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "spike", "engineering-spec", "scoping-rollout", "integration", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "spike", "product-requirements", "integration", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "spike", "test-strategy", "design-decision", "integration", "brainstorm-notes"],
engineer: ["engineering-spec", "design-decision", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "engineering-spec", "design-decision", "test-strategy"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "design-decision", "brainstorm-notes"],
}),
plan: orders({
engineer: ["engineering-spec", "bug-investigation", "refactor", "performance-problem", "integration", "data-migration", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "integration", "test-strategy", "design-decision", "performance-problem", "bug-investigation", "data-migration", "refactor"],
architect: ["design-decision", "engineering-spec", "data-migration", "integration", "refactor", "scoping-rollout", "performance-problem", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "performance-problem", "test-strategy", "bug-investigation", "integration", "refactor", "data-migration"],
qa: ["test-strategy", "bug-investigation", "performance-problem", "engineering-spec", "data-migration", "integration", "product-requirements", "scoping-rollout", "refactor", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "data-migration", "product-requirements", "test-strategy", "integration", "bug-investigation", "performance-problem", "refactor", "design-decision"],
engineer: ["engineering-spec", "bug-investigation", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "test-strategy", "design-decision", "bug-investigation"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "bug-investigation"],
qa: ["test-strategy", "bug-investigation", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "bug-investigation", "design-decision"],
}),
"quick-task": orders({
engineer: ["small-change", "bug-investigation", "refactor", "add-a-test", "dependency-upgrade", "performance-problem", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "performance-problem", "add-a-test", "record-decision", "dependency-upgrade", "refactor"],
architect: ["record-decision", "refactor", "small-change", "dependency-upgrade", "performance-problem", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "performance-problem", "add-a-test", "refactor", "dependency-upgrade", "record-decision"],
qa: ["add-a-test", "bug-investigation", "performance-problem", "small-change", "dependency-upgrade", "ui-polish", "refactor", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "dependency-upgrade", "add-a-test", "bug-investigation", "performance-problem", "refactor", "copy-tweak", "ui-polish", "visual-prototype"],
engineer: ["small-change", "bug-investigation", "add-a-test", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "add-a-test", "record-decision"],
architect: ["record-decision", "small-change", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "add-a-test", "record-decision"],
qa: ["add-a-test", "bug-investigation", "small-change", "ui-polish", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "add-a-test", "bug-investigation", "copy-tweak", "ui-polish", "visual-prototype"],
}),
});
@@ -88,7 +88,7 @@ export function cleanSetting(input) {
export const FRAME_LINES = Object.freeze([
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,14 +201,11 @@ export function switchLabel(frame) {
}
// What the Subagents tab draws: the working-alone note, or one row per helper
// in the order the agent reported them. A real helper supersedes the
// working-alone marker, so the note only draws when no helper was ever
// reported. A result shows once the helper ended.
// in the order the agent reported them. A result shows once the helper ended.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
const real = list.filter((h) => h.alone !== true);
if (!real.length) return { alone: list.some((h) => h.alone === true), rows: [] };
const rows = real.map(({ id, title, ask, state, result }) => ({
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -667,7 +667,7 @@ your next `chat` check.
Subagents: on (revision 2) — a console setting, not typed by the person.
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
With no way to start helpers, report one "working alone" entry for this skill run instead.
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
At most 3 helpers at once.
```
@@ -716,11 +716,8 @@ page never hears from a helper directly:
- Questions for the person stay with you, never with a helper: most harnesses
give helpers no way to ask, and an answer only reaches the agent holding the
session.
- **No way to start helpers at all?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
entry for the skill run instead. The tab then says you are working alone.
It is a claim about your tools, not about the moment — post it only when no
helper mechanism exists. Reporting a real helper removes it, so an early
`alone` can never hide a later helper.
- **Pathfinder:** research questions always use helpers and are always
reported, whatever the switch says. The switch governs recon, sketches and
lookups beside the conversation.
@@ -1211,10 +1211,6 @@ export function applyPatch(state, patch) {
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
// A real helper report supersedes the working-alone marker, whether it
// arrives after one or beside one.
if (next.helpers.some((h) => isPlainObject(h) && h.alone !== true))
next.helpers = next.helpers.filter((h) => !(isPlainObject(h) && h.alone === true));
break;
case "docs":
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
@@ -4345,11 +4345,8 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,9 +1540,8 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent reported it has no
way to start helpers here. If it starts one after all, the note
goes away and the helper's row shows instead.
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,271 +36,85 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording was revised in v2.5.1 (Markdown sections); a change is a page change.
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
const template = (id, label, lines) => Object.freeze({ id, label, text: lines.join("\n") });
export const TEMPLATES = Object.freeze({
"engineering-spec": template("engineering-spec", "Engineering spec", [
"## Engineering spec",
"[the feature or change, in a sentence]",
"",
"## Who reads it",
"The engineers who will build and review it.",
"",
"## What it should pin down",
"The behaviour, the parts of the code it touches, the interfaces between them, the simpler options we're turning down, and how we'll know it works.",
"",
"## Out of scope",
"[what this deliberately won't do]",
"",
"## What I already know",
"[constraints, links, earlier attempts]",
"Engineering spec for: [the feature or change, in a sentence]",
"Who reads it: the engineers who will build and review it.",
"What it should pin down: the behaviour, the parts of the code it touches, the interfaces between them, and how we'll know it works.",
"What I already know: [constraints, links, earlier attempts]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"## Product requirements",
"[the feature, in a sentence]",
"",
"## Who it's for",
"[the users], and the product, design and engineering people deciding on it.",
"",
"## What it should pin down",
"The problem, who has it, the evidence it's real, and how we'll measure success.",
"",
"## Not doing",
"[what this release leaves out]",
"",
"## What I already know",
"[customer asks, data, deadlines]",
"Product requirements for: [the feature, in a sentence]",
"Who it's for: [the users], and the product, design and engineering people deciding on it.",
"What it should pin down: the problem, who has it, what success looks like, and what waits for later.",
"What I already know: [customer asks, data, deadlines]",
]),
"design-decision": template("design-decision", "Design decision", [
"## Design decision",
"[the choice we're facing, in a sentence]",
"",
"## Who it's for",
"The engineers and architects who will live with it.",
"",
"## What it should pin down",
"The options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"",
"## Constraints",
"[performance, compatibility, deadlines, team skills]",
"A design decision to work out: [the choice we're facing, in a sentence]",
"Who it's for: the engineers and architects who will live with it.",
"What it should pin down: the options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"Constraints: [performance, compatibility, deadlines, team skills]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"## Test strategy",
"[the feature or area]",
"",
"## Who reads it",
"QA and the engineers writing the tests.",
"",
"## What it should pin down",
'What\'s riskiest, meaning what costs most if it breaks, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"",
"## What exists today",
"[current tests, known gaps]",
"Test strategy for: [the feature or area]",
"Who reads it: QA and the engineers writing the tests.",
'What it should pin down: what\'s risky, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"What exists today: [current tests, known gaps]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"## Scoping and rollout",
"[the feature or project]",
"",
"## Who reads it",
"The engineering manager, the product lead and the team.",
"",
"## What it should pin down",
"What's in the first release and what waits, the build order, risks to the timeline, how it reaches users (flags, stages, who sees it first), and how we roll it back.",
"",
"## Constraints",
"[dates, people, dependencies]",
"Scoping and rollout for: [the feature or project]",
"Who reads it: the engineering manager, the product lead and the team.",
"What it should pin down: what's in the first release and what waits, the build order, risks to the timeline, and how it reaches users (flags, stages, who goes first).",
"Constraints: [dates, people, dependencies]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"## Brainstorm to curated notes",
"[the topic or rough idea]",
"",
"## Who reads the notes",
"[the team or people this goes to]",
"",
"## What I want out of it",
"The ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"",
"## Starting thoughts",
"[anything already on your mind]",
"Brainstorm to turn into curated notes: [the topic or rough idea]",
"Who reads the notes: [the team or people this goes to]",
"What I want out of it: the ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"Starting thoughts: [anything already on your mind]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"## Bug investigation",
"[what's going wrong, in a sentence]",
"",
"## Steps to reproduce",
"1. [first step]",
"2. [next step]",
"",
"## Expected",
"[what should happen]",
"",
"## Actual",
"[what happens instead]",
"",
"## How often",
"[every time, sometimes, once]",
"",
"## Error or logs",
"[paste the exact text]",
"",
"## Where and since when",
"[environment, version, first seen]",
"Bug to investigate: [what's going wrong, in a sentence]",
"Steps to reproduce: [1. ... 2. ...]",
"Expected: [what should happen]. Actual: [what happens instead]",
"Where and since when: [environment, version, first seen]",
]),
"small-change": template("small-change", "Small change", [
"## Small change",
"[what to change, in a sentence]",
"",
"## Where",
"[the file, screen or command, if you know it]",
"",
"## Leave alone",
"[anything that must not change]",
"",
"## Done when",
"[the command to run or the thing to check]",
"Small change: [what to change, in a sentence]",
"Where: [the file, screen or command, if you know it]",
"Done when: [how you'll tell it worked]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"## Copy or content tweak",
"[the screen, message, email or doc]",
"",
"## Current text",
"[paste it]",
"",
"## New text",
"[paste it, or describe the tone you want]",
"",
"## Who reads it",
"[the people who see it]",
"Change the wording of: [the screen, message, email or doc]",
"Current text: [paste it]",
"New text: [paste it, or describe the tone you want]",
"Who reads it: [the people who see it]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"## UI polish",
"[the screen or component]",
"",
"## What looks or feels off",
"[spacing, alignment, colour, states, small screens]",
"",
"## What good looks like",
"[a reference, screenshot or description]",
"",
"## Leave alone",
"[anything that must not move]",
"UI polish on: [the screen or component]",
"What looks or feels off: [spacing, alignment, colour, states, small screens]",
"What good looks like: [a reference, screenshot or description]",
"Leave alone: [anything that must not move]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"## Visual prototype",
"[the screen or component to mock up]",
"",
"## What to show",
"[the states or flows to click through]",
"",
"## What I want to learn",
"[the question it should answer]",
"",
"## Where it lives",
"A prototypes/ folder [or its own branch], never wired into the real code.",
"A throwaway visual prototype of: [the screen or component]",
"What to show: [the states or flows to click through]",
"What I want to learn: [the question it should answer]",
"Where it lives: a prototypes/ folder [or its own branch], never wired into the real code.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"## Add a test",
"[the function, behaviour or bug]",
"",
"## Cases to cover",
"- [the normal case]",
"- [the edge cases]",
"- [the failure or bug it guards against]",
"",
"## Where tests live",
"[the test file or folder, if you know it]",
"Add a test for: [the function, behaviour or bug]",
"Cases to cover: [the normal case, the edge cases, the bug it guards against]",
"Where tests live: [the test file or folder, if you know it]",
]),
"record-decision": template("record-decision", "Record a decision", [
"## Record a decision",
"[the decision we've already made, in a sentence]",
"",
"## Why",
"[what forced the choice, and the options we turned down]",
"",
"## What it commits us to",
"[the consequences]",
"",
"## Save it in",
"docs/adr/ [or wherever this repo keeps them]",
]),
refactor: template("refactor", "Refactor", [
"## Refactor",
"[what to restructure, in a sentence]",
"",
"## Why now",
"[what the current shape makes hard]",
"",
"## Behaviour that must not change",
"[the public API, outputs or tests that must stay the same]",
"",
"## Done when",
"[the tests that must still pass, and the shape it ends in]",
]),
"performance-problem": template("performance-problem", "Performance problem", [
"## Performance problem",
"[what's slow, in a sentence]",
"",
"## How it's measured today",
"[the number, and how you got it]",
"",
"## Target",
"[the number that counts as fixed]",
"",
"## Where",
"[the endpoint, page, query or job]",
]),
"dependency-upgrade": template("dependency-upgrade", "Dependency upgrade", [
"## Dependency upgrade",
"[the package, from version to version]",
"",
"## Why",
"[security fix, a feature we need, end of support]",
"",
"## Known breaking changes",
'[release notes link, or "not checked yet"]',
"",
"## Done when",
"[the build, tests or checks that must pass]",
]),
spike: template("spike", "Spike", [
"## Spike",
"[the question to answer, in a sentence]",
"",
"## Why it matters",
"[the decision waiting on the answer]",
"",
"## Time box",
"[how long before we stop and decide anyway]",
"",
"## Answered when",
"[the evidence that would settle it]",
]),
integration: template("integration", "Integration", [
"## Integration",
"[the system we're connecting to, and why]",
"",
"## What flows",
"[the data or events, and in which direction]",
"",
"## Their side",
"[API docs, auth method, rate limits, test sandbox]",
"",
"## When it fails",
"[what should happen if they're down or slow]",
]),
"data-migration": template("data-migration", "Data migration", [
"## Data migration",
"[what moves or changes shape]",
"",
"## Size and downtime",
"[row counts, and whether users can stay on while it runs]",
"",
"## Rollback",
"[how we undo it if it goes wrong]",
"",
"## Done when",
"[the checks that prove nothing was lost]",
"Record a decision we've already made: [the decision, in a sentence]",
"Why: [the reasons, and what we turned down]",
"What it commits us to: [the consequences]",
"Save it as an ADR in: docs/adr/ [or wherever this repo keeps them]",
]),
});
@@ -309,28 +123,28 @@ const orders = (byRole) => Object.freeze(Object.fromEntries(Object.entries(byRol
// One full order per role per skill. No "none" row: Not set reads Engineer's.
export const TEMPLATE_ORDERS = Object.freeze({
pathfinder: orders({
engineer: ["engineering-spec", "design-decision", "spike", "integration", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "spike", "engineering-spec", "design-decision", "integration", "test-strategy"],
architect: ["design-decision", "engineering-spec", "integration", "spike", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "spike", "engineering-spec", "scoping-rollout", "integration", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "spike", "product-requirements", "integration", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "spike", "test-strategy", "design-decision", "integration", "brainstorm-notes"],
engineer: ["engineering-spec", "design-decision", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "engineering-spec", "design-decision", "test-strategy"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "design-decision", "brainstorm-notes"],
}),
plan: orders({
engineer: ["engineering-spec", "bug-investigation", "refactor", "performance-problem", "integration", "data-migration", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "integration", "test-strategy", "design-decision", "performance-problem", "bug-investigation", "data-migration", "refactor"],
architect: ["design-decision", "engineering-spec", "data-migration", "integration", "refactor", "scoping-rollout", "performance-problem", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "performance-problem", "test-strategy", "bug-investigation", "integration", "refactor", "data-migration"],
qa: ["test-strategy", "bug-investigation", "performance-problem", "engineering-spec", "data-migration", "integration", "product-requirements", "scoping-rollout", "refactor", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "data-migration", "product-requirements", "test-strategy", "integration", "bug-investigation", "performance-problem", "refactor", "design-decision"],
engineer: ["engineering-spec", "bug-investigation", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "test-strategy", "design-decision", "bug-investigation"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "bug-investigation"],
qa: ["test-strategy", "bug-investigation", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "bug-investigation", "design-decision"],
}),
"quick-task": orders({
engineer: ["small-change", "bug-investigation", "refactor", "add-a-test", "dependency-upgrade", "performance-problem", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "performance-problem", "add-a-test", "record-decision", "dependency-upgrade", "refactor"],
architect: ["record-decision", "refactor", "small-change", "dependency-upgrade", "performance-problem", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "performance-problem", "add-a-test", "refactor", "dependency-upgrade", "record-decision"],
qa: ["add-a-test", "bug-investigation", "performance-problem", "small-change", "dependency-upgrade", "ui-polish", "refactor", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "dependency-upgrade", "add-a-test", "bug-investigation", "performance-problem", "refactor", "copy-tweak", "ui-polish", "visual-prototype"],
engineer: ["small-change", "bug-investigation", "add-a-test", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "add-a-test", "record-decision"],
architect: ["record-decision", "small-change", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "add-a-test", "record-decision"],
qa: ["add-a-test", "bug-investigation", "small-change", "ui-polish", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "add-a-test", "bug-investigation", "copy-tweak", "ui-polish", "visual-prototype"],
}),
});
@@ -88,7 +88,7 @@ export function cleanSetting(input) {
export const FRAME_LINES = Object.freeze([
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,14 +201,11 @@ export function switchLabel(frame) {
}
// What the Subagents tab draws: the working-alone note, or one row per helper
// in the order the agent reported them. A real helper supersedes the
// working-alone marker, so the note only draws when no helper was ever
// reported. A result shows once the helper ended.
// in the order the agent reported them. A result shows once the helper ended.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
const real = list.filter((h) => h.alone !== true);
if (!real.length) return { alone: list.some((h) => h.alone === true), rows: [] };
const rows = real.map(({ id, title, ask, state, result }) => ({
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
+2 -2
View File
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -667,7 +667,7 @@ your next `chat` check.
Subagents: on (revision 2) — a console setting, not typed by the person.
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
With no way to start helpers, report one "working alone" entry for this skill run instead.
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
At most 3 helpers at once.
```
@@ -716,11 +716,8 @@ page never hears from a helper directly:
- Questions for the person stay with you, never with a helper: most harnesses
give helpers no way to ask, and an answer only reaches the agent holding the
session.
- **No way to start helpers at all?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
entry for the skill run instead. The tab then says you are working alone.
It is a claim about your tools, not about the moment — post it only when no
helper mechanism exists. Reporting a real helper removes it, so an early
`alone` can never hide a later helper.
- **Pathfinder:** research questions always use helpers and are always
reported, whatever the switch says. The switch governs recon, sketches and
lookups beside the conversation.
@@ -1211,10 +1211,6 @@ export function applyPatch(state, patch) {
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
// A real helper report supersedes the working-alone marker, whether it
// arrives after one or beside one.
if (next.helpers.some((h) => isPlainObject(h) && h.alone !== true))
next.helpers = next.helpers.filter((h) => !(isPlainObject(h) && h.alone === true));
break;
case "docs":
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
@@ -4345,11 +4345,8 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,9 +1540,8 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent reported it has no
way to start helpers here. If it starts one after all, the note
goes away and the helper's row shows instead.
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,271 +36,85 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording was revised in v2.5.1 (Markdown sections); a change is a page change.
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
const template = (id, label, lines) => Object.freeze({ id, label, text: lines.join("\n") });
export const TEMPLATES = Object.freeze({
"engineering-spec": template("engineering-spec", "Engineering spec", [
"## Engineering spec",
"[the feature or change, in a sentence]",
"",
"## Who reads it",
"The engineers who will build and review it.",
"",
"## What it should pin down",
"The behaviour, the parts of the code it touches, the interfaces between them, the simpler options we're turning down, and how we'll know it works.",
"",
"## Out of scope",
"[what this deliberately won't do]",
"",
"## What I already know",
"[constraints, links, earlier attempts]",
"Engineering spec for: [the feature or change, in a sentence]",
"Who reads it: the engineers who will build and review it.",
"What it should pin down: the behaviour, the parts of the code it touches, the interfaces between them, and how we'll know it works.",
"What I already know: [constraints, links, earlier attempts]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"## Product requirements",
"[the feature, in a sentence]",
"",
"## Who it's for",
"[the users], and the product, design and engineering people deciding on it.",
"",
"## What it should pin down",
"The problem, who has it, the evidence it's real, and how we'll measure success.",
"",
"## Not doing",
"[what this release leaves out]",
"",
"## What I already know",
"[customer asks, data, deadlines]",
"Product requirements for: [the feature, in a sentence]",
"Who it's for: [the users], and the product, design and engineering people deciding on it.",
"What it should pin down: the problem, who has it, what success looks like, and what waits for later.",
"What I already know: [customer asks, data, deadlines]",
]),
"design-decision": template("design-decision", "Design decision", [
"## Design decision",
"[the choice we're facing, in a sentence]",
"",
"## Who it's for",
"The engineers and architects who will live with it.",
"",
"## What it should pin down",
"The options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"",
"## Constraints",
"[performance, compatibility, deadlines, team skills]",
"A design decision to work out: [the choice we're facing, in a sentence]",
"Who it's for: the engineers and architects who will live with it.",
"What it should pin down: the options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"Constraints: [performance, compatibility, deadlines, team skills]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"## Test strategy",
"[the feature or area]",
"",
"## Who reads it",
"QA and the engineers writing the tests.",
"",
"## What it should pin down",
'What\'s riskiest, meaning what costs most if it breaks, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"",
"## What exists today",
"[current tests, known gaps]",
"Test strategy for: [the feature or area]",
"Who reads it: QA and the engineers writing the tests.",
'What it should pin down: what\'s risky, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"What exists today: [current tests, known gaps]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"## Scoping and rollout",
"[the feature or project]",
"",
"## Who reads it",
"The engineering manager, the product lead and the team.",
"",
"## What it should pin down",
"What's in the first release and what waits, the build order, risks to the timeline, how it reaches users (flags, stages, who sees it first), and how we roll it back.",
"",
"## Constraints",
"[dates, people, dependencies]",
"Scoping and rollout for: [the feature or project]",
"Who reads it: the engineering manager, the product lead and the team.",
"What it should pin down: what's in the first release and what waits, the build order, risks to the timeline, and how it reaches users (flags, stages, who goes first).",
"Constraints: [dates, people, dependencies]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"## Brainstorm to curated notes",
"[the topic or rough idea]",
"",
"## Who reads the notes",
"[the team or people this goes to]",
"",
"## What I want out of it",
"The ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"",
"## Starting thoughts",
"[anything already on your mind]",
"Brainstorm to turn into curated notes: [the topic or rough idea]",
"Who reads the notes: [the team or people this goes to]",
"What I want out of it: the ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"Starting thoughts: [anything already on your mind]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"## Bug investigation",
"[what's going wrong, in a sentence]",
"",
"## Steps to reproduce",
"1. [first step]",
"2. [next step]",
"",
"## Expected",
"[what should happen]",
"",
"## Actual",
"[what happens instead]",
"",
"## How often",
"[every time, sometimes, once]",
"",
"## Error or logs",
"[paste the exact text]",
"",
"## Where and since when",
"[environment, version, first seen]",
"Bug to investigate: [what's going wrong, in a sentence]",
"Steps to reproduce: [1. ... 2. ...]",
"Expected: [what should happen]. Actual: [what happens instead]",
"Where and since when: [environment, version, first seen]",
]),
"small-change": template("small-change", "Small change", [
"## Small change",
"[what to change, in a sentence]",
"",
"## Where",
"[the file, screen or command, if you know it]",
"",
"## Leave alone",
"[anything that must not change]",
"",
"## Done when",
"[the command to run or the thing to check]",
"Small change: [what to change, in a sentence]",
"Where: [the file, screen or command, if you know it]",
"Done when: [how you'll tell it worked]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"## Copy or content tweak",
"[the screen, message, email or doc]",
"",
"## Current text",
"[paste it]",
"",
"## New text",
"[paste it, or describe the tone you want]",
"",
"## Who reads it",
"[the people who see it]",
"Change the wording of: [the screen, message, email or doc]",
"Current text: [paste it]",
"New text: [paste it, or describe the tone you want]",
"Who reads it: [the people who see it]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"## UI polish",
"[the screen or component]",
"",
"## What looks or feels off",
"[spacing, alignment, colour, states, small screens]",
"",
"## What good looks like",
"[a reference, screenshot or description]",
"",
"## Leave alone",
"[anything that must not move]",
"UI polish on: [the screen or component]",
"What looks or feels off: [spacing, alignment, colour, states, small screens]",
"What good looks like: [a reference, screenshot or description]",
"Leave alone: [anything that must not move]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"## Visual prototype",
"[the screen or component to mock up]",
"",
"## What to show",
"[the states or flows to click through]",
"",
"## What I want to learn",
"[the question it should answer]",
"",
"## Where it lives",
"A prototypes/ folder [or its own branch], never wired into the real code.",
"A throwaway visual prototype of: [the screen or component]",
"What to show: [the states or flows to click through]",
"What I want to learn: [the question it should answer]",
"Where it lives: a prototypes/ folder [or its own branch], never wired into the real code.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"## Add a test",
"[the function, behaviour or bug]",
"",
"## Cases to cover",
"- [the normal case]",
"- [the edge cases]",
"- [the failure or bug it guards against]",
"",
"## Where tests live",
"[the test file or folder, if you know it]",
"Add a test for: [the function, behaviour or bug]",
"Cases to cover: [the normal case, the edge cases, the bug it guards against]",
"Where tests live: [the test file or folder, if you know it]",
]),
"record-decision": template("record-decision", "Record a decision", [
"## Record a decision",
"[the decision we've already made, in a sentence]",
"",
"## Why",
"[what forced the choice, and the options we turned down]",
"",
"## What it commits us to",
"[the consequences]",
"",
"## Save it in",
"docs/adr/ [or wherever this repo keeps them]",
]),
refactor: template("refactor", "Refactor", [
"## Refactor",
"[what to restructure, in a sentence]",
"",
"## Why now",
"[what the current shape makes hard]",
"",
"## Behaviour that must not change",
"[the public API, outputs or tests that must stay the same]",
"",
"## Done when",
"[the tests that must still pass, and the shape it ends in]",
]),
"performance-problem": template("performance-problem", "Performance problem", [
"## Performance problem",
"[what's slow, in a sentence]",
"",
"## How it's measured today",
"[the number, and how you got it]",
"",
"## Target",
"[the number that counts as fixed]",
"",
"## Where",
"[the endpoint, page, query or job]",
]),
"dependency-upgrade": template("dependency-upgrade", "Dependency upgrade", [
"## Dependency upgrade",
"[the package, from version to version]",
"",
"## Why",
"[security fix, a feature we need, end of support]",
"",
"## Known breaking changes",
'[release notes link, or "not checked yet"]',
"",
"## Done when",
"[the build, tests or checks that must pass]",
]),
spike: template("spike", "Spike", [
"## Spike",
"[the question to answer, in a sentence]",
"",
"## Why it matters",
"[the decision waiting on the answer]",
"",
"## Time box",
"[how long before we stop and decide anyway]",
"",
"## Answered when",
"[the evidence that would settle it]",
]),
integration: template("integration", "Integration", [
"## Integration",
"[the system we're connecting to, and why]",
"",
"## What flows",
"[the data or events, and in which direction]",
"",
"## Their side",
"[API docs, auth method, rate limits, test sandbox]",
"",
"## When it fails",
"[what should happen if they're down or slow]",
]),
"data-migration": template("data-migration", "Data migration", [
"## Data migration",
"[what moves or changes shape]",
"",
"## Size and downtime",
"[row counts, and whether users can stay on while it runs]",
"",
"## Rollback",
"[how we undo it if it goes wrong]",
"",
"## Done when",
"[the checks that prove nothing was lost]",
"Record a decision we've already made: [the decision, in a sentence]",
"Why: [the reasons, and what we turned down]",
"What it commits us to: [the consequences]",
"Save it as an ADR in: docs/adr/ [or wherever this repo keeps them]",
]),
});
@@ -309,28 +123,28 @@ const orders = (byRole) => Object.freeze(Object.fromEntries(Object.entries(byRol
// One full order per role per skill. No "none" row: Not set reads Engineer's.
export const TEMPLATE_ORDERS = Object.freeze({
pathfinder: orders({
engineer: ["engineering-spec", "design-decision", "spike", "integration", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "spike", "engineering-spec", "design-decision", "integration", "test-strategy"],
architect: ["design-decision", "engineering-spec", "integration", "spike", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "spike", "engineering-spec", "scoping-rollout", "integration", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "spike", "product-requirements", "integration", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "spike", "test-strategy", "design-decision", "integration", "brainstorm-notes"],
engineer: ["engineering-spec", "design-decision", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "engineering-spec", "design-decision", "test-strategy"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "design-decision", "brainstorm-notes"],
}),
plan: orders({
engineer: ["engineering-spec", "bug-investigation", "refactor", "performance-problem", "integration", "data-migration", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "integration", "test-strategy", "design-decision", "performance-problem", "bug-investigation", "data-migration", "refactor"],
architect: ["design-decision", "engineering-spec", "data-migration", "integration", "refactor", "scoping-rollout", "performance-problem", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "performance-problem", "test-strategy", "bug-investigation", "integration", "refactor", "data-migration"],
qa: ["test-strategy", "bug-investigation", "performance-problem", "engineering-spec", "data-migration", "integration", "product-requirements", "scoping-rollout", "refactor", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "data-migration", "product-requirements", "test-strategy", "integration", "bug-investigation", "performance-problem", "refactor", "design-decision"],
engineer: ["engineering-spec", "bug-investigation", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "test-strategy", "design-decision", "bug-investigation"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "bug-investigation"],
qa: ["test-strategy", "bug-investigation", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "bug-investigation", "design-decision"],
}),
"quick-task": orders({
engineer: ["small-change", "bug-investigation", "refactor", "add-a-test", "dependency-upgrade", "performance-problem", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "performance-problem", "add-a-test", "record-decision", "dependency-upgrade", "refactor"],
architect: ["record-decision", "refactor", "small-change", "dependency-upgrade", "performance-problem", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "performance-problem", "add-a-test", "refactor", "dependency-upgrade", "record-decision"],
qa: ["add-a-test", "bug-investigation", "performance-problem", "small-change", "dependency-upgrade", "ui-polish", "refactor", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "dependency-upgrade", "add-a-test", "bug-investigation", "performance-problem", "refactor", "copy-tweak", "ui-polish", "visual-prototype"],
engineer: ["small-change", "bug-investigation", "add-a-test", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "add-a-test", "record-decision"],
architect: ["record-decision", "small-change", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "add-a-test", "record-decision"],
qa: ["add-a-test", "bug-investigation", "small-change", "ui-polish", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "add-a-test", "bug-investigation", "copy-tweak", "ui-polish", "visual-prototype"],
}),
});
@@ -88,7 +88,7 @@ export function cleanSetting(input) {
export const FRAME_LINES = Object.freeze([
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,14 +201,11 @@ export function switchLabel(frame) {
}
// What the Subagents tab draws: the working-alone note, or one row per helper
// in the order the agent reported them. A real helper supersedes the
// working-alone marker, so the note only draws when no helper was ever
// reported. A result shows once the helper ended.
// in the order the agent reported them. A result shows once the helper ended.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
const real = list.filter((h) => h.alone !== true);
if (!real.length) return { alone: list.some((h) => h.alone === true), rows: [] };
const rows = real.map(({ id, title, ask, state, result }) => ({
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -667,7 +667,7 @@ your next `chat` check.
Subagents: on (revision 2) — a console setting, not typed by the person.
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
With no way to start helpers, report one "working alone" entry for this skill run instead.
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
At most 3 helpers at once.
```
@@ -716,11 +716,8 @@ page never hears from a helper directly:
- Questions for the person stay with you, never with a helper: most harnesses
give helpers no way to ask, and an answer only reaches the agent holding the
session.
- **No way to start helpers at all?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
entry for the skill run instead. The tab then says you are working alone.
It is a claim about your tools, not about the moment — post it only when no
helper mechanism exists. Reporting a real helper removes it, so an early
`alone` can never hide a later helper.
- **Pathfinder:** research questions always use helpers and are always
reported, whatever the switch says. The switch governs recon, sketches and
lookups beside the conversation.
@@ -1211,10 +1211,6 @@ export function applyPatch(state, patch) {
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
// A real helper report supersedes the working-alone marker, whether it
// arrives after one or beside one.
if (next.helpers.some((h) => isPlainObject(h) && h.alone !== true))
next.helpers = next.helpers.filter((h) => !(isPlainObject(h) && h.alone === true));
break;
case "docs":
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
@@ -4345,11 +4345,8 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,9 +1540,8 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent reported it has no
way to start helpers here. If it starts one after all, the note
goes away and the helper's row shows instead.
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,271 +36,85 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording was revised in v2.5.1 (Markdown sections); a change is a page change.
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
const template = (id, label, lines) => Object.freeze({ id, label, text: lines.join("\n") });
export const TEMPLATES = Object.freeze({
"engineering-spec": template("engineering-spec", "Engineering spec", [
"## Engineering spec",
"[the feature or change, in a sentence]",
"",
"## Who reads it",
"The engineers who will build and review it.",
"",
"## What it should pin down",
"The behaviour, the parts of the code it touches, the interfaces between them, the simpler options we're turning down, and how we'll know it works.",
"",
"## Out of scope",
"[what this deliberately won't do]",
"",
"## What I already know",
"[constraints, links, earlier attempts]",
"Engineering spec for: [the feature or change, in a sentence]",
"Who reads it: the engineers who will build and review it.",
"What it should pin down: the behaviour, the parts of the code it touches, the interfaces between them, and how we'll know it works.",
"What I already know: [constraints, links, earlier attempts]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"## Product requirements",
"[the feature, in a sentence]",
"",
"## Who it's for",
"[the users], and the product, design and engineering people deciding on it.",
"",
"## What it should pin down",
"The problem, who has it, the evidence it's real, and how we'll measure success.",
"",
"## Not doing",
"[what this release leaves out]",
"",
"## What I already know",
"[customer asks, data, deadlines]",
"Product requirements for: [the feature, in a sentence]",
"Who it's for: [the users], and the product, design and engineering people deciding on it.",
"What it should pin down: the problem, who has it, what success looks like, and what waits for later.",
"What I already know: [customer asks, data, deadlines]",
]),
"design-decision": template("design-decision", "Design decision", [
"## Design decision",
"[the choice we're facing, in a sentence]",
"",
"## Who it's for",
"The engineers and architects who will live with it.",
"",
"## What it should pin down",
"The options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"",
"## Constraints",
"[performance, compatibility, deadlines, team skills]",
"A design decision to work out: [the choice we're facing, in a sentence]",
"Who it's for: the engineers and architects who will live with it.",
"What it should pin down: the options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"Constraints: [performance, compatibility, deadlines, team skills]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"## Test strategy",
"[the feature or area]",
"",
"## Who reads it",
"QA and the engineers writing the tests.",
"",
"## What it should pin down",
'What\'s riskiest, meaning what costs most if it breaks, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"",
"## What exists today",
"[current tests, known gaps]",
"Test strategy for: [the feature or area]",
"Who reads it: QA and the engineers writing the tests.",
'What it should pin down: what\'s risky, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"What exists today: [current tests, known gaps]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"## Scoping and rollout",
"[the feature or project]",
"",
"## Who reads it",
"The engineering manager, the product lead and the team.",
"",
"## What it should pin down",
"What's in the first release and what waits, the build order, risks to the timeline, how it reaches users (flags, stages, who sees it first), and how we roll it back.",
"",
"## Constraints",
"[dates, people, dependencies]",
"Scoping and rollout for: [the feature or project]",
"Who reads it: the engineering manager, the product lead and the team.",
"What it should pin down: what's in the first release and what waits, the build order, risks to the timeline, and how it reaches users (flags, stages, who goes first).",
"Constraints: [dates, people, dependencies]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"## Brainstorm to curated notes",
"[the topic or rough idea]",
"",
"## Who reads the notes",
"[the team or people this goes to]",
"",
"## What I want out of it",
"The ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"",
"## Starting thoughts",
"[anything already on your mind]",
"Brainstorm to turn into curated notes: [the topic or rough idea]",
"Who reads the notes: [the team or people this goes to]",
"What I want out of it: the ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"Starting thoughts: [anything already on your mind]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"## Bug investigation",
"[what's going wrong, in a sentence]",
"",
"## Steps to reproduce",
"1. [first step]",
"2. [next step]",
"",
"## Expected",
"[what should happen]",
"",
"## Actual",
"[what happens instead]",
"",
"## How often",
"[every time, sometimes, once]",
"",
"## Error or logs",
"[paste the exact text]",
"",
"## Where and since when",
"[environment, version, first seen]",
"Bug to investigate: [what's going wrong, in a sentence]",
"Steps to reproduce: [1. ... 2. ...]",
"Expected: [what should happen]. Actual: [what happens instead]",
"Where and since when: [environment, version, first seen]",
]),
"small-change": template("small-change", "Small change", [
"## Small change",
"[what to change, in a sentence]",
"",
"## Where",
"[the file, screen or command, if you know it]",
"",
"## Leave alone",
"[anything that must not change]",
"",
"## Done when",
"[the command to run or the thing to check]",
"Small change: [what to change, in a sentence]",
"Where: [the file, screen or command, if you know it]",
"Done when: [how you'll tell it worked]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"## Copy or content tweak",
"[the screen, message, email or doc]",
"",
"## Current text",
"[paste it]",
"",
"## New text",
"[paste it, or describe the tone you want]",
"",
"## Who reads it",
"[the people who see it]",
"Change the wording of: [the screen, message, email or doc]",
"Current text: [paste it]",
"New text: [paste it, or describe the tone you want]",
"Who reads it: [the people who see it]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"## UI polish",
"[the screen or component]",
"",
"## What looks or feels off",
"[spacing, alignment, colour, states, small screens]",
"",
"## What good looks like",
"[a reference, screenshot or description]",
"",
"## Leave alone",
"[anything that must not move]",
"UI polish on: [the screen or component]",
"What looks or feels off: [spacing, alignment, colour, states, small screens]",
"What good looks like: [a reference, screenshot or description]",
"Leave alone: [anything that must not move]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"## Visual prototype",
"[the screen or component to mock up]",
"",
"## What to show",
"[the states or flows to click through]",
"",
"## What I want to learn",
"[the question it should answer]",
"",
"## Where it lives",
"A prototypes/ folder [or its own branch], never wired into the real code.",
"A throwaway visual prototype of: [the screen or component]",
"What to show: [the states or flows to click through]",
"What I want to learn: [the question it should answer]",
"Where it lives: a prototypes/ folder [or its own branch], never wired into the real code.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"## Add a test",
"[the function, behaviour or bug]",
"",
"## Cases to cover",
"- [the normal case]",
"- [the edge cases]",
"- [the failure or bug it guards against]",
"",
"## Where tests live",
"[the test file or folder, if you know it]",
"Add a test for: [the function, behaviour or bug]",
"Cases to cover: [the normal case, the edge cases, the bug it guards against]",
"Where tests live: [the test file or folder, if you know it]",
]),
"record-decision": template("record-decision", "Record a decision", [
"## Record a decision",
"[the decision we've already made, in a sentence]",
"",
"## Why",
"[what forced the choice, and the options we turned down]",
"",
"## What it commits us to",
"[the consequences]",
"",
"## Save it in",
"docs/adr/ [or wherever this repo keeps them]",
]),
refactor: template("refactor", "Refactor", [
"## Refactor",
"[what to restructure, in a sentence]",
"",
"## Why now",
"[what the current shape makes hard]",
"",
"## Behaviour that must not change",
"[the public API, outputs or tests that must stay the same]",
"",
"## Done when",
"[the tests that must still pass, and the shape it ends in]",
]),
"performance-problem": template("performance-problem", "Performance problem", [
"## Performance problem",
"[what's slow, in a sentence]",
"",
"## How it's measured today",
"[the number, and how you got it]",
"",
"## Target",
"[the number that counts as fixed]",
"",
"## Where",
"[the endpoint, page, query or job]",
]),
"dependency-upgrade": template("dependency-upgrade", "Dependency upgrade", [
"## Dependency upgrade",
"[the package, from version to version]",
"",
"## Why",
"[security fix, a feature we need, end of support]",
"",
"## Known breaking changes",
'[release notes link, or "not checked yet"]',
"",
"## Done when",
"[the build, tests or checks that must pass]",
]),
spike: template("spike", "Spike", [
"## Spike",
"[the question to answer, in a sentence]",
"",
"## Why it matters",
"[the decision waiting on the answer]",
"",
"## Time box",
"[how long before we stop and decide anyway]",
"",
"## Answered when",
"[the evidence that would settle it]",
]),
integration: template("integration", "Integration", [
"## Integration",
"[the system we're connecting to, and why]",
"",
"## What flows",
"[the data or events, and in which direction]",
"",
"## Their side",
"[API docs, auth method, rate limits, test sandbox]",
"",
"## When it fails",
"[what should happen if they're down or slow]",
]),
"data-migration": template("data-migration", "Data migration", [
"## Data migration",
"[what moves or changes shape]",
"",
"## Size and downtime",
"[row counts, and whether users can stay on while it runs]",
"",
"## Rollback",
"[how we undo it if it goes wrong]",
"",
"## Done when",
"[the checks that prove nothing was lost]",
"Record a decision we've already made: [the decision, in a sentence]",
"Why: [the reasons, and what we turned down]",
"What it commits us to: [the consequences]",
"Save it as an ADR in: docs/adr/ [or wherever this repo keeps them]",
]),
});
@@ -309,28 +123,28 @@ const orders = (byRole) => Object.freeze(Object.fromEntries(Object.entries(byRol
// One full order per role per skill. No "none" row: Not set reads Engineer's.
export const TEMPLATE_ORDERS = Object.freeze({
pathfinder: orders({
engineer: ["engineering-spec", "design-decision", "spike", "integration", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "spike", "engineering-spec", "design-decision", "integration", "test-strategy"],
architect: ["design-decision", "engineering-spec", "integration", "spike", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "spike", "engineering-spec", "scoping-rollout", "integration", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "spike", "product-requirements", "integration", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "spike", "test-strategy", "design-decision", "integration", "brainstorm-notes"],
engineer: ["engineering-spec", "design-decision", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "engineering-spec", "design-decision", "test-strategy"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "design-decision", "brainstorm-notes"],
}),
plan: orders({
engineer: ["engineering-spec", "bug-investigation", "refactor", "performance-problem", "integration", "data-migration", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "integration", "test-strategy", "design-decision", "performance-problem", "bug-investigation", "data-migration", "refactor"],
architect: ["design-decision", "engineering-spec", "data-migration", "integration", "refactor", "scoping-rollout", "performance-problem", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "performance-problem", "test-strategy", "bug-investigation", "integration", "refactor", "data-migration"],
qa: ["test-strategy", "bug-investigation", "performance-problem", "engineering-spec", "data-migration", "integration", "product-requirements", "scoping-rollout", "refactor", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "data-migration", "product-requirements", "test-strategy", "integration", "bug-investigation", "performance-problem", "refactor", "design-decision"],
engineer: ["engineering-spec", "bug-investigation", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "test-strategy", "design-decision", "bug-investigation"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "bug-investigation"],
qa: ["test-strategy", "bug-investigation", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "bug-investigation", "design-decision"],
}),
"quick-task": orders({
engineer: ["small-change", "bug-investigation", "refactor", "add-a-test", "dependency-upgrade", "performance-problem", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "performance-problem", "add-a-test", "record-decision", "dependency-upgrade", "refactor"],
architect: ["record-decision", "refactor", "small-change", "dependency-upgrade", "performance-problem", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "performance-problem", "add-a-test", "refactor", "dependency-upgrade", "record-decision"],
qa: ["add-a-test", "bug-investigation", "performance-problem", "small-change", "dependency-upgrade", "ui-polish", "refactor", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "dependency-upgrade", "add-a-test", "bug-investigation", "performance-problem", "refactor", "copy-tweak", "ui-polish", "visual-prototype"],
engineer: ["small-change", "bug-investigation", "add-a-test", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "add-a-test", "record-decision"],
architect: ["record-decision", "small-change", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "add-a-test", "record-decision"],
qa: ["add-a-test", "bug-investigation", "small-change", "ui-polish", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "add-a-test", "bug-investigation", "copy-tweak", "ui-polish", "visual-prototype"],
}),
});
@@ -88,7 +88,7 @@ export function cleanSetting(input) {
export const FRAME_LINES = Object.freeze([
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,14 +201,11 @@ export function switchLabel(frame) {
}
// What the Subagents tab draws: the working-alone note, or one row per helper
// in the order the agent reported them. A real helper supersedes the
// working-alone marker, so the note only draws when no helper was ever
// reported. A result shows once the helper ended.
// in the order the agent reported them. A result shows once the helper ended.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
const real = list.filter((h) => h.alone !== true);
if (!real.length) return { alone: list.some((h) => h.alone === true), rows: [] };
const rows = real.map(({ id, title, ask, state, result }) => ({
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -57,7 +57,7 @@ Run against EVERY finding. If any question raises doubt, re-investigate or drop.
**Finding survives (real bug):** Reviewer finds `processItems()` at line 47 accesses `items[0].id` with no empty-array check. Re-reads source — confirmed no guard. Traces callers — `orchestrator.js:82` can pass empty array. Adversarial check passes (correctness issue, additive fix). Presented at High.
**Finding dropped (pcweb-jira false positive):** Reviewer recommends removing `jira-api-catalog.md` from consumer loading to "reduce context." Adversarial check: "Does my fix remove something the system depends on?" YES — agents Read these files at runtime to construct valid API calls. Four of five checks fail. Dropped.
**Finding dropped (jira skill false positive):** Reviewer recommends removing `jira-api-catalog.md` from consumer loading to "reduce context." Adversarial check: "Does my fix remove something the system depends on?" YES — agents Read these files at runtime to construct valid API calls. Four of five checks fail. Dropped.
**Finding dropped (false consolidation):** Reviewer flags per-platform config files as "duplicates." Adversarial check: "Am I optimizing for the wrong metric?" YES — platforms have distinct values and will diverge further. Separation is a design choice. Dropped.
@@ -667,7 +667,7 @@ your next `chat` check.
Subagents: on (revision 2) — a console setting, not typed by the person.
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
With no way to start helpers, report one "working alone" entry for this skill run instead.
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
At most 3 helpers at once.
```
@@ -716,11 +716,8 @@ page never hears from a helper directly:
- Questions for the person stay with you, never with a helper: most harnesses
give helpers no way to ask, and an answer only reaches the agent holding the
session.
- **No way to start helpers at all?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
entry for the skill run instead. The tab then says you are working alone.
It is a claim about your tools, not about the moment — post it only when no
helper mechanism exists. Reporting a real helper removes it, so an early
`alone` can never hide a later helper.
- **Pathfinder:** research questions always use helpers and are always
reported, whatever the switch says. The switch governs recon, sketches and
lookups beside the conversation.
@@ -1211,10 +1211,6 @@ export function applyPatch(state, patch) {
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
// A real helper report supersedes the working-alone marker, whether it
// arrives after one or beside one.
if (next.helpers.some((h) => isPlainObject(h) && h.alone !== true))
next.helpers = next.helpers.filter((h) => !(isPlainObject(h) && h.alone === true));
break;
case "docs":
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
@@ -4345,11 +4345,8 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,9 +1540,8 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent reported it has no
way to start helpers here. If it starts one after all, the note
goes away and the helper's row shows instead.
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,271 +36,85 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording was revised in v2.5.1 (Markdown sections); a change is a page change.
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
const template = (id, label, lines) => Object.freeze({ id, label, text: lines.join("\n") });
export const TEMPLATES = Object.freeze({
"engineering-spec": template("engineering-spec", "Engineering spec", [
"## Engineering spec",
"[the feature or change, in a sentence]",
"",
"## Who reads it",
"The engineers who will build and review it.",
"",
"## What it should pin down",
"The behaviour, the parts of the code it touches, the interfaces between them, the simpler options we're turning down, and how we'll know it works.",
"",
"## Out of scope",
"[what this deliberately won't do]",
"",
"## What I already know",
"[constraints, links, earlier attempts]",
"Engineering spec for: [the feature or change, in a sentence]",
"Who reads it: the engineers who will build and review it.",
"What it should pin down: the behaviour, the parts of the code it touches, the interfaces between them, and how we'll know it works.",
"What I already know: [constraints, links, earlier attempts]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"## Product requirements",
"[the feature, in a sentence]",
"",
"## Who it's for",
"[the users], and the product, design and engineering people deciding on it.",
"",
"## What it should pin down",
"The problem, who has it, the evidence it's real, and how we'll measure success.",
"",
"## Not doing",
"[what this release leaves out]",
"",
"## What I already know",
"[customer asks, data, deadlines]",
"Product requirements for: [the feature, in a sentence]",
"Who it's for: [the users], and the product, design and engineering people deciding on it.",
"What it should pin down: the problem, who has it, what success looks like, and what waits for later.",
"What I already know: [customer asks, data, deadlines]",
]),
"design-decision": template("design-decision", "Design decision", [
"## Design decision",
"[the choice we're facing, in a sentence]",
"",
"## Who it's for",
"The engineers and architects who will live with it.",
"",
"## What it should pin down",
"The options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"",
"## Constraints",
"[performance, compatibility, deadlines, team skills]",
"A design decision to work out: [the choice we're facing, in a sentence]",
"Who it's for: the engineers and architects who will live with it.",
"What it should pin down: the options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"Constraints: [performance, compatibility, deadlines, team skills]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"## Test strategy",
"[the feature or area]",
"",
"## Who reads it",
"QA and the engineers writing the tests.",
"",
"## What it should pin down",
'What\'s riskiest, meaning what costs most if it breaks, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"",
"## What exists today",
"[current tests, known gaps]",
"Test strategy for: [the feature or area]",
"Who reads it: QA and the engineers writing the tests.",
'What it should pin down: what\'s risky, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"What exists today: [current tests, known gaps]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"## Scoping and rollout",
"[the feature or project]",
"",
"## Who reads it",
"The engineering manager, the product lead and the team.",
"",
"## What it should pin down",
"What's in the first release and what waits, the build order, risks to the timeline, how it reaches users (flags, stages, who sees it first), and how we roll it back.",
"",
"## Constraints",
"[dates, people, dependencies]",
"Scoping and rollout for: [the feature or project]",
"Who reads it: the engineering manager, the product lead and the team.",
"What it should pin down: what's in the first release and what waits, the build order, risks to the timeline, and how it reaches users (flags, stages, who goes first).",
"Constraints: [dates, people, dependencies]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"## Brainstorm to curated notes",
"[the topic or rough idea]",
"",
"## Who reads the notes",
"[the team or people this goes to]",
"",
"## What I want out of it",
"The ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"",
"## Starting thoughts",
"[anything already on your mind]",
"Brainstorm to turn into curated notes: [the topic or rough idea]",
"Who reads the notes: [the team or people this goes to]",
"What I want out of it: the ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"Starting thoughts: [anything already on your mind]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"## Bug investigation",
"[what's going wrong, in a sentence]",
"",
"## Steps to reproduce",
"1. [first step]",
"2. [next step]",
"",
"## Expected",
"[what should happen]",
"",
"## Actual",
"[what happens instead]",
"",
"## How often",
"[every time, sometimes, once]",
"",
"## Error or logs",
"[paste the exact text]",
"",
"## Where and since when",
"[environment, version, first seen]",
"Bug to investigate: [what's going wrong, in a sentence]",
"Steps to reproduce: [1. ... 2. ...]",
"Expected: [what should happen]. Actual: [what happens instead]",
"Where and since when: [environment, version, first seen]",
]),
"small-change": template("small-change", "Small change", [
"## Small change",
"[what to change, in a sentence]",
"",
"## Where",
"[the file, screen or command, if you know it]",
"",
"## Leave alone",
"[anything that must not change]",
"",
"## Done when",
"[the command to run or the thing to check]",
"Small change: [what to change, in a sentence]",
"Where: [the file, screen or command, if you know it]",
"Done when: [how you'll tell it worked]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"## Copy or content tweak",
"[the screen, message, email or doc]",
"",
"## Current text",
"[paste it]",
"",
"## New text",
"[paste it, or describe the tone you want]",
"",
"## Who reads it",
"[the people who see it]",
"Change the wording of: [the screen, message, email or doc]",
"Current text: [paste it]",
"New text: [paste it, or describe the tone you want]",
"Who reads it: [the people who see it]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"## UI polish",
"[the screen or component]",
"",
"## What looks or feels off",
"[spacing, alignment, colour, states, small screens]",
"",
"## What good looks like",
"[a reference, screenshot or description]",
"",
"## Leave alone",
"[anything that must not move]",
"UI polish on: [the screen or component]",
"What looks or feels off: [spacing, alignment, colour, states, small screens]",
"What good looks like: [a reference, screenshot or description]",
"Leave alone: [anything that must not move]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"## Visual prototype",
"[the screen or component to mock up]",
"",
"## What to show",
"[the states or flows to click through]",
"",
"## What I want to learn",
"[the question it should answer]",
"",
"## Where it lives",
"A prototypes/ folder [or its own branch], never wired into the real code.",
"A throwaway visual prototype of: [the screen or component]",
"What to show: [the states or flows to click through]",
"What I want to learn: [the question it should answer]",
"Where it lives: a prototypes/ folder [or its own branch], never wired into the real code.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"## Add a test",
"[the function, behaviour or bug]",
"",
"## Cases to cover",
"- [the normal case]",
"- [the edge cases]",
"- [the failure or bug it guards against]",
"",
"## Where tests live",
"[the test file or folder, if you know it]",
"Add a test for: [the function, behaviour or bug]",
"Cases to cover: [the normal case, the edge cases, the bug it guards against]",
"Where tests live: [the test file or folder, if you know it]",
]),
"record-decision": template("record-decision", "Record a decision", [
"## Record a decision",
"[the decision we've already made, in a sentence]",
"",
"## Why",
"[what forced the choice, and the options we turned down]",
"",
"## What it commits us to",
"[the consequences]",
"",
"## Save it in",
"docs/adr/ [or wherever this repo keeps them]",
]),
refactor: template("refactor", "Refactor", [
"## Refactor",
"[what to restructure, in a sentence]",
"",
"## Why now",
"[what the current shape makes hard]",
"",
"## Behaviour that must not change",
"[the public API, outputs or tests that must stay the same]",
"",
"## Done when",
"[the tests that must still pass, and the shape it ends in]",
]),
"performance-problem": template("performance-problem", "Performance problem", [
"## Performance problem",
"[what's slow, in a sentence]",
"",
"## How it's measured today",
"[the number, and how you got it]",
"",
"## Target",
"[the number that counts as fixed]",
"",
"## Where",
"[the endpoint, page, query or job]",
]),
"dependency-upgrade": template("dependency-upgrade", "Dependency upgrade", [
"## Dependency upgrade",
"[the package, from version to version]",
"",
"## Why",
"[security fix, a feature we need, end of support]",
"",
"## Known breaking changes",
'[release notes link, or "not checked yet"]',
"",
"## Done when",
"[the build, tests or checks that must pass]",
]),
spike: template("spike", "Spike", [
"## Spike",
"[the question to answer, in a sentence]",
"",
"## Why it matters",
"[the decision waiting on the answer]",
"",
"## Time box",
"[how long before we stop and decide anyway]",
"",
"## Answered when",
"[the evidence that would settle it]",
]),
integration: template("integration", "Integration", [
"## Integration",
"[the system we're connecting to, and why]",
"",
"## What flows",
"[the data or events, and in which direction]",
"",
"## Their side",
"[API docs, auth method, rate limits, test sandbox]",
"",
"## When it fails",
"[what should happen if they're down or slow]",
]),
"data-migration": template("data-migration", "Data migration", [
"## Data migration",
"[what moves or changes shape]",
"",
"## Size and downtime",
"[row counts, and whether users can stay on while it runs]",
"",
"## Rollback",
"[how we undo it if it goes wrong]",
"",
"## Done when",
"[the checks that prove nothing was lost]",
"Record a decision we've already made: [the decision, in a sentence]",
"Why: [the reasons, and what we turned down]",
"What it commits us to: [the consequences]",
"Save it as an ADR in: docs/adr/ [or wherever this repo keeps them]",
]),
});
@@ -309,28 +123,28 @@ const orders = (byRole) => Object.freeze(Object.fromEntries(Object.entries(byRol
// One full order per role per skill. No "none" row: Not set reads Engineer's.
export const TEMPLATE_ORDERS = Object.freeze({
pathfinder: orders({
engineer: ["engineering-spec", "design-decision", "spike", "integration", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "spike", "engineering-spec", "design-decision", "integration", "test-strategy"],
architect: ["design-decision", "engineering-spec", "integration", "spike", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "spike", "engineering-spec", "scoping-rollout", "integration", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "spike", "product-requirements", "integration", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "spike", "test-strategy", "design-decision", "integration", "brainstorm-notes"],
engineer: ["engineering-spec", "design-decision", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "engineering-spec", "design-decision", "test-strategy"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "design-decision", "brainstorm-notes"],
}),
plan: orders({
engineer: ["engineering-spec", "bug-investigation", "refactor", "performance-problem", "integration", "data-migration", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "integration", "test-strategy", "design-decision", "performance-problem", "bug-investigation", "data-migration", "refactor"],
architect: ["design-decision", "engineering-spec", "data-migration", "integration", "refactor", "scoping-rollout", "performance-problem", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "performance-problem", "test-strategy", "bug-investigation", "integration", "refactor", "data-migration"],
qa: ["test-strategy", "bug-investigation", "performance-problem", "engineering-spec", "data-migration", "integration", "product-requirements", "scoping-rollout", "refactor", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "data-migration", "product-requirements", "test-strategy", "integration", "bug-investigation", "performance-problem", "refactor", "design-decision"],
engineer: ["engineering-spec", "bug-investigation", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "test-strategy", "design-decision", "bug-investigation"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "bug-investigation"],
qa: ["test-strategy", "bug-investigation", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "bug-investigation", "design-decision"],
}),
"quick-task": orders({
engineer: ["small-change", "bug-investigation", "refactor", "add-a-test", "dependency-upgrade", "performance-problem", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "performance-problem", "add-a-test", "record-decision", "dependency-upgrade", "refactor"],
architect: ["record-decision", "refactor", "small-change", "dependency-upgrade", "performance-problem", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "performance-problem", "add-a-test", "refactor", "dependency-upgrade", "record-decision"],
qa: ["add-a-test", "bug-investigation", "performance-problem", "small-change", "dependency-upgrade", "ui-polish", "refactor", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "dependency-upgrade", "add-a-test", "bug-investigation", "performance-problem", "refactor", "copy-tweak", "ui-polish", "visual-prototype"],
engineer: ["small-change", "bug-investigation", "add-a-test", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "add-a-test", "record-decision"],
architect: ["record-decision", "small-change", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "add-a-test", "record-decision"],
qa: ["add-a-test", "bug-investigation", "small-change", "ui-polish", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "add-a-test", "bug-investigation", "copy-tweak", "ui-polish", "visual-prototype"],
}),
});
@@ -88,7 +88,7 @@ export function cleanSetting(input) {
export const FRAME_LINES = Object.freeze([
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,14 +201,11 @@ export function switchLabel(frame) {
}
// What the Subagents tab draws: the working-alone note, or one row per helper
// in the order the agent reported them. A real helper supersedes the
// working-alone marker, so the note only draws when no helper was ever
// reported. A result shows once the helper ended.
// in the order the agent reported them. A result shows once the helper ended.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
const real = list.filter((h) => h.alone !== true);
if (!real.length) return { alone: list.some((h) => h.alone === true), rows: [] };
const rows = real.map(({ id, title, ask, state, result }) => ({
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -10,7 +10,7 @@
//
// and derives the ticket from a branch named <prefix>/<TICKET-ID>-description,
// where the ticket is an uppercase project key, a hyphen and an integer
// (PCWEB-10968). This script reads the branch, extracts the ticket and prints
// (ABC-10968). This script reads the branch, extracts the ticket and prints
// the exact command, so no prompt re-implements the rule by eye.
import { execFileSync } from "node:child_process";
@@ -96,7 +96,7 @@ run(USAGE, async (argv) => {
let branch = null;
let ticket = args.ticket ? args.ticket.trim() : null;
if (ticket && !/^[A-Z][A-Z0-9]*-\d+$/.test(ticket)) fail(EXIT.INVALID, "bad-ticket", `"${ticket}" is not an uppercase KEY-123 ticket ID.`, "Pass a ticket like PCWEB-10968.");
if (ticket && !/^[A-Z][A-Z0-9]*-\d+$/.test(ticket)) fail(EXIT.INVALID, "bad-ticket", `"${ticket}" is not an uppercase KEY-123 ticket ID.`, "Pass a ticket like ABC-10968.");
if (!ticket) {
branch = currentBranch();
ticket = ticketFromBranch(branch);
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -57,7 +57,7 @@ Run against EVERY finding. If any question raises doubt, re-investigate or drop.
**Finding survives (real bug):** Reviewer finds `processItems()` at line 47 accesses `items[0].id` with no empty-array check. Re-reads source — confirmed no guard. Traces callers — `orchestrator.js:82` can pass empty array. Adversarial check passes (correctness issue, additive fix). Presented at High.
**Finding dropped (pcweb-jira false positive):** Reviewer recommends removing `jira-api-catalog.md` from consumer loading to "reduce context." Adversarial check: "Does my fix remove something the system depends on?" YES — agents Read these files at runtime to construct valid API calls. Four of five checks fail. Dropped.
**Finding dropped (jira skill false positive):** Reviewer recommends removing `jira-api-catalog.md` from consumer loading to "reduce context." Adversarial check: "Does my fix remove something the system depends on?" YES — agents Read these files at runtime to construct valid API calls. Four of five checks fail. Dropped.
**Finding dropped (false consolidation):** Reviewer flags per-platform config files as "duplicates." Adversarial check: "Am I optimizing for the wrong metric?" YES — platforms have distinct values and will diverge further. Separation is a design choice. Dropped.
@@ -667,7 +667,7 @@ your next `chat` check.
Subagents: on (revision 2) — a console setting, not typed by the person.
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
With no way to start helpers, report one "working alone" entry for this skill run instead.
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
At most 3 helpers at once.
```
@@ -716,11 +716,8 @@ page never hears from a helper directly:
- Questions for the person stay with you, never with a helper: most harnesses
give helpers no way to ask, and an answer only reaches the agent holding the
session.
- **No way to start helpers at all?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
entry for the skill run instead. The tab then says you are working alone.
It is a claim about your tools, not about the moment — post it only when no
helper mechanism exists. Reporting a real helper removes it, so an early
`alone` can never hide a later helper.
- **Pathfinder:** research questions always use helpers and are always
reported, whatever the switch says. The switch governs recon, sketches and
lookups beside the conversation.
@@ -1211,10 +1211,6 @@ export function applyPatch(state, patch) {
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
// A real helper report supersedes the working-alone marker, whether it
// arrives after one or beside one.
if (next.helpers.some((h) => isPlainObject(h) && h.alone !== true))
next.helpers = next.helpers.filter((h) => !(isPlainObject(h) && h.alone === true));
break;
case "docs":
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
@@ -4345,11 +4345,8 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,9 +1540,8 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent reported it has no
way to start helpers here. If it starts one after all, the note
goes away and the helper's row shows instead.
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,271 +36,85 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording was revised in v2.5.1 (Markdown sections); a change is a page change.
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
const template = (id, label, lines) => Object.freeze({ id, label, text: lines.join("\n") });
export const TEMPLATES = Object.freeze({
"engineering-spec": template("engineering-spec", "Engineering spec", [
"## Engineering spec",
"[the feature or change, in a sentence]",
"",
"## Who reads it",
"The engineers who will build and review it.",
"",
"## What it should pin down",
"The behaviour, the parts of the code it touches, the interfaces between them, the simpler options we're turning down, and how we'll know it works.",
"",
"## Out of scope",
"[what this deliberately won't do]",
"",
"## What I already know",
"[constraints, links, earlier attempts]",
"Engineering spec for: [the feature or change, in a sentence]",
"Who reads it: the engineers who will build and review it.",
"What it should pin down: the behaviour, the parts of the code it touches, the interfaces between them, and how we'll know it works.",
"What I already know: [constraints, links, earlier attempts]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"## Product requirements",
"[the feature, in a sentence]",
"",
"## Who it's for",
"[the users], and the product, design and engineering people deciding on it.",
"",
"## What it should pin down",
"The problem, who has it, the evidence it's real, and how we'll measure success.",
"",
"## Not doing",
"[what this release leaves out]",
"",
"## What I already know",
"[customer asks, data, deadlines]",
"Product requirements for: [the feature, in a sentence]",
"Who it's for: [the users], and the product, design and engineering people deciding on it.",
"What it should pin down: the problem, who has it, what success looks like, and what waits for later.",
"What I already know: [customer asks, data, deadlines]",
]),
"design-decision": template("design-decision", "Design decision", [
"## Design decision",
"[the choice we're facing, in a sentence]",
"",
"## Who it's for",
"The engineers and architects who will live with it.",
"",
"## What it should pin down",
"The options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"",
"## Constraints",
"[performance, compatibility, deadlines, team skills]",
"A design decision to work out: [the choice we're facing, in a sentence]",
"Who it's for: the engineers and architects who will live with it.",
"What it should pin down: the options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"Constraints: [performance, compatibility, deadlines, team skills]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"## Test strategy",
"[the feature or area]",
"",
"## Who reads it",
"QA and the engineers writing the tests.",
"",
"## What it should pin down",
'What\'s riskiest, meaning what costs most if it breaks, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"",
"## What exists today",
"[current tests, known gaps]",
"Test strategy for: [the feature or area]",
"Who reads it: QA and the engineers writing the tests.",
'What it should pin down: what\'s risky, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"What exists today: [current tests, known gaps]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"## Scoping and rollout",
"[the feature or project]",
"",
"## Who reads it",
"The engineering manager, the product lead and the team.",
"",
"## What it should pin down",
"What's in the first release and what waits, the build order, risks to the timeline, how it reaches users (flags, stages, who sees it first), and how we roll it back.",
"",
"## Constraints",
"[dates, people, dependencies]",
"Scoping and rollout for: [the feature or project]",
"Who reads it: the engineering manager, the product lead and the team.",
"What it should pin down: what's in the first release and what waits, the build order, risks to the timeline, and how it reaches users (flags, stages, who goes first).",
"Constraints: [dates, people, dependencies]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"## Brainstorm to curated notes",
"[the topic or rough idea]",
"",
"## Who reads the notes",
"[the team or people this goes to]",
"",
"## What I want out of it",
"The ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"",
"## Starting thoughts",
"[anything already on your mind]",
"Brainstorm to turn into curated notes: [the topic or rough idea]",
"Who reads the notes: [the team or people this goes to]",
"What I want out of it: the ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"Starting thoughts: [anything already on your mind]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"## Bug investigation",
"[what's going wrong, in a sentence]",
"",
"## Steps to reproduce",
"1. [first step]",
"2. [next step]",
"",
"## Expected",
"[what should happen]",
"",
"## Actual",
"[what happens instead]",
"",
"## How often",
"[every time, sometimes, once]",
"",
"## Error or logs",
"[paste the exact text]",
"",
"## Where and since when",
"[environment, version, first seen]",
"Bug to investigate: [what's going wrong, in a sentence]",
"Steps to reproduce: [1. ... 2. ...]",
"Expected: [what should happen]. Actual: [what happens instead]",
"Where and since when: [environment, version, first seen]",
]),
"small-change": template("small-change", "Small change", [
"## Small change",
"[what to change, in a sentence]",
"",
"## Where",
"[the file, screen or command, if you know it]",
"",
"## Leave alone",
"[anything that must not change]",
"",
"## Done when",
"[the command to run or the thing to check]",
"Small change: [what to change, in a sentence]",
"Where: [the file, screen or command, if you know it]",
"Done when: [how you'll tell it worked]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"## Copy or content tweak",
"[the screen, message, email or doc]",
"",
"## Current text",
"[paste it]",
"",
"## New text",
"[paste it, or describe the tone you want]",
"",
"## Who reads it",
"[the people who see it]",
"Change the wording of: [the screen, message, email or doc]",
"Current text: [paste it]",
"New text: [paste it, or describe the tone you want]",
"Who reads it: [the people who see it]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"## UI polish",
"[the screen or component]",
"",
"## What looks or feels off",
"[spacing, alignment, colour, states, small screens]",
"",
"## What good looks like",
"[a reference, screenshot or description]",
"",
"## Leave alone",
"[anything that must not move]",
"UI polish on: [the screen or component]",
"What looks or feels off: [spacing, alignment, colour, states, small screens]",
"What good looks like: [a reference, screenshot or description]",
"Leave alone: [anything that must not move]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"## Visual prototype",
"[the screen or component to mock up]",
"",
"## What to show",
"[the states or flows to click through]",
"",
"## What I want to learn",
"[the question it should answer]",
"",
"## Where it lives",
"A prototypes/ folder [or its own branch], never wired into the real code.",
"A throwaway visual prototype of: [the screen or component]",
"What to show: [the states or flows to click through]",
"What I want to learn: [the question it should answer]",
"Where it lives: a prototypes/ folder [or its own branch], never wired into the real code.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"## Add a test",
"[the function, behaviour or bug]",
"",
"## Cases to cover",
"- [the normal case]",
"- [the edge cases]",
"- [the failure or bug it guards against]",
"",
"## Where tests live",
"[the test file or folder, if you know it]",
"Add a test for: [the function, behaviour or bug]",
"Cases to cover: [the normal case, the edge cases, the bug it guards against]",
"Where tests live: [the test file or folder, if you know it]",
]),
"record-decision": template("record-decision", "Record a decision", [
"## Record a decision",
"[the decision we've already made, in a sentence]",
"",
"## Why",
"[what forced the choice, and the options we turned down]",
"",
"## What it commits us to",
"[the consequences]",
"",
"## Save it in",
"docs/adr/ [or wherever this repo keeps them]",
]),
refactor: template("refactor", "Refactor", [
"## Refactor",
"[what to restructure, in a sentence]",
"",
"## Why now",
"[what the current shape makes hard]",
"",
"## Behaviour that must not change",
"[the public API, outputs or tests that must stay the same]",
"",
"## Done when",
"[the tests that must still pass, and the shape it ends in]",
]),
"performance-problem": template("performance-problem", "Performance problem", [
"## Performance problem",
"[what's slow, in a sentence]",
"",
"## How it's measured today",
"[the number, and how you got it]",
"",
"## Target",
"[the number that counts as fixed]",
"",
"## Where",
"[the endpoint, page, query or job]",
]),
"dependency-upgrade": template("dependency-upgrade", "Dependency upgrade", [
"## Dependency upgrade",
"[the package, from version to version]",
"",
"## Why",
"[security fix, a feature we need, end of support]",
"",
"## Known breaking changes",
'[release notes link, or "not checked yet"]',
"",
"## Done when",
"[the build, tests or checks that must pass]",
]),
spike: template("spike", "Spike", [
"## Spike",
"[the question to answer, in a sentence]",
"",
"## Why it matters",
"[the decision waiting on the answer]",
"",
"## Time box",
"[how long before we stop and decide anyway]",
"",
"## Answered when",
"[the evidence that would settle it]",
]),
integration: template("integration", "Integration", [
"## Integration",
"[the system we're connecting to, and why]",
"",
"## What flows",
"[the data or events, and in which direction]",
"",
"## Their side",
"[API docs, auth method, rate limits, test sandbox]",
"",
"## When it fails",
"[what should happen if they're down or slow]",
]),
"data-migration": template("data-migration", "Data migration", [
"## Data migration",
"[what moves or changes shape]",
"",
"## Size and downtime",
"[row counts, and whether users can stay on while it runs]",
"",
"## Rollback",
"[how we undo it if it goes wrong]",
"",
"## Done when",
"[the checks that prove nothing was lost]",
"Record a decision we've already made: [the decision, in a sentence]",
"Why: [the reasons, and what we turned down]",
"What it commits us to: [the consequences]",
"Save it as an ADR in: docs/adr/ [or wherever this repo keeps them]",
]),
});
@@ -309,28 +123,28 @@ const orders = (byRole) => Object.freeze(Object.fromEntries(Object.entries(byRol
// One full order per role per skill. No "none" row: Not set reads Engineer's.
export const TEMPLATE_ORDERS = Object.freeze({
pathfinder: orders({
engineer: ["engineering-spec", "design-decision", "spike", "integration", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "spike", "engineering-spec", "design-decision", "integration", "test-strategy"],
architect: ["design-decision", "engineering-spec", "integration", "spike", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "spike", "engineering-spec", "scoping-rollout", "integration", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "spike", "product-requirements", "integration", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "spike", "test-strategy", "design-decision", "integration", "brainstorm-notes"],
engineer: ["engineering-spec", "design-decision", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "engineering-spec", "design-decision", "test-strategy"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "design-decision", "brainstorm-notes"],
}),
plan: orders({
engineer: ["engineering-spec", "bug-investigation", "refactor", "performance-problem", "integration", "data-migration", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "integration", "test-strategy", "design-decision", "performance-problem", "bug-investigation", "data-migration", "refactor"],
architect: ["design-decision", "engineering-spec", "data-migration", "integration", "refactor", "scoping-rollout", "performance-problem", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "performance-problem", "test-strategy", "bug-investigation", "integration", "refactor", "data-migration"],
qa: ["test-strategy", "bug-investigation", "performance-problem", "engineering-spec", "data-migration", "integration", "product-requirements", "scoping-rollout", "refactor", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "data-migration", "product-requirements", "test-strategy", "integration", "bug-investigation", "performance-problem", "refactor", "design-decision"],
engineer: ["engineering-spec", "bug-investigation", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "test-strategy", "design-decision", "bug-investigation"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "bug-investigation"],
qa: ["test-strategy", "bug-investigation", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "bug-investigation", "design-decision"],
}),
"quick-task": orders({
engineer: ["small-change", "bug-investigation", "refactor", "add-a-test", "dependency-upgrade", "performance-problem", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "performance-problem", "add-a-test", "record-decision", "dependency-upgrade", "refactor"],
architect: ["record-decision", "refactor", "small-change", "dependency-upgrade", "performance-problem", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "performance-problem", "add-a-test", "refactor", "dependency-upgrade", "record-decision"],
qa: ["add-a-test", "bug-investigation", "performance-problem", "small-change", "dependency-upgrade", "ui-polish", "refactor", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "dependency-upgrade", "add-a-test", "bug-investigation", "performance-problem", "refactor", "copy-tweak", "ui-polish", "visual-prototype"],
engineer: ["small-change", "bug-investigation", "add-a-test", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "add-a-test", "record-decision"],
architect: ["record-decision", "small-change", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "add-a-test", "record-decision"],
qa: ["add-a-test", "bug-investigation", "small-change", "ui-polish", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "add-a-test", "bug-investigation", "copy-tweak", "ui-polish", "visual-prototype"],
}),
});
@@ -88,7 +88,7 @@ export function cleanSetting(input) {
export const FRAME_LINES = Object.freeze([
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,14 +201,11 @@ export function switchLabel(frame) {
}
// What the Subagents tab draws: the working-alone note, or one row per helper
// in the order the agent reported them. A real helper supersedes the
// working-alone marker, so the note only draws when no helper was ever
// reported. A result shows once the helper ended.
// in the order the agent reported them. A result shows once the helper ended.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
const real = list.filter((h) => h.alone !== true);
if (!real.length) return { alone: list.some((h) => h.alone === true), rows: [] };
const rows = real.map(({ id, title, ask, state, result }) => ({
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -10,7 +10,7 @@
//
// and derives the ticket from a branch named <prefix>/<TICKET-ID>-description,
// where the ticket is an uppercase project key, a hyphen and an integer
// (PCWEB-10968). This script reads the branch, extracts the ticket and prints
// (ABC-10968). This script reads the branch, extracts the ticket and prints
// the exact command, so no prompt re-implements the rule by eye.
import { execFileSync } from "node:child_process";
@@ -96,7 +96,7 @@ run(USAGE, async (argv) => {
let branch = null;
let ticket = args.ticket ? args.ticket.trim() : null;
if (ticket && !/^[A-Z][A-Z0-9]*-\d+$/.test(ticket)) fail(EXIT.INVALID, "bad-ticket", `"${ticket}" is not an uppercase KEY-123 ticket ID.`, "Pass a ticket like PCWEB-10968.");
if (ticket && !/^[A-Z][A-Z0-9]*-\d+$/.test(ticket)) fail(EXIT.INVALID, "bad-ticket", `"${ticket}" is not an uppercase KEY-123 ticket ID.`, "Pass a ticket like ABC-10968.");
if (!ticket) {
branch = currentBranch();
ticket = ticketFromBranch(branch);
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -667,7 +667,7 @@ your next `chat` check.
Subagents: on (revision 2) — a console setting, not typed by the person.
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
With no way to start helpers, report one "working alone" entry for this skill run instead.
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
At most 3 helpers at once.
```
@@ -716,11 +716,8 @@ page never hears from a helper directly:
- Questions for the person stay with you, never with a helper: most harnesses
give helpers no way to ask, and an answer only reaches the agent holding the
session.
- **No way to start helpers at all?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
entry for the skill run instead. The tab then says you are working alone.
It is a claim about your tools, not about the moment — post it only when no
helper mechanism exists. Reporting a real helper removes it, so an early
`alone` can never hide a later helper.
- **Pathfinder:** research questions always use helpers and are always
reported, whatever the switch says. The switch governs recon, sketches and
lookups beside the conversation.
@@ -1211,10 +1211,6 @@ export function applyPatch(state, patch) {
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
// A real helper report supersedes the working-alone marker, whether it
// arrives after one or beside one.
if (next.helpers.some((h) => isPlainObject(h) && h.alone !== true))
next.helpers = next.helpers.filter((h) => !(isPlainObject(h) && h.alone === true));
break;
case "docs":
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
@@ -4345,11 +4345,8 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,9 +1540,8 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent reported it has no
way to start helpers here. If it starts one after all, the note
goes away and the helper's row shows instead.
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,271 +36,85 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording was revised in v2.5.1 (Markdown sections); a change is a page change.
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
const template = (id, label, lines) => Object.freeze({ id, label, text: lines.join("\n") });
export const TEMPLATES = Object.freeze({
"engineering-spec": template("engineering-spec", "Engineering spec", [
"## Engineering spec",
"[the feature or change, in a sentence]",
"",
"## Who reads it",
"The engineers who will build and review it.",
"",
"## What it should pin down",
"The behaviour, the parts of the code it touches, the interfaces between them, the simpler options we're turning down, and how we'll know it works.",
"",
"## Out of scope",
"[what this deliberately won't do]",
"",
"## What I already know",
"[constraints, links, earlier attempts]",
"Engineering spec for: [the feature or change, in a sentence]",
"Who reads it: the engineers who will build and review it.",
"What it should pin down: the behaviour, the parts of the code it touches, the interfaces between them, and how we'll know it works.",
"What I already know: [constraints, links, earlier attempts]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"## Product requirements",
"[the feature, in a sentence]",
"",
"## Who it's for",
"[the users], and the product, design and engineering people deciding on it.",
"",
"## What it should pin down",
"The problem, who has it, the evidence it's real, and how we'll measure success.",
"",
"## Not doing",
"[what this release leaves out]",
"",
"## What I already know",
"[customer asks, data, deadlines]",
"Product requirements for: [the feature, in a sentence]",
"Who it's for: [the users], and the product, design and engineering people deciding on it.",
"What it should pin down: the problem, who has it, what success looks like, and what waits for later.",
"What I already know: [customer asks, data, deadlines]",
]),
"design-decision": template("design-decision", "Design decision", [
"## Design decision",
"[the choice we're facing, in a sentence]",
"",
"## Who it's for",
"The engineers and architects who will live with it.",
"",
"## What it should pin down",
"The options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"",
"## Constraints",
"[performance, compatibility, deadlines, team skills]",
"A design decision to work out: [the choice we're facing, in a sentence]",
"Who it's for: the engineers and architects who will live with it.",
"What it should pin down: the options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"Constraints: [performance, compatibility, deadlines, team skills]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"## Test strategy",
"[the feature or area]",
"",
"## Who reads it",
"QA and the engineers writing the tests.",
"",
"## What it should pin down",
'What\'s riskiest, meaning what costs most if it breaks, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"",
"## What exists today",
"[current tests, known gaps]",
"Test strategy for: [the feature or area]",
"Who reads it: QA and the engineers writing the tests.",
'What it should pin down: what\'s risky, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"What exists today: [current tests, known gaps]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"## Scoping and rollout",
"[the feature or project]",
"",
"## Who reads it",
"The engineering manager, the product lead and the team.",
"",
"## What it should pin down",
"What's in the first release and what waits, the build order, risks to the timeline, how it reaches users (flags, stages, who sees it first), and how we roll it back.",
"",
"## Constraints",
"[dates, people, dependencies]",
"Scoping and rollout for: [the feature or project]",
"Who reads it: the engineering manager, the product lead and the team.",
"What it should pin down: what's in the first release and what waits, the build order, risks to the timeline, and how it reaches users (flags, stages, who goes first).",
"Constraints: [dates, people, dependencies]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"## Brainstorm to curated notes",
"[the topic or rough idea]",
"",
"## Who reads the notes",
"[the team or people this goes to]",
"",
"## What I want out of it",
"The ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"",
"## Starting thoughts",
"[anything already on your mind]",
"Brainstorm to turn into curated notes: [the topic or rough idea]",
"Who reads the notes: [the team or people this goes to]",
"What I want out of it: the ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"Starting thoughts: [anything already on your mind]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"## Bug investigation",
"[what's going wrong, in a sentence]",
"",
"## Steps to reproduce",
"1. [first step]",
"2. [next step]",
"",
"## Expected",
"[what should happen]",
"",
"## Actual",
"[what happens instead]",
"",
"## How often",
"[every time, sometimes, once]",
"",
"## Error or logs",
"[paste the exact text]",
"",
"## Where and since when",
"[environment, version, first seen]",
"Bug to investigate: [what's going wrong, in a sentence]",
"Steps to reproduce: [1. ... 2. ...]",
"Expected: [what should happen]. Actual: [what happens instead]",
"Where and since when: [environment, version, first seen]",
]),
"small-change": template("small-change", "Small change", [
"## Small change",
"[what to change, in a sentence]",
"",
"## Where",
"[the file, screen or command, if you know it]",
"",
"## Leave alone",
"[anything that must not change]",
"",
"## Done when",
"[the command to run or the thing to check]",
"Small change: [what to change, in a sentence]",
"Where: [the file, screen or command, if you know it]",
"Done when: [how you'll tell it worked]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"## Copy or content tweak",
"[the screen, message, email or doc]",
"",
"## Current text",
"[paste it]",
"",
"## New text",
"[paste it, or describe the tone you want]",
"",
"## Who reads it",
"[the people who see it]",
"Change the wording of: [the screen, message, email or doc]",
"Current text: [paste it]",
"New text: [paste it, or describe the tone you want]",
"Who reads it: [the people who see it]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"## UI polish",
"[the screen or component]",
"",
"## What looks or feels off",
"[spacing, alignment, colour, states, small screens]",
"",
"## What good looks like",
"[a reference, screenshot or description]",
"",
"## Leave alone",
"[anything that must not move]",
"UI polish on: [the screen or component]",
"What looks or feels off: [spacing, alignment, colour, states, small screens]",
"What good looks like: [a reference, screenshot or description]",
"Leave alone: [anything that must not move]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"## Visual prototype",
"[the screen or component to mock up]",
"",
"## What to show",
"[the states or flows to click through]",
"",
"## What I want to learn",
"[the question it should answer]",
"",
"## Where it lives",
"A prototypes/ folder [or its own branch], never wired into the real code.",
"A throwaway visual prototype of: [the screen or component]",
"What to show: [the states or flows to click through]",
"What I want to learn: [the question it should answer]",
"Where it lives: a prototypes/ folder [or its own branch], never wired into the real code.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"## Add a test",
"[the function, behaviour or bug]",
"",
"## Cases to cover",
"- [the normal case]",
"- [the edge cases]",
"- [the failure or bug it guards against]",
"",
"## Where tests live",
"[the test file or folder, if you know it]",
"Add a test for: [the function, behaviour or bug]",
"Cases to cover: [the normal case, the edge cases, the bug it guards against]",
"Where tests live: [the test file or folder, if you know it]",
]),
"record-decision": template("record-decision", "Record a decision", [
"## Record a decision",
"[the decision we've already made, in a sentence]",
"",
"## Why",
"[what forced the choice, and the options we turned down]",
"",
"## What it commits us to",
"[the consequences]",
"",
"## Save it in",
"docs/adr/ [or wherever this repo keeps them]",
]),
refactor: template("refactor", "Refactor", [
"## Refactor",
"[what to restructure, in a sentence]",
"",
"## Why now",
"[what the current shape makes hard]",
"",
"## Behaviour that must not change",
"[the public API, outputs or tests that must stay the same]",
"",
"## Done when",
"[the tests that must still pass, and the shape it ends in]",
]),
"performance-problem": template("performance-problem", "Performance problem", [
"## Performance problem",
"[what's slow, in a sentence]",
"",
"## How it's measured today",
"[the number, and how you got it]",
"",
"## Target",
"[the number that counts as fixed]",
"",
"## Where",
"[the endpoint, page, query or job]",
]),
"dependency-upgrade": template("dependency-upgrade", "Dependency upgrade", [
"## Dependency upgrade",
"[the package, from version to version]",
"",
"## Why",
"[security fix, a feature we need, end of support]",
"",
"## Known breaking changes",
'[release notes link, or "not checked yet"]',
"",
"## Done when",
"[the build, tests or checks that must pass]",
]),
spike: template("spike", "Spike", [
"## Spike",
"[the question to answer, in a sentence]",
"",
"## Why it matters",
"[the decision waiting on the answer]",
"",
"## Time box",
"[how long before we stop and decide anyway]",
"",
"## Answered when",
"[the evidence that would settle it]",
]),
integration: template("integration", "Integration", [
"## Integration",
"[the system we're connecting to, and why]",
"",
"## What flows",
"[the data or events, and in which direction]",
"",
"## Their side",
"[API docs, auth method, rate limits, test sandbox]",
"",
"## When it fails",
"[what should happen if they're down or slow]",
]),
"data-migration": template("data-migration", "Data migration", [
"## Data migration",
"[what moves or changes shape]",
"",
"## Size and downtime",
"[row counts, and whether users can stay on while it runs]",
"",
"## Rollback",
"[how we undo it if it goes wrong]",
"",
"## Done when",
"[the checks that prove nothing was lost]",
"Record a decision we've already made: [the decision, in a sentence]",
"Why: [the reasons, and what we turned down]",
"What it commits us to: [the consequences]",
"Save it as an ADR in: docs/adr/ [or wherever this repo keeps them]",
]),
});
@@ -309,28 +123,28 @@ const orders = (byRole) => Object.freeze(Object.fromEntries(Object.entries(byRol
// One full order per role per skill. No "none" row: Not set reads Engineer's.
export const TEMPLATE_ORDERS = Object.freeze({
pathfinder: orders({
engineer: ["engineering-spec", "design-decision", "spike", "integration", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "spike", "engineering-spec", "design-decision", "integration", "test-strategy"],
architect: ["design-decision", "engineering-spec", "integration", "spike", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "spike", "engineering-spec", "scoping-rollout", "integration", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "spike", "product-requirements", "integration", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "spike", "test-strategy", "design-decision", "integration", "brainstorm-notes"],
engineer: ["engineering-spec", "design-decision", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "engineering-spec", "design-decision", "test-strategy"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "design-decision", "brainstorm-notes"],
}),
plan: orders({
engineer: ["engineering-spec", "bug-investigation", "refactor", "performance-problem", "integration", "data-migration", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "integration", "test-strategy", "design-decision", "performance-problem", "bug-investigation", "data-migration", "refactor"],
architect: ["design-decision", "engineering-spec", "data-migration", "integration", "refactor", "scoping-rollout", "performance-problem", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "performance-problem", "test-strategy", "bug-investigation", "integration", "refactor", "data-migration"],
qa: ["test-strategy", "bug-investigation", "performance-problem", "engineering-spec", "data-migration", "integration", "product-requirements", "scoping-rollout", "refactor", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "data-migration", "product-requirements", "test-strategy", "integration", "bug-investigation", "performance-problem", "refactor", "design-decision"],
engineer: ["engineering-spec", "bug-investigation", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "test-strategy", "design-decision", "bug-investigation"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "bug-investigation"],
qa: ["test-strategy", "bug-investigation", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "bug-investigation", "design-decision"],
}),
"quick-task": orders({
engineer: ["small-change", "bug-investigation", "refactor", "add-a-test", "dependency-upgrade", "performance-problem", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "performance-problem", "add-a-test", "record-decision", "dependency-upgrade", "refactor"],
architect: ["record-decision", "refactor", "small-change", "dependency-upgrade", "performance-problem", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "performance-problem", "add-a-test", "refactor", "dependency-upgrade", "record-decision"],
qa: ["add-a-test", "bug-investigation", "performance-problem", "small-change", "dependency-upgrade", "ui-polish", "refactor", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "dependency-upgrade", "add-a-test", "bug-investigation", "performance-problem", "refactor", "copy-tweak", "ui-polish", "visual-prototype"],
engineer: ["small-change", "bug-investigation", "add-a-test", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "add-a-test", "record-decision"],
architect: ["record-decision", "small-change", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "add-a-test", "record-decision"],
qa: ["add-a-test", "bug-investigation", "small-change", "ui-polish", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "add-a-test", "bug-investigation", "copy-tweak", "ui-polish", "visual-prototype"],
}),
});
@@ -88,7 +88,7 @@ export function cleanSetting(input) {
export const FRAME_LINES = Object.freeze([
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,14 +201,11 @@ export function switchLabel(frame) {
}
// What the Subagents tab draws: the working-alone note, or one row per helper
// in the order the agent reported them. A real helper supersedes the
// working-alone marker, so the note only draws when no helper was ever
// reported. A result shows once the helper ended.
// in the order the agent reported them. A result shows once the helper ended.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
const real = list.filter((h) => h.alone !== true);
if (!real.length) return { alone: list.some((h) => h.alone === true), rows: [] };
const rows = real.map(({ id, title, ask, state, result }) => ({
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -10,7 +10,7 @@
//
// and derives the ticket from a branch named <prefix>/<TICKET-ID>-description,
// where the ticket is an uppercase project key, a hyphen and an integer
// (PCWEB-10968). This script reads the branch, extracts the ticket and prints
// (ABC-10968). This script reads the branch, extracts the ticket and prints
// the exact command, so no prompt re-implements the rule by eye.
import { execFileSync } from "node:child_process";
@@ -96,7 +96,7 @@ run(USAGE, async (argv) => {
let branch = null;
let ticket = args.ticket ? args.ticket.trim() : null;
if (ticket && !/^[A-Z][A-Z0-9]*-\d+$/.test(ticket)) fail(EXIT.INVALID, "bad-ticket", `"${ticket}" is not an uppercase KEY-123 ticket ID.`, "Pass a ticket like PCWEB-10968.");
if (ticket && !/^[A-Z][A-Z0-9]*-\d+$/.test(ticket)) fail(EXIT.INVALID, "bad-ticket", `"${ticket}" is not an uppercase KEY-123 ticket ID.`, "Pass a ticket like ABC-10968.");
if (!ticket) {
branch = currentBranch();
ticket = ticketFromBranch(branch);
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -667,7 +667,7 @@ your next `chat` check.
Subagents: on (revision 2) — a console setting, not typed by the person.
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
With no way to start helpers, report one "working alone" entry for this skill run instead.
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
At most 3 helpers at once.
```
@@ -716,11 +716,8 @@ page never hears from a helper directly:
- Questions for the person stay with you, never with a helper: most harnesses
give helpers no way to ask, and an answer only reaches the agent holding the
session.
- **No way to start helpers at all?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
entry for the skill run instead. The tab then says you are working alone.
It is a claim about your tools, not about the moment — post it only when no
helper mechanism exists. Reporting a real helper removes it, so an early
`alone` can never hide a later helper.
- **Pathfinder:** research questions always use helpers and are always
reported, whatever the switch says. The switch governs recon, sketches and
lookups beside the conversation.
@@ -1211,10 +1211,6 @@ export function applyPatch(state, patch) {
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
// A real helper report supersedes the working-alone marker, whether it
// arrives after one or beside one.
if (next.helpers.some((h) => isPlainObject(h) && h.alone !== true))
next.helpers = next.helpers.filter((h) => !(isPlainObject(h) && h.alone === true));
break;
case "docs":
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
@@ -4345,11 +4345,8 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,9 +1540,8 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent reported it has no
way to start helpers here. If it starts one after all, the note
goes away and the helper's row shows instead.
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,271 +36,85 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording was revised in v2.5.1 (Markdown sections); a change is a page change.
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
const template = (id, label, lines) => Object.freeze({ id, label, text: lines.join("\n") });
export const TEMPLATES = Object.freeze({
"engineering-spec": template("engineering-spec", "Engineering spec", [
"## Engineering spec",
"[the feature or change, in a sentence]",
"",
"## Who reads it",
"The engineers who will build and review it.",
"",
"## What it should pin down",
"The behaviour, the parts of the code it touches, the interfaces between them, the simpler options we're turning down, and how we'll know it works.",
"",
"## Out of scope",
"[what this deliberately won't do]",
"",
"## What I already know",
"[constraints, links, earlier attempts]",
"Engineering spec for: [the feature or change, in a sentence]",
"Who reads it: the engineers who will build and review it.",
"What it should pin down: the behaviour, the parts of the code it touches, the interfaces between them, and how we'll know it works.",
"What I already know: [constraints, links, earlier attempts]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"## Product requirements",
"[the feature, in a sentence]",
"",
"## Who it's for",
"[the users], and the product, design and engineering people deciding on it.",
"",
"## What it should pin down",
"The problem, who has it, the evidence it's real, and how we'll measure success.",
"",
"## Not doing",
"[what this release leaves out]",
"",
"## What I already know",
"[customer asks, data, deadlines]",
"Product requirements for: [the feature, in a sentence]",
"Who it's for: [the users], and the product, design and engineering people deciding on it.",
"What it should pin down: the problem, who has it, what success looks like, and what waits for later.",
"What I already know: [customer asks, data, deadlines]",
]),
"design-decision": template("design-decision", "Design decision", [
"## Design decision",
"[the choice we're facing, in a sentence]",
"",
"## Who it's for",
"The engineers and architects who will live with it.",
"",
"## What it should pin down",
"The options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"",
"## Constraints",
"[performance, compatibility, deadlines, team skills]",
"A design decision to work out: [the choice we're facing, in a sentence]",
"Who it's for: the engineers and architects who will live with it.",
"What it should pin down: the options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"Constraints: [performance, compatibility, deadlines, team skills]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"## Test strategy",
"[the feature or area]",
"",
"## Who reads it",
"QA and the engineers writing the tests.",
"",
"## What it should pin down",
'What\'s riskiest, meaning what costs most if it breaks, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"",
"## What exists today",
"[current tests, known gaps]",
"Test strategy for: [the feature or area]",
"Who reads it: QA and the engineers writing the tests.",
'What it should pin down: what\'s risky, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"What exists today: [current tests, known gaps]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"## Scoping and rollout",
"[the feature or project]",
"",
"## Who reads it",
"The engineering manager, the product lead and the team.",
"",
"## What it should pin down",
"What's in the first release and what waits, the build order, risks to the timeline, how it reaches users (flags, stages, who sees it first), and how we roll it back.",
"",
"## Constraints",
"[dates, people, dependencies]",
"Scoping and rollout for: [the feature or project]",
"Who reads it: the engineering manager, the product lead and the team.",
"What it should pin down: what's in the first release and what waits, the build order, risks to the timeline, and how it reaches users (flags, stages, who goes first).",
"Constraints: [dates, people, dependencies]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"## Brainstorm to curated notes",
"[the topic or rough idea]",
"",
"## Who reads the notes",
"[the team or people this goes to]",
"",
"## What I want out of it",
"The ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"",
"## Starting thoughts",
"[anything already on your mind]",
"Brainstorm to turn into curated notes: [the topic or rough idea]",
"Who reads the notes: [the team or people this goes to]",
"What I want out of it: the ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"Starting thoughts: [anything already on your mind]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"## Bug investigation",
"[what's going wrong, in a sentence]",
"",
"## Steps to reproduce",
"1. [first step]",
"2. [next step]",
"",
"## Expected",
"[what should happen]",
"",
"## Actual",
"[what happens instead]",
"",
"## How often",
"[every time, sometimes, once]",
"",
"## Error or logs",
"[paste the exact text]",
"",
"## Where and since when",
"[environment, version, first seen]",
"Bug to investigate: [what's going wrong, in a sentence]",
"Steps to reproduce: [1. ... 2. ...]",
"Expected: [what should happen]. Actual: [what happens instead]",
"Where and since when: [environment, version, first seen]",
]),
"small-change": template("small-change", "Small change", [
"## Small change",
"[what to change, in a sentence]",
"",
"## Where",
"[the file, screen or command, if you know it]",
"",
"## Leave alone",
"[anything that must not change]",
"",
"## Done when",
"[the command to run or the thing to check]",
"Small change: [what to change, in a sentence]",
"Where: [the file, screen or command, if you know it]",
"Done when: [how you'll tell it worked]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"## Copy or content tweak",
"[the screen, message, email or doc]",
"",
"## Current text",
"[paste it]",
"",
"## New text",
"[paste it, or describe the tone you want]",
"",
"## Who reads it",
"[the people who see it]",
"Change the wording of: [the screen, message, email or doc]",
"Current text: [paste it]",
"New text: [paste it, or describe the tone you want]",
"Who reads it: [the people who see it]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"## UI polish",
"[the screen or component]",
"",
"## What looks or feels off",
"[spacing, alignment, colour, states, small screens]",
"",
"## What good looks like",
"[a reference, screenshot or description]",
"",
"## Leave alone",
"[anything that must not move]",
"UI polish on: [the screen or component]",
"What looks or feels off: [spacing, alignment, colour, states, small screens]",
"What good looks like: [a reference, screenshot or description]",
"Leave alone: [anything that must not move]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"## Visual prototype",
"[the screen or component to mock up]",
"",
"## What to show",
"[the states or flows to click through]",
"",
"## What I want to learn",
"[the question it should answer]",
"",
"## Where it lives",
"A prototypes/ folder [or its own branch], never wired into the real code.",
"A throwaway visual prototype of: [the screen or component]",
"What to show: [the states or flows to click through]",
"What I want to learn: [the question it should answer]",
"Where it lives: a prototypes/ folder [or its own branch], never wired into the real code.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"## Add a test",
"[the function, behaviour or bug]",
"",
"## Cases to cover",
"- [the normal case]",
"- [the edge cases]",
"- [the failure or bug it guards against]",
"",
"## Where tests live",
"[the test file or folder, if you know it]",
"Add a test for: [the function, behaviour or bug]",
"Cases to cover: [the normal case, the edge cases, the bug it guards against]",
"Where tests live: [the test file or folder, if you know it]",
]),
"record-decision": template("record-decision", "Record a decision", [
"## Record a decision",
"[the decision we've already made, in a sentence]",
"",
"## Why",
"[what forced the choice, and the options we turned down]",
"",
"## What it commits us to",
"[the consequences]",
"",
"## Save it in",
"docs/adr/ [or wherever this repo keeps them]",
]),
refactor: template("refactor", "Refactor", [
"## Refactor",
"[what to restructure, in a sentence]",
"",
"## Why now",
"[what the current shape makes hard]",
"",
"## Behaviour that must not change",
"[the public API, outputs or tests that must stay the same]",
"",
"## Done when",
"[the tests that must still pass, and the shape it ends in]",
]),
"performance-problem": template("performance-problem", "Performance problem", [
"## Performance problem",
"[what's slow, in a sentence]",
"",
"## How it's measured today",
"[the number, and how you got it]",
"",
"## Target",
"[the number that counts as fixed]",
"",
"## Where",
"[the endpoint, page, query or job]",
]),
"dependency-upgrade": template("dependency-upgrade", "Dependency upgrade", [
"## Dependency upgrade",
"[the package, from version to version]",
"",
"## Why",
"[security fix, a feature we need, end of support]",
"",
"## Known breaking changes",
'[release notes link, or "not checked yet"]',
"",
"## Done when",
"[the build, tests or checks that must pass]",
]),
spike: template("spike", "Spike", [
"## Spike",
"[the question to answer, in a sentence]",
"",
"## Why it matters",
"[the decision waiting on the answer]",
"",
"## Time box",
"[how long before we stop and decide anyway]",
"",
"## Answered when",
"[the evidence that would settle it]",
]),
integration: template("integration", "Integration", [
"## Integration",
"[the system we're connecting to, and why]",
"",
"## What flows",
"[the data or events, and in which direction]",
"",
"## Their side",
"[API docs, auth method, rate limits, test sandbox]",
"",
"## When it fails",
"[what should happen if they're down or slow]",
]),
"data-migration": template("data-migration", "Data migration", [
"## Data migration",
"[what moves or changes shape]",
"",
"## Size and downtime",
"[row counts, and whether users can stay on while it runs]",
"",
"## Rollback",
"[how we undo it if it goes wrong]",
"",
"## Done when",
"[the checks that prove nothing was lost]",
"Record a decision we've already made: [the decision, in a sentence]",
"Why: [the reasons, and what we turned down]",
"What it commits us to: [the consequences]",
"Save it as an ADR in: docs/adr/ [or wherever this repo keeps them]",
]),
});
@@ -309,28 +123,28 @@ const orders = (byRole) => Object.freeze(Object.fromEntries(Object.entries(byRol
// One full order per role per skill. No "none" row: Not set reads Engineer's.
export const TEMPLATE_ORDERS = Object.freeze({
pathfinder: orders({
engineer: ["engineering-spec", "design-decision", "spike", "integration", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "spike", "engineering-spec", "design-decision", "integration", "test-strategy"],
architect: ["design-decision", "engineering-spec", "integration", "spike", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "spike", "engineering-spec", "scoping-rollout", "integration", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "spike", "product-requirements", "integration", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "spike", "test-strategy", "design-decision", "integration", "brainstorm-notes"],
engineer: ["engineering-spec", "design-decision", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "engineering-spec", "design-decision", "test-strategy"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "design-decision", "brainstorm-notes"],
}),
plan: orders({
engineer: ["engineering-spec", "bug-investigation", "refactor", "performance-problem", "integration", "data-migration", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "integration", "test-strategy", "design-decision", "performance-problem", "bug-investigation", "data-migration", "refactor"],
architect: ["design-decision", "engineering-spec", "data-migration", "integration", "refactor", "scoping-rollout", "performance-problem", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "performance-problem", "test-strategy", "bug-investigation", "integration", "refactor", "data-migration"],
qa: ["test-strategy", "bug-investigation", "performance-problem", "engineering-spec", "data-migration", "integration", "product-requirements", "scoping-rollout", "refactor", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "data-migration", "product-requirements", "test-strategy", "integration", "bug-investigation", "performance-problem", "refactor", "design-decision"],
engineer: ["engineering-spec", "bug-investigation", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "test-strategy", "design-decision", "bug-investigation"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "bug-investigation"],
qa: ["test-strategy", "bug-investigation", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "bug-investigation", "design-decision"],
}),
"quick-task": orders({
engineer: ["small-change", "bug-investigation", "refactor", "add-a-test", "dependency-upgrade", "performance-problem", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "performance-problem", "add-a-test", "record-decision", "dependency-upgrade", "refactor"],
architect: ["record-decision", "refactor", "small-change", "dependency-upgrade", "performance-problem", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "performance-problem", "add-a-test", "refactor", "dependency-upgrade", "record-decision"],
qa: ["add-a-test", "bug-investigation", "performance-problem", "small-change", "dependency-upgrade", "ui-polish", "refactor", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "dependency-upgrade", "add-a-test", "bug-investigation", "performance-problem", "refactor", "copy-tweak", "ui-polish", "visual-prototype"],
engineer: ["small-change", "bug-investigation", "add-a-test", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "add-a-test", "record-decision"],
architect: ["record-decision", "small-change", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "add-a-test", "record-decision"],
qa: ["add-a-test", "bug-investigation", "small-change", "ui-polish", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "add-a-test", "bug-investigation", "copy-tweak", "ui-polish", "visual-prototype"],
}),
});
@@ -88,7 +88,7 @@ export function cleanSetting(input) {
export const FRAME_LINES = Object.freeze([
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,14 +201,11 @@ export function switchLabel(frame) {
}
// What the Subagents tab draws: the working-alone note, or one row per helper
// in the order the agent reported them. A real helper supersedes the
// working-alone marker, so the note only draws when no helper was ever
// reported. A result shows once the helper ended.
// in the order the agent reported them. A result shows once the helper ended.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
const real = list.filter((h) => h.alone !== true);
if (!real.length) return { alone: list.some((h) => h.alone === true), rows: [] };
const rows = real.map(({ id, title, ask, state, result }) => ({
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -667,7 +667,7 @@ your next `chat` check.
Subagents: on (revision 2) — a console setting, not typed by the person.
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
With no way to start helpers, report one "working alone" entry for this skill run instead.
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
At most 3 helpers at once.
```
@@ -716,11 +716,8 @@ page never hears from a helper directly:
- Questions for the person stay with you, never with a helper: most harnesses
give helpers no way to ask, and an answer only reaches the agent holding the
session.
- **No way to start helpers at all?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
entry for the skill run instead. The tab then says you are working alone.
It is a claim about your tools, not about the moment — post it only when no
helper mechanism exists. Reporting a real helper removes it, so an early
`alone` can never hide a later helper.
- **Pathfinder:** research questions always use helpers and are always
reported, whatever the switch says. The switch governs recon, sketches and
lookups beside the conversation.
@@ -1211,10 +1211,6 @@ export function applyPatch(state, patch) {
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
// A real helper report supersedes the working-alone marker, whether it
// arrives after one or beside one.
if (next.helpers.some((h) => isPlainObject(h) && h.alone !== true))
next.helpers = next.helpers.filter((h) => !(isPlainObject(h) && h.alone === true));
break;
case "docs":
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
@@ -4345,11 +4345,8 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,9 +1540,8 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent reported it has no
way to start helpers here. If it starts one after all, the note
goes away and the helper's row shows instead.
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,271 +36,85 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording was revised in v2.5.1 (Markdown sections); a change is a page change.
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
const template = (id, label, lines) => Object.freeze({ id, label, text: lines.join("\n") });
export const TEMPLATES = Object.freeze({
"engineering-spec": template("engineering-spec", "Engineering spec", [
"## Engineering spec",
"[the feature or change, in a sentence]",
"",
"## Who reads it",
"The engineers who will build and review it.",
"",
"## What it should pin down",
"The behaviour, the parts of the code it touches, the interfaces between them, the simpler options we're turning down, and how we'll know it works.",
"",
"## Out of scope",
"[what this deliberately won't do]",
"",
"## What I already know",
"[constraints, links, earlier attempts]",
"Engineering spec for: [the feature or change, in a sentence]",
"Who reads it: the engineers who will build and review it.",
"What it should pin down: the behaviour, the parts of the code it touches, the interfaces between them, and how we'll know it works.",
"What I already know: [constraints, links, earlier attempts]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"## Product requirements",
"[the feature, in a sentence]",
"",
"## Who it's for",
"[the users], and the product, design and engineering people deciding on it.",
"",
"## What it should pin down",
"The problem, who has it, the evidence it's real, and how we'll measure success.",
"",
"## Not doing",
"[what this release leaves out]",
"",
"## What I already know",
"[customer asks, data, deadlines]",
"Product requirements for: [the feature, in a sentence]",
"Who it's for: [the users], and the product, design and engineering people deciding on it.",
"What it should pin down: the problem, who has it, what success looks like, and what waits for later.",
"What I already know: [customer asks, data, deadlines]",
]),
"design-decision": template("design-decision", "Design decision", [
"## Design decision",
"[the choice we're facing, in a sentence]",
"",
"## Who it's for",
"The engineers and architects who will live with it.",
"",
"## What it should pin down",
"The options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"",
"## Constraints",
"[performance, compatibility, deadlines, team skills]",
"A design decision to work out: [the choice we're facing, in a sentence]",
"Who it's for: the engineers and architects who will live with it.",
"What it should pin down: the options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"Constraints: [performance, compatibility, deadlines, team skills]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"## Test strategy",
"[the feature or area]",
"",
"## Who reads it",
"QA and the engineers writing the tests.",
"",
"## What it should pin down",
'What\'s riskiest, meaning what costs most if it breaks, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"",
"## What exists today",
"[current tests, known gaps]",
"Test strategy for: [the feature or area]",
"Who reads it: QA and the engineers writing the tests.",
'What it should pin down: what\'s risky, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"What exists today: [current tests, known gaps]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"## Scoping and rollout",
"[the feature or project]",
"",
"## Who reads it",
"The engineering manager, the product lead and the team.",
"",
"## What it should pin down",
"What's in the first release and what waits, the build order, risks to the timeline, how it reaches users (flags, stages, who sees it first), and how we roll it back.",
"",
"## Constraints",
"[dates, people, dependencies]",
"Scoping and rollout for: [the feature or project]",
"Who reads it: the engineering manager, the product lead and the team.",
"What it should pin down: what's in the first release and what waits, the build order, risks to the timeline, and how it reaches users (flags, stages, who goes first).",
"Constraints: [dates, people, dependencies]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"## Brainstorm to curated notes",
"[the topic or rough idea]",
"",
"## Who reads the notes",
"[the team or people this goes to]",
"",
"## What I want out of it",
"The ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"",
"## Starting thoughts",
"[anything already on your mind]",
"Brainstorm to turn into curated notes: [the topic or rough idea]",
"Who reads the notes: [the team or people this goes to]",
"What I want out of it: the ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"Starting thoughts: [anything already on your mind]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"## Bug investigation",
"[what's going wrong, in a sentence]",
"",
"## Steps to reproduce",
"1. [first step]",
"2. [next step]",
"",
"## Expected",
"[what should happen]",
"",
"## Actual",
"[what happens instead]",
"",
"## How often",
"[every time, sometimes, once]",
"",
"## Error or logs",
"[paste the exact text]",
"",
"## Where and since when",
"[environment, version, first seen]",
"Bug to investigate: [what's going wrong, in a sentence]",
"Steps to reproduce: [1. ... 2. ...]",
"Expected: [what should happen]. Actual: [what happens instead]",
"Where and since when: [environment, version, first seen]",
]),
"small-change": template("small-change", "Small change", [
"## Small change",
"[what to change, in a sentence]",
"",
"## Where",
"[the file, screen or command, if you know it]",
"",
"## Leave alone",
"[anything that must not change]",
"",
"## Done when",
"[the command to run or the thing to check]",
"Small change: [what to change, in a sentence]",
"Where: [the file, screen or command, if you know it]",
"Done when: [how you'll tell it worked]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"## Copy or content tweak",
"[the screen, message, email or doc]",
"",
"## Current text",
"[paste it]",
"",
"## New text",
"[paste it, or describe the tone you want]",
"",
"## Who reads it",
"[the people who see it]",
"Change the wording of: [the screen, message, email or doc]",
"Current text: [paste it]",
"New text: [paste it, or describe the tone you want]",
"Who reads it: [the people who see it]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"## UI polish",
"[the screen or component]",
"",
"## What looks or feels off",
"[spacing, alignment, colour, states, small screens]",
"",
"## What good looks like",
"[a reference, screenshot or description]",
"",
"## Leave alone",
"[anything that must not move]",
"UI polish on: [the screen or component]",
"What looks or feels off: [spacing, alignment, colour, states, small screens]",
"What good looks like: [a reference, screenshot or description]",
"Leave alone: [anything that must not move]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"## Visual prototype",
"[the screen or component to mock up]",
"",
"## What to show",
"[the states or flows to click through]",
"",
"## What I want to learn",
"[the question it should answer]",
"",
"## Where it lives",
"A prototypes/ folder [or its own branch], never wired into the real code.",
"A throwaway visual prototype of: [the screen or component]",
"What to show: [the states or flows to click through]",
"What I want to learn: [the question it should answer]",
"Where it lives: a prototypes/ folder [or its own branch], never wired into the real code.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"## Add a test",
"[the function, behaviour or bug]",
"",
"## Cases to cover",
"- [the normal case]",
"- [the edge cases]",
"- [the failure or bug it guards against]",
"",
"## Where tests live",
"[the test file or folder, if you know it]",
"Add a test for: [the function, behaviour or bug]",
"Cases to cover: [the normal case, the edge cases, the bug it guards against]",
"Where tests live: [the test file or folder, if you know it]",
]),
"record-decision": template("record-decision", "Record a decision", [
"## Record a decision",
"[the decision we've already made, in a sentence]",
"",
"## Why",
"[what forced the choice, and the options we turned down]",
"",
"## What it commits us to",
"[the consequences]",
"",
"## Save it in",
"docs/adr/ [or wherever this repo keeps them]",
]),
refactor: template("refactor", "Refactor", [
"## Refactor",
"[what to restructure, in a sentence]",
"",
"## Why now",
"[what the current shape makes hard]",
"",
"## Behaviour that must not change",
"[the public API, outputs or tests that must stay the same]",
"",
"## Done when",
"[the tests that must still pass, and the shape it ends in]",
]),
"performance-problem": template("performance-problem", "Performance problem", [
"## Performance problem",
"[what's slow, in a sentence]",
"",
"## How it's measured today",
"[the number, and how you got it]",
"",
"## Target",
"[the number that counts as fixed]",
"",
"## Where",
"[the endpoint, page, query or job]",
]),
"dependency-upgrade": template("dependency-upgrade", "Dependency upgrade", [
"## Dependency upgrade",
"[the package, from version to version]",
"",
"## Why",
"[security fix, a feature we need, end of support]",
"",
"## Known breaking changes",
'[release notes link, or "not checked yet"]',
"",
"## Done when",
"[the build, tests or checks that must pass]",
]),
spike: template("spike", "Spike", [
"## Spike",
"[the question to answer, in a sentence]",
"",
"## Why it matters",
"[the decision waiting on the answer]",
"",
"## Time box",
"[how long before we stop and decide anyway]",
"",
"## Answered when",
"[the evidence that would settle it]",
]),
integration: template("integration", "Integration", [
"## Integration",
"[the system we're connecting to, and why]",
"",
"## What flows",
"[the data or events, and in which direction]",
"",
"## Their side",
"[API docs, auth method, rate limits, test sandbox]",
"",
"## When it fails",
"[what should happen if they're down or slow]",
]),
"data-migration": template("data-migration", "Data migration", [
"## Data migration",
"[what moves or changes shape]",
"",
"## Size and downtime",
"[row counts, and whether users can stay on while it runs]",
"",
"## Rollback",
"[how we undo it if it goes wrong]",
"",
"## Done when",
"[the checks that prove nothing was lost]",
"Record a decision we've already made: [the decision, in a sentence]",
"Why: [the reasons, and what we turned down]",
"What it commits us to: [the consequences]",
"Save it as an ADR in: docs/adr/ [or wherever this repo keeps them]",
]),
});
@@ -309,28 +123,28 @@ const orders = (byRole) => Object.freeze(Object.fromEntries(Object.entries(byRol
// One full order per role per skill. No "none" row: Not set reads Engineer's.
export const TEMPLATE_ORDERS = Object.freeze({
pathfinder: orders({
engineer: ["engineering-spec", "design-decision", "spike", "integration", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "spike", "engineering-spec", "design-decision", "integration", "test-strategy"],
architect: ["design-decision", "engineering-spec", "integration", "spike", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "spike", "engineering-spec", "scoping-rollout", "integration", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "spike", "product-requirements", "integration", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "spike", "test-strategy", "design-decision", "integration", "brainstorm-notes"],
engineer: ["engineering-spec", "design-decision", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "engineering-spec", "design-decision", "test-strategy"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "design-decision", "brainstorm-notes"],
}),
plan: orders({
engineer: ["engineering-spec", "bug-investigation", "refactor", "performance-problem", "integration", "data-migration", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "integration", "test-strategy", "design-decision", "performance-problem", "bug-investigation", "data-migration", "refactor"],
architect: ["design-decision", "engineering-spec", "data-migration", "integration", "refactor", "scoping-rollout", "performance-problem", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "performance-problem", "test-strategy", "bug-investigation", "integration", "refactor", "data-migration"],
qa: ["test-strategy", "bug-investigation", "performance-problem", "engineering-spec", "data-migration", "integration", "product-requirements", "scoping-rollout", "refactor", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "data-migration", "product-requirements", "test-strategy", "integration", "bug-investigation", "performance-problem", "refactor", "design-decision"],
engineer: ["engineering-spec", "bug-investigation", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "test-strategy", "design-decision", "bug-investigation"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "bug-investigation"],
qa: ["test-strategy", "bug-investigation", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "bug-investigation", "design-decision"],
}),
"quick-task": orders({
engineer: ["small-change", "bug-investigation", "refactor", "add-a-test", "dependency-upgrade", "performance-problem", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "performance-problem", "add-a-test", "record-decision", "dependency-upgrade", "refactor"],
architect: ["record-decision", "refactor", "small-change", "dependency-upgrade", "performance-problem", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "performance-problem", "add-a-test", "refactor", "dependency-upgrade", "record-decision"],
qa: ["add-a-test", "bug-investigation", "performance-problem", "small-change", "dependency-upgrade", "ui-polish", "refactor", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "dependency-upgrade", "add-a-test", "bug-investigation", "performance-problem", "refactor", "copy-tweak", "ui-polish", "visual-prototype"],
engineer: ["small-change", "bug-investigation", "add-a-test", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "add-a-test", "record-decision"],
architect: ["record-decision", "small-change", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "add-a-test", "record-decision"],
qa: ["add-a-test", "bug-investigation", "small-change", "ui-polish", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "add-a-test", "bug-investigation", "copy-tweak", "ui-polish", "visual-prototype"],
}),
});
@@ -88,7 +88,7 @@ export function cleanSetting(input) {
export const FRAME_LINES = Object.freeze([
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,14 +201,11 @@ export function switchLabel(frame) {
}
// What the Subagents tab draws: the working-alone note, or one row per helper
// in the order the agent reported them. A real helper supersedes the
// working-alone marker, so the note only draws when no helper was ever
// reported. A result shows once the helper ended.
// in the order the agent reported them. A result shows once the helper ended.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
const real = list.filter((h) => h.alone !== true);
if (!real.length) return { alone: list.some((h) => h.alone === true), rows: [] };
const rows = real.map(({ id, title, ask, state, result }) => ({
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -10,7 +10,7 @@
//
// and derives the ticket from a branch named <prefix>/<TICKET-ID>-description,
// where the ticket is an uppercase project key, a hyphen and an integer
// (PCWEB-10968). This script reads the branch, extracts the ticket and prints
// (ABC-10968). This script reads the branch, extracts the ticket and prints
// the exact command, so no prompt re-implements the rule by eye.
import { execFileSync } from "node:child_process";
@@ -96,7 +96,7 @@ run(USAGE, async (argv) => {
let branch = null;
let ticket = args.ticket ? args.ticket.trim() : null;
if (ticket && !/^[A-Z][A-Z0-9]*-\d+$/.test(ticket)) fail(EXIT.INVALID, "bad-ticket", `"${ticket}" is not an uppercase KEY-123 ticket ID.`, "Pass a ticket like PCWEB-10968.");
if (ticket && !/^[A-Z][A-Z0-9]*-\d+$/.test(ticket)) fail(EXIT.INVALID, "bad-ticket", `"${ticket}" is not an uppercase KEY-123 ticket ID.`, "Pass a ticket like ABC-10968.");
if (!ticket) {
branch = currentBranch();
ticket = ticketFromBranch(branch);
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -667,7 +667,7 @@ your next `chat` check.
Subagents: on (revision 2) — a console setting, not typed by the person.
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
With no way to start helpers, report one "working alone" entry for this skill run instead.
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
At most 3 helpers at once.
```
@@ -716,11 +716,8 @@ page never hears from a helper directly:
- Questions for the person stay with you, never with a helper: most harnesses
give helpers no way to ask, and an answer only reaches the agent holding the
session.
- **No way to start helpers at all?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
entry for the skill run instead. The tab then says you are working alone.
It is a claim about your tools, not about the moment — post it only when no
helper mechanism exists. Reporting a real helper removes it, so an early
`alone` can never hide a later helper.
- **Pathfinder:** research questions always use helpers and are always
reported, whatever the switch says. The switch governs recon, sketches and
lookups beside the conversation.
@@ -1211,10 +1211,6 @@ export function applyPatch(state, patch) {
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
// A real helper report supersedes the working-alone marker, whether it
// arrives after one or beside one.
if (next.helpers.some((h) => isPlainObject(h) && h.alone !== true))
next.helpers = next.helpers.filter((h) => !(isPlainObject(h) && h.alone === true));
break;
case "docs":
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
@@ -4345,11 +4345,8 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,9 +1540,8 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent reported it has no
way to start helpers here. If it starts one after all, the note
goes away and the helper's row shows instead.
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,271 +36,85 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording was revised in v2.5.1 (Markdown sections); a change is a page change.
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
const template = (id, label, lines) => Object.freeze({ id, label, text: lines.join("\n") });
export const TEMPLATES = Object.freeze({
"engineering-spec": template("engineering-spec", "Engineering spec", [
"## Engineering spec",
"[the feature or change, in a sentence]",
"",
"## Who reads it",
"The engineers who will build and review it.",
"",
"## What it should pin down",
"The behaviour, the parts of the code it touches, the interfaces between them, the simpler options we're turning down, and how we'll know it works.",
"",
"## Out of scope",
"[what this deliberately won't do]",
"",
"## What I already know",
"[constraints, links, earlier attempts]",
"Engineering spec for: [the feature or change, in a sentence]",
"Who reads it: the engineers who will build and review it.",
"What it should pin down: the behaviour, the parts of the code it touches, the interfaces between them, and how we'll know it works.",
"What I already know: [constraints, links, earlier attempts]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"## Product requirements",
"[the feature, in a sentence]",
"",
"## Who it's for",
"[the users], and the product, design and engineering people deciding on it.",
"",
"## What it should pin down",
"The problem, who has it, the evidence it's real, and how we'll measure success.",
"",
"## Not doing",
"[what this release leaves out]",
"",
"## What I already know",
"[customer asks, data, deadlines]",
"Product requirements for: [the feature, in a sentence]",
"Who it's for: [the users], and the product, design and engineering people deciding on it.",
"What it should pin down: the problem, who has it, what success looks like, and what waits for later.",
"What I already know: [customer asks, data, deadlines]",
]),
"design-decision": template("design-decision", "Design decision", [
"## Design decision",
"[the choice we're facing, in a sentence]",
"",
"## Who it's for",
"The engineers and architects who will live with it.",
"",
"## What it should pin down",
"The options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"",
"## Constraints",
"[performance, compatibility, deadlines, team skills]",
"A design decision to work out: [the choice we're facing, in a sentence]",
"Who it's for: the engineers and architects who will live with it.",
"What it should pin down: the options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"Constraints: [performance, compatibility, deadlines, team skills]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"## Test strategy",
"[the feature or area]",
"",
"## Who reads it",
"QA and the engineers writing the tests.",
"",
"## What it should pin down",
'What\'s riskiest, meaning what costs most if it breaks, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"",
"## What exists today",
"[current tests, known gaps]",
"Test strategy for: [the feature or area]",
"Who reads it: QA and the engineers writing the tests.",
'What it should pin down: what\'s risky, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"What exists today: [current tests, known gaps]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"## Scoping and rollout",
"[the feature or project]",
"",
"## Who reads it",
"The engineering manager, the product lead and the team.",
"",
"## What it should pin down",
"What's in the first release and what waits, the build order, risks to the timeline, how it reaches users (flags, stages, who sees it first), and how we roll it back.",
"",
"## Constraints",
"[dates, people, dependencies]",
"Scoping and rollout for: [the feature or project]",
"Who reads it: the engineering manager, the product lead and the team.",
"What it should pin down: what's in the first release and what waits, the build order, risks to the timeline, and how it reaches users (flags, stages, who goes first).",
"Constraints: [dates, people, dependencies]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"## Brainstorm to curated notes",
"[the topic or rough idea]",
"",
"## Who reads the notes",
"[the team or people this goes to]",
"",
"## What I want out of it",
"The ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"",
"## Starting thoughts",
"[anything already on your mind]",
"Brainstorm to turn into curated notes: [the topic or rough idea]",
"Who reads the notes: [the team or people this goes to]",
"What I want out of it: the ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"Starting thoughts: [anything already on your mind]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"## Bug investigation",
"[what's going wrong, in a sentence]",
"",
"## Steps to reproduce",
"1. [first step]",
"2. [next step]",
"",
"## Expected",
"[what should happen]",
"",
"## Actual",
"[what happens instead]",
"",
"## How often",
"[every time, sometimes, once]",
"",
"## Error or logs",
"[paste the exact text]",
"",
"## Where and since when",
"[environment, version, first seen]",
"Bug to investigate: [what's going wrong, in a sentence]",
"Steps to reproduce: [1. ... 2. ...]",
"Expected: [what should happen]. Actual: [what happens instead]",
"Where and since when: [environment, version, first seen]",
]),
"small-change": template("small-change", "Small change", [
"## Small change",
"[what to change, in a sentence]",
"",
"## Where",
"[the file, screen or command, if you know it]",
"",
"## Leave alone",
"[anything that must not change]",
"",
"## Done when",
"[the command to run or the thing to check]",
"Small change: [what to change, in a sentence]",
"Where: [the file, screen or command, if you know it]",
"Done when: [how you'll tell it worked]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"## Copy or content tweak",
"[the screen, message, email or doc]",
"",
"## Current text",
"[paste it]",
"",
"## New text",
"[paste it, or describe the tone you want]",
"",
"## Who reads it",
"[the people who see it]",
"Change the wording of: [the screen, message, email or doc]",
"Current text: [paste it]",
"New text: [paste it, or describe the tone you want]",
"Who reads it: [the people who see it]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"## UI polish",
"[the screen or component]",
"",
"## What looks or feels off",
"[spacing, alignment, colour, states, small screens]",
"",
"## What good looks like",
"[a reference, screenshot or description]",
"",
"## Leave alone",
"[anything that must not move]",
"UI polish on: [the screen or component]",
"What looks or feels off: [spacing, alignment, colour, states, small screens]",
"What good looks like: [a reference, screenshot or description]",
"Leave alone: [anything that must not move]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"## Visual prototype",
"[the screen or component to mock up]",
"",
"## What to show",
"[the states or flows to click through]",
"",
"## What I want to learn",
"[the question it should answer]",
"",
"## Where it lives",
"A prototypes/ folder [or its own branch], never wired into the real code.",
"A throwaway visual prototype of: [the screen or component]",
"What to show: [the states or flows to click through]",
"What I want to learn: [the question it should answer]",
"Where it lives: a prototypes/ folder [or its own branch], never wired into the real code.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"## Add a test",
"[the function, behaviour or bug]",
"",
"## Cases to cover",
"- [the normal case]",
"- [the edge cases]",
"- [the failure or bug it guards against]",
"",
"## Where tests live",
"[the test file or folder, if you know it]",
"Add a test for: [the function, behaviour or bug]",
"Cases to cover: [the normal case, the edge cases, the bug it guards against]",
"Where tests live: [the test file or folder, if you know it]",
]),
"record-decision": template("record-decision", "Record a decision", [
"## Record a decision",
"[the decision we've already made, in a sentence]",
"",
"## Why",
"[what forced the choice, and the options we turned down]",
"",
"## What it commits us to",
"[the consequences]",
"",
"## Save it in",
"docs/adr/ [or wherever this repo keeps them]",
]),
refactor: template("refactor", "Refactor", [
"## Refactor",
"[what to restructure, in a sentence]",
"",
"## Why now",
"[what the current shape makes hard]",
"",
"## Behaviour that must not change",
"[the public API, outputs or tests that must stay the same]",
"",
"## Done when",
"[the tests that must still pass, and the shape it ends in]",
]),
"performance-problem": template("performance-problem", "Performance problem", [
"## Performance problem",
"[what's slow, in a sentence]",
"",
"## How it's measured today",
"[the number, and how you got it]",
"",
"## Target",
"[the number that counts as fixed]",
"",
"## Where",
"[the endpoint, page, query or job]",
]),
"dependency-upgrade": template("dependency-upgrade", "Dependency upgrade", [
"## Dependency upgrade",
"[the package, from version to version]",
"",
"## Why",
"[security fix, a feature we need, end of support]",
"",
"## Known breaking changes",
'[release notes link, or "not checked yet"]',
"",
"## Done when",
"[the build, tests or checks that must pass]",
]),
spike: template("spike", "Spike", [
"## Spike",
"[the question to answer, in a sentence]",
"",
"## Why it matters",
"[the decision waiting on the answer]",
"",
"## Time box",
"[how long before we stop and decide anyway]",
"",
"## Answered when",
"[the evidence that would settle it]",
]),
integration: template("integration", "Integration", [
"## Integration",
"[the system we're connecting to, and why]",
"",
"## What flows",
"[the data or events, and in which direction]",
"",
"## Their side",
"[API docs, auth method, rate limits, test sandbox]",
"",
"## When it fails",
"[what should happen if they're down or slow]",
]),
"data-migration": template("data-migration", "Data migration", [
"## Data migration",
"[what moves or changes shape]",
"",
"## Size and downtime",
"[row counts, and whether users can stay on while it runs]",
"",
"## Rollback",
"[how we undo it if it goes wrong]",
"",
"## Done when",
"[the checks that prove nothing was lost]",
"Record a decision we've already made: [the decision, in a sentence]",
"Why: [the reasons, and what we turned down]",
"What it commits us to: [the consequences]",
"Save it as an ADR in: docs/adr/ [or wherever this repo keeps them]",
]),
});
@@ -309,28 +123,28 @@ const orders = (byRole) => Object.freeze(Object.fromEntries(Object.entries(byRol
// One full order per role per skill. No "none" row: Not set reads Engineer's.
export const TEMPLATE_ORDERS = Object.freeze({
pathfinder: orders({
engineer: ["engineering-spec", "design-decision", "spike", "integration", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "spike", "engineering-spec", "design-decision", "integration", "test-strategy"],
architect: ["design-decision", "engineering-spec", "integration", "spike", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "spike", "engineering-spec", "scoping-rollout", "integration", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "spike", "product-requirements", "integration", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "spike", "test-strategy", "design-decision", "integration", "brainstorm-notes"],
engineer: ["engineering-spec", "design-decision", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "engineering-spec", "design-decision", "test-strategy"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "design-decision", "brainstorm-notes"],
}),
plan: orders({
engineer: ["engineering-spec", "bug-investigation", "refactor", "performance-problem", "integration", "data-migration", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "integration", "test-strategy", "design-decision", "performance-problem", "bug-investigation", "data-migration", "refactor"],
architect: ["design-decision", "engineering-spec", "data-migration", "integration", "refactor", "scoping-rollout", "performance-problem", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "performance-problem", "test-strategy", "bug-investigation", "integration", "refactor", "data-migration"],
qa: ["test-strategy", "bug-investigation", "performance-problem", "engineering-spec", "data-migration", "integration", "product-requirements", "scoping-rollout", "refactor", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "data-migration", "product-requirements", "test-strategy", "integration", "bug-investigation", "performance-problem", "refactor", "design-decision"],
engineer: ["engineering-spec", "bug-investigation", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "test-strategy", "design-decision", "bug-investigation"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "bug-investigation"],
qa: ["test-strategy", "bug-investigation", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "bug-investigation", "design-decision"],
}),
"quick-task": orders({
engineer: ["small-change", "bug-investigation", "refactor", "add-a-test", "dependency-upgrade", "performance-problem", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "performance-problem", "add-a-test", "record-decision", "dependency-upgrade", "refactor"],
architect: ["record-decision", "refactor", "small-change", "dependency-upgrade", "performance-problem", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "performance-problem", "add-a-test", "refactor", "dependency-upgrade", "record-decision"],
qa: ["add-a-test", "bug-investigation", "performance-problem", "small-change", "dependency-upgrade", "ui-polish", "refactor", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "dependency-upgrade", "add-a-test", "bug-investigation", "performance-problem", "refactor", "copy-tweak", "ui-polish", "visual-prototype"],
engineer: ["small-change", "bug-investigation", "add-a-test", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "add-a-test", "record-decision"],
architect: ["record-decision", "small-change", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "add-a-test", "record-decision"],
qa: ["add-a-test", "bug-investigation", "small-change", "ui-polish", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "add-a-test", "bug-investigation", "copy-tweak", "ui-polish", "visual-prototype"],
}),
});
@@ -88,7 +88,7 @@ export function cleanSetting(input) {
export const FRAME_LINES = Object.freeze([
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,14 +201,11 @@ export function switchLabel(frame) {
}
// What the Subagents tab draws: the working-alone note, or one row per helper
// in the order the agent reported them. A real helper supersedes the
// working-alone marker, so the note only draws when no helper was ever
// reported. A result shows once the helper ended.
// in the order the agent reported them. A result shows once the helper ended.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
const real = list.filter((h) => h.alone !== true);
if (!real.length) return { alone: list.some((h) => h.alone === true), rows: [] };
const rows = real.map(({ id, title, ask, state, result }) => ({
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
+2 -2
View File
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.1",
"version": "2.5.0",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-10-07",
"releaseDate": "2026-10-06",
"mode": "utility"
}
@@ -57,7 +57,7 @@ Run against EVERY finding. If any question raises doubt, re-investigate or drop.
**Finding survives (real bug):** Reviewer finds `processItems()` at line 47 accesses `items[0].id` with no empty-array check. Re-reads source — confirmed no guard. Traces callers — `orchestrator.js:82` can pass empty array. Adversarial check passes (correctness issue, additive fix). Presented at High.
**Finding dropped (pcweb-jira false positive):** Reviewer recommends removing `jira-api-catalog.md` from consumer loading to "reduce context." Adversarial check: "Does my fix remove something the system depends on?" YES — agents Read these files at runtime to construct valid API calls. Four of five checks fail. Dropped.
**Finding dropped (jira skill false positive):** Reviewer recommends removing `jira-api-catalog.md` from consumer loading to "reduce context." Adversarial check: "Does my fix remove something the system depends on?" YES — agents Read these files at runtime to construct valid API calls. Four of five checks fail. Dropped.
**Finding dropped (false consolidation):** Reviewer flags per-platform config files as "duplicates." Adversarial check: "Am I optimizing for the wrong metric?" YES — platforms have distinct values and will diverge further. Separation is a design choice. Dropped.
@@ -667,7 +667,7 @@ your next `chat` check.
Subagents: on (revision 2) — a console setting, not typed by the person.
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
With no way to start helpers, report one "working alone" entry for this skill run instead.
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
At most 3 helpers at once.
```
@@ -716,11 +716,8 @@ page never hears from a helper directly:
- Questions for the person stay with you, never with a helper: most harnesses
give helpers no way to ask, and an answer only reaches the agent holding the
session.
- **No way to start helpers at all?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
entry for the skill run instead. The tab then says you are working alone.
It is a claim about your tools, not about the moment — post it only when no
helper mechanism exists. Reporting a real helper removes it, so an early
`alone` can never hide a later helper.
- **Pathfinder:** research questions always use helpers and are always
reported, whatever the switch says. The switch governs recon, sketches and
lookups beside the conversation.
@@ -1211,10 +1211,6 @@ export function applyPatch(state, patch) {
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
// A real helper report supersedes the working-alone marker, whether it
// arrives after one or beside one.
if (next.helpers.some((h) => isPlainObject(h) && h.alone !== true))
next.helpers = next.helpers.filter((h) => !(isPlainObject(h) && h.alone === true));
break;
case "docs":
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
@@ -4345,11 +4345,8 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
input.setSelectionRange(text.length, text.length);
} catch {}
};
Loaded 100 of 132 files, more files were not shown because too many files have changed in this diff. Show more