Compare commits

...
2 Commits
117 changed files with 4011 additions and 1162 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 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/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/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 @@
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
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
+6 -3
View File
@@ -264,9 +264,12 @@ 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, 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
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
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.
+15
View File
@@ -2,6 +2,21 @@
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.0 · MIT · 📖 [plan2code.jparkerweb.com](https://plan2code.jparkerweb.com)
Version 2.5.1 · MIT · 📖 [plan2code.jparkerweb.com](https://plan2code.jparkerweb.com)
---
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "plan2code",
"version": "2.5.0",
"version": "2.5.1",
"private": true,
"bin": {
"plan2code-install": "./install.js"
+42 -11
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: 6, plan: 6, "quick-task": 7 };
const TEMPLATE_SET_SIZE = { pathfinder: 8, plan: 10, "quick-task": 10 };
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: thirteen non-empty texts, the five Pathfinder and Plan share held once", () => {
test("TEMPLATES: nineteen non-empty texts, the six Pathfinder and Plan share held once", () => {
const ids = Object.keys(TEMPLATES);
assert.equal(ids.length, 13);
assert.equal(ids.length, 19);
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: thirteen non-empty texts, the five Pathfinder and Plan share he
const shared = TEMPLATE_ORDERS.pathfinder.engineer.filter((id) => TEMPLATE_ORDERS.plan.engineer.includes(id));
assert.deepEqual(
[...shared].sort(),
["design-decision", "engineering-spec", "product-requirements", "scoping-rollout", "test-strategy"]
["design-decision", "engineering-spec", "integration", "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,6 +4535,24 @@ test("TEMPLATES: thirteen non-empty texts, the five Pathfinder and Plan share he
}
});
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) {
@@ -5303,6 +5321,11 @@ 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" },
@@ -6009,7 +6032,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, takes one working-alone entry, and null clears the list", () => {
test("helpers: post merges them by id, a real helper supersedes working alone, and null clears the list", () => {
const s = consoleSession(["--workflow", "implement"]);
try {
assert.equal(postPatch(s, { helpers: [reportedHelper("h1")] }).status, 0);
@@ -6017,15 +6040,23 @@ test("helpers: post merges them by id, takes one working-alone entry, and null c
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"]);
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.map((h) => h.id), ["h1", "h2", "alone"], "the refused entry was not written");
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 }]);
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.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");
} finally {
cli(["stop", "--session", s.sid]);
}
@@ -6115,7 +6146,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"), { id: "alone", alone: true }] }).status, 0);
assert.equal(postPatch(s, { helpers: [reportedHelper("h1"), reportedHelper("h2")] }).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.
With no way to start helpers, report one "working alone" entry for this skill run instead.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
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,8 +716,11 @@ 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?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers at all?** 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,6 +1211,10 @@ 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,8 +4345,11 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
input.setSelectionRange(text.length, text.length);
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,8 +1540,9 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
<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.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,85 +36,271 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
// The wording was revised in v2.5.1 (Markdown sections); 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 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]",
"## 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]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"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]",
"## 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]",
]),
"design-decision": template("design-decision", "Design decision", [
"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]",
"## 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]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"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]",
"## 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]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"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]",
"## 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]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"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]",
"## 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]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"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]",
"## 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]",
]),
"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]",
"Done when: [how you'll tell it worked]",
"## 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]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"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]",
"## 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]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"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]",
"## 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]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"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.",
"## 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.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"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]",
"## 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]",
]),
"record-decision": template("record-decision", "Record a decision", [
"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]",
"## 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]",
]),
});
@@ -123,28 +309,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", "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"],
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"],
}),
plan: orders({
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"],
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"],
}),
"quick-task": orders({
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"],
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"],
}),
});
@@ -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.",
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,11 +201,14 @@ 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 result shows once the helper ended.
// 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.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
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 }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"mode": "utility"
}
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"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.
With no way to start helpers, report one "working alone" entry for this skill run instead.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
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,8 +716,11 @@ 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?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers at all?** 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,6 +1211,10 @@ 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,8 +4345,11 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
input.setSelectionRange(text.length, text.length);
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,8 +1540,9 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
<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.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,85 +36,271 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
// The wording was revised in v2.5.1 (Markdown sections); 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 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]",
"## 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]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"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]",
"## 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]",
]),
"design-decision": template("design-decision", "Design decision", [
"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]",
"## 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]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"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]",
"## 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]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"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]",
"## 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]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"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]",
"## 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]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"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]",
"## 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]",
]),
"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]",
"Done when: [how you'll tell it worked]",
"## 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]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"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]",
"## 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]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"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]",
"## 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]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"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.",
"## 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.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"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]",
"## 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]",
]),
"record-decision": template("record-decision", "Record a decision", [
"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]",
"## 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]",
]),
});
@@ -123,28 +309,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", "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"],
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"],
}),
plan: orders({
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"],
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"],
}),
"quick-task": orders({
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"],
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"],
}),
});
@@ -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.",
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,11 +201,14 @@ 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 result shows once the helper ended.
// 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.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
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 }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"mode": "utility"
}
+2 -2
View File
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"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.
With no way to start helpers, report one "working alone" entry for this skill run instead.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
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,8 +716,11 @@ 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?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers at all?** 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,6 +1211,10 @@ 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,8 +4345,11 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
input.setSelectionRange(text.length, text.length);
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,8 +1540,9 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
<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.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,85 +36,271 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
// The wording was revised in v2.5.1 (Markdown sections); 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 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]",
"## 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]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"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]",
"## 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]",
]),
"design-decision": template("design-decision", "Design decision", [
"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]",
"## 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]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"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]",
"## 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]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"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]",
"## 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]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"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]",
"## 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]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"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]",
"## 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]",
]),
"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]",
"Done when: [how you'll tell it worked]",
"## 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]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"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]",
"## 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]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"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]",
"## 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]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"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.",
"## 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.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"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]",
"## 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]",
]),
"record-decision": template("record-decision", "Record a decision", [
"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]",
"## 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]",
]),
});
@@ -123,28 +309,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", "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"],
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"],
}),
plan: orders({
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"],
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"],
}),
"quick-task": orders({
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"],
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"],
}),
});
@@ -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.",
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,11 +201,14 @@ 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 result shows once the helper ended.
// 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.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
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 }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"mode": "utility"
}
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"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.
With no way to start helpers, report one "working alone" entry for this skill run instead.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
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,8 +716,11 @@ 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?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers at all?** 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,6 +1211,10 @@ 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,8 +4345,11 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
input.setSelectionRange(text.length, text.length);
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,8 +1540,9 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
<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.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,85 +36,271 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
// The wording was revised in v2.5.1 (Markdown sections); 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 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]",
"## 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]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"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]",
"## 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]",
]),
"design-decision": template("design-decision", "Design decision", [
"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]",
"## 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]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"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]",
"## 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]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"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]",
"## 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]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"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]",
"## 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]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"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]",
"## 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]",
]),
"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]",
"Done when: [how you'll tell it worked]",
"## 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]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"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]",
"## 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]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"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]",
"## 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]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"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.",
"## 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.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"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]",
"## 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]",
]),
"record-decision": template("record-decision", "Record a decision", [
"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]",
"## 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]",
]),
});
@@ -123,28 +309,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", "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"],
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"],
}),
plan: orders({
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"],
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"],
}),
"quick-task": orders({
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"],
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"],
}),
});
@@ -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.",
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,11 +201,14 @@ 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 result shows once the helper ended.
// 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.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
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 }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"mode": "utility"
}
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"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.
With no way to start helpers, report one "working alone" entry for this skill run instead.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
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,8 +716,11 @@ 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?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers at all?** 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,6 +1211,10 @@ 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,8 +4345,11 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
input.setSelectionRange(text.length, text.length);
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,8 +1540,9 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
<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.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,85 +36,271 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
// The wording was revised in v2.5.1 (Markdown sections); 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 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]",
"## 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]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"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]",
"## 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]",
]),
"design-decision": template("design-decision", "Design decision", [
"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]",
"## 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]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"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]",
"## 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]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"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]",
"## 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]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"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]",
"## 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]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"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]",
"## 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]",
]),
"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]",
"Done when: [how you'll tell it worked]",
"## 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]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"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]",
"## 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]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"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]",
"## 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]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"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.",
"## 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.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"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]",
"## 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]",
]),
"record-decision": template("record-decision", "Record a decision", [
"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]",
"## 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]",
]),
});
@@ -123,28 +309,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", "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"],
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"],
}),
plan: orders({
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"],
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"],
}),
"quick-task": orders({
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"],
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"],
}),
});
@@ -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.",
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,11 +201,14 @@ 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 result shows once the helper ended.
// 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.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
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 }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"mode": "utility"
}
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"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.
With no way to start helpers, report one "working alone" entry for this skill run instead.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
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,8 +716,11 @@ 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?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers at all?** 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,6 +1211,10 @@ 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,8 +4345,11 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
input.setSelectionRange(text.length, text.length);
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,8 +1540,9 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
<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.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,85 +36,271 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
// The wording was revised in v2.5.1 (Markdown sections); 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 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]",
"## 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]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"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]",
"## 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]",
]),
"design-decision": template("design-decision", "Design decision", [
"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]",
"## 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]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"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]",
"## 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]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"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]",
"## 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]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"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]",
"## 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]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"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]",
"## 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]",
]),
"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]",
"Done when: [how you'll tell it worked]",
"## 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]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"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]",
"## 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]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"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]",
"## 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]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"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.",
"## 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.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"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]",
"## 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]",
]),
"record-decision": template("record-decision", "Record a decision", [
"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]",
"## 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]",
]),
});
@@ -123,28 +309,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", "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"],
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"],
}),
plan: orders({
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"],
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"],
}),
"quick-task": orders({
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"],
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"],
}),
});
@@ -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.",
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,11 +201,14 @@ 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 result shows once the helper ended.
// 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.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
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 }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"mode": "utility"
}
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"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.
With no way to start helpers, report one "working alone" entry for this skill run instead.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
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,8 +716,11 @@ 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?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers at all?** 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,6 +1211,10 @@ 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,8 +4345,11 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
input.setSelectionRange(text.length, text.length);
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,8 +1540,9 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
<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.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,85 +36,271 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
// The wording was revised in v2.5.1 (Markdown sections); 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 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]",
"## 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]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"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]",
"## 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]",
]),
"design-decision": template("design-decision", "Design decision", [
"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]",
"## 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]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"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]",
"## 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]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"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]",
"## 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]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"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]",
"## 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]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"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]",
"## 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]",
]),
"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]",
"Done when: [how you'll tell it worked]",
"## 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]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"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]",
"## 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]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"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]",
"## 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]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"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.",
"## 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.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"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]",
"## 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]",
]),
"record-decision": template("record-decision", "Record a decision", [
"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]",
"## 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]",
]),
});
@@ -123,28 +309,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", "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"],
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"],
}),
plan: orders({
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"],
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"],
}),
"quick-task": orders({
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"],
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"],
}),
});
@@ -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.",
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,11 +201,14 @@ 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 result shows once the helper ended.
// 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.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
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 }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"mode": "utility"
}
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"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.
With no way to start helpers, report one "working alone" entry for this skill run instead.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
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,8 +716,11 @@ 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?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers at all?** 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,6 +1211,10 @@ 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,8 +4345,11 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
input.setSelectionRange(text.length, text.length);
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,8 +1540,9 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
<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.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,85 +36,271 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
// The wording was revised in v2.5.1 (Markdown sections); 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 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]",
"## 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]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"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]",
"## 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]",
]),
"design-decision": template("design-decision", "Design decision", [
"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]",
"## 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]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"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]",
"## 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]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"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]",
"## 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]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"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]",
"## 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]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"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]",
"## 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]",
]),
"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]",
"Done when: [how you'll tell it worked]",
"## 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]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"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]",
"## 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]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"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]",
"## 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]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"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.",
"## 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.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"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]",
"## 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]",
]),
"record-decision": template("record-decision", "Record a decision", [
"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]",
"## 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]",
]),
});
@@ -123,28 +309,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", "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"],
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"],
}),
plan: orders({
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"],
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"],
}),
"quick-task": orders({
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"],
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"],
}),
});
@@ -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.",
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,11 +201,14 @@ 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 result shows once the helper ended.
// 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.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
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 }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"mode": "utility"
}
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"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.
With no way to start helpers, report one "working alone" entry for this skill run instead.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
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,8 +716,11 @@ 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?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers at all?** 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,6 +1211,10 @@ 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,8 +4345,11 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
input.setSelectionRange(text.length, text.length);
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,8 +1540,9 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
<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.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,85 +36,271 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
// The wording was revised in v2.5.1 (Markdown sections); 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 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]",
"## 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]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"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]",
"## 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]",
]),
"design-decision": template("design-decision", "Design decision", [
"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]",
"## 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]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"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]",
"## 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]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"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]",
"## 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]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"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]",
"## 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]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"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]",
"## 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]",
]),
"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]",
"Done when: [how you'll tell it worked]",
"## 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]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"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]",
"## 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]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"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]",
"## 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]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"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.",
"## 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.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"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]",
"## 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]",
]),
"record-decision": template("record-decision", "Record a decision", [
"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]",
"## 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]",
]),
});
@@ -123,28 +309,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", "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"],
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"],
}),
plan: orders({
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"],
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"],
}),
"quick-task": orders({
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"],
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"],
}),
});
@@ -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.",
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,11 +201,14 @@ 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 result shows once the helper ended.
// 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.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
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 }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"mode": "utility"
}
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"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.
With no way to start helpers, report one "working alone" entry for this skill run instead.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
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,8 +716,11 @@ 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?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers at all?** 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,6 +1211,10 @@ 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,8 +4345,11 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
input.setSelectionRange(text.length, text.length);
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,8 +1540,9 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
<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.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,85 +36,271 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
// The wording was revised in v2.5.1 (Markdown sections); 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 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]",
"## 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]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"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]",
"## 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]",
]),
"design-decision": template("design-decision", "Design decision", [
"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]",
"## 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]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"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]",
"## 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]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"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]",
"## 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]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"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]",
"## 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]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"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]",
"## 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]",
]),
"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]",
"Done when: [how you'll tell it worked]",
"## 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]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"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]",
"## 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]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"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]",
"## 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]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"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.",
"## 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.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"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]",
"## 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]",
]),
"record-decision": template("record-decision", "Record a decision", [
"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]",
"## 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]",
]),
});
@@ -123,28 +309,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", "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"],
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"],
}),
plan: orders({
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"],
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"],
}),
"quick-task": orders({
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"],
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"],
}),
});
@@ -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.",
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,11 +201,14 @@ 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 result shows once the helper ended.
// 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.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
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 }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"mode": "utility"
}
+2 -2
View File
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"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.
With no way to start helpers, report one "working alone" entry for this skill run instead.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
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,8 +716,11 @@ 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?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers at all?** 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,6 +1211,10 @@ 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,8 +4345,11 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
input.setSelectionRange(text.length, text.length);
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,8 +1540,9 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
<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.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,85 +36,271 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
// The wording was revised in v2.5.1 (Markdown sections); 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 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]",
"## 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]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"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]",
"## 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]",
]),
"design-decision": template("design-decision", "Design decision", [
"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]",
"## 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]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"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]",
"## 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]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"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]",
"## 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]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"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]",
"## 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]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"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]",
"## 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]",
]),
"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]",
"Done when: [how you'll tell it worked]",
"## 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]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"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]",
"## 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]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"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]",
"## 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]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"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.",
"## 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.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"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]",
"## 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]",
]),
"record-decision": template("record-decision", "Record a decision", [
"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]",
"## 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]",
]),
});
@@ -123,28 +309,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", "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"],
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"],
}),
plan: orders({
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"],
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"],
}),
"quick-task": orders({
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"],
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"],
}),
});
@@ -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.",
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
@@ -201,11 +201,14 @@ 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 result shows once the helper ended.
// 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.
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
const rows = list.map(({ id, title, ask, state, result }) => ({
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 }) => ({
id,
title,
ask,
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"mode": "utility"
}
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.5.0",
"version": "2.5.1",
"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-06",
"releaseDate": "2026-10-07",
"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.
With no way to start helpers, report one "working alone" entry for this skill run instead.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
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,8 +716,11 @@ 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?** Post one `{ "id": "alone", "alone": true }`
- **No way to start helpers at all?** 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,6 +1211,10 @@ 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,8 +4345,11 @@ function templateRow(item, input, entries, check) {
save();
paint();
input.focus();
const start = text.indexOf("[");
const end = start < 0 ? -1 : text.indexOf("]", start);
try {
input.setSelectionRange(text.length, text.length);
if (end > start) input.setSelectionRange(start, end + 1);
else input.setSelectionRange(text.length, text.length);
} catch {}
};
@@ -1540,8 +1540,9 @@
on the Ask tab if one should stop.
</li>
<li>
<strong>Working alone</strong> means your agent has no way to start
helpers here, so it is doing the work itself.
<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.
</li>
<li>
Pathfinder always uses helpers for its research questions, whatever
@@ -36,85 +36,271 @@ export function needsRoleNudge(looks) {
return !Object.hasOwn(looks, "role");
}
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
// The wording was revised in v2.5.1 (Markdown sections); 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 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]",
"## 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]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"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]",
"## 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]",
]),
"design-decision": template("design-decision", "Design decision", [
"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]",
"## 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]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"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]",
"## 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]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"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]",
"## 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]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"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]",
"## 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]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"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]",
"## 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]",
]),
"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]",
"Done when: [how you'll tell it worked]",
"## 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]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"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]",
"## 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]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"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]",
"## 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]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"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.",
"## 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.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"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]",
"## 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]",
]),
"record-decision": template("record-decision", "Record a decision", [
"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]",
"## 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]",
]),
});
@@ -123,28 +309,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", "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"],
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"],
}),
plan: orders({
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"],
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"],
}),
"quick-task": orders({
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"],
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"],
}),
});
Loaded 100 of 117 files, more files were not shown because too many files have changed in this diff. Show more