From 54b316cdf37fc145d93ad241f7d64fe5e7ca8c84 Mon Sep 17 00:00:00 2001 From: Justin Parker Date: Wed, 11 Nov 2026 22:01:55 -0800 Subject: [PATCH] Add the UI Prototype skill, and have Quick Task confirm a saved prototype's brief before planning AI Assisted --- .agents-docs/AGENTS-architecture-console.md | 2 +- .agents-docs/AGENTS-architecture-install.md | 16 +- .../AGENTS-architecture-skill-scripts.md | 1 + .agents-docs/AGENTS-development-commands.md | 1 + .agents-docs/AGENTS-test-map.md | 1 + .readme/web-console.md | 2 +- AGENTS.md | 2 +- QUICK-REFERENCE.md | 1 + README.md | 4 + docs/index.html | 1 + .../screenshots/dashboard-utilities-dark.webp | Bin 119508 -> 123644 bytes .../dashboard-utilities-light.webp | Bin 129686 -> 134746 bytes install.js | 48 +- package.json | 2 +- scripts/check-console-openings.mjs | 4 +- .../bad-length-missing/round.json | 34 + .../bad-length-missing/variant-a.html | 23 + .../bad-length-missing/variant-b.html | 21 + .../bad-length-missing/variant-c.html | 18 + .../ui-prototype/bad-outside-link/round.json | 34 + .../bad-outside-link/variant-a.html | 23 + .../bad-outside-link/variant-b.html | 22 + .../bad-outside-link/variant-c.html | 19 + .../bad-round/missing-variant-file/round.json | 34 + .../missing-variant-file/variant-a.html | 23 + .../missing-variant-file/variant-b.html | 21 + .../bad-round/six-variants/round.json | 107 ++ .../bad-round/six-variants/variant-a.html | 23 + .../bad-round/six-variants/variant-b.html | 21 + .../bad-round/six-variants/variant-c.html | 19 + .../bad-round/six-variants/variant-d.html | 23 + .../bad-round/six-variants/variant-e.html | 23 + .../bad-round/six-variants/variant-f.html | 23 + .../bad-round/unknown-font-set/round.json | 92 ++ .../bad-round/unknown-font-set/variant-a.html | 23 + .../bad-round/unknown-font-set/variant-b.html | 21 + .../bad-round/unknown-font-set/variant-c.html | 19 + .../ui-prototype/bad-script/round.json | 34 + .../ui-prototype/bad-script/variant-a.html | 23 + .../ui-prototype/bad-script/variant-b.html | 22 + .../ui-prototype/bad-script/variant-c.html | 19 + .../ui-prototype/bad-state-missing/round.json | 34 + .../bad-state-missing/variant-a.html | 22 + .../bad-state-missing/variant-b.html | 21 + .../bad-state-missing/variant-c.html | 19 + .../ui-prototype/bad-step-missing/round.json | 29 + .../bad-step-missing/variant-a.html | 21 + .../bad-step-missing/variant-b.html | 14 + .../ui-prototype/bad-value-unused/round.json | 34 + .../bad-value-unused/variant-a.html | 23 + .../bad-value-unused/variant-b.html | 21 + .../bad-value-unused/variant-c.html | 19 + .../fixtures/ui-prototype/blocks/edited.txt | 21 + .../ui-prototype/blocks/not-a-block.txt | 3 + .../fixtures/ui-prototype/blocks/screen.txt | 21 + .../fixtures/ui-prototype/blocks/terminal.txt | 13 + .../ui-prototype/contract-example/round.json | 29 + .../contract-example/variant-a.html | 27 + .../contract-example/variant-b.html | 19 + .../ui-prototype/good-flow/expected-block.txt | 20 + .../ui-prototype/good-flow/round.json | 29 + .../ui-prototype/good-flow/variant-a.html | 21 + .../ui-prototype/good-flow/variant-b.html | 21 + .../good-screen/expected-block.txt | 23 + .../ui-prototype/good-screen/round.json | 34 + .../ui-prototype/good-screen/variant-a.html | 23 + .../ui-prototype/good-screen/variant-b.html | 22 + .../ui-prototype/good-screen/variant-c.html | 19 + .../good-terminal/expected-block.txt | 17 + .../ui-prototype/good-terminal/round.json | 25 + .../ui-prototype/good-terminal/variant-a.html | 7 + .../ui-prototype/good-terminal/variant-b.html | 7 + .../ui-prototype/hostile-text/round.json | 34 + .../ui-prototype/hostile-text/variant-a.html | 25 + .../ui-prototype/hostile-text/variant-b.html | 21 + .../ui-prototype/hostile-text/variant-c.html | 19 + .../fixtures/ui-prototype/images/avatar.webp | Bin 0 -> 34 bytes .../fixtures/ui-prototype/images/badge.svg | 1 + scripts/fixtures/ui-prototype/images/hero.jpg | Bin 0 -> 134 bytes scripts/fixtures/ui-prototype/images/logo.png | Bin 0 -> 70 bytes .../fixtures/ui-prototype/images/photo.png | 1 + .../ui-prototype/with-images/round.json | 113 ++ .../ui-prototype/with-images/variant-a.html | 32 + .../ui-prototype/with-images/variant-b.html | 22 + .../ui-prototype/with-images/variant-c.html | 19 + scripts/test-check-console-openings.mjs | 3 +- scripts/test-console-wire-budgets.mjs | 9 +- scripts/test-lanes.json | 2 + scripts/test-script-ui-prototype.mjs | 1025 +++++++++++++ scripts/test-ui-prototype-page.mjs | 910 +++++++++++ scripts/test-web-console-logic.mjs | 12 +- scripts/test-web-console-page-dashboard.mjs | 33 + scripts/test-web-console-server.mjs | 5 +- scripts/test-web-console-spec-states.mjs | 51 +- scripts/test-web-console-speed.mjs | 2 +- .../resolve.md | 12 +- src/plan2code-0-pathfinder.md | 1 + src/plan2code-1-plan.md | 5 +- src/plan2code-1b-revise-plan.md | 6 +- src/plan2code-3-implement.md | 2 + src/plan2code-quick-task.md | 5 +- .../ui-prototype-contract.md | 280 ++++ .../ui-prototype-design.md | 114 ++ .../ui-prototype-rounds.md | 84 + .../ui-prototype-shell/base.css | 170 +++ .../ui-prototype-shell/shell.css | 582 +++++++ .../ui-prototype-shell/shell.html | 51 + .../ui-prototype-shell/shell.js | 1360 +++++++++++++++++ src/plan2code-ui-prototype.md | 145 ++ src/plan2code.md | 15 +- src/skill-scripts/ui-prototype-block.mjs | 114 ++ src/skill-scripts/ui-prototype-drafts.mjs | 61 + src/skill-scripts/ui-prototype-page.mjs | 352 +++++ src/skill-scripts/ui-prototype-round.mjs | 178 +++ src/skill-scripts/ui-prototype.mjs | 575 +++++++ src/web-console/console-meter.md | 2 +- src/web-console/console.md | 2 +- src/web-console/notes/pathfinder.md | 2 + src/web-console/notes/plan.md | 1 + src/web-console/notes/quick-task.md | 3 + src/web-console/notes/revise-plan.md | 2 + src/web-console/notes/ui-prototype.md | 31 + src/web-console/public/answers.js | 8 +- src/web-console/public/index.html | 34 + src/web-console/public/meter.js | 4 + src/web-console/public/screens/dashboard.js | 3 +- src/web-console/public/skills.js | 25 + src/web-console/public/styles/poses.css | 11 + src/web-console/scan.mjs | 27 +- src/web-console/sessions.mjs | 2 +- 130 files changed, 8065 insertions(+), 50 deletions(-) create mode 100644 scripts/fixtures/ui-prototype/bad-length-missing/round.json create mode 100644 scripts/fixtures/ui-prototype/bad-length-missing/variant-a.html create mode 100644 scripts/fixtures/ui-prototype/bad-length-missing/variant-b.html create mode 100644 scripts/fixtures/ui-prototype/bad-length-missing/variant-c.html create mode 100644 scripts/fixtures/ui-prototype/bad-outside-link/round.json create mode 100644 scripts/fixtures/ui-prototype/bad-outside-link/variant-a.html create mode 100644 scripts/fixtures/ui-prototype/bad-outside-link/variant-b.html create mode 100644 scripts/fixtures/ui-prototype/bad-outside-link/variant-c.html create mode 100644 scripts/fixtures/ui-prototype/bad-round/missing-variant-file/round.json create mode 100644 scripts/fixtures/ui-prototype/bad-round/missing-variant-file/variant-a.html create mode 100644 scripts/fixtures/ui-prototype/bad-round/missing-variant-file/variant-b.html create mode 100644 scripts/fixtures/ui-prototype/bad-round/six-variants/round.json create mode 100644 scripts/fixtures/ui-prototype/bad-round/six-variants/variant-a.html create mode 100644 scripts/fixtures/ui-prototype/bad-round/six-variants/variant-b.html create mode 100644 scripts/fixtures/ui-prototype/bad-round/six-variants/variant-c.html create mode 100644 scripts/fixtures/ui-prototype/bad-round/six-variants/variant-d.html create mode 100644 scripts/fixtures/ui-prototype/bad-round/six-variants/variant-e.html create mode 100644 scripts/fixtures/ui-prototype/bad-round/six-variants/variant-f.html create mode 100644 scripts/fixtures/ui-prototype/bad-round/unknown-font-set/round.json create mode 100644 scripts/fixtures/ui-prototype/bad-round/unknown-font-set/variant-a.html create mode 100644 scripts/fixtures/ui-prototype/bad-round/unknown-font-set/variant-b.html create mode 100644 scripts/fixtures/ui-prototype/bad-round/unknown-font-set/variant-c.html create mode 100644 scripts/fixtures/ui-prototype/bad-script/round.json create mode 100644 scripts/fixtures/ui-prototype/bad-script/variant-a.html create mode 100644 scripts/fixtures/ui-prototype/bad-script/variant-b.html create mode 100644 scripts/fixtures/ui-prototype/bad-script/variant-c.html create mode 100644 scripts/fixtures/ui-prototype/bad-state-missing/round.json create mode 100644 scripts/fixtures/ui-prototype/bad-state-missing/variant-a.html create mode 100644 scripts/fixtures/ui-prototype/bad-state-missing/variant-b.html create mode 100644 scripts/fixtures/ui-prototype/bad-state-missing/variant-c.html create mode 100644 scripts/fixtures/ui-prototype/bad-step-missing/round.json create mode 100644 scripts/fixtures/ui-prototype/bad-step-missing/variant-a.html create mode 100644 scripts/fixtures/ui-prototype/bad-step-missing/variant-b.html create mode 100644 scripts/fixtures/ui-prototype/bad-value-unused/round.json create mode 100644 scripts/fixtures/ui-prototype/bad-value-unused/variant-a.html create mode 100644 scripts/fixtures/ui-prototype/bad-value-unused/variant-b.html create mode 100644 scripts/fixtures/ui-prototype/bad-value-unused/variant-c.html create mode 100644 scripts/fixtures/ui-prototype/blocks/edited.txt create mode 100644 scripts/fixtures/ui-prototype/blocks/not-a-block.txt create mode 100644 scripts/fixtures/ui-prototype/blocks/screen.txt create mode 100644 scripts/fixtures/ui-prototype/blocks/terminal.txt create mode 100644 scripts/fixtures/ui-prototype/contract-example/round.json create mode 100644 scripts/fixtures/ui-prototype/contract-example/variant-a.html create mode 100644 scripts/fixtures/ui-prototype/contract-example/variant-b.html create mode 100644 scripts/fixtures/ui-prototype/good-flow/expected-block.txt create mode 100644 scripts/fixtures/ui-prototype/good-flow/round.json create mode 100644 scripts/fixtures/ui-prototype/good-flow/variant-a.html create mode 100644 scripts/fixtures/ui-prototype/good-flow/variant-b.html create mode 100644 scripts/fixtures/ui-prototype/good-screen/expected-block.txt create mode 100644 scripts/fixtures/ui-prototype/good-screen/round.json create mode 100644 scripts/fixtures/ui-prototype/good-screen/variant-a.html create mode 100644 scripts/fixtures/ui-prototype/good-screen/variant-b.html create mode 100644 scripts/fixtures/ui-prototype/good-screen/variant-c.html create mode 100644 scripts/fixtures/ui-prototype/good-terminal/expected-block.txt create mode 100644 scripts/fixtures/ui-prototype/good-terminal/round.json create mode 100644 scripts/fixtures/ui-prototype/good-terminal/variant-a.html create mode 100644 scripts/fixtures/ui-prototype/good-terminal/variant-b.html create mode 100644 scripts/fixtures/ui-prototype/hostile-text/round.json create mode 100644 scripts/fixtures/ui-prototype/hostile-text/variant-a.html create mode 100644 scripts/fixtures/ui-prototype/hostile-text/variant-b.html create mode 100644 scripts/fixtures/ui-prototype/hostile-text/variant-c.html create mode 100644 scripts/fixtures/ui-prototype/images/avatar.webp create mode 100644 scripts/fixtures/ui-prototype/images/badge.svg create mode 100644 scripts/fixtures/ui-prototype/images/hero.jpg create mode 100644 scripts/fixtures/ui-prototype/images/logo.png create mode 100644 scripts/fixtures/ui-prototype/images/photo.png create mode 100644 scripts/fixtures/ui-prototype/with-images/round.json create mode 100644 scripts/fixtures/ui-prototype/with-images/variant-a.html create mode 100644 scripts/fixtures/ui-prototype/with-images/variant-b.html create mode 100644 scripts/fixtures/ui-prototype/with-images/variant-c.html create mode 100644 scripts/test-script-ui-prototype.mjs create mode 100644 scripts/test-ui-prototype-page.mjs create mode 100644 src/plan2code-ui-prototype-references/ui-prototype-contract.md create mode 100644 src/plan2code-ui-prototype-references/ui-prototype-design.md create mode 100644 src/plan2code-ui-prototype-references/ui-prototype-rounds.md create mode 100644 src/plan2code-ui-prototype-references/ui-prototype-shell/base.css create mode 100644 src/plan2code-ui-prototype-references/ui-prototype-shell/shell.css create mode 100644 src/plan2code-ui-prototype-references/ui-prototype-shell/shell.html create mode 100644 src/plan2code-ui-prototype-references/ui-prototype-shell/shell.js create mode 100644 src/plan2code-ui-prototype.md create mode 100644 src/skill-scripts/ui-prototype-block.mjs create mode 100644 src/skill-scripts/ui-prototype-drafts.mjs create mode 100644 src/skill-scripts/ui-prototype-page.mjs create mode 100644 src/skill-scripts/ui-prototype-round.mjs create mode 100644 src/skill-scripts/ui-prototype.mjs create mode 100644 src/web-console/notes/ui-prototype.md diff --git a/.agents-docs/AGENTS-architecture-console.md b/.agents-docs/AGENTS-architecture-console.md index 4efd093..0ffc6dd 100644 --- a/.agents-docs/AGENTS-architecture-console.md +++ b/.agents-docs/AGENTS-architecture-console.md @@ -45,5 +45,5 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web | `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. The `plan2code` launcher reads the same cache for its terminal release notice (a copy of this module sits in `~/.plan2code/bin/`) | | `console.md` | the core of the agent-facing contract, read once per conversation (every skill ships the same copy, so a dashboard hop never re-reads it): starting, the turn (`post --wait`, the exit codes, handling a send, `settle`), posting, the payload and its kinds, documents (including `file` blocks), the house rules, and an index of the topic files below with the moment each is read. A test caps it at 24,000 characters | | `console-finish.md` · `console-stop.md` · `console-chat.md` · `console-workspace.md` · `console-subagents.md` · `console-launches.md` · `console-meter.md` · `console-attachments.md` · `console-trouble.md` | topic files, each read only when its moment first comes: finishing (the finish and its buttons), stop requests (the way home mid-workflow, `stopWarning`, resuming a pause), Quick questions, the Workspace, standing instructions and helper reports, dashboard launches and the menu payload, the session meter's `run` events (read only when a `run` is refused: the notes inline every `run`), keeping a cited note attachment, and recovery | -| `notes/.md` | per-workflow notes (`init` for both inits, `pathfinder` with Briefs, `plan`, `revise-plan`, `document`, `implement` for both builds, `loop` for a build the desktop app's Implementation Loop runs with `--loop` (where it reports a `loopOutcome` instead of asking for sign-off), `quick-task`, `review`, `finalize`, `handoff`, `changelog`, `git`, `xray`, `diagnose`, `pr-prep`, `test`, `dead-code`). Each skill's Interface line reads `/console.md` and its own notes file right after `open`; a test checks every skill names one that exists | +| `notes/.md` | per-workflow notes (`init` for both inits, `pathfinder` with Briefs, `plan`, `revise-plan`, `document`, `implement` for both builds, `loop` for a build the desktop app's Implementation Loop runs with `--loop` (where it reports a `loopOutcome` instead of asking for sign-off), `quick-task`, `review`, `finalize`, `handoff`, `changelog`, `git`, `xray`, `diagnose`, `pr-prep`, `test`, `dead-code`, `ui-prototype`). Each skill's Interface line reads `/console.md` and its own notes file right after `open`; a test checks every skill names one that exists | | `building.md` · `building-review.md` | the build half of the contract, for `implement`, `implement-review` and `quick-task`: progress posts (`agent.activity`, `agent.quietMinutes`, `file` blocks re-read with `refresh`), the chat check between tasks, questions mid-build and stop requests; `building-review.md` is the review run on the page (the sign-off's `review` verdict, **Review it now**, Implement + Review's Stage 2, Finalize's Step 2.5), read only when asked for | diff --git a/.agents-docs/AGENTS-architecture-install.md b/.agents-docs/AGENTS-architecture-install.md index 7f49373..80782df 100644 --- a/.agents-docs/AGENTS-architecture-install.md +++ b/.agents-docs/AGENTS-architecture-install.md @@ -5,7 +5,7 @@ ``` plan2code/ -├── src/ # Source workflow prompts (20 markdown files) +├── src/ # Source workflow prompts (21 markdown files) │ ├── plan2code-0-pathfinder-references/ # Reference files for pathfinder skill │ │ ├── brief.md # Dated plain-English decision briefs │ │ ├── chart.md # MODE A: destination + frontier grills, templates @@ -32,6 +32,11 @@ plan2code/ │ │ └── community-feedback-submission.md # STEP 6.5 payload schema + submission tiers │ ├── plan2code-dead-code-references/ # Reference files for dead-code skill │ │ └── caller-search.md # How to search for a symbol's callers before calling it dead +│ ├── plan2code-ui-prototype-references/ # Reference files for ui-prototype skill +│ │ ├── ui-prototype-contract.md # The contract between model-written variants and the shipped shell +│ │ ├── ui-prototype-design.md # Making each variant look designed: structure, type, color, the dials +│ │ ├── ui-prototype-rounds.md # Rounds, the paste back, the save into a spec +│ │ └── ui-prototype-shell/ # The page shell the script assembles every round from (shell.html, shell.js, shell.css, base.css) │ ├── skill-scripts/ # Scripts shared across skills: install.js copies the ones a skill lists into skills//scripts/ (specs, commit-msg, review-scope, agents-md, agent-files, glob, test-map, test-match, test-commands, run-check, common) │ └── plan2code--scripts/ # A skill's own scripts, same copy rule (pathfinder, finalize, changelog, git, xray, pr-prep, test and dead-code each have one) ├── plan2code-bot/ # Autonomous end-to-end workflow test runner (TypeScript, tsup, Claude Agent SDK, vitest); user docs in .readme/test-bot.md @@ -134,10 +139,10 @@ plan2code/ | `plan2code.md` | — | The dashboard: opens the web console's skill menu and launches the picked skill into its own session | | `plan2code-init.md` | Init | Generate AGENTS.md as index + `.agents-docs/` section files (progressive discovery) | | `plan2code-init-update.md` | Update | Update AGENTS.md with learnings; detects and routes edits to `.agents-docs/` files | -| `plan2code-0-pathfinder.md` | 0 | Chart a foggy idea as a map (local files, or GitHub Issues) of decision questions under `specs//pathfinder/`, resolve them one at a time, hand a seeded PLAN-DRAFT to Step 1 | -| `plan2code-quick-task.md` | quick | Lightweight planning for small tasks (standalone — not a pipeline step) | -| `plan2code-1-plan.md` | 1 | Requirements analysis & architecture | -| `plan2code-1b-revise-plan.md` | 1b | Mid-implementation revisions | +| `plan2code-0-pathfinder.md` | 0 | Chart a foggy idea as a map (local files, or GitHub Issues) of decision questions under `specs//pathfinder/`, resolve them one at a time, hand a seeded PLAN-DRAFT to Step 1; ships `ui-prototype.md`, its `ui-prototype-*` references, the shell and the five `ui-prototype*.mjs` scripts (ride-along) for its offer of a UI prototype, which replaces the runnable UI sketch | +| `plan2code-quick-task.md` | quick | Lightweight planning for small tasks (standalone — not a pipeline step); ships `ui-prototype.md`, its `ui-prototype-*` references, the shell and the five `ui-prototype*.mjs` scripts (ride-along) for its offer of a UI prototype | +| `plan2code-1-plan.md` | 1 | Requirements analysis & architecture; ships `ui-prototype.md`, its `ui-prototype-*` references, the shell and the five `ui-prototype*.mjs` scripts (ride-along) for its offer of a UI prototype | +| `plan2code-1b-revise-plan.md` | 1b | Mid-implementation revisions; ships `ui-prototype.md`, its `ui-prototype-*` references, the shell and the five `ui-prototype*.mjs` scripts (ride-along) for its offer of a UI prototype | | `plan2code-2-document.md` | 2 | Create implementation specs | | `plan2code-3-implement.md` | 3 | Execute implementation (phase by phase) | | `plan2code-3-implement-review.md` | 3 | Execute one phase, run focused review and fixes, then request approval | @@ -149,6 +154,7 @@ plan2code/ | `plan2code-pr-prep.md` | pr-prep | Get a branch ready for review: pick the checks its changes need from the project's `## Test map` (or its config files), let the person trim the plan, run it, give Ready, Ready with notes or Not ready, and write a PR description to copy (following the repo's template) with the create-a-PR link; offers to save `PR-READINESS-.md` into the branch's spec folder; never commits, pushes or opens the PR | | `plan2code-test.md` | test | Write missing tests: ask where to look, find source files no test covers (matching, plus real coverage when the project already has a coverage tool, offered first), show a plan opening with how this project writes tests, then write and run unit and integration tests; escalates past 8 source files, 8 new test files or 2 runners to a PLAN-DRAFT for Plan, hands a real bug to Diagnose, never changes source code | | `plan2code-dead-code.md` | dead-code | Find unused code and dead code: use the project's own dead-code tools, one per language that has files (Knip, vulture, cargo check and others), or search by itself, check every item for callers across the project (`references/caller-search.md`), label each Safe to remove, Check first or Warning, remove only what the person picks, then run the tests and build and put back anything that breaks them, then offer a final review of the removals in the same session (Step 7.5, recommended yes; ships `review.md`, `review-in-build.md`, `test-runs.md` and the review references, as Finalize does); never commits, never installs a tool. Scripts: `dead-code.mjs` (own), `test-map.mjs`, `glob.mjs`, `test-commands.mjs`, `run-check.mjs`, `specs.mjs`, `commit-msg.mjs`, `review-scope.mjs` | +| `plan2code-ui-prototype.md` | ui-prototype | Draw several versions of a screen or flow on one page with live dials (drafts under `~/.plan2code/prototypes/`), bring the pick back by Copy and paste for the next round, and save the pair into `specs//prototypes/` only on a yes; never changes code | | `plan2code-changelog.md` | changelog | Check the CHANGELOG version against the default branch, suggest editable entries for new work, keep `package.json` aligned, offer to commit the result through Git | | `plan2code-git.md` | git | Branches, pull (with conflict help), push, publish and commits (clear message, suggested splits) on the web console's git board, or plain instructions in the terminal (`switch to main`, `commit and push`); asks before every push, publish and delete | diff --git a/.agents-docs/AGENTS-architecture-skill-scripts.md b/.agents-docs/AGENTS-architecture-skill-scripts.md index b77672c..a2e2992 100644 --- a/.agents-docs/AGENTS-architecture-skill-scripts.md +++ b/.agents-docs/AGENTS-architecture-skill-scripts.md @@ -32,6 +32,7 @@ Anything a workflow step decides with one correct answer (parsing a spec's check | `xray.mjs` (own) | xray | `hotspots` (churn, files changed together, often-changed files with no test, from `git log` over a capped window) and `history ` (commits following renames, a blame summary, PR titles and first paragraphs through `gh` when signed in, and which sources were used). Read-only | | `changelog-state.mjs` (own) | changelog | `state`, `bump`, `set-package-version`: the default branch's version, whether the branch's entry can be extended (not released, not on another branch), the file's heading style, the gap since the entry was last touched; only `set-package-version` writes, and only the version field | | `git.mjs` (own) | git | `state`, `plan`, `branch-check`, `init-check`, `delete-check`, `cleanup-list`, `conflicts`, `pr-url`, `classify-error`: the repo snapshot, each action's exact command and confirm text (shared by the terminal and the board), branch-name, delete, cleanup and git init checks, a stopped rebase's conflicts, the pull-request link and git's errors sorted into kinds with a next step. Read-only: the agent runs every command it prints, and `guard()` refuses force push, hook skipping, amend, remote delete and blanket add | +| `ui-prototype.mjs` (shared, with `ui-prototype-round.mjs`, `ui-prototype-page.mjs`, `ui-prototype-drafts.mjs`, `ui-prototype-block.mjs`) | ui-prototype, pathfinder, plan, revise-plan, quick-task (ride-along) | `sweep` (drafts older than 30 days), `new-round`, `assemble` (the page from `round.json`, the variant files and the shell in `references/ui-prototype-shell/`, images and fonts embedded; exit 4 `round-mismatch` when a drafts round's `round.json` names another `name` or `round` than its folder), `check` (the contract's rules, the three image rules `image-type`, `image-size` and `image-missing`, and the size ceiling), `open` (the default browser), `read-block` (a pasted choice block from stdin into fields) and `save` (the pair `specs//prototypes/.html` and `.md`, then that prototype's drafts removed). Writes only under `~/.plan2code/prototypes//` and, on `save`, the spec's `prototypes/`; never writes project code, never opens a page outside the drafts or `specs/`, never fetches anything over the network. The helper modules are imported only by `ui-prototype.mjs` | **Conventions** (`common.mjs`): Node 18+ built-ins only; one JSON object on stdout (`ok: false` plus `error`, `message`, `next` on a handled failure, the same line on stderr); exit 0 ok, 1 crash, 2 bad arguments, 3 not found, 4 invalid or check failed, 5 refused; `--help` documents commands and exit codes; writes take `--dry-run`; `PLAN2CODE_NOW` pins the clock for tests. A SKILL.md names a script as `node "/.mjs"`, where `` is `scripts/` beside it. diff --git a/.agents-docs/AGENTS-development-commands.md b/.agents-docs/AGENTS-development-commands.md index bd7de65..fb6ebe3 100644 --- a/.agents-docs/AGENTS-development-commands.md +++ b/.agents-docs/AGENTS-development-commands.md @@ -90,6 +90,7 @@ The same areas as one-command rows live in the [Test map](./AGENTS-test-map.md), | The launcher (`src/launcher/`) | `node --test scripts/test-launcher.mjs` | | A skill's script | `npm run build:skills`, then `node --test scripts/test-script-.mjs` (and `test-skill-scripts.mjs` for the shared plumbing) | | Dead Code (`src/plan2code-dead-code-scripts/`, `scripts/fixtures/dead-code/`) | `npm run build:skills`, then `node scripts/node-test.mjs scripts/test-script-dead-code.mjs` | +| UI Prototype (`src/skill-scripts/ui-prototype*.mjs`, `src/plan2code-ui-prototype-references/`, `scripts/fixtures/ui-prototype/`) | `npm run build:skills`, then `node scripts/node-test.mjs scripts/test-script-ui-prototype.mjs scripts/test-ui-prototype-page.mjs` | | A workflow prompt (`src/plan2code-*.md`) | `node scripts/validate-char-count.js` and `node scripts/check-skill-table.mjs` | | A new skill or console workflow | First update the hand-written tables that list every workflow: the `SUBAGENT_WORKFLOWS` count and the meter's `WEIGHTS`, `LAUNCH_LABELS` and `RUN_LABELS` in `test-web-console-logic.mjs`, `notesFor` in `test-web-console-speed.mjs`, the event list in `src/web-console/console-meter.md` (checked by `test-web-console-chat-stress.mjs`) and a `BUDGETS.notes` entry in `test-console-wire-budgets.mjs`. Then run those four suites plus `test-web-console-skills.mjs` and `test-web-console-spec-states.mjs`; the PR Prep and Test build missed all five tables and only the full suite caught them | | Docs or comments only | `node --test scripts/test-us-english.mjs scripts/test-line-endings.mjs` | diff --git a/.agents-docs/AGENTS-test-map.md b/.agents-docs/AGENTS-test-map.md index 7222dc2..68caee5 100644 --- a/.agents-docs/AGENTS-test-map.md +++ b/.agents-docs/AGENTS-test-map.md @@ -8,6 +8,7 @@ Which checks cover which files, read by PR Prep and Test (`test-map.mjs read` ch | Activities games | `src/web-console/public/activities/**`, `src/web-console/public/tones.js`, `src/web-console/public/music.js` | `node --test scripts/test-web-console-tones.mjs scripts/test-web-console-activities.mjs` | no | | Launcher | `src/launcher/**` | `node --test scripts/test-launcher.mjs` | no | | Dead Code script | `src/plan2code-dead-code-scripts/**`, `scripts/fixtures/dead-code/**` | `npm run build:skills && node scripts/node-test.mjs scripts/test-script-dead-code.mjs` | no | +| UI Prototype script and shell | `src/skill-scripts/ui-prototype*.mjs`, `src/plan2code-ui-prototype-references/**`, `scripts/fixtures/ui-prototype/**` | `npm run build:skills && node scripts/node-test.mjs scripts/test-script-ui-prototype.mjs scripts/test-ui-prototype-page.mjs` | no | | Workflow prompts | `src/plan2code-*.md` | `node scripts/validate-char-count.js && node scripts/check-skill-table.mjs` | no | | Desktop app | `plan2code-app/**` | `cd plan2code-app && cargo test` | no | | Metrics | `plan2code-metrics/**` | `cd plan2code-metrics && npm test` | no | diff --git a/.readme/web-console.md b/.readme/web-console.md index a35f95f..c4ea114 100644 --- a/.readme/web-console.md +++ b/.readme/web-console.md @@ -55,7 +55,7 @@ Scroll down for the utilities. Outside a git repository the **Git** card says so - The utility cards: Get a PR ready, Write missing tests, Clear out dead code, Changelog, Git, which notes that the folder is not a git repository yet and offers to start one, and Handoff. + The utility cards: Get a PR ready, Write missing tests, Clear out dead code, Prototype a screen, Changelog, and Git, which notes that the folder is not a git repository yet and offers to start one. --- diff --git a/AGENTS.md b/AGENTS.md index fb12d7f..3e49984 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,7 +36,7 @@ Details: [Status line](./.agents-docs/AGENTS-architecture-statusline.md) ## Web Console -Optional local browser UI (`src/web-console/`, zero dependencies, detached `node` server on `127.0.0.1`) installed once under `~/.plan2code/console//` (`installSharedConsole` in `install.js`) and reached from every skill through a forwarding stub, `src/web-console-stub/console.mjs`. The bare `plan2code` skill opens its dashboard, a card menu that launches any skill in the same session. Pages cover questions, sign-off gates (with an in-page code review), build progress, the living document, an **Ask** chat, a read-only **Workspace** of extra folders (remembered per folder and spec in `~/.plan2code/console/workspaces.json`), a session meter, a **git board** for the `git` workflow (three tabs, Changes, Branches and Sync, opening on the likely next step; branches, pull, push, commits and pull-request links, drawn from `state.git`; contract in `notes/git.md`), **Stop with a handoff** (handoffs live in `~/.plan2code/handoffs/`, owned by `handoffs.mjs`, swept after 30 days, and offered as dashboard chips to pick up in the same session), a private **Notebook** in the top bar (named tabs of Markdown and pictures, a live-preview CodeMirror editor, one notepad per folder in `~/.plan2code/notepads/`, owned by `notepads.mjs`, private: the agent reads a tab only when you start Pathfinder, Plan, Quick Task or Revise plan from the dashboard with it and send the box it fills (an idea box marked `fill: "note"`, up to five ticked pictures attached), which then marks the tab sent via `POST /notepad/tab/sent`; the agent CLI never imports the store; removed only through Cleanup once a month untouched), **Activities** behind the top bar's die (thirteen small games, Snake, Mini golf, Light Trails, Bug Hunt, Sunset Drive, Stack Deploy, Bumper Ring, Rapids Run, Hot Potato, Crossing Rush, Bounce Road, Ghoul Rush and Flock Dash, listed in `public/activities.js` with one module per game under `public/activities/` (Ghoul Rush is its own folder of modules, `public/activities/ghoul-rush/`) and a card line (`blurb`) each, a picker page of game cards once two are listed that plays one game at a time (another pick drops the last game's round), driven by `screens/activities.js` (keys, key releases for a game with `release()`, canvas pointer events for a game with `pointer()`, one frame timer), paused whenever the person's turn comes and resumed only by the person (while that pause's banner is up, only by its **Unpause game** button), best scores in flat `activityBest` keys in `looks.json` (lowest wins for a game that sets `lowerIsBetter`; Mini golf opens on a dashboard of its six 18-hole courses, one file each under `public/activities/golf-course-.js`, and keeps a best per course, `activityBestGolf`), and one number a game may keep between sessions in `activityMemo` (Snake's tally of surprises found, Light Trails' furthest arena, Bug Hunt's tally of finds, Sunset Drive's roads found, Stack Deploy's highest floor, Bumper Ring's furthest arena, Rapids Run's furthest dam, Hot Potato's furthest venue, Crossing Rush's furthest zone, Bounce Road's furthest stage, Ghoul Rush's most stages cleared in a run, Flock Dash's furthest stage), never shown to the agent), a built-in 21-topic Help, the app-only **Implementation Loop** (a dashboard card and a setup screen drawn by the page, `public/screens/loop-setup.js`; the last setup remembered per project in `~/.plan2code/console/loop-setup.json`, owned by `loop-setup.mjs`; a page that locks while `state.loop.driving` is set, until the app posts `loopEnd`; a skill run with `--loop` reports a `loopOutcome` instead of asking for sign-off, per `notes/loop.md`), a first-run Welcome, User Preferences (gear: four tabs, Appearance, Agents & models, System and Sounds & activities, on the `public/tabs.js` helper Help also uses, with `public/prefs.js`, `screens/prefs-dialog.js` and `screens/agents-view.js`), an agent-less **setup** page (the `setup` workflow `plan2code` or the desktop app opens when no agent can run: each built-in's found / outside-PATH / missing state from `agent-lookup.mjs`, install lines, Check again, Use it from here, starter templates and Start, which hands the tab to the new agent through a token-guarded `POST /handover` and a `move` event; the app shows it in its window from a Set up an agent button instead) and a bug/idea link to GitHub issues. On opted-in skills (every workflow but the dashboard, setup, Changelog, Git and Handoff) a **Subagents** button in the top bar turns helpers on or off per project and skill (on by default for those skills until switched off, saved in `~/.plan2code/console/subagents.json`), and a Helper strength choice (Balanced, Thrifty, Best, Match my session; rules in `src/shared-references/helper-strength.md`, shipped in the sixteen helper skills); the agent hears of it as a standing instruction only when it changes, and reports its helpers in a **Subagents** tab beside Ask (contract in `console-subagents.md`). Per-skill facts live in one list, `public/skills.js`, from which the meter, the resume command, Help's card list and the CLI's workflow list are derived; task files are read through `spec-files.mjs` (shared with the `specs.mjs` skill script), and the rule for which hops start the page clean is `startsClean()` in `public/hops.js`. The agent contract is a card plus pointers: `console.md` (the card) once per conversation, then a topic file (`console-*.md` such as `console-docs.md`, `notes/.md`, `building*.md`) only when the console names it in its own `read` output, once per session per topic (remembered in `pointers.json` in the session folder, owned by `pointers.mjs`); the console refuses the slips it can see (a `stop` with no `finish`, a `finish` while `stopWarning` is set, with `stop --force` for a dead page) instead of the docs repeating each rule. Byte budgets for the card, every notes file and a sample session's outputs run in `npm test` (`scripts/test-console-wire-budgets.mjs`). The server never writes into a project; the one thing it deletes there is an old `specs--completed/` the person picks in Cleanup, and only when git tracks it (an untracked one is refused, with the reason on the page). +Optional local browser UI (`src/web-console/`, zero dependencies, detached `node` server on `127.0.0.1`) installed once under `~/.plan2code/console//` (`installSharedConsole` in `install.js`) and reached from every skill through a forwarding stub, `src/web-console-stub/console.mjs`. The bare `plan2code` skill opens its dashboard, a card menu that launches any skill in the same session. Pages cover questions, sign-off gates (with an in-page code review), build progress, the living document, an **Ask** chat, a read-only **Workspace** of extra folders (remembered per folder and spec in `~/.plan2code/console/workspaces.json`), a session meter, a **git board** for the `git` workflow (three tabs, Changes, Branches and Sync, opening on the likely next step; branches, pull, push, commits and pull-request links, drawn from `state.git`; contract in `notes/git.md`), **Stop with a handoff** (handoffs live in `~/.plan2code/handoffs/`, owned by `handoffs.mjs`, swept after 30 days, and offered as dashboard chips to pick up in the same session), a private **Notebook** in the top bar (named tabs of Markdown and pictures, a live-preview CodeMirror editor, one notepad per folder in `~/.plan2code/notepads/`, owned by `notepads.mjs`, private: the agent reads a tab only when you start Pathfinder, Plan, Quick Task or Revise plan from the dashboard with it and send the box it fills (an idea box marked `fill: "note"`, up to five ticked pictures attached), which then marks the tab sent via `POST /notepad/tab/sent`; the agent CLI never imports the store; removed only through Cleanup once a month untouched), **Activities** behind the top bar's die (thirteen small games, Snake, Mini golf, Light Trails, Bug Hunt, Sunset Drive, Stack Deploy, Bumper Ring, Rapids Run, Hot Potato, Crossing Rush, Bounce Road, Ghoul Rush and Flock Dash, listed in `public/activities.js` with one module per game under `public/activities/` (Ghoul Rush is its own folder of modules, `public/activities/ghoul-rush/`) and a card line (`blurb`) each, a picker page of game cards once two are listed that plays one game at a time (another pick drops the last game's round), driven by `screens/activities.js` (keys, key releases for a game with `release()`, canvas pointer events for a game with `pointer()`, one frame timer), paused whenever the person's turn comes and resumed only by the person (while that pause's banner is up, only by its **Unpause game** button), best scores in flat `activityBest` keys in `looks.json` (lowest wins for a game that sets `lowerIsBetter`; Mini golf opens on a dashboard of its six 18-hole courses, one file each under `public/activities/golf-course-.js`, and keeps a best per course, `activityBestGolf`), and one number a game may keep between sessions in `activityMemo` (Snake's tally of surprises found, Light Trails' furthest arena, Bug Hunt's tally of finds, Sunset Drive's roads found, Stack Deploy's highest floor, Bumper Ring's furthest arena, Rapids Run's furthest dam, Hot Potato's furthest venue, Crossing Rush's furthest zone, Bounce Road's furthest stage, Ghoul Rush's most stages cleared in a run, Flock Dash's furthest stage), never shown to the agent), a built-in 21-topic Help, the app-only **Implementation Loop** (a dashboard card and a setup screen drawn by the page, `public/screens/loop-setup.js`; the last setup remembered per project in `~/.plan2code/console/loop-setup.json`, owned by `loop-setup.mjs`; a page that locks while `state.loop.driving` is set, until the app posts `loopEnd`; a skill run with `--loop` reports a `loopOutcome` instead of asking for sign-off, per `notes/loop.md`), a first-run Welcome, User Preferences (gear: four tabs, Appearance, Agents & models, System and Sounds & activities, on the `public/tabs.js` helper Help also uses, with `public/prefs.js`, `screens/prefs-dialog.js` and `screens/agents-view.js`), an agent-less **setup** page (the `setup` workflow `plan2code` or the desktop app opens when no agent can run: each built-in's found / outside-PATH / missing state from `agent-lookup.mjs`, install lines, Check again, Use it from here, starter templates and Start, which hands the tab to the new agent through a token-guarded `POST /handover` and a `move` event; the app shows it in its window from a Set up an agent button instead) and a bug/idea link to GitHub issues. On opted-in skills (every workflow but the dashboard, setup, Changelog, Git, Handoff and UI Prototype) a **Subagents** button in the top bar turns helpers on or off per project and skill (on by default for those skills until switched off, saved in `~/.plan2code/console/subagents.json`), and a Helper strength choice (Balanced, Thrifty, Best, Match my session; rules in `src/shared-references/helper-strength.md`, shipped in the sixteen helper skills); the agent hears of it as a standing instruction only when it changes, and reports its helpers in a **Subagents** tab beside Ask (contract in `console-subagents.md`). Per-skill facts live in one list, `public/skills.js`, from which the meter, the resume command, Help's card list and the CLI's workflow list are derived; task files are read through `spec-files.mjs` (shared with the `specs.mjs` skill script), and the rule for which hops start the page clean is `startsClean()` in `public/hops.js`. The agent contract is a card plus pointers: `console.md` (the card) once per conversation, then a topic file (`console-*.md` such as `console-docs.md`, `notes/.md`, `building*.md`) only when the console names it in its own `read` output, once per session per topic (remembered in `pointers.json` in the session folder, owned by `pointers.mjs`); the console refuses the slips it can see (a `stop` with no `finish`, a `finish` while `stopWarning` is set, with `stop --force` for a dead page) instead of the docs repeating each rule. Byte budgets for the card, every notes file and a sample session's outputs run in `npm test` (`scripts/test-console-wire-budgets.mjs`). The server never writes into a project; the one thing it deletes there is an old `specs--completed/` the person picks in Cleanup, and only when git tracks it (an untracked one is refused, with the reason on the page). One agent list and one lookup rule serve the launcher, the console and the app: `src/launcher/agents.json` (the built-ins and starter templates with per-OS install data) and `src/web-console/agent-lookup.mjs` (`loadAgentList()` and `findAgent()`, both copied by `install.js` into `~/.plan2code/bin/`); the app carries a Rust twin held to the same cases by `scripts/fixtures/agent-lookup-cases.json`. Building or changing an Activities game: follow the game rules in [Activities](./.agents-docs/AGENTS-architecture-activities.md) ("Building an Activities game": lives in the solid lives pill, the endless-lives code (`cheat(on)`) in every game with lives, banners placed away from the player and see-through over what matters, pausing left to the window). diff --git a/QUICK-REFERENCE.md b/QUICK-REFERENCE.md index 03fb369..763392b 100644 --- a/QUICK-REFERENCE.md +++ b/QUICK-REFERENCE.md @@ -51,6 +51,7 @@ Every command below is what a dashboard card runs. Typed on its own, each one as | pr-prep | /plan2code-pr-prep | Your branch | A readiness verdict (Ready, Ready with notes, Not ready) and a PR description to copy; no commits, no push | | test | /plan2code-test | An area, or none | New unit and integration tests in the project's style, run; a bug handed to Diagnose; no source changes | | dead-code | /plan2code-dead-code | A folder, or none | Findings labeled Safe, Check first or Warning, then only the removals you pick, checked by the tests and build; no commits, no installs | +| ui-prototype | /plan2code-ui-prototype | A screen or flow, or none | One page of several versions with live dials, your pick pasted back; `prototypes/.html` and `.md` in a spec on a yes; no code changes | | changelog | /plan2code-changelog | Your branch | `CHANGELOG.md` entries and the `package.json` version, from the default branch's latest version | | git | /plan2code-git | Your repo | Commits (`` / `AI Assisted`), branches, pull with conflict help, push, publish | diff --git a/README.md b/README.md index d49eb0e..bd6ec3d 100644 --- a/README.md +++ b/README.md @@ -260,9 +260,12 @@ The dashboard's cards, and when each one lights up for the spec you pick: | Get a PR ready | Runs the checks your branch needs, says if it is ready, and writes the PR description to copy. Never commits, pushes or opens the PR. | Always | | Write missing tests | Finds code with no tests and writes unit and integration tests in your project's own style. Never changes source code. | Always | | Clear out dead code | Finds code nothing uses, says how safe each piece is to remove, and removes only what you pick. Uses the dead-code tools your project already has, and never commits. | Always | +| Prototype a screen | Several versions of a screen on one page, tuned with live dials, and your pick brought back by Copy and paste. Saved into a spec only when you say, and never changes your code. | Always (takes the picked spec as the save folder) | | Changelog | Checks the CHANGELOG version against the main branch and suggests entries for what is new. | Always | | Git | Branches, pull, push and commits on one board, asking before anything leaves your machine. | Always (offers to start a repository outside one) | +Pathfinder, Plan, Revise the plan and Quick task can each offer a prototype when a decision is about how a screen looks or flows, and run it right there in the same session; nothing is drawn without your yes. + --- ## The four rules that do most of the work @@ -433,6 +436,7 @@ console or the terminal; add `--web` to skip the question and go straight to the | `/plan2code-pr-prep` | Before you open a pull request. Picks the checks the branch's changes need from the project's `## Test map` (or its config files), runs the ones you keep, says Ready, Ready with notes or Not ready, and writes a PR description to copy with the create-a-PR link; never commits, pushes or opens the PR | | `/plan2code-test` | Parts of the code have no tests. Asks where to look, finds the untested files (plus real coverage when the project already has a coverage tool), shows a plan in the project's own style, then writes and runs unit and integration tests; never changes source code, hands a real bug to `/plan2code-diagnose` | | `/plan2code-dead-code` | Code nothing calls anymore. Uses the project's own dead-code tools, one per language (Knip, vulture, cargo check and others), or searches by itself, checks every item for callers across the project, labels each Safe to remove, Check first or Warning, removes only what you pick, then runs the tests and build and puts back anything that breaks them; never commits, never installs anything | +| `/plan2code-ui-prototype` | See a screen before it gets built. Draws several versions of a screen or flow on one page that opens in your browser, with live dials for fonts, colors, spacing and feel; Copy and paste brings your pick back for the next round, and a yes saves it as `specs//prototypes/.html` and `.md`; never changes your code | | `/plan2code-changelog` | Check the CHANGELOG version against the default branch, suggest entries for new work you can edit, keep `package.json` aligned, then hand off to Git to commit | | `/plan2code-git` | Branches, pull, push and commits on one board (or plain instructions in the terminal); asks before every push, publish and delete | diff --git a/docs/index.html b/docs/index.html index 1a27c5e..b6ee833 100644 --- a/docs/index.html +++ b/docs/index.html @@ -641,6 +641,7 @@ footer .brand { margin-right: auto; }

And a drawer of skills for any time

Each one is a card on the dashboard and a command in the terminal.