diff --git a/.agents-docs/AGENTS-architecture.md b/.agents-docs/AGENTS-architecture.md index 0a8abb2..48a7023 100644 --- a/.agents-docs/AGENTS-architecture.md +++ b/.agents-docs/AGENTS-architecture.md @@ -16,7 +16,8 @@ plan2code/ │ │ ├── handoff.md # Clearing gate + PLAN-DRAFT handoff │ │ └── 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) +│ │ ├── 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) │ ├── plan2code-review-references/ # Reference files for review skill │ │ ├── verification-protocol.md # Deep verification + confidence calibration │ │ ├── dimensions.md # 11 dimensions with detailed checklists @@ -254,7 +255,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 `` 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 `continue` and Enter into the agent's terminal) 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 }` or `{ error }`: `bad`, `too-long` past 2,000 characters, `max` outside 1-20), `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`, 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 `.json` (`{ v: 1, id, title, worktree, project, spec, workflow, skill, written, fromStop, usedAt }`), the agent writing `.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/-<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//note.md` with `tabs//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//` 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) | diff --git a/.readme/web-console.md b/.readme/web-console.md index 50f7b0f..15daeee 100644 --- a/.readme/web-console.md +++ b/.readme/web-console.md @@ -397,7 +397,11 @@ Pathfinder, the agent can hand independent pieces of work to helpers - **The dialog.** A click opens it; the button never switches anything by itself. **Use helpers** or **Work alone**, the instruction the agent follows (**Reset to default** puts the shipped one back), and how many helpers may - run at once (1 to 20; your agent's own limit still applies). **Save** sends + run at once (1 to 20; your agent's own limit still applies). Under Helpers, + **Helper strength** sets how strong a model and how much effort helpers get: + **Balanced** (the default), **Thrifty** (one step lighter; reviews never + below standard), **Best** (strongest and high effort, except lookups) or + **Match my session** (nothing set on helpers). **Save** sends it; the agent hears of it at its next check-in, as a setting, not as something you typed. - **Saved per project and per skill**, on until switched off, in @@ -407,7 +411,10 @@ Pathfinder, the agent can hand independent pieces of work to helpers appears before Ask: one row per helper with what it was asked and whether it is running, done or failed, plus a one-line result at the end. Rows change at the agent's check-ins, not live. *Working alone* means your agent has no way - to start helpers here. The tab clears when you go back to the dashboard. + to start helpers here. Each row may carry one quiet line such as "Standard, + medium effort" ("Session model" when the helper runs on yours). The rules + live in `helper-strength.md` and apply in terminal sessions too. The tab + clears when you go back to the dashboard. - **Pathfinder's research** always uses helpers, whatever the switch says, and they show in the tab too. diff --git a/AGENTS.md b/AGENTS.md index 16ae6db..9690906 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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`); 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/.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) 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/.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 @@ -103,7 +103,8 @@ When you make a mistake, get corrected, or discover something about this codebas - Before deleting a test file that upstream split or removed, diff plan2code's copy against the rebranded upstream base and port the plan2code-only tests: v2.7.0's split of the web console suite would otherwise have dropped seven hardening tests (now in `scripts/test-web-console-hardening.mjs`). - Register a new skill in `install.js` `SOURCE_PROMPTS` before running its `scripts/test-script-.mjs`: importing `scripts/skill-script-helpers.mjs` rebuilds `skills/` and prunes any skill folder `install.js` does not list, so the script under test vanishes. - When a `CHANGELOG.md` heading gets a version number, set the same number in `version.json` (with its `releaseDate`), the root `package.json` and README's `Version X.Y.Z` line in the same change, then run `npm run build:skills`. The changelog skill only touches `package.json`: v2.9.0 nearly shipped with `version.json` at 2.8.1, and README's line sat at 2.6.0 for three releases. -- When `npm test` fails only timing-bound suites (the chat stress test, the page-cards redraw test "a redraw keeps the place of...", then a cascade in the session suite starting at "no submitted frame within 5s") while the machine is busy, rerun those files alone, and the `node --test` list with `--test-concurrency=4`, before suspecting the change: they failed that way on untouched code under load during the web console file split, and the redraw test did again in three phases of web-console-health. In web-console-notepad, four more failed only in full runs and passed alone: the Workspace page's @-mention test, the dashboard page's handoff chip test, the session suite's document route (`connect ETIMEDOUT`) and the notepad page's 200 KB typing test (why its budget there is 200 ms, not the 92 ms it takes alone). +- When `npm test` fails only timing-bound suites (the chat stress test, the page-cards redraw test "a redraw keeps the place of...", then a cascade in the session suite starting at "no submitted frame within 5s") while the machine is busy, rerun those files alone, and the `node --test` list with `--test-concurrency=4`, before suspecting the change: they failed that way on untouched code under load during the web console file split, and the redraw test did again in three phases of web-console-health. In web-console-notepad, four more failed only in full runs and passed alone: the Workspace page's @-mention test, the dashboard page's handoff chip test, the session suite's document route (`connect ETIMEDOUT`) and the notepad page's 200 KB typing test (why its budget there is 200 ms, not the 92 ms it takes alone). In helper-strength, the page-cards test "a card cut by the window fades at its bottom edge..." did the same. +- Run `npm test` from a terminal outside the desktop app, or with `PLAN2CODE_IN_APP`, `PLAN2CODE_APP_TOKEN`, `PLAN2CODE_APP_VERSION`, `PLAN2CODE_APP_ANNOUNCE` and `PLAN2CODE_EMBED_ORIGIN` unset (`env -u ... npm test`): inherited from the app they fail about 34 tests that check behaviour outside the app (the update banner, the terminal line, cookies, open's browser launch), which pass once unset. - Post a helper as `done` or `failed` in the same turn its completion notice arrives: its row stays `running` on the Subagents tab until a post says otherwise (a build once reached its sign-off with one row spinning). A `finish` is now refused while any helper is `running`. - Bring the Windows folder picker (`picker.mjs`, copied into `src/launcher/plan2code.js`) to the front with an Alt tap before `SetForegroundWindow`, never with `windowsHide`, the owner form's `TopMost`, `HWND_TOPMOST` or `AttachThreadInput`: measured on Windows 11, `SetWindowPos(HWND_TOPMOST)` returns true while the dialog stays non-topmost behind the browser, and only the Alt tap made it the foreground window. Check with `GetForegroundWindow` from a second process, since no test can see it. - Add any new file or folder Plan2Code writes at the top of `~/.plan2code/` to `KEPT_PLAN2CODE_ENTRIES` in `src/web-console/sessions.mjs` and to the Cleanup test in `scripts/test-web-console-server.mjs`: User Preferences → Cleanup offers every other entry there for deletion once it is an hour old, and the desktop app's `app/` and `app.json` were about to be listed. diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f290b9..d6b9310 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ All notable changes to Plan2Code will be documented in this file. - **desktop app**: a cross-platform app (Rust, Tauri) that is the single window for working with an AI agent. It opens the Plan2Code dashboard as its main surface, runs Claude Code, Devin or Codex in a pseudo-terminal panel it owns, and adds a **New Session** button that replaces the agent with a fresh one on a brief the app builds from its own record of the session, with the in-progress work and recent activity carried over. Every console page (Ask, Workspace, Help, Preferences, Git, Notebook) opens inside the app, not a separate browser tab. - **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. +- **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. ### 🔧 Changed diff --git a/install.js b/install.js index e3e5ef2..f70cddd 100644 --- a/install.js +++ b/install.js @@ -161,7 +161,10 @@ const SOURCE_PROMPTS = [ name: 'pathfinder', displayName: 'Pathfinder Mode', description: 'charting of a foggy idea as a map of decision questions, cleared one at a time', - 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-quick-task.md', @@ -176,6 +179,7 @@ const SOURCE_PROMPTS = [ additionalReferences: [ { source: 'web-console', target: 'web-console' }, { source: 'shared-references/building-habits.md', target: 'building-habits.md' }, + { source: 'shared-references/helper-strength.md', target: 'helper-strength.md' }, { source: 'plan2code-review.md', target: 'review.md' }, { source: 'plan2code-review-references' } ] @@ -219,6 +223,7 @@ const SOURCE_PROMPTS = [ additionalReferences: [ { source: 'web-console', target: 'web-console' }, { source: 'shared-references/building-habits.md', target: 'building-habits.md' }, + { source: 'shared-references/helper-strength.md', target: 'helper-strength.md' }, { source: 'plan2code-review.md', target: 'review.md' }, { source: 'plan2code-review-references' } ] @@ -234,6 +239,7 @@ const SOURCE_PROMPTS = [ { source: 'web-console', target: 'web-console' }, { source: 'plan2code-3-implement.md', target: 'implement.md' }, { source: 'shared-references/building-habits.md', target: 'building-habits.md' }, + { source: 'shared-references/helper-strength.md', target: 'helper-strength.md' }, { source: 'plan2code-review.md', target: 'review.md' }, { source: 'plan2code-review-references' } ] @@ -246,7 +252,10 @@ const SOURCE_PROMPTS = [ description: 'Comprehensive post-implementation review with spec compliance checking', isUtility: true, scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.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-4-finalize.md', diff --git a/scripts/test-web-console-logic.mjs b/scripts/test-web-console-logic.mjs index 1766807..f280603 100644 --- a/scripts/test-web-console-logic.mjs +++ b/scripts/test-web-console-logic.mjs @@ -1999,7 +1999,7 @@ test("subagents: only the five opted-in workflows offer the switch", () => { assert.equal(defaultInstruction(w), ""); } assert.equal(Object.keys(SUBAGENT_WORKFLOWS).length, 5); - assert.deepEqual(defaultSetting("review"), { workflow: "review", on: true, instruction: null, max: 3 }); + 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(effectiveInstruction({ workflow: "review", instruction: " " }), defaultInstruction("review")); assert.equal(effectiveInstruction({ workflow: "review", instruction: " Mine " }), "Mine"); @@ -2015,7 +2015,7 @@ test("subagents: blockFor walks every switch transition, and never says off to a const on = blockFor(setting(true, 2), none); assert.equal(on.lines[0], "Subagents: on (revision 2) — a console setting, not typed by the person."); assert.ok(!on.lines[0].includes("replaces")); - assert.deepEqual(on.field, { state: "on", revision: 2, max: 3, instruction: defaultInstruction("implement") }); + assert.deepEqual(on.field, { state: "on", revision: 2, max: 3, instruction: defaultInstruction("implement"), strength: "balanced" }); assert.deepEqual(on.cursor, { revision: 2, state: "on" }); assert.equal(on.lines[on.lines.length - 1], " At most 3 helpers at once."); for (const frame of FRAME_LINES) assert.ok(on.lines.includes(" " + frame), frame); @@ -2025,7 +2025,7 @@ test("subagents: blockFor walks every switch transition, and never says off to a assert.ok(edit.lines.includes(" First line") && edit.lines.includes(" Second line"), "the instruction's own lines are indented"); assert.ok(!edit.lines.some((line) => !line.trim()), "blank instruction lines are dropped"); const nested = blockFor(setting(true, 2, { instruction: "- a\r\n - b\n \n" }), none); - assert.deepEqual(nested.lines.slice(-3, -1), [" - a", " - b"], "the person's own indentation survives, CRLF and blank lines do not"); + assert.deepEqual(nested.lines.slice(-4, -2), [" - a", " - b"], "the person's own indentation survives, CRLF and blank lines do not"); assert.equal(edit.field.max, 7); for (const line of edit.lines.slice(1)) assert.match(line, /^ {2}\S/, "only the first line starts at column 0"); @@ -2053,9 +2053,26 @@ test("subagents: the injected wording names no harness tool", () => { } }); +// Guards NFR-1: the strength guidance and the wording the console injects speak +// in strength words only, never a model or vendor name, so they stay right on +// every harness and every model line-up. +const MODEL_NAMES = /\b(haiku|sonnet|opus|fable|gpt|o\d|codex|gemini|flash|pro|claude|anthropic|openai|google|swe-\d)\b/i; + +test("subagents: the strength guidance and the injected wording name no model or vendor", () => { + const texts = [ + fs.readFileSync(path.join(ROOT, "src", "shared-references", "helper-strength.md"), "utf8"), + ...FRAME_LINES, + ...Object.keys(SUBAGENT_WORKFLOWS).map(defaultInstruction), + ]; + for (const text of texts) assert.doesNotMatch(text, MODEL_NAMES); + assert.match("Start it on Sonnet at high effort.", MODEL_NAMES, "the check catches a model name"); +}); + test("subagents: cleanSetting accepts a good setting and names the field that fails", () => { - assert.deepEqual(cleanSetting({ on: true, instruction: null, max: 3 }), { on: true, instruction: null, max: 3 }); - assert.deepEqual(cleanSetting({ on: false, instruction: " Do it ", max: 20 }), { on: false, instruction: "Do it", max: 20 }); + assert.deepEqual(cleanSetting({ on: true, instruction: null, max: 3 }), { on: true, instruction: null, max: 3, strength: "balanced" }); + assert.deepEqual(cleanSetting({ on: false, instruction: " Do it ", max: 20, strength: "best" }), { on: false, instruction: "Do it", max: 20, strength: "best" }); + assert.equal(cleanSetting({ on: true, instruction: null, max: 3, strength: null }).strength, "balanced", "a null strength is the default"); + for (const strength of ["fast", "Balanced", 1, ""]) assert.deepEqual(cleanSetting({ on: true, instruction: null, max: 3, strength }), { error: "strength" }, String(strength)); assert.equal(cleanSetting({ on: true, instruction: "", max: 1 }).instruction, null, "an empty instruction is the default"); for (const max of [0, 21, 2.5, "3"]) assert.deepEqual(cleanSetting({ on: true, instruction: null, max }), { error: "max" }, String(max)); assert.deepEqual(cleanSetting({ on: true, instruction: "x".repeat(2001), max: 3 }), { error: "too-long" }); @@ -2129,6 +2146,28 @@ test("subagents: helperRows labels each state, shows a result only once a helper assert.equal(rows[2].result, "Timed out"); }); +test("subagents: helperRows turns a reported strength and effort into one line, and leaves it out when neither was reported", () => { + const line = (extra) => helperRows([{ id: "h1", title: "One", ask: "a", state: "running", ...extra }]).rows[0]; + const cases = [ + [{ strength: "standard", effort: "medium" }, "Standard, medium effort"], + [{ strength: "light" }, "Light"], + [{ strength: "strongest", effort: "high" }, "Strongest, high effort"], + [{ strength: "inherit", effort: "high" }, "Session model, high effort"], + [{ strength: "inherit" }, "Session model"], + [{ effort: "low" }, "Low effort"], + ]; + for (const [extra, want] of cases) { + const row = line(extra); + assert.equal(row.strengthLine, want, JSON.stringify(extra)); + assert.equal(row.strength, extra.strength); + assert.equal(row.effort, extra.effort); + } + for (const extra of [{}, { strength: "huge", effort: "max" }]) { + const row = line(extra); + for (const key of ["strengthLine", "strength", "effort"]) assert.equal(key in row, false, `${JSON.stringify(extra)}: no ${key}`); + } +}); + test("page: the Subagents button sits right after Write a brief, and its dialog is in the page with no inline styles or scripts", () => { const html = fs.readFileSync(path.join(ROOT, "src", "web-console", "public", "index.html"), "utf8"); const row = html.match(/
([\s\S]*?)<\/div>\s*
/); @@ -2153,7 +2192,7 @@ test("subagents: the store round-trips per project and workflow under the consol const script = ` const lib = await import(${JSON.stringify(new URL("../src/web-console/settings.mjs", import.meta.url).href)}); const project = ${JSON.stringify(project)}; - lib.saveSubagentStoreEntry(project, "implement", { on: true, instruction: "Mine", max: 5 }); + lib.saveSubagentStoreEntry(project, "implement", { on: true, instruction: "Mine", max: 5, strength: "best" }); const flipped = project.replace(/My Repo$/, "MY REPO"); console.log(JSON.stringify({ file: lib.SUBAGENTS_FILE, @@ -2169,11 +2208,11 @@ test("subagents: the store round-trips per project and workflow under the consol assert.equal(res.status, 0, res.stderr); const out = JSON.parse(res.stdout); assert.equal(out.file, path.join(home, "subagents.json"), "the store follows PLAN2CODE_CONSOLE_HOME"); - assert.deepEqual(out.saved, { on: true, instruction: "Mine", max: 5 }); + assert.deepEqual(out.saved, { on: true, instruction: "Mine", max: 5, strength: "best" }); if (process.platform === "win32" || process.platform === "darwin") { assert.deepEqual(out.otherCase, out.saved, "a different-case path reads the same entry"); } - assert.deepEqual(out.unsaved, { on: true, instruction: null, max: 3 }, "nothing saved means on"); + assert.deepEqual(out.unsaved, { on: true, instruction: null, max: 3, strength: "balanced" }, "nothing saved means on, at balanced"); assert.ok(!fs.existsSync(path.join(home, "subagents.json.lock")), "the lock is released"); } finally { fs.rmSync(home, { recursive: true, force: true }); diff --git a/scripts/test-web-console-page-ask.mjs b/scripts/test-web-console-page-ask.mjs index ca9318a..a061847 100644 --- a/scripts/test-web-console-page-ask.mjs +++ b/scripts/test-web-console-page-ask.mjs @@ -211,3 +211,64 @@ test("posting helpers adds a Subagents tab that lists each with its state and re assert.match(await textOf(done), /All 9 pass\./); assert.match(await textOf(running), /Find the callers of applyPatch/); }); + +// What a person sees break: the strength they saved not shown when the dialog +// opens again, a help line that ignores their pick, or Save dropping it. +test("the Subagents dialog shows the saved strength, explains the picked one, goes inert under Work alone and saves it", async (t) => { + const s = await openSession(await suite.browser(), { + t, + workflow: "implement", + payload: { agent: { status: "working", activity: "Task 1 of 2" } }, + }); + const modal = s.page.locator("#subagents-modal"); + const radio = (value) => modal.locator(`input[name="subagents-strength"][value="${value}"]`); + const help = modal.locator("#subagents-strength-help"); + const open = async () => { + await s.page.locator("#btn-subagents").click(); + await modal.waitFor(); + }; + + await open(); + assert.equal(await radio("balanced").isChecked(), true, "an unsaved strength opens as Balanced"); + assert.match(await textOf(help), /light for lookups/); + await radio("thrifty").check(); + assert.match(await textOf(help), /One step lighter everywhere/); + await modal.locator('input[name="subagents-on"][value="off"]').check(); + for (const value of ["balanced", "thrifty", "best", "session"]) assert.equal(await radio(value).isDisabled(), true, `${value} is inert under Work alone`); + await modal.locator('input[name="subagents-on"][value="on"]').check(); + assert.equal(await radio("thrifty").isEnabled(), true); + + const posted = s.page.waitForRequest((r) => r.url().endsWith("/subagents") && r.method() === "POST"); + await modal.getByRole("button", { name: "Save", exact: true }).click(); + assert.equal(JSON.parse((await posted).postData()).strength, "thrifty"); + await modal.waitFor({ state: "hidden" }); + + // The next frame carries the saved strength; the dialog opens on it. + await s.page.waitForFunction(async () => (await (await fetch("/state")).json()).subagents.strength === "thrifty"); + await open(); + assert.equal(await radio("thrifty").isChecked(), true, "the saved strength is checked"); + assert.match(await textOf(help), /One step lighter everywhere/); +}); + +// What a person sees break: the strength a helper ran with missing from the +// tab, or a stray line under a helper that reported none. +test("the Subagents tab shows a reported helper's strength line and none for a helper without one", async (t) => { + const s = await openSession(await suite.browser(), { + t, + workflow: "implement", + payload: { agent: { status: "working", activity: "Task 1 of 2" } }, + }); + s.post({ + helpers: [ + reportedHelper("h1", { title: "Read the store helpers", strength: "standard", effort: "medium" }), + reportedHelper("h2", { title: "Check the tests" }), + ], + }); + const tab = s.page.locator("nav").getByRole("button", { name: /^Subagents/ }); + await tab.waitFor(); + await tab.click(); + const rows = s.page.locator("#main .sa-card .sa-row"); + await rows.first().waitFor(); + assert.equal(await textOf(rows.filter({ hasText: "Read the store helpers" }).locator(".sa-strength")), "Standard, medium effort"); + assert.equal(await rows.filter({ hasText: "Check the tests" }).locator(".sa-strength").count(), 0); +}); diff --git a/scripts/test-web-console-skills.mjs b/scripts/test-web-console-skills.mjs index 18a7e02..a0169b1 100644 --- a/scripts/test-web-console-skills.mjs +++ b/scripts/test-web-console-skills.mjs @@ -25,6 +25,7 @@ import fs from "node:fs"; import os from "node:os"; import path from "node:path"; import { createRequire } from "node:module"; +import { execFileSync } from "node:child_process"; import { ROOT, cli, poseTemplate } from "./web-console-test-helpers.mjs"; import { SUBAGENT_WORKFLOWS } from "../src/web-console/public/subagents.js"; import { TEMPLATE_WORKFLOWS } from "../src/web-console/public/starters.js"; @@ -380,3 +381,19 @@ test("Implement's card launches Implement + Review when Review is ticked", () => const quick = SKILL_CATALOG.find((e) => e.skill === "plan2code-quick-task"); 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", () => { + // 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" }); + } + const built = path.join(ROOT, "skills"); + 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-3-implement", + "plan2code-3-implement-review", + "plan2code-quick-task", + "plan2code-review", + ]); +}); diff --git a/scripts/test-web-console-subagents.mjs b/scripts/test-web-console-subagents.mjs index 7be706e..881303c 100644 --- a/scripts/test-web-console-subagents.mjs +++ b/scripts/test-web-console-subagents.mjs @@ -8,7 +8,7 @@ import test from "node:test"; import assert from "node:assert/strict"; import fs from "node:fs"; import path from "node:path"; -import { defaultInstruction, offered } from "../src/web-console/public/subagents.js"; +import { defaultInstruction, offered, onLines, STRENGTH_LINES, STRENGTHS } from "../src/web-console/public/subagents.js"; import { readSubagentCursor } from "../src/web-console/settings.mjs"; import { ROOT, @@ -64,13 +64,13 @@ test("subagents: a change reaches the next pickup once, last in reply, edits nam assert.equal(on.status, 200); assert.equal(on.body.ok, true); const rev = on.body.setting.revision; - assert.deepEqual(on.body.setting, { workflow: "implement", on: true, instruction: null, max: 3, revision: rev }); + assert.deepEqual(on.body.setting, { workflow: "implement", on: true, instruction: null, max: 3, strength: "balanced", revision: rev }); assert.equal((await ask(s, "Which files does the first task touch?")).status, 200); assert.equal((await addFolder(s, { path: extra })).status, 200); const first = await submitAndWait(s); assert.equal(first.status, 0); - assert.deepEqual(first.json.subagents, { state: "on", revision: rev, max: 3, instruction: defaultInstruction("implement") }); + assert.deepEqual(first.json.subagents, { state: "on", revision: rev, max: 3, instruction: defaultInstruction("implement"), strength: "balanced" }); const reply = first.json.reply; const at = (re) => reply.search(re); assert.ok(at(/^Export format: a$/m) === 0, reply); @@ -149,7 +149,7 @@ test("subagents: a resume re-states an on setting once, says nothing when off, a const rev = (await setSubagents(s, ON3)).body.setting.revision; const resumed = cli(["open", "--resume", s.sid, "--no-open"]); assert.equal(resumed.json.ok, true); - assert.deepEqual(resumed.json.subagents, { state: "on", revision: rev, max: 3, instruction: defaultInstruction("implement") }); + assert.deepEqual(resumed.json.subagents, { state: "on", revision: rev, max: 3, instruction: defaultInstruction("implement"), strength: "balanced" }); assert.equal(subagentLines(resumed.json.reply)[0], `Subagents: on (revision ${rev}) — a console setting, not typed by the person.`); assert.ok(resumed.json.reply.split("\n").every((l, i) => i === 0 || l.startsWith(" ")), "only the block's lines"); assert.equal("subagents" in (await submitAndWait(s)).json, false, "the next pickup carries nothing"); @@ -254,6 +254,7 @@ test("subagents: a workflow without the switch refuses it, bad bodies name the f assert.deepEqual(await setSubagents(s, { ...ON3, max: 21 }), { status: 400, body: { error: "max" } }); assert.deepEqual(await setSubagents(s, { ...ON3, instruction: "x".repeat(2001) }), { status: 400, body: { error: "too-long" } }); assert.deepEqual(await setSubagents(s, { ...ON3, on: "yes" }), { status: 400, body: { error: "bad" } }); + assert.deepEqual(await setSubagents(s, { ...ON3, strength: "fast" }), { status: 400, body: { error: "strength" } }); assert.equal((await frameSubagents(s)).supported, true, "this copy's open carries caps"); fs.appendFileSync(path.join(s.session, "events.ndjson"), JSON.stringify({ at: new Date().toISOString(), type: "open", resumed: true }) + "\n"); @@ -272,6 +273,60 @@ test("subagents: a workflow without the switch refuses it, bad bodies name the f } }); +test("subagents: a strength-only change reaches the agent once, with its profile line", async () => { + const s = subagentsSession(); + try { + const before = (await frameSubagents(s)).revision; + const thrifty = await setSubagents(s, { ...ON3, strength: "thrifty" }); + assert.equal(thrifty.status, 200); + assert.equal(thrifty.body.setting.revision, before + 1, "a strength alone is a change"); + assert.equal(thrifty.body.setting.strength, "thrifty"); + const picked = await submitAndWait(s); + assert.equal(picked.json.subagents.strength, "thrifty"); + assert.ok(picked.json.reply.endsWith(["", STRENGTH_LINES.thrifty, "At most 3 helpers at once."].join("\n ")), picked.json.reply); + assert.equal((await frameSubagents(s)).strength, "thrifty"); + + const again = await setSubagents(s, { ...ON3, strength: "thrifty" }); + assert.equal(again.body.setting.revision, before + 1, "the same strength again bumps nothing"); + assert.equal("subagents" in (await submitAndWait(s)).json, false); + } finally { + cli(["stop", "--session", s.sid]); + } +}); + +test("subagents: a setting saved before strength existed reads as balanced and bumps nothing", async () => { + const s = subagentsSession(); + try { + assert.equal((await setSubagents(s, { ...ON3, max: 4 })).status, 200); + const strip = (file, entries) => { + const saved = JSON.parse(fs.readFileSync(file, "utf8")); + for (const entry of entries(saved)) delete entry.strength; + fs.writeFileSync(file, JSON.stringify(saved)); + }; + strip(SUBAGENTS_STORE, (store) => Object.values(store).flatMap((project) => Object.values(project))); + strip(path.join(s.session, "subagents-setting.json"), (setting) => [setting]); + const rev = JSON.parse(fs.readFileSync(path.join(s.session, "subagents-setting.json"), "utf8")).revision; + + cli(["stop", "--session", s.sid]); + const resumed = sessionUrl(cli(["open", "--resume", s.sid, "--no-open"]).json.url); + const frame = (await (await fetch(`${resumed.base}/state`, { headers: { cookie: resumed.cookie, connection: "close" } })).json()).subagents; + assert.deepEqual([frame.max, frame.strength, frame.revision], [4, "balanced", rev], "an upgrade alone bumps nothing"); + } finally { + cli(["stop", "--session", s.sid]); + } +}); + +test("subagents: every strength renders its own profile line, and a missing one is balanced", () => { + const base = { revision: 1, max: 3, instruction: "Split by file." }; + for (const strength of STRENGTHS) { + const lines = onLines({ ...base, strength }); + assert.equal(lines[lines.length - 2], " " + STRENGTH_LINES[strength], strength); + assert.equal(lines.filter((l) => l.includes("Helper strength:")).length, 1, strength); + } + assert.equal(new Set(STRENGTHS.map((k) => STRENGTH_LINES[k])).size, STRENGTHS.length, "four different lines"); + assert.equal(onLines(base).at(-2), " " + STRENGTH_LINES.balanced); +}); + /* ------------------------------------------ subagents: helper reports */ @@ -334,6 +389,30 @@ test("helpers: every malformed report exits 3 naming the helper, and nothing is } }); +test("helpers: a reported strength and effort are kept, other values exit 3 naming the helper, and both stay optional", () => { + const s = consoleSession(["--workflow", "implement"]); + try { + const ran = reportedHelper("h1", { strength: "standard", effort: "medium" }); + assert.equal(postPatch(s, { helpers: [ran] }).status, 0); + assert.deepEqual(readState(s.session).helpers, [ran], "strength and effort are kept as reported"); + const statePath = path.join(s.session, "state.json"); + const before = fs.readFileSync(statePath, "utf8"); + for (const [name, extra, re] of [ + ["unknown strength", { strength: "huge" }, /helper "h2": strength must be light, standard, strongest or inherit/], + ["unknown effort", { effort: "max" }, /helper "h2": effort must be low, medium or high/], + ]) { + const res = postPatch(s, { helpers: [reportedHelper("h2", extra)] }, { expectFail: true }); + assert.equal(res.status, 3, name); + assert.match(res.stderr, re, name); + assert.equal(fs.readFileSync(statePath, "utf8"), before, `${name}: nothing written`); + } + assert.equal(postPatch(s, { helpers: [reportedHelper("h3")] }).status, 0, "a helper without the fields still posts"); + assert.deepEqual(readState(s.session).helpers.map((h) => h.id), ["h1", "h3"]); + } finally { + cli(["stop", "--session", s.sid]); + } +}); + test("docs: a doc's version never goes back; the same version again is fine, and a hop starts every doc fresh", () => { const s = consoleSession(["--workflow", "implement"]); try { diff --git a/src/plan2code-0-pathfinder-references/resolve.md b/src/plan2code-0-pathfinder-references/resolve.md index 3a4b37a..7a9e9e1 100644 --- a/src/plan2code-0-pathfinder-references/resolve.md +++ b/src/plan2code-0-pathfinder-references/resolve.md @@ -58,6 +58,8 @@ The only type an agent resolves alone, and the only type that may run several at One subagent per research question. Do not read the docs yourself in the main session — the point is that the main session's context stays clean for the decision work. +Start each research subagent at standard strength and medium effort per `helper-strength.md` (its fallback order applies; a re-fired subagent from `refire` goes one strength up). + The subagent's brief must carry, verbatim: 1. The absolute path of the question file it owns. diff --git a/src/plan2code-3-implement-review.md b/src/plan2code-3-implement-review.md index bfbb05a..812c026 100644 --- a/src/plan2code-3-implement-review.md +++ b/src/plan2code-3-implement-review.md @@ -54,7 +54,7 @@ Run Review Mode with this explicit scope: - Use overview.md and the active phase file for spec-compliance context; they do not broaden scope to other phases. - Read related callers, dependencies, and project files when needed to verify a finding, but do not turn them into unrelated review targets. - Review all changed files completely and apply the full focused-review depth required by Review Mode. -- Review Mode's helper rule applies: a fresh helper runs the analysis when available, this session verifies every finding, and the Stage 4 report carries the Reviewed by line. The helper's brief carries the phase's `phase-X.md` and its change set only, never Stage 1's work notes. +- Review Mode's helper rule applies: a fresh helper runs the analysis when available, at the strength `helper-strength.md` gives for the phase's review (standard and high, or strongest and high when the phase touches security, auth or data), this session verifies every finding, and the Stage 4 report carries the Reviewed by line. The helper's brief carries the phase's `phase-X.md` and its change set only, never Stage 1's work notes. Override Review Mode's completion and session-end behavior: diff --git a/src/plan2code-review-references/reviewer-brief.md b/src/plan2code-review-references/reviewer-brief.md index f56216d..9f62106 100644 --- a/src/plan2code-review-references/reviewer-brief.md +++ b/src/plan2code-review-references/reviewer-brief.md @@ -1,7 +1,7 @@ # Reviewer Brief > Part of plan2code-review: filled in by the main session at Step 3 (Analyze) and handed, whole, to ONE fresh helper. -Fill every `{{...}}` field, drop the lines that do not apply, and send the filled text as the helper's entire instructions. Never add the builder's conversation, reasoning, work notes or self-review: the helper's value is that it did not see them. +Fill every `{{...}}` field, drop the lines that do not apply, and send the filled text as the helper's entire instructions. Never add the builder's conversation, reasoning, work notes or self-review: the helper's value is that it did not see them. Start the helper at the strength and effort `helper-strength.md` gives for review analysis, following its fallback order. --- diff --git a/src/plan2code-review.md b/src/plan2code-review.md index 1886ef0..a7a4207 100644 --- a/src/plan2code-review.md +++ b/src/plan2code-review.md @@ -93,7 +93,7 @@ Three levels -- auto-detected, always respect explicit user override: ### Step 3: Analyze -**Who reviews:** when your tool can start a helper (subagent) and helpers are not switched off for this skill run, fill references/reviewer-brief.md and hand the analysis to ONE fresh helper; do not analyze in parallel. The brief carries the review-depth references, the dimensions and the finding format: send only the filled brief. With no helper, or one that fails or returns nothing usable, run this step in this session. +**Who reviews:** when your tool can start a helper (subagent) and helpers are not switched off for this skill run, fill references/reviewer-brief.md and hand the analysis to ONE fresh helper; do not analyze in parallel. The brief carries the review-depth references, the dimensions and the finding format: send only the filled brief. Start the helper at the strength and effort references/helper-strength.md gives for review analysis (standard and high for a focused scope; strongest and high for branch or full scope, or changes touching security, auth or data), following its fallback order. With no helper, or one that fails or returns nothing usable, run this step in this session. **Load review depth (conditional on scope):** diff --git a/src/shared-references/helper-strength.md b/src/shared-references/helper-strength.md new file mode 100644 index 0000000..467282f --- /dev/null +++ b/src/shared-references/helper-strength.md @@ -0,0 +1,58 @@ +# 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. + +## The words + +- **Strength:** `light`, `standard`, `strongest` or `inherit`. + - `light`: your tool's fastest, cheapest model class. + - `strongest`: its most capable model class. + - `standard`: the one between them, often your tool's default. + - `inherit`: the helper runs with the session's own model. +- **Effort:** `low`, `medium` or `high`, where your tool lets you set how hard a model thinks. + +Never write a model or vendor name in a brief, a report or a file, and never invent a model id: map the word to whatever your tool offers. + +## Picking a strength + +| Helper's job | Strength | Effort | +|---|---|---| +| Lookups, reading code, checking docs, recon | light | low | +| 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 | +| Review analysis, focused scope | standard | high | +| Review analysis, branch or full scope, or touching security, auth or data | strongest | high | + +Decide from these signals: how many files the job touches, whether the task spells out the change, whether a design decision is still open, and the review's scope and risk. Never decide from how hard the task feels. + +## Floor and escalation + +- A review helper 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. + +## Setting it + +In this order: + +1. Your tool accepts a model or effort setting when it starts a helper: set the closest match. +2. It lets you choose a helper profile or agent type instead: pick the one that matches. +3. Neither: start the helper without one, and it inherits. + +Set it explicitly wherever you can. A helper left unset usually inherits the session's most capable and most expensive model. + +## The person's choice (web console) + +On the web console the person picks a profile in the Subagents dialog. A `Helper strength:` line in a `Subagents:` block replaces the Balanced default: + +| Choice | Effect | +|---|---| +| Balanced (default) | The table as written | +| Thrifty | One step lighter in strength and effort; reviews never below standard | +| Best | Strongest and high effort for everything except lookups, which stay light | +| Match my session | No model or effort set on any helper, whatever the skill files say | + +## Reporting + +On the web console, report each helper's `strength` and `effort` as it actually ran (`console-subagents.md`, Reporting helpers). Report `inherit` when you could not set it. When `console-subagents.md` does not list those two fields yet, your console is older than this file: leave them out, since it ignores them. diff --git a/src/web-console/cmd-help.mjs b/src/web-console/cmd-help.mjs index 21cee09..b049727 100644 --- a/src/web-console/cmd-help.mjs +++ b/src/web-console/cmd-help.mjs @@ -51,7 +51,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface. path, description?, original? }], missing? }, the folders this console session reads as context, addressed as @name. The list is remembered per folder and spec in workspaces.json beside looks.json. - May also print subagents: { state, revision, max, instruction } and + May also print subagents: { state, revision, max, instruction, strength } and a reply holding only its "Subagents: ..." lines, when a standing instruction (the page's Subagents switch) is owed to you. post --session --file [--wait ] @@ -66,9 +66,9 @@ port, and the filesystem as transport; this CLI is the whole agent surface. carry run: { event, id, tasks? } (session meter points) and folderIssue: { name, reason, hint? } (a workspace folder you could not read); both go to the ledger, never into the state. A patch may also - carry helpers: [{ id, title, ask, state, result? }] or one - { id: "alone", alone: true }, merged by id, for the Subagents tab - (help subagents). + carry helpers: [{ id, title, ask, state, result?, strength?, + effort? }] or one { id: "alone", alone: true }, merged by id, for + the Subagents tab (help subagents). wait --session [--seconds ] A bounded wait slice, sized below your shell timeout. Exit 0 = the result is on stdout, 10 = still waiting ("Waiting on your answer diff --git a/src/web-console/console-subagents.md b/src/web-console/console-subagents.md index 598660a..33f546a 100644 --- a/src/web-console/console-subagents.md +++ b/src/web-console/console-subagents.md @@ -22,11 +22,21 @@ 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-subagents.md); questions for the person stay with you. If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it. - 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. + Match each helper's strength and effort to its job, as helper-strength.md says; when your tools cannot set them, start the helper without them. + 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. Pick each helper's strength and effort from helper-strength.md's table: light for a 1-2 file task the task file spells out, standard for multi-file or debugging work. + Helper strength: balanced (the table in helper-strength.md as written). At most 3 helpers at once. ``` -beside `"subagents": { "state": "on", "revision": 2, "max": 3, "instruction": "…" }`. +beside `"subagents": { "state": "on", "revision": 2, "max": 3, "instruction": "…", "strength": "balanced" }`. +The `Helper strength:` line carries the person's profile, and replaces the +Balanced default when they pick another: + +- `balanced`: the table in `helper-strength.md` as written (the default). +- `thrifty`: one step lighter in strength and effort; reviews never below standard. +- `best`: strongest and high effort for every helper except lookups, which stay light. +- `session`: set no model or effort on any helper. + An edit while on arrives as `Subagents: on (revision 3, replaces revision 2) — …` with the whole block again; switching off arrives as one line: `Subagents: off (revision 4) — don't start new helpers for the rest of this session.` @@ -39,6 +49,9 @@ card, and it is never recorded under `specs/`. - **On:** hand independent work to helpers if your tools allow it, at most `max` at once, following the instruction lines. `max` is advisory: your harness's own limit still applies. +- **Strength:** start each helper at the strength and effort + `helper-strength.md` (in the skill's `references/`) gives for its job, + following its fallback order. Read it when you first start a helper. - **A higher revision replaces a lower one.** Follow the latest block only. - **Off:** start no new helpers for the rest of the session. Let running ones finish and report them. @@ -56,13 +69,16 @@ page never hears from a helper directly: ```jsonc { "helpers": [ { "id": "h1", "title": "Read the store helpers", "ask": "Find every caller of readSubagentSetting.", "state": "running" }, - { "id": "h2", "title": "Check the tests", "ask": "Run the subagents tests and report failures.", "state": "done", "result": "All 9 pass." } + { "id": "h2", "title": "Check the tests", "ask": "Run the subagents tests and report failures.", "state": "done", "result": "All 9 pass.", "strength": "light", "effort": "low" } ] } ``` - `id` (non-empty), `title` (at most 80 characters), `ask` (at most 400) and `state` (`running`, `done` or `failed`) are required; `result` (at most 200) - is the one line you add once a helper ends. Anything else is exit `3`, and + is the one line you add once a helper ends. `strength` (`light`, + `standard`, `strongest` or `inherit`) and `effort` (`low`, `medium` or + `high`) are optional: report what the helper actually ran with, and + `inherit` when its strength could not be set. Anything else is exit `3`, and the house rules on completion markers and metric-like words cover `title`, `ask` and `result`. - Merged by `id`: post a helper again with its new `state` and `result` and it diff --git a/src/web-console/public/index.html b/src/web-console/public/index.html index 290428e..51dad7b 100644 --- a/src/web-console/public/index.html +++ b/src/web-console/public/index.html @@ -2086,6 +2086,31 @@
  • The button only appears on skills that use helpers, and only when Plan2Code can pass the setting on.
  • +

    Helper strength

    +

    + Under Helpers, the dialog also asks how strong the helpers should be. + Like the rest of the dialog it is saved for this project and this + skill, and it does nothing under Work alone. +

    +
      +
    • + Balanced (the default): each helper gets the + strength its job needs: light for lookups, stronger for reviews and + design work. +
    • +
    • + Thrifty: one step lighter everywhere to save cost; + reviews stay at standard or above. +
    • +
    • + Best: the strongest model and high effort for + everything except lookups. +
    • +
    • + Match my session: helpers run on whatever your + session uses; nothing is set for them. +
    • +

    The Subagents tab

    • @@ -2099,6 +2124,12 @@ check-ins, not live. The page cannot stop a helper; ask Plan2Code on the Ask tab if one should stop.
    • +
    • + Under each helper, a line such as "Standard, medium effort" shows + what that helper actually ran with. "Session model" means the agent + could not set a strength for it, so it ran on the session's own + model. A helper that reported neither shows no line. +
    • Working alone means your agent reported it has no way to start helpers here. If it starts one after all, the note @@ -2639,6 +2670,14 @@ +