mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-16 04:45:33 -08:00
Offer helpers (subagents) in Plan and Revise Plan
AI Assisted
This commit is contained in:
1 parent
a2b43d1188
commit
b99a1a701f
16 files changed
+70
-28
No files matched your search
@@ -17,7 +17,7 @@ plan2code/
|
||||
│ │ └── trail.md # Every-response map visual + pathed resume command
|
||||
│ ├── shared-references/ # Reference files shared across skills
|
||||
│ │ ├── building-habits.md # Find the cause, test first, pin behaviour (quick-task, implement, implement-review)
|
||||
│ │ └── helper-strength.md # How strong a model and how much effort each helper gets (pathfinder, quick-task, implement, implement-review, review)
|
||||
│ │ └── helper-strength.md # How strong a model and how much effort each helper gets (pathfinder, plan, revise-plan, quick-task, implement, implement-review, review)
|
||||
│ ├── plan2code-review-references/ # Reference files for review skill
|
||||
│ │ ├── verification-protocol.md # Deep verification + confidence calibration
|
||||
│ │ ├── dimensions.md # 11 dimensions with detailed checklists
|
||||
@@ -261,7 +261,7 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
|
||||
| `public/mentions.js` | PURE, no imports: the `@name` popover's logic — `mentionAt()` finds an `@partial` at the caret, `matchNames()` filters the workspace names, `applyMention()` splices a pick in and returns the new caret. Used by the Ask box, notes and text answers |
|
||||
| `public/favicon.js` | The tab icon's status bar. `faviconState({ mood, spin, finished })` (PURE) maps the call `renderStatus()` makes for Planny's line to `busy` (the spinning ring), `ready` (`point`), `attention` (`adrift`, `gone`, or `work` without the ring — the stale line) or `plain` (finished, `happy`); `faviconSvg()` is `FAVICON_BODY` (kept equal to `favicon.svg` by a test) plus a bar along the bottom edge in the `FAVICON_COLORS` color (busy dashed on a white strip, so the states differ by pattern; the rest solid); `setFavicon()` swaps both `<link rel=icon>` hrefs only on a change — the SVG as a data URL, the PNG link drawn through a canvas. Called from `say()` in `renderStatus()`, which runs every second |
|
||||
| `public/app-bridge.js` | The messages the page posts to the desktop app that frames it. `framed()` is true inside a frame; `tellApp(kind, extra)` posts `{ plan2code: kind }`, a named request with no free text: `looks` (the highlight's dark shades, from `applyLooks()`, for the app bar's buttons), `agent-continue` (the in-app **continue** button on the Not running line: the app types the keystrokes `continueKeys()` in `plan2code-app/ui/meter.js` names into the agent's terminal, `continue` and Enter, then under Claude Code its send-now chord ctrl+x ctrl+s, so a word queued behind a stuck turn is delivered) and `new-session` (the meter popover's New Session: the app presses its own bar button, confirm and all). Nothing outside a frame |
|
||||
| `public/subagents.js` | PURE, no imports: the Subagents switch. `SUBAGENT_WORKFLOWS` / `offered()` (the opt-in table: `implement`, `implement-review`, `quick-task`, `review`, `pathfinder`, each with its default instruction), `cleanSetting()` (`{ on, instruction, max, strength }` or `{ error }`: `bad`, `too-long` past 2,000 characters, `max` outside 1-20, `strength` not one of `STRENGTHS`; `strength` is `balanced`, `thrifty`, `best` or `session`, missing reads as `balanced`, saved per project and skill in each `subagents.json` entry and sent as a `Helper strength:` line in the "on" block), `FRAME_LINES`, `blockFor(setting, told)` (the `Subagents:` lines and `subagents` field an agent is owed, given the session setting and its cursor; never says "off" to an agent not told "on"), `checkHelper()` / `checkHelpers()` (the `helpers` house rule) and the page's view rules `showSwitch()`, `switchLabel()`, `helperRows()`, `showTab()`, `CHECKIN_LINE`. Imported by the server, the `cmd-*.mjs` files, `patches.mjs`, `settings.mjs`, the page and the tests; in `SERVABLE` and preloaded |
|
||||
| `public/subagents.js` | PURE, no imports: the Subagents switch. `SUBAGENT_WORKFLOWS` / `offered()` (the opt-in table: `implement`, `implement-review`, `quick-task`, `review`, `pathfinder`, `plan`, `revise-plan`, each with its default instruction), `cleanSetting()` (`{ on, instruction, max, strength }` or `{ error }`: `bad`, `too-long` past 2,000 characters, `max` outside 1-20, `strength` not one of `STRENGTHS`; `strength` is `balanced`, `thrifty`, `best` or `session`, missing reads as `balanced`, saved per project and skill in each `subagents.json` entry and sent as a `Helper strength:` line in the "on" block), `FRAME_LINES`, `blockFor(setting, told)` (the `Subagents:` lines and `subagents` field an agent is owed, given the session setting and its cursor; never says "off" to an agent not told "on"), `checkHelper()` / `checkHelpers()` (the `helpers` house rule) and the page's view rules `showSwitch()`, `switchLabel()`, `helperRows()`, `showTab()`, `CHECKIN_LINE`. Imported by the server, the `cmd-*.mjs` files, `patches.mjs`, `settings.mjs`, the page and the tests; in `SERVABLE` and preloaded |
|
||||
| `handoffs.mjs` | the handoff store, the only code that names, lists, marks, deletes and sweeps handoffs, all in `~/.plan2code/handoffs/` (`PLAN2CODE_HANDOFFS_DIR` for tests; `PLAN2CODE_NOW` pins its clock): `newHandoff()` claims `YYYY-MM-DD-HHmm-handoff` (`-2`, `-3` on a clash, the `.json` created exclusively) and writes only `<id>.json` (`{ v: 1, id, title, worktree, project, spec, workflow, skill, written, fromStop, usedAt }`), the agent writing `<id>.md`; `listHandoffs(worktree)` (unused, same worktree, `.md` present, newest first, title and Next task read off the document); `readHandoffMeta()`, `markHandoffUsed()`; `removeHandoff()` (`HANDOFF_ID` only, regular files, never a link, realpath inside the folder, throws on any refusal); `staleHandoffs()` / `removeHandoffs()` for the sweep |
|
||||
| `notepads.mjs` | the notebook store (the feature is named Notebook; its code, routes and storage folder keep the name `notepad`), the only code that names, reads, writes and removes notebooks, one per folder Plan2Code runs in, in `~/.plan2code/notepads/<folder-name>-<12 hex>/` (`PLAN2CODE_NOTEPADS_DIR` for tests), split into named tabs: `meta.json` (`{ v: 2, folder, created }`), `tabs.json` (`{ v: 1, order, last, tabs: { id: { name, created } } }`) and `tabs/<id>/note.md` with `tabs/<id>/images/`. `notepadKey()` (the folder's basename slug and the first 12 hex of `sha256(foldKey(folder))`), `listTabs()` / `defaultTabId()`, `readNotepad(folder, tab)` (never creates or writes anything; `{ tabs, last, tab }` with the tab's `text`, `savedAt` and `images` repeated at the top), the tab changes `createTab()` / `renameTab()` / `reorderTabs()` / `setLastTab()` / `deleteTab()` (index first, then the folder; names pass `normalizeTabName()`, `TAB_NAME_MAX` 40, any case compared by `nameKey()`, `NOTEPAD_MAX_TABS` 20), `saveNote(folder, tab, text)` (1 MB cap, atomic), `addImage()` / `addThumb()` / `removeImage()` (JPEG bytes only, 200 pictures per tab, UUID names), `imagePath()` (regular files whose realpath stays inside the folder), `staleNotepads(now, maxAgeMs)` (the real folders directly under it named like a key, never a link or a file, whose newest file is at least `maxAgeMs` old, as `{ key, folder, path }` with `folder` from `meta.json` or null), `removeNotepad(key)` (the key checked against `NOTEPAD_KEY_RE`, the path kept inside the notepads folder by `path.relative`, a link refused, then the whole folder removed; User Preferences, Cleanup is its only caller) and `NotepadError` (`code` and `status`, turned into `{ error }` by the `/notepad` routes). **Migration:** a notepad in the first shape (`note.md` and `images/` at the top) reads as one virtual tab, Notes (`LEGACY_TAB_ID`), and writes nothing; its first write moves the files into `tabs/<LEGACY_TAB_ID>/` and writes `tabs.json` last, every step safe to run again after a crash. A `tabs.json` that does not hold up is set aside as `tabs.json.corrupt` and rebuilt from the tab folders on the next write. Every write runs under a `notepad.lock` in the notepad's folder. The agent CLI never imports it: nothing in a notepad reaches the agent |
|
||||
| `public/notepad.js` | PURE, no imports: the Notebook's rules. `SAVE_DEBOUNCE_MS` 800, `RETRY_STEPS_MS` (1 s up to 30 s), `NOTE_MAX_BYTES` / `NOTEPAD_MAX_IMAGES` / `TAB_NAME_MAX` / `NOTEPAD_MAX_TABS` / `IMAGE_ID_RE` / `TAB_ID_RE` (kept equal to `notepads.mjs` by a test), `noteBytes()`, the save-state reducer `nextSave(state, event)` from `SAVE_START` (states `idle`, `pending`, `saving`, `saved`, `failed`, `too-long`; it returns the timer to arm), `saveStatus()` (the status line's words), `unsaved()` (what `beforeunload` asks on), `keepsText()` (unsaved or too long: a reopen never replaces the editor's text then), `tabSwitch()` (whether leaving a tab must save it first), `NOT_LOADED`, `EDITOR_NOT_LOADED`, `errorSentence()` (one sentence per `/notepad` refusal, else a lost connection), the tab rules `cleanTabName()`, `nameTaken()`, `tabNameProblem()`, `moveTab()`, `dropTab()` and the two-confirm delete `nextDelete()` / `DELETE_STAGES`, and `step()` (wrapping through the pictures) |
|
||||
@@ -299,7 +299,7 @@ Key design points:
|
||||
- **User Preferences → Cleanup deletes on demand, from a list the server makes.** `POST /cleanup` (origin-checked) with `{ scan: true }` returns `cleanupFindings()`: `{ items: [{ id, where, name, kind, bytes, folder? }], bytes }` (`folder` on `notepad:` items only), ids `session:<sid>` (the `staleSessions()` rule, and every file in the folder that old too, never the serving sid), `console:<name>` (anything at the top of the console home but `PROTECTED_CONSOLE_FILES`, `sessions` and `runtime`, directories too) and `root:<name>` (anything at the top of `~/.plan2code` but `KEPT_PLAN2CODE_ENTRIES`: `console`, `bin`, `launcher.json`, `install.json`, `models.json`, `handoffs`, `notepads`, `app`, `app.json`, `agents.json`), `notepad:<key>` (a month-old notepad, whole; see Notebook below) and `completed:<name>` (each folder or link directly under the session worktree's `specs--completed/` whose newest mtime is older than the session age, 30 days; loose files there stay; the server passes `project: sessionWorktree() || PROJECT`, and without a `project` the archive is never scanned). Both stray kinds must be untouched for `STRAY_GRACE_MS` (an hour, by the newest `lstat` mtime anywhere inside, since rewriting a file never moves its folder's mtime; unreadable reads as fresh): the same folders hold `workspaces.json.lock` and `writeJsonAtomic()`'s `<file>.<pid>.tmp`, which live for milliseconds. `root:` is only scanned when the console home is `<PLAN2CODE_MODELS_DIR or ~/.plan2code>/console`, so a test or dev home never reaches the real folder. Paths never go to the page. `{ delete: [id] }` runs `removeCleanup()`, which re-scans and removes only ids still on the fresh list (symlinks unlinked, never followed), returning `{ removed, bytes, failed }`. The page always shows the list before **Delete these**.
|
||||
- **The console's path is stated, not searched for.** Each Interface line names `references/web-console/` beside the SKILL.md and the `~/.plan2code/console/console-dir` fallback; the prompts with room (all but pathfinder, plan, document and finalize, which sit near the char limit) also name the canonical global install path `~/.agents/skills/<skill>/references/web-console/` (the skills CLI's real store; every agent dir links into it), and every `console.mjs open` writes `HERE` to `~/.plan2code/console/console-dir` (only `open`, so a `help` or dev run from `src/` never repoints it) so a later session can read the path from a fixed place. Without these the agent hunts the skill install dirs on every session.
|
||||
- **`open` needs no payload, and runs first.** `--file` and `--title` are optional (the title defaults to the folder name). Every skill's Interface line puts `node "<D>/console.mjs" open --workflow <w>` BEFORE reading console.md or the project, and a test (`every skill opens the console before it reads anything`) keeps it that way; a blank session renders a starting screen ("Starting Pathfinder", Planny in flight) until the first post. Every skill replaces the flight with its own animated pose (init — init-update borrows it — pathfinder, plan — revise-plan borrows it — document, implement — implement-review borrows it — finalize, quick-task, review, handoff; only the dashboard keeps the flight), cloned by `startStage()` in `screens/starting.js` from `<template id="start-poses">` in `index.html` and animated under `.pose` in `styles/poses.css`; each `SKILLS` entry's `pose` in `skills.js` is the list (`START_POSES`/`startPose()` in `answers.js` read it), and a test keeps the template in sync with it and every catalog workflow mapped to a pose. The same pose stands above the waiting pane (`.waiting-pane`, agent working with an `activity` and nothing to ask). `posePane()` keeps the pane on screen across renders when the pose is unchanged — `renderMain()` holds any `:scope > [data-pose]` child back from the clear — so the SVG never leaves the DOM, its animations never restart on a state frame, and Planny carries unbroken from launching → starting → waiting. The dashboard's launch hand-off resumes first and reads the launched skill's file after.
|
||||
- **The dashboard scan knows whether the folder is a git repository.** `scanProject()` returns `{ hasAgents, isGit, pending, specs }`; `isGit` comes from `insideGitRepo()`, the same filesystem walk `findRoots()` does (no `git` process, linked worktrees and submodules count, a set `GIT_DIR` / `GIT_WORK_TREE` / `GIT_COMMON_DIR` counts as a repo). The Git card is never greyed, since a clean tree still has branches to switch, pull and push. When `isGit` is `false` the card shows `GIT_INIT_NOTE` ("Not a git repository yet: it offers to start one") as its detail line; a scan with no `isGit` counts as a repo. In a repo, `pending` is `pendingFiles()` in `sessions.mjs`, which calls `countPending()` in `git-repo.mjs`: one bounded `git status --porcelain -z` under `GIT_OPTIONAL_LOCKS=0` (`null` when git cannot say) counting modified, staged, deleted and untracked paths. Above `0` the detail line is `pendingNote(n)` ("3 files to commit"); `0` and `null` show no note. A finish with `commit: true` puts a **Commit it now** button on the finished screen (`commitOffer()`, `renderCommitOffer()`); its `__commit` press makes the agent resume as `git` in the same session and run the commit flow above the board. `open --resume` treats any switch into `git` (this press, or Changelog's "Commit this now?") as a hop, like a dashboard launch: `switchWorkflow()` blanks the page, finish and the last run's `state.git` included, and `draft.json` goes. Without that, the old finish outlived the switch, and the page sat on the old ending above the new questions and the board. A confirm item may carry `files: [{ path, state }]`, drawn as a collapsed table by `filesTable()`. Subagents is **on** by default for the five opted-in skills (`defaultSetting()`); a saved Off stays off.
|
||||
- **The dashboard scan knows whether the folder is a git repository.** `scanProject()` returns `{ hasAgents, isGit, pending, specs }`; `isGit` comes from `insideGitRepo()`, the same filesystem walk `findRoots()` does (no `git` process, linked worktrees and submodules count, a set `GIT_DIR` / `GIT_WORK_TREE` / `GIT_COMMON_DIR` counts as a repo). The Git card is never greyed, since a clean tree still has branches to switch, pull and push. When `isGit` is `false` the card shows `GIT_INIT_NOTE` ("Not a git repository yet: it offers to start one") as its detail line; a scan with no `isGit` counts as a repo. In a repo, `pending` is `pendingFiles()` in `sessions.mjs`, which calls `countPending()` in `git-repo.mjs`: one bounded `git status --porcelain -z` under `GIT_OPTIONAL_LOCKS=0` (`null` when git cannot say) counting modified, staged, deleted and untracked paths. Above `0` the detail line is `pendingNote(n)` ("3 files to commit"); `0` and `null` show no note. A finish with `commit: true` puts a **Commit it now** button on the finished screen (`commitOffer()`, `renderCommitOffer()`); its `__commit` press makes the agent resume as `git` in the same session and run the commit flow above the board. `open --resume` treats any switch into `git` (this press, or Changelog's "Commit this now?") as a hop, like a dashboard launch: `switchWorkflow()` blanks the page, finish and the last run's `state.git` included, and `draft.json` goes. Without that, the old finish outlived the switch, and the page sat on the old ending above the new questions and the board. A confirm item may carry `files: [{ path, state }]`, drawn as a collapsed table by `filesTable()`. Subagents is **on** by default for the seven opted-in skills (`defaultSetting()`); a saved Off stays off.
|
||||
- **The start path is timed, and `open` is built around it.** Measure with `node scripts/bench-web-console.mjs` (`--browser-delay 900` for a real Chrome launch, `--roundtrip` for Send→agent and post→page, `PLAN2CODE_CONSOLE_TRACE=1` on `open` for a step timeline). Four things make it fast, and each is load-bearing:
|
||||
- **No git process.** `repoRoots()` in `sessions.mjs` finds the common dir and worktree top by walking to `.git` (following `gitdir:` and `commondir` files) — each `git rev-parse` cost 150ms+ on Windows. It asks git only when `GIT_DIR`/`GIT_WORK_TREE`/`GIT_COMMON_DIR` relocate the repo, and uses the native realpath so an 8.3 short name keys the same project git would.
|
||||
- **The socket handover.** `open` spawns the server first, then binds the loopback port itself (the first `listen()` blocks ~50ms on Windows, overlapped with the server's boot), launches the browser on that URL immediately (Chrome via `start` takes ~900ms to its first request, the longest step of all), and hands the listening socket to the server over IPC (`bindLoopback()`/`handOff()` in `sessions.mjs`, `--handoff` in `server.mjs`). Requests queue in the socket until the server takes it; one `open` already accepted is passed across as a socket and acknowledged (`conn-held`) before the channel is closed. No channel, or no socket within 3s, and the server binds its own port; `open` then opens the real URL.
|
||||
|
||||
@@ -386,8 +386,8 @@ it is remembered for next time:
|
||||
|
||||
### Subagents
|
||||
|
||||
On a build (Implement, Implement + review, Quick task), a review and
|
||||
Pathfinder, the agent can hand independent pieces of work to helpers
|
||||
On a build (Implement, Implement + review, Quick task), a review,
|
||||
Pathfinder, Plan and Revise plan, the agent can hand independent pieces of work to helpers
|
||||
(subagents) while it keeps the conversation with you.
|
||||
|
||||
- **The button.** An icon in the top bar, after Stop session (and Write a
|
||||
|
||||
@@ -42,7 +42,7 @@ Details: [Architecture](./.agents-docs/AGENTS-architecture.md) (see Status Line
|
||||
|
||||
## Web Console
|
||||
|
||||
Optional local browser UI (`src/web-console/`, zero dependencies, detached `node` server on `127.0.0.1`) bundled into every skill via `additionalReferences`. The bare `plan2code` skill opens its dashboard, a card menu that launches any skill in the same session. Pages cover questions, sign-off gates (with an in-page code review), build progress, the living document, an **Ask** chat, a read-only **Workspace** of extra folders (remembered per folder and spec in `~/.plan2code/console/workspaces.json`), a session meter, a **git board** for the `git` workflow (three tabs, Changes, Branches and Sync, opening on the likely next step; branches, pull, push, commits and pull-request links, drawn from `state.git`; contract in `notes/git.md`), **Stop with a handoff** (handoffs live in `~/.plan2code/handoffs/`, owned by `handoffs.mjs`, swept after 30 days, and offered as dashboard chips to pick up in the same session), a private **Notebook** in the top bar (named tabs of Markdown and pictures, a live-preview CodeMirror editor, one notepad per folder in `~/.plan2code/notepads/`, owned by `notepads.mjs`, never shown to the agent, removed only through Cleanup once a month untouched), a built-in 18-topic Help, a first-run Welcome, User Preferences (gear) and a bug/idea link to GitHub issues. On opted-in skills (builds, review, Pathfinder) a **Subagents** button in the top bar turns helpers on or off per project and skill (on by default for those skills until switched off, saved in `~/.plan2code/console/subagents.json`), and a Helper strength choice (Balanced, Thrifty, Best, Match my session; rules in `src/shared-references/helper-strength.md`, shipped in the five helper skills); the agent hears of it as a standing instruction only when it changes, and reports its helpers in a **Subagents** tab beside Ask (contract in `console-subagents.md`). Per-skill facts live in one list, `public/skills.js`, from which the meter, the resume command, Help's card list and the CLI's workflow list are derived; task files are read through `spec-files.mjs` (shared with the `specs.mjs` skill script), and the rule for which hops start the page clean is `startsClean()` in `public/hops.js`. The agent contract is read in pieces: `console.md` once per conversation, then a topic file (`console-*.md`, `notes/<workflow>.md`, `building*.md`) only when its moment comes; the server never writes into a project.
|
||||
Optional local browser UI (`src/web-console/`, zero dependencies, detached `node` server on `127.0.0.1`) bundled into every skill via `additionalReferences`. The bare `plan2code` skill opens its dashboard, a card menu that launches any skill in the same session. Pages cover questions, sign-off gates (with an in-page code review), build progress, the living document, an **Ask** chat, a read-only **Workspace** of extra folders (remembered per folder and spec in `~/.plan2code/console/workspaces.json`), a session meter, a **git board** for the `git` workflow (three tabs, Changes, Branches and Sync, opening on the likely next step; branches, pull, push, commits and pull-request links, drawn from `state.git`; contract in `notes/git.md`), **Stop with a handoff** (handoffs live in `~/.plan2code/handoffs/`, owned by `handoffs.mjs`, swept after 30 days, and offered as dashboard chips to pick up in the same session), a private **Notebook** in the top bar (named tabs of Markdown and pictures, a live-preview CodeMirror editor, one notepad per folder in `~/.plan2code/notepads/`, owned by `notepads.mjs`, never shown to the agent, removed only through Cleanup once a month untouched), a built-in 18-topic Help, a first-run Welcome, User Preferences (gear) and a bug/idea link to GitHub issues. On opted-in skills (builds, review, Pathfinder, Plan, Revise plan) a **Subagents** button in the top bar turns helpers on or off per project and skill (on by default for those skills until switched off, saved in `~/.plan2code/console/subagents.json`), and a Helper strength choice (Balanced, Thrifty, Best, Match my session; rules in `src/shared-references/helper-strength.md`, shipped in the seven helper skills); the agent hears of it as a standing instruction only when it changes, and reports its helpers in a **Subagents** tab beside Ask (contract in `console-subagents.md`). Per-skill facts live in one list, `public/skills.js`, from which the meter, the resume command, Help's card list and the CLI's workflow list are derived; task files are read through `spec-files.mjs` (shared with the `specs.mjs` skill script), and the rule for which hops start the page clean is `startsClean()` in `public/hops.js`. The agent contract is read in pieces: `console.md` once per conversation, then a topic file (`console-*.md`, `notes/<workflow>.md`, `building*.md`) only when its moment comes; the server never writes into a project.
|
||||
Details: [Architecture](./.agents-docs/AGENTS-architecture.md) (see Web Console section) and [.readme/web-console.md](./.readme/web-console.md)
|
||||
|
||||
## Skill Scripts
|
||||
|
||||
@@ -10,6 +10,7 @@ All notable changes to Plan2Code will be documented in this file.
|
||||
- **desktop app**: **Update skills** in the bar brings the installed skills level with the app from the exact release the app ships, with live progress and a **Reconnect the console** offer once it finishes; an app older than the installed skills says so instead of trying to fix it by updating skills again.
|
||||
- **desktop app**: the window's own title (and so its taskbar entry) now reads **Plan2Code - <folder name>** once a project is open, instead of a plain **Plan2Code** every window shares; two or more windows on different projects read apart without opening each one to check.
|
||||
- **helpers**: a helper (subagent) no longer has to run on the session's own model and effort. A new shared reference, `helper-strength.md`, shipped in Pathfinder, Quick Task, Implement, Implement + Review and Review, matches each helper job to a strength (`light`, `standard`, `strongest` or `inherit`) and an effort (`low`, `medium` or `high`) from signals that can be checked, with floors, one-step escalation and a fallback order for tools that cannot set either, and never names a model or vendor. Review, Implement + Review and Pathfinder name the strength for the helpers they start, and the rules apply in terminal sessions too.
|
||||
- **helpers**: Plan and Revise Plan now offer helpers (subagents), with the web console's **Subagents** button in the top bar, on by default like the other opted-in skills. Each skill has its own rule for what is independent enough to hand off. Plan uses helpers for reading the sources the person names, mapping separate areas of the codebase in Phase 2, gathering evidence on each open tech choice in Phase 4, and one fresh cross-check of the PLAN-DRAFT against the conversation in Phase 7; questions, decisions, sign-offs and the writing of the PLAN-DRAFT stay with the session. Revise Plan uses read-only lookups on the code behind affected and at-risk completed tasks at Steps 1 and 2 and, only after approval and when a revision touches 3 or more phase files, one helper per phase file to apply the approved edits under `specs/`. The rules live in each skill's Helpers section, so they apply in terminal sessions too. `helper-strength.md` now ships in both, with a row for each new kind of helper job (Plan's recon reuses the lookups row) and the PLAN-DRAFT cross-check held at `standard` or above, like a review.
|
||||
- **web console**: the Subagents dialog has a **Helper strength** choice under Helpers: **Balanced** (the default), **Thrifty**, **Best** or **Match my session**, saved per project and skill and delivered to the agent as a `Helper strength:` line. Helper reports may say what each helper ran with (`strength`, `effort`), and the Subagents tab shows it as one quiet line, such as "Standard, medium effort".
|
||||
- `plan2code` opens the app automatically when a desktop is available; `plan2code --classic` (or no desktop, e.g. over SSH) keeps today's terminal-only flow unchanged, and the installer brings the app in alongside the skills and the command.
|
||||
|
||||
|
||||
+8
-2
@@ -191,7 +191,10 @@ const SOURCE_PROMPTS = [
|
||||
displayName: 'Planning Mode',
|
||||
description: 'Requirements analysis and architecture design',
|
||||
scripts: ['specs.mjs'],
|
||||
additionalReferences: [{ source: 'web-console', target: 'web-console' }]
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
source: 'plan2code-1b-revise-plan.md',
|
||||
@@ -200,7 +203,10 @@ const SOURCE_PROMPTS = [
|
||||
displayName: 'Revision Mode',
|
||||
description: 'Modify specs mid-implementation when requirements change',
|
||||
scripts: ['specs.mjs'],
|
||||
additionalReferences: [{ source: 'web-console', target: 'web-console' }]
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
source: 'plan2code-2-document.md',
|
||||
|
||||
@@ -1989,18 +1989,18 @@ test("workspace cursor never moves backwards, and only changes past it are pendi
|
||||
}
|
||||
});
|
||||
|
||||
test("subagents: only the five opted-in workflows offer the switch", () => {
|
||||
for (const w of ["implement", "implement-review", "quick-task", "review", "pathfinder"]) {
|
||||
test("subagents: only the seven opted-in workflows offer the switch", () => {
|
||||
for (const w of ["implement", "implement-review", "quick-task", "review", "pathfinder", "plan", "revise-plan"]) {
|
||||
assert.equal(offered(w), true, w);
|
||||
assert.ok(defaultInstruction(w).length > 0, `${w} has a default instruction`);
|
||||
}
|
||||
for (const w of ["dashboard", "plan", "document", "init", "handoff", "constructor", "toString", undefined]) {
|
||||
for (const w of ["dashboard", "document", "finalize", "init", "handoff", "constructor", "toString", undefined]) {
|
||||
assert.equal(offered(w), false, String(w));
|
||||
assert.equal(defaultInstruction(w), "");
|
||||
}
|
||||
assert.equal(Object.keys(SUBAGENT_WORKFLOWS).length, 5);
|
||||
assert.equal(Object.keys(SUBAGENT_WORKFLOWS).length, 7);
|
||||
assert.deepEqual(defaultSetting("review"), { workflow: "review", on: true, instruction: null, max: 3, strength: "balanced" });
|
||||
assert.equal(defaultSetting("plan").on, false, "a skill without the switch is never on");
|
||||
assert.equal(defaultSetting("document").on, false, "a skill without the switch is never on");
|
||||
assert.equal(effectiveInstruction({ workflow: "review", instruction: " " }), defaultInstruction("review"));
|
||||
assert.equal(effectiveInstruction({ workflow: "review", instruction: " Mine " }), "Mine");
|
||||
});
|
||||
@@ -2041,7 +2041,7 @@ test("subagents: blockFor walks every switch transition, and never says off to a
|
||||
|
||||
assert.equal(blockFor(setting(true, 6), none).lines[0], "Subagents: on (revision 6) — a console setting, not typed by the person.", "a reset cursor re-states on");
|
||||
assert.equal(blockFor(setting(false, 6), none), null, "a reset cursor with it off: nothing");
|
||||
assert.equal(blockFor({ ...setting(true, 9), workflow: "plan" }, none), null, "a workflow that does not offer it: nothing");
|
||||
assert.equal(blockFor({ ...setting(true, 9), workflow: "document" }, none), null, "a workflow that does not offer it: nothing");
|
||||
});
|
||||
|
||||
test("subagents: the injected wording names no harness tool", () => {
|
||||
|
||||
@@ -382,7 +382,7 @@ test("Implement's card launches Implement + Review when Review is ticked", () =>
|
||||
assert.equal(launchVariant(quick, true), quick, "a card with no Review box is unchanged");
|
||||
});
|
||||
|
||||
test("helper-strength.md ships in the five skills that start helpers, and in no other", () => {
|
||||
test("helper-strength.md ships in the seven skills that start helpers, and in no other", () => {
|
||||
// npm test has just built skills/; a direct run builds it so the check never reads a stale tree.
|
||||
if (process.env.npm_lifecycle_event !== "test") {
|
||||
execFileSync(process.execPath, [path.join(ROOT, "install.js"), "--build-skills"], { stdio: "ignore" });
|
||||
@@ -391,6 +391,8 @@ test("helper-strength.md ships in the five skills that start helpers, and in no
|
||||
const having = fs.readdirSync(built).filter((dir) => fs.existsSync(path.join(built, dir, "references", "helper-strength.md")));
|
||||
assert.deepEqual(having.sort(), [
|
||||
"plan2code-0-pathfinder",
|
||||
"plan2code-1-plan",
|
||||
"plan2code-1b-revise-plan",
|
||||
"plan2code-3-implement",
|
||||
"plan2code-3-implement-review",
|
||||
"plan2code-quick-task",
|
||||
|
||||
@@ -243,12 +243,12 @@ test("subagents: a save that matches this session still becomes the project's se
|
||||
});
|
||||
|
||||
test("subagents: a workflow without the switch refuses it, bad bodies name the field, and an older copy's open hides it", async () => {
|
||||
const plan = subagentsSession({ workflow: "plan" });
|
||||
const doc = subagentsSession({ workflow: "document" });
|
||||
const s = subagentsSession();
|
||||
try {
|
||||
assert.deepEqual(await setSubagents(plan, ON3), { status: 400, body: { error: "not-offered" } });
|
||||
assert.equal((await frameSubagents(plan)).offered, false);
|
||||
assert.equal("subagents" in (await submitAndWait(plan)).json, false);
|
||||
assert.deepEqual(await setSubagents(doc, ON3), { status: 400, body: { error: "not-offered" } });
|
||||
assert.equal((await frameSubagents(doc)).offered, false);
|
||||
assert.equal("subagents" in (await submitAndWait(doc)).json, false);
|
||||
|
||||
assert.deepEqual(await setSubagents(s, { ...ON3, max: 0 }), { status: 400, body: { error: "max" } });
|
||||
assert.deepEqual(await setSubagents(s, { ...ON3, max: 21 }), { status: 400, body: { error: "max" } });
|
||||
@@ -268,7 +268,7 @@ test("subagents: a workflow without the switch refuses it, bad bodies name the f
|
||||
fs.rmSync(path.join(s.session, "subagents-setting.json"), { force: true });
|
||||
assert.equal("subagents" in (await submitAndWait(s)).json, false);
|
||||
} finally {
|
||||
cli(["stop", "--session", plan.sid]);
|
||||
cli(["stop", "--session", doc.sid]);
|
||||
cli(["stop", "--session", s.sid]);
|
||||
}
|
||||
});
|
||||
|
||||
@@ -43,6 +43,16 @@ Check if `./AGENTS.md` exists:
|
||||
- NEVER write implementation code; keep responses conceptual, detailed specs belong in the final PLAN-DRAFT only
|
||||
- If no file access, output content in code blocks with file path headers
|
||||
|
||||
## Helpers
|
||||
|
||||
When your tool can start helpers (subagents) and they are not switched off for this run (on the web console a `Subagents:` block says which, console-subagents.md), hand them the work whose answer does not hang on the conversation still to come:
|
||||
- **Phase 1:** reading each file, folder or reference the person names, and the domain research; one source per helper.
|
||||
- **Phase 2:** mapping separate areas of the codebase, one area per helper (structure, one component's real behavior, one integration point). Each returns facts with `file:line`, never a design.
|
||||
- **Phase 4:** evidence on each open tech choice (current version, upkeep, fit with the stack); the recommendation stays yours.
|
||||
- **Phase 7, step 3:** one fresh helper, briefed only with the PLAN-CONVERSATION and the PLAN-DRAFT, lists the gaps between them; confirm each yourself before you add it.
|
||||
|
||||
Keep with you: every question, confidence score, decision and sign-off, Phases 3, 5 and 6, and the writing of the PLAN-DRAFT (its sections cross-reference each other and rest on decisions only this session holds). Pick each helper's strength and effort from references/helper-strength.md. Every helper reports back before that phase's sign-off. No helpers? Do the same work yourself.
|
||||
|
||||
---
|
||||
|
||||
### Check for Existing Progress
|
||||
|
||||
@@ -31,6 +31,14 @@ The FIRST thing you do, before anything else in this file — before Step 1, bef
|
||||
- `node "<S>/specs.mjs" status <spec>`: phases, task counts by marker, `checks`, `pending`.
|
||||
- `node "<S>/specs.mjs" mark <spec> --phase <N> --to open`: re-open a completed phase in overview.md.
|
||||
|
||||
## Helpers
|
||||
|
||||
When your tool can start helpers (subagents) and they are not switched off for this run (on the web console a `Subagents:` block says which, console-subagents.md):
|
||||
- **Steps 1 and 2, read-only lookups:** the code behind each affected task (its functions and files as they stand now, for Step 3's code references), and the code behind completed tasks the change could undo, so **Completed Work at Risk** rests on evidence. One area per helper.
|
||||
- **Step 3, only after approval, when the revision touches 3 or more phase files:** one helper per `phase-X.md` whose edits the approved plan spells out. Run `mark` for every re-opened phase before starting them, since it rewrites that phase file too. Its brief carries that file's approved changes, the `🔄 REVISED` / `🆕 ADDED` formats, and the rule that it edits that one file under `specs/` and nothing else.
|
||||
|
||||
Keep with you: every question, the Step 2 approval, overview.md (`mark`, Revision History), the waiting brief's line, dependencies and numbering across phases, and Steps 4 to 6. Re-read every file a helper edited against the approved plan before Step 4. Strength and effort per references/helper-strength.md. No helpers? Do the same work yourself.
|
||||
|
||||
## Required Context
|
||||
|
||||
Find the spec with `specs.mjs list`, then request these files if not provided:
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
# Helper Strength
|
||||
> Shared by the skills that start helpers (subagents): Pathfinder, Quick Task, Implement, Implement + Review and Review. Read it when you first start a helper in a session. Never invoked as a skill.
|
||||
> Shared by the skills that start helpers (subagents): Pathfinder, Plan, Revise Plan, Quick Task, Implement, Implement + Review and Review. Read it when you first start a helper in a session. Never invoked as a skill.
|
||||
|
||||
## The words
|
||||
|
||||
@@ -17,10 +17,12 @@ Never write a model or vendor name in a brief, a report or a file, and never inv
|
||||
| Helper's job | Strength | Effort |
|
||||
|---|---|---|
|
||||
| Lookups, reading code, checking docs, recon | light | low |
|
||||
| Revise Plan edit to one phase file, spelled out in the approved plan | light | medium |
|
||||
| Build task in 1 or 2 files, with the change spelled out in the task | light | medium |
|
||||
| Build task across several files, integration work, debugging | standard | medium |
|
||||
| Build task needing a design decision the spec leaves open | strongest (or keep it yourself) | high |
|
||||
| Pathfinder research question, sketch | standard | medium |
|
||||
| Plan's PLAN-DRAFT cross-check against the conversation | standard | medium |
|
||||
| Review analysis, focused scope | standard | high |
|
||||
| Review analysis, branch or full scope, or touching security, auth or data | strongest | high |
|
||||
|
||||
@@ -28,7 +30,7 @@ Decide from these signals: how many files the job touches, whether the task spel
|
||||
|
||||
## Floor and escalation
|
||||
|
||||
- A review helper never runs below `standard`.
|
||||
- A review helper, or Plan's PLAN-DRAFT cross-check, never runs below `standard`.
|
||||
- A retry, after a helper fails or after its work fails the phase's tests, goes one strength up and at least `medium` effort. Never retry at the same strength.
|
||||
- When a `strongest` helper fails, its task comes back to you.
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ Part of the web console contract (`console.md`). Read when a `Subagents:` block
|
||||
arrives, or when your workflow notes say to report helpers.
|
||||
|
||||
On the skills that offer it (`implement`, `implement-review`, `quick-task`,
|
||||
`review`, `pathfinder`), the person can turn **helpers** (subagents) on or off
|
||||
`review`, `pathfinder`, `plan`, `revise-plan`), the person can turn **helpers** (subagents) on or off
|
||||
from the top bar's Subagents button. Their pick is saved per project and per
|
||||
skill, on until switched off, and reaches you as a standing instruction, only when it
|
||||
changes.
|
||||
|
||||
@@ -15,3 +15,8 @@ Workflow notes for `plan`, part of the web console contract (`console.md`).
|
||||
browser user is not watching.
|
||||
- The Large checkpoint finish is a pause: a headline starting "Paused", no
|
||||
`dashboard`, and `stop` at once.
|
||||
- Plan offers the Subagents switch. A `Subagents:` block may arrive on `open`
|
||||
output or a `wait` / `chat` pickup: follow `console-subagents.md` and the
|
||||
skill's Helpers section, and report each helper as `helpers`. Post a helper
|
||||
as `done` or `failed` before the sign-off it feeds, and every one before a
|
||||
`finish`. Questions, sign-offs and the PLAN-DRAFT stay with you.
|
||||
@@ -16,3 +16,11 @@ offers to execute or implement.** Pass `--spec specs/<feature>` to `open`, or
|
||||
post `specDir` once you know it. The finish command is
|
||||
`/plan2code-3-implement specs/<feature>/overview.md`; an abort's is
|
||||
`/plan2code-1b-revise-plan specs/<feature>/overview.md`.
|
||||
|
||||
Revision offers the Subagents switch. A `Subagents:` block may arrive on
|
||||
`open` output or a `wait` / `chat` pickup: follow `console-subagents.md` and
|
||||
the skill's Helpers section, and report each helper as `helpers`. Lookup
|
||||
helpers report back before the Step 2 review item goes up; phase-file helpers
|
||||
report back before the Step 4 check. Every gate stays with you, and a helper's
|
||||
`title`, `ask` and `result` follow the same rule as every label: nothing
|
||||
offers to execute or implement.
|
||||
@@ -2061,9 +2061,9 @@
|
||||
<section class="help-panel" data-tab="subagents">
|
||||
<h3>Helpers (subagents)</h3>
|
||||
<p>
|
||||
On a build, a review and Pathfinder, Plan2Code can hand independent
|
||||
pieces of work to helpers (subagents) while it keeps the conversation
|
||||
with you. The <strong>Subagents</strong> button in the top bar, after
|
||||
On a build, a review, Pathfinder, Plan and Revise plan, Plan2Code
|
||||
can hand independent pieces of work to helpers (subagents) while it
|
||||
keeps the conversation with you. The <strong>Subagents</strong> button in the top bar, after
|
||||
Stop session, is lit while helpers are on.
|
||||
</p>
|
||||
<h4>The switch</h4>
|
||||
|
||||
@@ -135,7 +135,7 @@ export const SKILLS = Object.freeze([
|
||||
pose: "plan",
|
||||
builds: false, phased: false, metered: true, templates: true,
|
||||
weight: 2, started: "Plan started", ran: "Plan drafted", resume: null,
|
||||
subagents: null,
|
||||
subagents: "Use helpers for research and recon beside the conversation: reading the files and references the person points you to, mapping separate areas of the codebase in Phase 2, and gathering evidence on each open tech choice in Phase 4. In Phase 7, one fresh helper may cross-check the PLAN-DRAFT against the PLAN-CONVERSATION; confirm each gap it finds yourself. Keep every question, decision and sign-off, and the writing of the PLAN-DRAFT, with you. Recon and lookups at light strength, the cross-check at standard.",
|
||||
states: ["none", "unrecognized", "diagnosed", "mapped", "planned"], marksNext: true,
|
||||
greyed: {
|
||||
default: "The plan is written. Revise it instead if it moved.",
|
||||
@@ -160,7 +160,7 @@ export const SKILLS = Object.freeze([
|
||||
pose: "plan",
|
||||
builds: false, phased: false, metered: true, templates: false,
|
||||
weight: 1, started: "Revise plan started", ran: "Plan revised", resume: "overview",
|
||||
subagents: null,
|
||||
subagents: "Use helpers for lookups at Steps 1 and 2: reading the code behind the affected tasks, and behind the completed tasks the change could undo. After the Step 2 approval, when the revision touches 3 or more phase files, one helper per phase file may apply the edits the approved plan spells out for it, editing under specs/ only. Keep the questions, the approval, overview.md, task numbering across phases and the consistency check with you, and re-read every file a helper edited. Lookups at light strength, low effort; phase-file edits at light, medium.",
|
||||
states: ["documented", "building", "built"],
|
||||
greyed: { default: "Needs a spec that is already written up" },
|
||||
card: {
|
||||
|
||||
Reference in new issue
Block a user