diff --git a/.readme/status-line.md b/.readme/status-line.md index c513d4d..99d39e0 100644 --- a/.readme/status-line.md +++ b/.readme/status-line.md @@ -17,16 +17,16 @@ On Pro / Max / Teams accounts, where rate limits are available: ``` ╭───╮ Opus 5 / high │ plan2code │ feature/pathfinder-github-iss │ +12 -3 │ ★ │ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ - ╰┬─┬╯ 3h 5m ($4.62) │ ▰▰▰▰▰▱▱▱▱▱▱▱ 42% (84K) │ 5h: 28% · 7d: 61% + ╰┬─┬╯ 84k ⋅ ▰▰▰▰▰▱▱▱▱▱▱▱ 42% │ 5h: 28% · 7d: 61% | 3h 5m ($4.62) ``` -On Enterprise / Bedrock / Vertex / pay-as-you-go, where they aren't, the last segment becomes session +On Enterprise / Bedrock / Vertex / pay-as-you-go, where they aren't, the usage segment becomes session token counts instead: ``` ╭───╮ Sonnet 5 │ plan2code │ main │ +12 -3 │ ★ │ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ - ╰┬─┬╯ 2m ($0.18) │ ▰▰▱▱▱▱▱▱▱▱▱▱ 18% │ 88k in · 3k out + ╰┬─┬╯ ▰▰▱▱▱▱▱▱▱▱▱▱ 18% │ 88k in · 3k out | 2m ($0.18) ``` The icons down the left are Planny, the project mascot. diff --git a/install.js b/install.js index a6d8894..4b13862 100644 --- a/install.js +++ b/install.js @@ -180,6 +180,7 @@ const SOURCE_PROMPTS = [ { 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: 'shared-references/test-runs.md', target: 'test-runs.md' }, { source: 'plan2code-review.md', target: 'review.md' }, { source: 'plan2code-review-references' } ] @@ -215,7 +216,10 @@ const SOURCE_PROMPTS = [ displayName: 'Documentation Mode', description: 'Transform planning output into structured implementation docs', scripts: ['specs.mjs'], - additionalReferences: [{ source: 'web-console', target: 'web-console' }] + additionalReferences: [ + { source: 'web-console', target: 'web-console' }, + { source: 'shared-references/test-runs.md', target: 'test-runs.md' } + ] }, { source: 'plan2code-3-implement.md', @@ -230,6 +234,7 @@ const SOURCE_PROMPTS = [ { 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: 'shared-references/test-runs.md', target: 'test-runs.md' }, { source: 'plan2code-review.md', target: 'review.md' }, { source: 'plan2code-review-references' } ] @@ -246,6 +251,7 @@ const SOURCE_PROMPTS = [ { 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: 'shared-references/test-runs.md', target: 'test-runs.md' }, { source: 'plan2code-review.md', target: 'review.md' }, { source: 'plan2code-review-references' } ] @@ -260,7 +266,8 @@ const SOURCE_PROMPTS = [ scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs'], additionalReferences: [ { source: 'web-console', target: 'web-console' }, - { source: 'shared-references/helper-strength.md', target: 'helper-strength.md' } + { source: 'shared-references/helper-strength.md', target: 'helper-strength.md' }, + { source: 'shared-references/test-runs.md', target: 'test-runs.md' } ] }, { @@ -270,7 +277,10 @@ const SOURCE_PROMPTS = [ displayName: 'Finalization Mode', description: 'Validate, summarize, and archive completed work', scripts: ['specs.mjs', 'commit-msg.mjs'], - additionalReferences: [{ source: 'web-console', target: 'web-console' }] + additionalReferences: [ + { source: 'web-console', target: 'web-console' }, + { source: 'shared-references/test-runs.md', target: 'test-runs.md' } + ] }, { source: 'plan2code-handoff.md', diff --git a/plan2code-loop/src/prompt/templates.ts b/plan2code-loop/src/prompt/templates.ts index c58fa83..3c4260b 100644 --- a/plan2code-loop/src/prompt/templates.ts +++ b/plan2code-loop/src/prompt/templates.ts @@ -39,7 +39,7 @@ Prerequisites use plain bullets with inline annotations, not checkboxes. ## Implementation Steps 1. Read and understand the single task 2. Implement it completely -3. Validate it works (run tests if applicable and double-check code) +3. Validate it works (run the tests the task or phase file lists, and double-check code) 4. Mark ONLY that task's checkbox as \`[x]\` in the phase file 5. If that was the LAST task in the phase, also mark the phase \`[x]\` in overview.md 6. Output your completion marker and STOP @@ -129,7 +129,7 @@ Prerequisites use plain bullets with inline annotations, not checkboxes. ## Implementation Steps (repeat for EACH task in the phase) 1. Read and understand the task 2. Implement it completely -3. Validate it works (run tests if applicable and double-check code) +3. Validate it works (run the tests the task or phase file lists, and double-check code) 4. Mark that task's checkbox as \`[x]\` in the phase file 5. **Create a git commit** for this task (see Git Policy below) 6. Output a TASK_COMPLETE marker for this task diff --git a/scripts/test-script-pathfinder.mjs b/scripts/test-script-pathfinder.mjs index eff25ad..b74715c 100644 --- a/scripts/test-script-pathfinder.mjs +++ b/scripts/test-script-pathfinder.mjs @@ -208,7 +208,7 @@ test("pathfinder gate: mechanical checks and hard caps", () => { assert.equal(g.mechanicalPass, false); const failed = g.checks.filter((c) => !c.pass).map((c) => c.id); assert.deepEqual(failed, ["no-open-claimed-blocked", "fog-empty", "hard-caps", "scores-at-least-18"]); - assert.ok(g.caps.some((c) => c.dimension === "Requirements" && /not resolved/.test(c.why))); + assert.ok(!g.caps.some((c) => c.dimension === "Requirements"), "testing is Plan's question, so no testing cap"); assert.ok(g.caps.some((c) => c.dimension === "Risk" && /Export format records no consequences/.test(c.why))); assert.equal(g.planDraftPath, "specs/audit-export/PLAN-DRAFT-20260803.md"); // Settle everything. @@ -312,19 +312,15 @@ test("pathfinder reconcile: rows stay in place among grouping lines, a re-opened assert.match(map, /### Group two\n\n- \[ \] \[Export format\]\(\.\/questions\/01-export-format\.md\)\n/, "the group heading keeps its place and the row its old tail is gone"); }); -test("pathfinder gate: testing posture by keyword (never from Rejected), research-style consequences count", () => { +test("pathfinder gate: research-style consequences count", () => { const { root, pf } = mapFixture(); const qd = path.join(root, pf, "questions"); const P = (...a) => runScript("plan2code-0-pathfinder", "pathfinder.mjs", [...a, "--root", root]); - fs.writeFileSync(path.join(qd, "03-testing-posture.md"), q("Testing posture", { state: "resolved", resolved: "2026-08-02", answer: "Unit + integration, run after each phase, moderate coverage.\n\n**Gist:** Unit." })); fs.writeFileSync(path.join(qd, "01-export-format.md"), q("Export format", { state: "resolved", resolved: "2026-08-02", locked: "yes", answer: "### What this implies\n\n- Excel only.\n\n**Gist:** CSV." })); P("reconcile", "audit-export"); - let caps = P("gate", "audit-export").json.caps; + const caps = P("gate", "audit-export").json.caps; assert.ok(!caps.some((c) => c.dimension === "Requirements"), JSON.stringify(caps)); assert.ok(!caps.some((c) => c.dimension === "Risk"), JSON.stringify(caps)); - fs.writeFileSync(path.join(qd, "03-testing-posture.md"), q("Testing posture", { state: "resolved", resolved: "2026-08-02", answer: "Unit tests.\n\n**Rejected**\n\n- Run after each phase with Moderate coverage: too slow.\n\n**Gist:** Unit." })); - caps = P("gate", "audit-export").json.caps; - assert.ok(caps.some((c) => c.dimension === "Requirements" && /cadence/.test(c.why)), "a cadence named only as rejected does not count"); }); test("pathfinder: Form C needs a frontier; names come from the rows; NN is never handed out twice", () => { diff --git a/scripts/test-skill-test-runs.mjs b/scripts/test-skill-test-runs.mjs new file mode 100644 index 0000000..5e94cfc --- /dev/null +++ b/scripts/test-skill-test-runs.mjs @@ -0,0 +1,137 @@ +// Skill text for targeted test runs: the wording that tells Plan, Pathfinder, +// Document and the build skills which tests to run and who asks about them. +// Run with: node --test scripts/test-skill-test-runs.mjs + +import test from "node:test"; +import assert from "node:assert/strict"; +import fs from "node:fs"; +import path from "node:path"; +import { execFileSync } from "node:child_process"; +import { fileURLToPath } from "node:url"; + +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +const src = (...p) => fs.readFileSync(path.join(ROOT, "src", ...p), "utf8"); + +test("Plan offers the cadence and full-suite answers and checks old drafts for them", () => { + const plan = src("plan2code-1-plan.md"); + assert.match(plan, /Phase testing\*\*: Targeted per phase.*Dedicated phase only.*None/); + assert.match(plan, /Full suite\*\*: Offered at Finalize.*At Phase N.*Never/); + assert.match(plan, /Before going on with any existing draft.*Deferred to Plan.*Not discussed.*Full Suite/, "the progress check names a deferred, empty or undiscussed 2.4"); + assert.match(plan, /skip testing' writes `None` and `Never`/); + assert.match(plan, /Full Suite/, "2.4 carries a Full Suite row"); +}); + +test("Pathfinder hands testing to Plan and no longer gates on it", () => { + const dir = path.join(ROOT, "src"); + const files = []; + for (const entry of fs.readdirSync(dir)) { + if (!entry.startsWith("plan2code-0-pathfinder")) continue; + const full = path.join(dir, entry); + if (fs.statSync(full).isDirectory()) { + for (const f of fs.readdirSync(full)) if (f.endsWith(".md")) files.push(path.join(full, f)); + } else if (entry.endsWith(".md")) files.push(full); + } + assert.ok(files.length > 3, "found the Pathfinder prompts"); + assert.ok(src("plan2code-0-pathfinder-references", "handoff.md").includes("Deferred to Plan"), "the handoff writes Deferred to Plan"); + for (const f of files) { + if (path.basename(f) === "handoff.md") continue; + assert.doesNotMatch(fs.readFileSync(f, "utf8"), /testing posture|Run after each phase/i, `${path.basename(f)} asks no testing question`); + } + assert.ok(!src("plan2code-0-pathfinder-scripts", "pathfinder.mjs").includes("CADENCE_RE"), "the gate has no testing cap"); +}); + +test("Document writes Targeted, Quick checks and Full suite lines and reads test-runs.md", () => { + const doc = src("plan2code-2-document.md"); + for (const line of ["Targeted:", "Quick checks:", "Full suite:", "test-runs.md"]) assert.ok(doc.includes(line), `Document names ${line}`); + assert.match(doc, /only to the phase named by "At Phase N"/); + assert.match(doc, /no Full Suite row: ask/); +}); + +test("test-runs.md ships in the six skills that run, write or offer tests, 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", "test-runs.md"))); + assert.deepEqual(having.sort(), [ + "plan2code-2-document", + "plan2code-3-implement", + "plan2code-3-implement-review", + "plan2code-4-finalize", + "plan2code-quick-task", + "plan2code-review", + ]); +}); + +test("test-runs.md names no runner as the default and asks when unsure", () => { + const rule = src("shared-references", "test-runs.md"); + assert.match(rule, /Ask when unsure/); + assert.doesNotMatch(rule.replace(/`npm test`/g, ""), /\b(jest|vitest|pytest|mocha|cargo test)\b/i); + assert.ok(rule.length < 3200, "the shared rule stays short"); +}); + +test("Implement and Implement + Review say the same targeted rule", () => { + const impl = src("plan2code-3-implement.md"); + const both = src("plan2code-3-implement-review.md"); + for (const text of [impl, both]) { + assert.match(text, /after each task (run )?the tests covering what it touched/); + assert.match(text, /the phase file's `## Phase Testing` lines plus tests for any other file the phase changed/); + assert.match(text, /never the full suite unless the phase file lists a `Full suite:` line/); + assert.match(text, /Read `references\/test-runs\.md` before the first test run of a phase/); + } + assert.doesNotMatch(impl, /Run tests ONLY if/); + assert.doesNotMatch(both, /explicitly listed as a phase task/); +}); + +test("Implement's sign-off offers a wider run for shared ground and asks when unsure", () => { + const impl = src("plan2code-3-implement.md"); + assert.match(impl, /changed shared ground the plan did not foresee/); + assert.match(impl, /offer the full suite or a wider set as a choice beside approval/); + assert.match(impl, /Unsure whether it is shared ground\? Ask\./); + assert.match(src("web-console", "building.md"), /\| Shared ground touched \| `choice` \|/); +}); + +test("Quick Task and Review name the tests covering the changed files", () => { + const quick = src("plan2code-quick-task.md"); + assert.match(quick, /\[Targeted: the command and the tests covering the changed files\]/); + assert.ok(quick.includes("**Write the test first?**"), "the test-first question stays"); + assert.ok(quick.includes("references/test-runs.md"), "Quick Task reads the shared rule"); + assert.match(src("plan2code-review.md"), /\*\*Verify\*\* -- build and run the tests covering the fixed files \(per `references\/test-runs\.md`/); +}); + +test("the loop prompt points at the tests the task or phase file lists", () => { + const tpl = fs.readFileSync(path.join(ROOT, "plan2code-loop", "src", "prompt", "templates.ts"), "utf8"); + assert.equal(tpl.split("run the tests the task or phase file lists").length - 1, 2); + assert.ok(!tpl.includes("if applicable")); +}); + +test("Finalize offers the full suite, skips it for Never and records the four outcomes", () => { + const fin = src("plan2code-4-finalize.md"); + assert.ok(fin.includes("Run the full suite now?"), "Finalize asks the question"); + assert.match(fin, /`Never`: skip the offer; record `not planned`/); + assert.ok(fin.includes("references/test-runs.md"), "Finalize reads the shared rule"); + assert.match(fin, /Never forced/); + for (const outcome of ["passed", "failed (N)", "skipped (your choice)", "not planned"]) { + assert.ok(fin.includes(outcome), `Finalize records ${outcome}`); + } + assert.match(fin, /Full suite: \[passed \/ failed \(N\) \/ skipped \(your choice\) \/ not planned\]/, "the summary template carries the line"); + assert.doesNotMatch(fin, /Test Validation \(if defined\)/); + const notes = src("web-console", "notes", "finalize.md"); + assert.match(notes, /`confirm` "Run the full suite" \(`yesLabel` "Run it", `noLabel` "Skip it"/); + assert.match(notes, /a failure is the building notes' `choice`/); +}); + +test("test-runs.md says to ask when a check or its tests are unclear", () => { + const rule = src("shared-references", "test-runs.md"); + assert.match(rule, /which tests cover a file, ask the person\. Never guess/); +}); + +test("Init and Init-update keep a test map beside the single-test command", () => { + const init = src("plan2code-init.md"); + assert.match(init, /run single test \(and beside it a short \*\*Test map\*\*: `area -> tests or command`/); + assert.match(init, /which checks are quick/); + const upd = src("plan2code-init-update.md"); + assert.match(upd, /\*\*4\. Testing\*\* - .*the test map and quick checks/); + assert.match(upd, /\| Testing \| Commands\? Test map and quick checks stale\?/); +}); diff --git a/src/plan2code-0-pathfinder-references/brief.md b/src/plan2code-0-pathfinder-references/brief.md index bca23d8..bd6ccf4 100644 --- a/src/plan2code-0-pathfinder-references/brief.md +++ b/src/plan2code-0-pathfinder-references/brief.md @@ -54,7 +54,7 @@ Substitute real content; keep the section order. `` reads naturally pe ## Open - ready to decide next - **Delivery channel** - can now be decided; the row-count ceiling it was waiting on landed today. -- **Testing posture** - needs Product and Engineering together. +- **Retention window** - needs Product and Engineering together. ## Open - waiting on something first diff --git a/src/plan2code-0-pathfinder-references/chart.md b/src/plan2code-0-pathfinder-references/chart.md index 9075148..04439c9 100644 --- a/src/plan2code-0-pathfinder-references/chart.md +++ b/src/plan2code-0-pathfinder-references/chart.md @@ -90,7 +90,7 @@ Deliver it as a multi-select (`multi` on the web console) of 3–5 features a re > "What made this come up now? A deadline, an incident, an audit, a customer?" -*Fishing for:* constraints that will shape half the questions and that nobody volunteers unprompted. A regulatory deadline changes the delivery question, the testing posture question, and the out-of-scope line all at once. +*Fishing for:* constraints that will shape half the questions and that nobody volunteers unprompted. A regulatory deadline changes the delivery question and the out-of-scope line all at once. **The probe names above are internal labels, not headings the human reads.** Head each Q block plainly — *What you end up with*, *Who uses it*, *Leave for later*, *Smallest version that counts*, *How you know it's done*, *Why now* — and keep the probe text itself as plain as the quotes above. "The sacrificial boundary" and "the arrival signal" mean something to this playbook and nothing to the person answering. Full rule in the grilling playbook, *Say it in plain English*. @@ -275,7 +275,7 @@ Say it out loud so the human tracks the move, then jump: Two mechanics keep the fan-out honest: -1. **Round-robin the areas.** Before you start, list the axes you intend to cross — engineering axes (data, surface, permissions, volume, delivery, failure, operations, testing) AND product axes (user value, success measurement, target user, rollout, analytics, support & docs, legal/compliance). Not every axis applies to every destination: name the ones that do before the first probe, say which you are skipping and why, then take one probe per axis before any second probe on any axis. +1. **Round-robin the areas.** Before you start, list the axes you intend to cross — engineering axes (data, surface, permissions, volume, delivery, failure, operations) AND product axes (user value, success measurement, target user, rollout, analytics, support & docs, legal/compliance). Not every axis applies to every destination: name the ones that do before the first probe, say which you are skipping and why, then take one probe per axis before any second probe on any axis. 2. **Ask for the axis you have not touched.** Near the end: "What have I not asked about that would embarrass us to discover in week three?" **Breadth-first is the ideal batch.** One probe per axis means the probes are independent by construction — that is what breadth-first *means* — so this grill should run as batches of three, not as a stream of singles. If you catch yourself wanting to batch two probes on the same axis, that is depth wearing a batch's clothes; pull back. @@ -294,7 +294,6 @@ Each opens a different axis. Batch three at a time in list order (skipping axes 4. **Volume and time** — "If an export takes four minutes, is that fine, bad, or a redesign?" 5. **Delivery and failure** — "The export succeeds but the download link expires before they click it. What should have happened?" 6. **Operations** — "Six months from now someone asks who exported what. Does this feature audit itself?" -7. **Testing** — "What would you need to see pass before you would let this near a customer's compliance data?" *(This one always runs — see the mandatory testing-posture question below.)* The product axes, same style — one sample probe each: @@ -382,7 +381,6 @@ A worked ordering for the audit-log export map: | `01` | Export format | `grill · HITL` | none | Nothing gates it; it gates the artifact shape | | `02` | Row-count ceiling | `research · AFK` | none | A fact about the data, independent of every preference | | `03` | Export authorization | `grill · HITL` | none | Independent axis; can be argued today | -| `04` | Testing posture | `grill · HITL` | none | Mandatory; independent of everything else | | `05` | Delivery channel | `grill · HITL` | `02` | Synchronous download versus queued link turns entirely on volume | | `06` | SIEM push connector | `grill · HITL` | none | Created, then immediately ruled out of scope during charting — `State: out-of-scope`, no `## Answer` | @@ -473,7 +471,6 @@ plan, not at shipped code. Continuous streaming to external systems is not on th - [x] [Export format](./questions/01-export-format.md) — CSV with a UTF-8 BOM and RFC 4180 quoting, plus a sidecar SHA-256 manifest; JSONL rejected because recipients open these in Excel. *(2026-08-03)* - [/] [Row-count ceiling](./questions/02-row-count-ceiling.md) - [ ] [Export authorization](./questions/03-export-authorization.md) -- [ ] [Testing posture](./questions/04-testing-posture.md) - [!] [Delivery channel](./questions/05-delivery-channel.md) — Blocked by 02 - [-] [SIEM push connector](./questions/06-siem-push-connector.md) — out of scope, see below @@ -631,61 +628,3 @@ Do this, in order: 4. **Stop.** Do not chart anyway "just in case", do not create questions, do not start planning in this session. Be honest about the trigger. If two areas are genuinely unformed, that is fog and the map earns its keep. The off-ramp is for the case where you fanned out across every axis and kept landing on solid ground. - ---- - -## Step 6: The mandatory testing-posture question - -**Every map includes a `grill · HITL` question on testing posture.** No exceptions, including maps where testing feels obvious. - -The reason is mechanical: `/plan2code-1-plan` Phase 1 asks for three things — testing types, whether tests run after each implementation phase, and a coverage target — and `/plan2code-2-document` **string-matches** that answer, either appending a testing block to every phase, creating a dedicated final testing phase, or omitting testing entirely. A map that clears without this answer hands the human a planning session that stalls on its first question. Ask it while there is still someone in the room. - -Record the answer in the literals downstream matches on, not in paraphrase. ("Phase" here names `/plan2code-1-plan`'s implementation phases and is a downstream contract string — it is never a pathfinder unit of work.) - -It is almost never blocked. Give it whatever number the dependency ordering leaves free, and expect it to sit on the frontier from day one. - -```markdown -> Pathfinder planning note - decisions, not implementation work. Archive with the spec; do not delete. - -# Testing posture - -Type: grill · HITL -State: open -Blocked by: none -Claimed: none -Resolved: none -Locked: no - -## Question - -What testing does this work carry, so `/plan2code-1-plan` Phase 1 can be answered without -stalling? Three parts, all needed: - -- **Types** — unit, integration, end-to-end, some combination, or none. -- **Phase testing** — record one of the two literals `/plan2code-2-document` matches: - `Run after each phase` (a testing block closes every implementation phase) or - `Dedicated phase only` (one final testing phase). -- **Coverage target** — record one of Phase 1's three literals: `Critical paths`, - `Moderate (~60-80%)`, or `Comprehensive (>80%)`. - -Recommended answer to react to: unit plus integration; `Run after each phase`; -`Critical paths`. Rationale — this touches compliance data, so the correctness of the -CSV writer and the authorization predicate must be pinned by tests, but the admin UI is thin -enough that end-to-end coverage would cost more than it catches. - -Two specific cases worth naming in the answer regardless of the general posture, because -Codebase context shows both are easy to get wrong here: - -- The UTF-8 BOM survives Excel round-tripping for non-ASCII actor names. -- The tenant-scope predicate actually excludes other tenants' events, asserted against seeded - cross-tenant data rather than a mock. - -Note for whoever resolves this: the coverage target is a number the human owns. Do not infer -it from the codebase's current coverage, and do not soften it to whatever the repo already -achieves. - -## Evidence - -- `AGENTS.md` records Vitest as the runner with fixtures colocated under `test/`. -- Codebase context: no end-to-end harness exists today; adding one is a real cost, not a flag. -``` \ No newline at end of file diff --git a/src/plan2code-0-pathfinder-references/grilling.md b/src/plan2code-0-pathfinder-references/grilling.md index 8afbe1d..0d08f1e 100644 --- a/src/plan2code-0-pathfinder-references/grilling.md +++ b/src/plan2code-0-pathfinder-references/grilling.md @@ -90,7 +90,7 @@ A probe may join the current batch only if **all three** hold: In doubt, hold it back. A held probe costs one extra round trip. A dependent probe sent early costs a wrong answer recorded as a decision, and you will not find out until the plan contradicts itself. -Independent probes are usually the ones that came from **different areas** — data, interface, security, operations, testing. Dependent probes are usually consecutive steps down one thread. +Independent probes are usually the ones that came from **different areas** — data, interface, security, operations. Dependent probes are usually consecutive steps down one thread. ### Delivering a batch: structured UI first @@ -314,25 +314,9 @@ Offer it, do not impose it: *"This one looks hard to reverse and the reasoning w **Where locks go at handoff:** the handoff playbook lifts every `Locked: yes` question into the PLAN-DRAFT's **Architecture** section, and their rejected alternatives and standing constraints into **Assumptions**. Unlocked answers still inform the draft, but locks are the ones that survive verbatim into planning. Grill them harder for that reason. -## The one grill every map must resolve, and the lens applied to all of them +## The lens applied to every grill -### 1. Testing posture — `grill · HITL` - -Chart Step 6 requires this question. It exists because `/plan2code-1-plan` Phase 1 asks for exactly three things and stalls without them: testing types, whether tests run after each phase, and the coverage target. A map that clears without answering them hands the human a plan session that immediately re-asks. - -The first three probes below pass the independence test against each other — none reads differently under another's answer — so **send all three as one structured-tool batch**. Every probe has named alternatives and fixed literals; `Other` remains available. - -| Probe | Recommend by default | -|---|---| -| Which types are in scope — unit, integration, E2E, or none? | Unit plus integration; E2E only where a real browser or real broker is the only honest test | -| Does the suite run after each implementation phase, or once at the end? | `Run after each phase` — work that cannot be verified when it lands cannot be signed off | -| Coverage target: critical paths, moderate (~60-80%), or comprehensive (>80%)? | Critical paths, named explicitly, rather than a percentage nobody defends | -| What is deliberately not tested, and why? | **Fourth probe, and it does not ride in the batch.** It has no option set — the explicit no-s have to be composed — and it reads differently once the types are settled. Fold it into the recap turn, where you are already waiting on them. | -| What is already there — runner, fixtures, CI wiring? | **Not a probe.** Look it up before you send the batch, and cite it in the probes above | - -Record the answer in the exact literals `/plan2code-2-document` string-matches: the types; `Run after each phase` or `Dedicated phase only`; and `Critical paths`, `Moderate (~60-80%)`, or `Comprehensive (>80%)`. Not prose — a paraphrase matches no branch downstream. - -### 2. Test seams and verifiability — a lens, not a question file +### Test seams and verifiability — a lens, not a question file For each major decision on the map, ask the same question: **how will anyone know it works?** A decision nobody can verify is a decision that silently rots. diff --git a/src/plan2code-0-pathfinder-references/handoff.md b/src/plan2code-0-pathfinder-references/handoff.md index 9133233..2e9dfb0 100644 --- a/src/plan2code-0-pathfinder-references/handoff.md +++ b/src/plan2code-0-pathfinder-references/handoff.md @@ -44,7 +44,7 @@ The 18-boundary is the honest line between *"needs designing"* and *"needs decid | Dimension | Scores | Raises it | Lowers it | |---|---|---|---| -| **Requirements Clarity** | Are the requirements unambiguous? | Every resolved `grill` answer states the decision AND what was rejected; the testing-posture answer names types, cadence, and coverage | Answers phrased as preferences ("probably NDJSON") instead of decisions; a requirement that only exists in the map gist and not in a question file | +| **Requirements Clarity** | Are the requirements unambiguous? | Every resolved `grill` answer states the decision AND what was rejected | Answers phrased as preferences ("probably NDJSON") instead of decisions; a requirement that only exists in the map gist and not in a question file | | **Technical Feasibility** | Do we know HOW to build each component? | Resolved `sketch` questions with a real artifact under `sketch-NN/`; `research` answers citing primary sources under `## Evidence`; `00-codebase-context.md` naming the actual files that change | A mechanism nobody has exercised in this codebase; a research answer whose `## Evidence` is empty or cites only a blog post | | **Integration Points** | Are all external dependencies identified? | Every system named in `## Destination` has a resolved question touching it; auth, quota, and failure behavior named per integration | An integration mentioned in an answer but never questioned; a config store that was read but never written to during a sketch | | **Risk Assessment** | Are blockers documented with mitigations? | Answers that record consequences; `Locked: yes` answers that say what breaks if reversed; ceilings with a stated behavior at the ceiling | A recorded limit with no decided behavior past it; a `Locked: yes` answer with no consequences section | @@ -55,7 +55,6 @@ A cap overrides your judgment. While a cap condition holds, the dimension **cann | Cap | Condition | |---|---| -| Requirements ≤ 17 | The testing-posture question is not `resolved`, or its answer omits any of types / cadence / coverage | | Feasibility ≤ 17 | Any `research` question is `resolved` with an empty `## Evidence` | | Integration ≤ 17 | A system named in `## Destination` has no resolved question touching it | | Risk ≤ 17 | Any `Locked: yes` answer records no consequences | @@ -72,13 +71,13 @@ A cap overrides your judgment. While a cap condition holds, the dimension **cann Destination: *"A spec a developer can implement: nightly export of tenant audit logs to customer-owned S3 buckets, with a signed manifest per run."* -Resolved questions: [Codebase context](./questions/00-codebase-context.md), [Export format](./questions/01-export-format.md), [Scheduling model](./questions/02-scheduling-model.md), [Destination auth](./questions/03-destination-auth.md), [Retention and replay](./questions/04-retention-and-replay.md), [Testing posture](./questions/05-testing-posture.md), [Throughput ceiling](./questions/06-throughput-ceiling.md). Ruled out: [Failure notification](./questions/07-failure-notification.md). +Resolved questions: [Codebase context](./questions/00-codebase-context.md), [Export format](./questions/01-export-format.md), [Scheduling model](./questions/02-scheduling-model.md), [Destination auth](./questions/03-destination-auth.md), [Retention and replay](./questions/04-retention-and-replay.md), [Throughput ceiling](./questions/06-throughput-ceiling.md). Ruled out: [Failure notification](./questions/07-failure-notification.md). **First scoring pass:** | Dimension | Score | Justification against evidence | |---|---|---| -| Requirements Clarity | 22/25 | Four `grill` answers state decisions and rejections (NDJSON chosen, CSV rejected for nested actor payloads). Testing posture settled: integration + unit, run after each phase, moderate coverage. Minus 3: the manifest's exact field list is unspecified — a Phase 5 spec detail, not an open decision. | +| Requirements Clarity | 22/25 | Four `grill` answers state decisions and rejections (NDJSON chosen, CSV rejected for nested actor payloads). Minus 3: the manifest's exact field list is unspecified — a Phase 5 spec detail, not an open decision. | | Technical Feasibility | 21/25 | `sketch-02` uploaded a 400 MB multipart object to a real bucket end to end. `00-codebase-context.md` names `AuditExportJob` and the existing Hangfire registration as the extension points. Minus 4: no component in this codebase has ever assumed a cross-account IAM role; the pattern is documented in AWS docs cited under `## Evidence` but unexercised here. | | Integration Points | 23/25 | Three integrations, each with a resolved question: S3 (Destination auth), Hangfire (Scheduling model), tenant config store (Codebase context). Auth and quota named per integration. Minus 2: the tenant config store's write path was read but never exercised by a sketch. | | Risk Assessment | **16/25** | Consequences recorded on Export format and Destination auth. But Throughput ceiling establishes 200 MB per tenant per day at p95 and **records no decided behavior above it** — truncate, spill to the next run, or fail the run is still undecided. | @@ -129,7 +128,7 @@ Everything in the draft traces to something on the map. Nothing is invented at h | Resolved `grill` answers describing behavior | Section 2.1 Functional Requirements, one `FR-N` per decided behavior | | Resolved `grill` answers describing performance, security, scale, operability | Section 2.2 Non-Functional Requirements, one `NFR-N` each | | `## Out of scope` | Section 2.3 Out of Scope — copied line for line, wording and order intact. The ONLY permitted change is the link prefix: `./questions/` becomes `./pathfinder/questions/`, because the draft sits one level above the map. Do not re-word, re-order, or summarize; a re-worded scope boundary is a re-litigated one. | -| The testing-posture question's answer | Section 2.4 Testing Strategy table (Types / Phase Testing / Coverage) | +| Testing | Section 2.4 Testing Strategy: the single row `Status` = `Deferred to Plan` (the 2.4 table below shows it), which Plan Phase 1 replaces. A map from an older version that holds a resolved testing answer has it copied into the 2.4 table as before | | Resolved `research` answers and their `## Evidence` | Section 3 Tech Stack — the cited source becomes the Justification cell | | `questions/00-codebase-context.md` | The `## System Context` section, and the components table in 4.3 | | Answers with `Locked: yes` | Section 4 Architecture (4.1 Pattern rationale, 4.4 Data Model, 4.5 API Design) **and** Section 9 Assumptions — a locked decision is an assumption downstream work is allowed to rely on | @@ -198,9 +197,7 @@ next run rather than truncating. | Aspect | Decision | |---|---| -| Types | Unit + Integration | -| Phase Testing | Run after each phase | -| Coverage | Moderate (~60-80%) | +| Status | Deferred to Plan | ## System Context @@ -317,7 +314,6 @@ question for what was rejected, why, and what it costs. | [Scheduling model](./pathfinder/questions/02-scheduling-model.md) | Reuse the existing Hangfire recurring job; a dedicated export service was rejected | | [Destination auth](./pathfinder/questions/03-destination-auth.md) | Customer-owned bucket via assumed role plus external ID; no platform-held customer credentials | | [Retention and replay](./pathfinder/questions/04-retention-and-replay.md) | 7-day replay window, sequence numbers reused on replay | -| [Testing posture](./pathfinder/questions/05-testing-posture.md) | Unit + integration, run after each phase, moderate coverage | | [Throughput ceiling](./pathfinder/questions/06-throughput-ceiling.md) | 200 MB per tenant per day at p95; multipart upload proven in `pathfinder/sketch-02/` | | [Overflow behavior](./pathfinder/questions/08-overflow-behavior.md) | Spill oldest-first into the next run; alarm after three consecutive spills | @@ -352,7 +348,7 @@ These two named, unnumbered sections are what make "Resume at Phase 4" legitimat | Draft section | Satisfies | Because pathfinder already | |---|---|---| -| Sections 1 and 2 (including 2.4 Testing Strategy) | 1-plan **Phase 1: Requirements Analysis** | Grilled every functional and non-functional decision, and always charted a testing-posture question — that question exists specifically so Phase 1's testing prompt is already answered | +| Sections 1 and 2 (including 2.4 Testing Strategy) | 1-plan **Phase 1: Requirements Analysis** | Grilled every functional and non-functional decision, and left testing to Plan Phase 1, which still owns 2.4's testing answer | | `## System Context` | 1-plan **Phase 2: System Context Examination** | Wrote `questions/00-codebase-context.md` at Chart Step 3: directory structure, key components verified against actual code, patterns and conventions, integration points, technical debt, boundaries — Phase 2's own checklist, item for item | | `## Scope Assessment` | 1-plan **Phase 3: Scope Assessment** | Produced the counts Phase 3 measures — requirements, components, integrations — as a byproduct of charting. Map the totals onto Phase 3's Small / Medium / Large table and state the verdict | diff --git a/src/plan2code-0-pathfinder-references/trail.md b/src/plan2code-0-pathfinder-references/trail.md index 3b978f6..84b988e 100644 --- a/src/plan2code-0-pathfinder-references/trail.md +++ b/src/plan2code-0-pathfinder-references/trail.md @@ -36,7 +36,7 @@ One idea per session, so there is only ever one trail. START ●━●━◉··○··○··⊘··⊝ ····⚑ ● done · ◉ here · ○ open · ⊘ blocked · ⊝ out of scope · ⚑ destination · ~4 fog 1 Codebase context ✔ · 2 Export format ✔ · 3 Row-count ceiling ◀ here · 4 Export authorization - 5 Testing posture · 6 Delivery channel (blocked:3) · 7 SIEM push (out of scope) + 5 Retention window · 6 Delivery channel (blocked:3) · 7 SIEM push (out of scope) Confidence: solid, but Risk is borderline. WAITING ON YOU · answer here, in this conversation: diff --git a/src/plan2code-0-pathfinder-scripts/pathfinder.mjs b/src/plan2code-0-pathfinder-scripts/pathfinder.mjs index 721d532..593cde0 100644 --- a/src/plan2code-0-pathfinder-scripts/pathfinder.mjs +++ b/src/plan2code-0-pathfinder-scripts/pathfinder.mjs @@ -963,19 +963,6 @@ async function cmdTrail(loc, args) { /* ---------------------------------------------------------------- gate */ -// The testing-posture answer must name types, cadence and coverage. Matched as -// keywords, case-insensitive ("run after each phase, moderate coverage" counts), -// and never inside the answer's Rejected block, where a losing option is named. -const TYPES_RE = /\b(unit|integration|end-to-end|e2e|none)\b/i; -const CADENCE_RE = /after each phase|dedicated (testing )?phase/i; -const COVERAGE_RE = /critical paths?|moderate|comprehensive/i; -const CADENCE = ["Run after each phase", "Dedicated phase only"]; -const COVERAGE = ["Critical paths", "Moderate (~60-80%)", "Comprehensive (>80%)"]; - -function withoutRejected(body) { - return body.replace(/^\s*\*\*Rejected\b[\s\S]*?(?=^\s*\*\*(?!Rejected)[A-Z]|^#{1,6}\s|(?![\s\S]))/m, ""); -} - async function cmdGate(loc) { const map = parseMap(requireMap(loc)); const questions = loadQuestions(loc); @@ -995,16 +982,6 @@ async function cmdGate(loc) { // Hard caps: while one holds, that dimension cannot exceed 17. const caps = []; - const testing = questions.find((q) => /testing posture/i.test(q.name)); - if (!testing || testing.state !== "resolved") caps.push({ dimension: "Requirements", why: testing ? `${testing.name} is not resolved` : "no testing-posture question exists" }); - else { - const a = withoutRejected(testing.answerBody); - const missing = []; - if (!TYPES_RE.test(a)) missing.push("types"); - if (!CADENCE_RE.test(a)) missing.push(`cadence (${CADENCE.join(" / ")})`); - if (!COVERAGE_RE.test(a)) missing.push(`coverage (${COVERAGE.join(" / ")})`); - if (missing.length) caps.push({ dimension: "Requirements", why: `the testing-posture answer omits ${missing.join(", ")}` }); - } for (const q of questions.filter((x) => x.kind === "research" && x.state === "resolved" && !x.hasEvidence)) caps.push({ dimension: "Feasibility", why: `research ${q.nn} ${q.name} is resolved with an empty ## Evidence` }); for (const q of questions.filter((x) => x.locked && x.state === "resolved" && !x.hasConsequences)) caps.push({ dimension: "Risk", why: `Locked: yes ${q.nn} ${q.name} records no consequences` }); add("hard-caps", caps.length === 0, caps.length ? caps.map((c) => `${c.dimension} <= 17: ${c.why}`).join("; ") : null); diff --git a/src/plan2code-0-pathfinder.md b/src/plan2code-0-pathfinder.md index dcf071a..49ff1d6 100644 --- a/src/plan2code-0-pathfinder.md +++ b/src/plan2code-0-pathfinder.md @@ -86,7 +86,7 @@ Read references/chart.md 3. `[Chart - Step 3: Recon]` Explore the codebase; record codebase context, resolved on the spot, `legwork · AFK`. On `github` hold it until Step 6 so a Step 4 off-ramp leaves no litter. Unfamiliar code? `/plan2code-xray` explains an area first. 4. `[Chart - Step 4: Map the frontier]` Grill again **breadth-first**: fan out, never deep on one thread. Surface the open decisions and what is takeable now. 5. `[Chart - Step 5: Create the map]` `**Status:** Charting`, Destination, Ground rules (backend first), an empty index, the fog in `## Not yet specified`. Say once where it lives and who sees it. -6. `[Chart - Step 6: Write the questions]` One per decision you can phrase sharply NOW, dependency order, `Blocked by:` filled the same pass — on `github`, create all first, wire edges second. The rest stays fog. Include a `grill · HITL` testing-posture question; `/plan2code-1-plan` Phase 1 needs it. +6. `[Chart - Step 6: Write the questions]` One per decision you can phrase sharply NOW, dependency order, `Blocked by:` filled the same pass — on `github`, create all first, wire edges second. The rest stays fog. Testing is not charted here: `/plan2code-1-plan` Phase 1 asks it. 7. `[Chart - Step 7: Index]` `local`: `reconcile` fills `## Question Checklist` from the files (every missing row, with its marker). Either backend: set `**Status:** Working`. `local`: then `lint`. 8. `[Chart - Step 8: Fire research]` One subagent per `research` question, in parallel. Each writes only its `## Evidence`, never decides. **Wait for all** (they die with the terminal), then Session End. @@ -140,8 +140,6 @@ Close EVERY response with the trail once the map exists; the turn picks the form Report each question resolved (name + gist), what graduated, what's still open; offer a brief for today. Nothing to commit (`local` is gitignored). Then the mascot, then the Trail Footer. -**Web console:** at session end or on a `__stop`, post `finish` (Form A's command) BEFORE `stop` (notes/pathfinder.md). - ``` ⋅ ╭───╮ diff --git a/src/plan2code-1-plan.md b/src/plan2code-1-plan.md index 60fdd55..6b15c9b 100644 --- a/src/plan2code-1-plan.md +++ b/src/plan2code-1-plan.md @@ -61,8 +61,9 @@ Before Phase 1, run `node "/specs.mjs" list` from the project root (``: `s - Status "Phase 3 Complete - Resume at Phase 4": Resume at Phase 4 - Status "Escalated from Quick Task - Resume at Phase 2": Acknowledge, verify requirements, skip to Phase 2 - Status "Draft" or "Complete": Ask user how to proceed +- Before going on with any existing draft (a Pathfinder handoff, a Quick Task escalation, a Draft or Complete one), read its 2.4: `| Status | Deferred to Plan |`, empty or `Not discussed` means ask the Phase 1 testing question now and write the answer into 2.4; a cadence with no `Full Suite` row means ask only the full-suite part. - A spec folder holding a `DIAGNOSIS-*.md` (Diagnose's write-up of a bug): read it first, as the Phase 1 brief (the bug, its cause, the suggested fix); that folder's name is the feature name (do not ask for one), so the PLAN-DRAFT lands beside the diagnosis -- No PLAN-DRAFT: Begin at Phase 1. Console: its idea card carries `"templates": "idea"` (console.md → The kinds) +- No PLAN-DRAFT: Begin at Phase 1. Console: its idea card carries `"templates": "idea"` (console.md → A patch) `node "/specs.mjs" check-draft specs/` checks a written PLAN-DRAFT (Phase 7). @@ -111,13 +112,14 @@ After confirmation, proceed with analysis: 6. **Testing Preferences (Optional):** > "Include testing? > 1. **Types**: Unit, Integration, E2E, or None - > 2. **Phase testing**: Run after each phase? - > 3. **Coverage**: Critical paths / Moderate (~60-80%) / Comprehensive (>80%) - > 4. **Approach**: Code first (default) or Test first (each task's test is written and seen failing before its code) + > 2. **Phase testing**: Targeted per phase (default: each phase runs the tests covering what it changes) / Dedicated phase only / None + > 3. **Full suite**: Offered at Finalize (default) / At Phase N / Never + > 4. **Coverage**: Critical paths / Moderate (~60-80%) / Comprehensive (>80%) + > 5. **Approach**: Code first (default) or Test first (each task's test is written and seen failing before its code) > > Say 'skip testing' to omit." - Default: No testing. + Default if skipped: Phase Testing `None`, Full Suite `Never`. 7. Report confidence score 8. **Requirements Sign-Off:** @@ -129,7 +131,7 @@ After confirmation, proceed with analysis: > **Non-Functional:** > NFR-1: [req] > ... - > **Testing:** [approach or None] + > **Testing:** [types, phase testing, full suite, approach, or None] > > **Confirm:** Complete and accurate? (approved / needs changes) @@ -173,7 +175,7 @@ State assessment and ask user to confirm. 3. Create `specs//PLAN-DRAFT-.md` with Phases 1-3 4. Set status: `Phase 3 Complete - Resume at Phase 4` 5. Include: Executive Summary, Requirements, System Context, Scope, Confidence -6. Instruct: "Large project. Progress saved. Start NEW conversation with `/plan2code-1-plan --web` to resume at Phase 4." On the web console, post `finish` with that command first, then `stop`. +6. Instruct: "Large project. Progress saved. Start NEW conversation with `/plan2code-1-plan --web` to resume at Phase 4." On the web console, the finish carries that command. 7. STOP ### PHASE 4: Tech Stack @@ -258,7 +260,7 @@ Header: Title, Created date, Status (Draft | Phase 3 Complete - Resume at Phase Sections: 1. **Executive Summary** — 2-3 sentences -2. **Requirements** — 2.1 Functional (FR-N checklist), 2.2 Non-Functional (NFR-N checklist), 2.3 Out of Scope, 2.4 Testing Strategy table (Types, Phase Testing, Coverage, plus a `| Approach | Test first |` row only when picked; absent means code first) +2. **Requirements** — 2.1 Functional (FR-N checklist), 2.2 Non-Functional (NFR-N checklist), 2.3 Out of Scope, 2.4 Testing Strategy table (Types, Phase Testing, Full Suite, Coverage, plus a `| Approach | Test first |` row only when picked; absent means code first). Phase Testing is `Targeted per phase`, `Dedicated phase only` or `None` (an old `Run after each phase` reads as `Targeted per phase`; 'skip testing' writes `None` and `Never`); Full Suite is `Offered at Finalize`, `At Phase N` or `Never` 3. **Tech Stack** — table: Category / Technology / Version / Justification 4. **Architecture** — 4.1 Pattern (name + rationale), 4.2 System Context Diagram, 4.3 Components table, 4.4 Data Model, 4.5 API Design 5. **Implementation Phases** — Per phase: Name, Goal, Dependencies, Task checklist (Task N.N) @@ -284,7 +286,6 @@ When complete (PLAN-DRAFT created), tell user: 2. **Next: `/plan2code-2-document`** (NOT implementation) 3. Documentation auto-discovers planning files -**On the web console:** at every session end, and on a `__stop`, post `finish` BEFORE `stop`, per notes/plan.md. **Closing example:** > "Planning complete. Created in `specs//`: diff --git a/src/plan2code-1b-revise-plan.md b/src/plan2code-1b-revise-plan.md index e59161f..7a3ae94 100644 --- a/src/plan2code-1b-revise-plan.md +++ b/src/plan2code-1b-revise-plan.md @@ -250,4 +250,4 @@ Work summary — tell user: change type, tasks added/modified/removed, phases re Returning context: Revised specs in `specs//`. Run `/plan2code-3-implement --web` in a new conversation to continue implementation. -**On the web console:** a `__stop` action in a send is the person ending the session: see console-stop.md. Specs change only at Step 3, so a stop before then saves nothing and needs none. At every session end post `finish` BEFORE `stop`: `"command": "/plan2code-3-implement specs//overview.md"` when revised, or the revise-plan command on an abort. The closing box above is printed to a terminal the browser user is not watching. +**On the web console:** specs change only at Step 3, so stopping before then saves nothing. The finish command is `/plan2code-3-implement specs//overview.md` when revised, or the revise-plan command on an abort. The closing box above is printed to a terminal the browser user is not watching. diff --git a/src/plan2code-2-document.md b/src/plan2code-2-document.md index 8d8efd0..563caa5 100644 --- a/src/plan2code-2-document.md +++ b/src/plan2code-2-document.md @@ -8,7 +8,7 @@ Technical writer transforming planning documents into precise, complete implemen ## Interface -The FIRST thing you do, before anything else — before Auto-Discovery: ask **web console** (suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow document` before reading (: references/web-console/ beside this SKILL.md, or the dir in ~/.plan2code/console/console-dir; `--spec` once known), then read /console.md and /notes/document.md. Switchable anytime. `--web` or `Use the web console for this session.` in the argument answers it; drop the flag. Dashboard-launched? Resume its open session (console-launches.md), then Auto-Discovery. `__stop` ends it; post `finish` BEFORE `stop` at every end. +The FIRST thing you do, before anything else — before Auto-Discovery: ask **web console** (suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow document` before reading (: references/web-console/ beside this SKILL.md, or the dir in ~/.plan2code/console/console-dir; `--spec` once known), then read /console.md and /notes/document.md. Switchable anytime. `--web` or `Use the web console for this session.` in the argument answers it; drop the flag. Dashboard-launched? Resume its open session (console-launches.md), then Auto-Discovery. ## Scripts @@ -161,7 +161,9 @@ Use kebab-case for feature name (e.g., `user-authentication`). ### Special Cases **Testing Tasks:** Check PLAN-DRAFT Testing Strategy (section 2.4): -- "Run after each phase": Add testing task block at end of EVERY phase +- Read `references/test-runs.md` before writing the testing blocks. When you cannot tell which tests cover a file, or whether a check is fast, ask the person. +- "Targeted per phase" (or the old "Run after each phase"): end EVERY phase with a `## Phase Testing` block: ``- [ ] Targeted: `` (covers )`` naming the tests that cover that phase's files (from `AGENTS.md`'s test map, else from the code), and ``- [ ] Quick checks: `` `` only for checks known to be fast. +- Full Suite: add ``- [ ] Full suite: `` `` only to the phase named by "At Phase N"; none for "Offered at Finalize" or "Never" (under "Dedicated phase only", the testing phase carries it when it is Phase N). A draft with no Full Suite row: ask which they want before writing phase files. - "Dedicated phase only": Create final Phase N: Testing - "None" or empty: Omit testing tasks - `| Approach | Test first |` in 2.4: in every phase, order each task's test before its code and put a plain sub-bullet ` - Test: ` directly under the task line (no checkbox, so the loop's task count is unchanged), for example `` - Test: through `POST /votes` `` @@ -182,7 +184,7 @@ Sections, in this order: Summary (from Executive Summary), Phase Checklist, Para Header: Phase name, Status on its own line as `**Status:** ` (Not Started | In Progress | Complete; `specs.mjs mark` updates it), Estimated Tasks count. -Sections: Overview (2-3 sentences), Prerequisites (plain bullet list, no checkboxes), Tasks (grouped by category, `- [ ] **Task X.N:** [Description]` with File path and details, plus a ` - Test:` sub-bullet under each task when the approach is Test first), Phase Testing (if enabled), Acceptance Criteria (plain bullet list, no checkboxes), Notes, Phase Completion Summary (filled after implementation: date, implementer, what was done, files changed, issues). +Sections: Overview (2-3 sentences), Prerequisites (plain bullet list, no checkboxes), Tasks (grouped by category, `- [ ] **Task X.N:** [Description]` with File path and details, plus a ` - Test:` sub-bullet under each task when the approach is Test first), Phase Testing (if enabled: the Targeted, Quick checks and Full suite lines above), Acceptance Criteria (plain bullet list, no checkboxes), Notes, Phase Completion Summary (filled after implementation: date, implementer, what was done, files changed, issues). ## Session End diff --git a/src/plan2code-3-implement-review.md b/src/plan2code-3-implement-review.md index 812c026..355bee7 100644 --- a/src/plan2code-3-implement-review.md +++ b/src/plan2code-3-implement-review.md @@ -8,7 +8,7 @@ Orchestrate one implementation phase and its focused independent review as a sin ## Web Console -The FIRST thing you do, before anything else in this file: Implementation Mode's Interface question — **web console** or **terminal**? On the web console, run `node "/console.mjs" open --workflow implement-review` before reading (: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-3-implement-review/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read /console.md, /building.md and /notes/implement.md in one batch (all of it; its Implement + Review section covers Stages 2–5), and /building-review.md when Stage 2 starts: the Stage 2 findings go out as the page's fix list, Stage 4 is the only sign-off item, and the Stage 5 `finish` never carries the review offer. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console-launches.md), then the spec. +The FIRST thing you do, before anything else in this file: Implementation Mode's Interface question — **web console** or **terminal**? On the web console, run `node "/console.mjs" open --workflow implement-review` before reading (: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-3-implement-review/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read /console.md, /building.md and /notes/implement.md in one batch (all of it; its Implement + Review section covers Stages 2–5), and /building-review.md when Stage 2 starts: the Stage 2 findings go out as the page's fix list, Stage 4 is the only sign-off item, and the Stage 5 `finish` never carries the review offer. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. `--loop` (only inside the desktop app): read /notes/loop.md after console.md; it replaces the sign-off, marking and git steps, and Stages 2 to 4 run as its review section says. Launched by the dashboard? Its session is already open — resume it (console-launches.md), then the spec. ## Controlling Contract @@ -19,7 +19,7 @@ This file controls the two referenced workflows. Follow each referenced workflow - Never treat implementation completion, review completion, or a fix selection as phase approval. - Never ask for implementation sign-off before review. - Never invoke another installed skill; load the packaged references below. -- Preserve Implementation Mode's rule that tests run only when explicitly listed as a phase task. +- Preserve Implementation Mode's tests rule: after each task the tests covering what it touched; at phase end the phase file's `## Phase Testing` lines plus tests for any other file the phase changed; never the full suite unless the phase file lists a `Full suite:` line. Read `references/test-runs.md` before the first test run of a phase. - Track an exact phase change set: files created or modified while implementing this phase, plus implementation artifacts named by its tasks. Do not include unrelated working-tree changes. - Abort, blockers, and spec conflicts stop or pause the combined workflow exactly as Implementation Mode requires. Do not begin review when implementation cannot reach its self-review gate. diff --git a/src/plan2code-3-implement.md b/src/plan2code-3-implement.md index 859cec0..c7fb128 100644 --- a/src/plan2code-3-implement.md +++ b/src/plan2code-3-implement.md @@ -8,7 +8,7 @@ Senior software engineer building exactly what the spec says, keeping progress c ## Interface -The FIRST thing you do, before anything else in this file — before reading a spec, before Phase 1: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow implement` before reading (: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-3-implement/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read /console.md, /building.md and /notes/implement.md in one batch; progress, every question and the sign-off go through it. Switchable anytime. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console-launches.md), then the spec. +The FIRST thing you do, before anything else in this file — before reading a spec, before Phase 1: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow implement` before reading (: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-3-implement/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read /console.md, /building.md and /notes/implement.md in one batch; progress, every question and the sign-off go through it. Switchable anytime. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. `--loop` (only inside the desktop app): read /notes/loop.md after console.md; it replaces the sign-off, marking and git steps below. Launched by the dashboard? Its session is already open — resume it (console-launches.md), then the spec. ## Scripts @@ -23,7 +23,8 @@ The FIRST thing you do, before anything else in this file — before reading a s - Follow `./AGENTS.md` if it exists - Implement specs EXACTLY - no creative additions - ONE phase per conversation (default) -- Run tests ONLY if a phase task or a task's `Test:` line lists them +- Tests: after each task run the tests covering what it touched; at phase end run the phase file's `## Phase Testing` lines plus tests for any other file the phase changed; never the full suite unless the phase file lists a `Full suite:` line +- Read `references/test-runs.md` before the first test run of a phase - Do NOT run git commands - provide commit instructions for user - Flag blockers clearly - never skip silently - Read `references/building-habits.md` when a bug or unexpected failing test turns up, before any task in a Test first phase (its tasks carry `Test:` lines), and before any task that changes no behavior; follow it. @@ -142,11 +143,12 @@ After all tasks: > 1. Fix now > 2. Document and proceed > 3. Investigate first" -3. Use Completion Report Format -4. Do NOT mark phase `[x]` until user says "approved" -5. Address issues before re-requesting sign-off -6. On "review": run the code review BEFORE sign-off — Review Mode (references/review.md in the installed skill, src/plan2code-review.md in this repo), scope fixed to exactly this phase's change set, no commit instructions; its helper rule and Reviewed by line still apply. Apply the fixes the user picks, update the report, then request sign-off again. The phase stays `[/]` throughout. -7. **Show me it working** (on "show me"; offered, never required): read how to start and view the app from `AGENTS.md` (Commands). Missing: work it out from the project (`package.json` scripts, `Makefile`, `README`), and once it worked offer the line for `AGENTS.md`; cannot work it out: ask the person. Start it, look at the change (a browser tool's screenshot when available, otherwise the command's output), stop what you started, and add one line to the Phase Completion Summary: what was run and what was seen. Screenshots go on the web console page only, never under `specs/`. Then request sign-off again. +3. If the phase changed shared ground the plan did not foresee (a test helper, build or test config, a widely imported module), say what was touched and why it is wide, and offer the full suite or a wider set as a choice beside approval. Unsure whether it is shared ground? Ask. +4. Use Completion Report Format +5. Do NOT mark phase `[x]` until user says "approved" +6. Address issues before re-requesting sign-off +7. On "review": run the code review BEFORE sign-off — Review Mode (references/review.md in the installed skill, src/plan2code-review.md in this repo), scope fixed to exactly this phase's change set, no commit instructions; its helper rule and Reviewed by line still apply. Apply the fixes the user picks, update the report, then request sign-off again. The phase stays `[/]` throughout. +8. **Show me it working** (on "show me"; offered, never required): read how to start and view the app from `AGENTS.md` (Commands). Missing: work it out from the project (`package.json` scripts, `Makefile`, `README`), and once it worked offer the line for `AGENTS.md`; cannot work it out: ask the person. Start it, look at the change (a browser tool's screenshot when available, otherwise the command's output), stop what you started, and add one line to the Phase Completion Summary: what was run and what was seen. Screenshots go on the web console page only, never under `specs/`. Then request sign-off again. ## Issue Handling @@ -171,7 +173,7 @@ Before sign-off, verify: - [ ] No unaddressed TODO/FIXME in new code - [ ] Code compiles without syntax errors - [ ] Implementation matches spec exactly -- [ ] Tests run and results documented (if testing tasks present) +- [ ] Tests run per the rule above; which ran or were skipped documented - [ ] Blocked tasks documented - [ ] "Phase Completion Summary" filled - [ ] READY FOR SIGN-OFF (do NOT update overview.md yet) @@ -209,7 +211,7 @@ On user "approved": 6. **If more phases:** "NEXT STEP: Start NEW conversation and run: `/plan2code-3-implement specs//overview.md --web`" 7. **If final phase:** "NEXT STEP: Start NEW conversation and run: `/plan2code-4-finalize --web`" 8. Mention `/plan2code-1b-revise-plan --web` option -9. **On the web console:** post `finish` with the next step — never a review offer; it was on the sign-off card — then wait and `stop` per notes/implement.md. +9. **On the web console:** the finish carries the next step, never a review offer (it was on the sign-off card). Planny (continuing): ``` @@ -238,7 +240,7 @@ If user says "abort", "cancel", or similar: - Note created/modified files - Do NOT change phase checkbox (stays `[/]`) - Explain: "Run `/plan2code-3-implement --web` again to resume." -3. Stop implementation. On the web console, post `finish` with that command, then `stop`. +3. Stop implementation. On the web console, the finish carries that command. ## Recovery diff --git a/src/plan2code-4-finalize.md b/src/plan2code-4-finalize.md index d768c77..ff517c5 100644 --- a/src/plan2code-4-finalize.md +++ b/src/plan2code-4-finalize.md @@ -112,13 +112,15 @@ INCOMPLETE TASKS DETECTED - [ ] Required environment variables documented - [ ] No hardcoded secrets or credentials - [ ] Code follows existing codebase patterns - -### Test Validation (if defined) -| Test Type | Passed | Failed | Coverage | -|-----------|--------|--------|----------| -| Unit | X | X | X% | ``` +**Full suite:** read `references/test-runs.md`, then the PLAN-DRAFT's 2.4 `Full Suite` row. +- `Never`: skip the offer; record `not planned`. +- `At Phase N`: it ran in that phase; record that run's outcome without asking, and offer a rerun only if shared ground changed after it. +- Otherwise ask "Run the full suite now?" with a one-line reason (for example, which shared areas the build touched). Recommend yes; the person may skip. Never forced. +- A failing run gets the choice: 1 Fix now, 2 Document and proceed, 3 Investigate first. +- Record one outcome for Step 3: `passed`, `failed (N)`, `skipped (your choice)` or `not planned`. + #### Report: ```markdown @@ -165,6 +167,8 @@ INCOMPLETE TASKS DETECTED ### Known Limitations / Blocked Items [List or "None"] + +Full suite: [passed / failed (N) / skipped (your choice) / not planned] ``` Add this summary to `overview.md` under `## Completion Summary`. @@ -348,4 +352,4 @@ Suggested commit (only if README, CHANGELOG, or other tracked docs were updated) Returning context: Feature complete. Specs archived to `specs--completed//`. -**On the web console:** a `__stop` action in a send ends the session: see console-stop.md. At every session end post `finish` BEFORE `stop`, per notes/finalize.md — the completion summary is printed to a terminal the browser user is not watching. +**On the web console:** the completion summary is printed to a terminal the browser user is not watching. diff --git a/src/plan2code-changelog.md b/src/plan2code-changelog.md index 65e9754..4277cf8 100644 --- a/src/plan2code-changelog.md +++ b/src/plan2code-changelog.md @@ -8,7 +8,7 @@ Careful release scribe. Work out the right version from the default branch, find ## Interface -The FIRST thing you do, before anything else in this file, before reading the repository: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow changelog` before reading (: references/web-console/ beside this SKILL.md, ~/.agents/skills/plan2code-changelog/references/web-console/ globally, or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/changelog.md. Every question goes through it. Switchable anytime. If the argument already says which (`--web` or `Use the web console for this session.`) take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open: resume it (console-launches.md), then Step 1. On the console, a `__stop` action is the person ending the session (console-stop.md); at every session end post `finish` BEFORE `stop`. +The FIRST thing you do, before anything else in this file, before reading the repository: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow changelog` before reading (: references/web-console/ beside this SKILL.md, ~/.agents/skills/plan2code-changelog/references/web-console/ globally, or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/changelog.md. Every question goes through it. Switchable anytime. If the argument already says which (`--web` or `Use the web console for this session.`) take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open: resume it (console-launches.md), then Step 1. ## Scripts @@ -50,10 +50,10 @@ Optional: a note on what the work is, for example `/plan2code-changelog the expo 4. **Suggest entries.** Compare `entry` with the gap (`commits`, `files`, `uncommitted`). Anything the entry already says is covered. Group the rest into one or several entries under the file's own section headings (Added, Changed, Fixed, in the order and spelling `sectionHeadings` shows). Name the internal-only work you left out. Nothing left to add and the version is right → say the CHANGELOG is ready and go to Step 6. 5. **Edit and approve.** Show the suggested entries so each can be edited, removed or added to (notes/changelog.md has the cards). Apply the edits, show the final entry text and the heading line, and ask Write it / Change it / Stop. On yes, write `CHANGELOG.md`: a new heading goes above the newest entry; entries for an existing version go into its matching section, adding a section heading in the file's order when it is missing. 6. **package.json.** When `package.exists`, `package.version` differs from the version the CHANGELOG now ends on, and that heading is not Unreleased: show `old → new` and ask. On yes run `set-package-version`. When `package.lockfile`, remind the person to refresh it (`npm install`); do not run it. When it already matches, say so. -7. **Hand off.** Ask: Commit this now? (yes / no). Yes → hand off to Git right here: on the console run `open --resume --no-open --workflow git` (no `finish`, no `stop`), then read `~/.agents/skills/plan2code-git/SKILL.md` with your file-read tool (never a skill-invocation tool) and start with its commit flow, its Interface step already answered; in the terminal just read and follow it, starting with its commit flow. No → Session End. This skill never commits itself. +7. **Hand off.** Ask: Commit this now? (yes / no). Yes → hand off to Git right here: on the console run `open --resume --no-open --workflow git` (no finish), then read `~/.agents/skills/plan2code-git/SKILL.md` with your file-read tool (never a skill-invocation tool) and start with its commit flow, its Interface step already answered; in the terminal just read and follow it, starting with its commit flow. No → Session End. This skill never commits itself. ## Session End -Reached only when they declined to commit now (a yes hands the session to Git instead). Terminal: the version, the entries written and the `package.json` change. Web console: post `finish` (headline, a body with the version and entries, `"dashboard": true`, no `command`) BEFORE `stop`, then keep waiting for the dashboard press (console-finish.md). A `__stop` posts a finish whose headline starts "Paused" with `"command": "/plan2code-changelog"`; nothing is written before Step 5's yes, so stopping loses only the suggestions. +Reached only when they declined to commit now (a yes hands the session to Git instead). Terminal: the version, the entries written and the `package.json` change. Web console: the finish has a headline and a body with the version and entries, and no command. A stop's finish says Paused, with the command `/plan2code-changelog`; nothing is written before Step 5's yes, so stopping loses only the suggestions. Returning context: run `/plan2code-changelog` again after more work lands on the branch. diff --git a/src/plan2code-diagnose.md b/src/plan2code-diagnose.md index acc2810..e336537 100644 --- a/src/plan2code-diagnose.md +++ b/src/plan2code-diagnose.md @@ -8,7 +8,7 @@ Bug detective. Find a bug's cause and write it up, **without fixing it**: reprod ## Interface -The FIRST thing you do, before anything else in this file, before asking about the bug: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow diagnose` before reading (: references/web-console/ beside this SKILL.md (~/.agents/skills/plan2code-diagnose/references/web-console/ globally) or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/diagnose.md. The bug questions, the growing cause, the bug name and the hand-off all go through it. Switchable anytime. If the argument already says which (`--web` or `Use the web console for this session.`), take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open: resume it (console-launches.md), then Project Context. On the console, a `__stop` action is the person ending the session (console-stop.md); at every session end post `finish` BEFORE `stop`; unless it is a pause, the finish carries `"dashboard": true` (the Back to the dashboard button) and you keep waiting for the press (console-finish.md). +The FIRST thing you do, before anything else in this file, before asking about the bug: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow diagnose` before reading (: references/web-console/ beside this SKILL.md (~/.agents/skills/plan2code-diagnose/references/web-console/ globally) or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/diagnose.md. The bug questions, the growing cause, the bug name and the hand-off all go through it. Switchable anytime. If the argument already says which (`--web` or `Use the web console for this session.`), take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open: resume it (console-launches.md), then Project Context. ## Project Context (BLOCKING) diff --git a/src/plan2code-git.md b/src/plan2code-git.md index 526beab..df0d4c3 100644 --- a/src/plan2code-git.md +++ b/src/plan2code-git.md @@ -8,7 +8,7 @@ Careful git operator. Read where the repository stands, do what the person asks ## Interface -An instruction in the argument (`/plan2code-git switch to main`, `/plan2code-git commit and push`, a commit subject) runs in the terminal at once: do not ask about the console. With no argument, the FIRST thing you do, before anything else in this file, before reading the repository: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow git` before reading (: references/web-console/ beside this SKILL.md, ~/.agents/skills/plan2code-git/references/web-console/ globally, or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/git.md. Switchable anytime. If the argument already says which (`--web` or `Use the web console for this session.`) take it and do not ask; drop the flag. Launched by the dashboard, or by a **Commit it now** or Changelog hand-off? Its session is already open: resume it with `--workflow git` (console-launches.md). Handed off to commit (Commit it now, Changelog's yes): post `reread`, then run the Commit flow from step 1 over every changed file (risky ones left out and named), its cards on the board; afterwards the board is theirs with Push lit. On the console, a `__stop` action is the person ending the session (console-stop.md); at every session end post `finish` BEFORE `stop`. +An instruction in the argument (`/plan2code-git switch to main`, `/plan2code-git commit and push`, a commit subject) runs in the terminal at once: do not ask about the console. With no argument, the FIRST thing you do, before anything else in this file, before reading the repository: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow git` before reading (: references/web-console/ beside this SKILL.md, ~/.agents/skills/plan2code-git/references/web-console/ globally, or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/git.md. Switchable anytime. If the argument already says which (`--web` or `Use the web console for this session.`) take it and do not ask; drop the flag. Launched by the dashboard, or by a **Commit it now** or Changelog hand-off? Its session is already open: resume it with `--workflow git` (console-launches.md). Handed off to commit (Commit it now, Changelog's yes): post `reread`, then run the Commit flow from step 1 over every changed file (risky ones left out and named), its cards on the board; afterwards the board is theirs with Push lit. ## Project context @@ -55,7 +55,7 @@ Optional: a plain instruction (`switch to main`, `pull`, `commit and push`, `del ## The board -On the console the page draws the board itself from `state.git`; you never post it. Each click arrives through the wait loop as one `__git` action (`{ "i": "__git", "type": "git", "op": "switch", "branch": "main" }`, field shapes in notes/git.md), with `reply` the plain instruction the terminal would get. One action per turn: +On the console the page draws the board itself from `state.git`; you never post it. Each click arrives through the wait loop as one `__git` action (its `op` and fields in notes/git.md), with `reply` the plain instruction the terminal would get. One action per turn: 1. Post an `activity` line ("Pulling from origin…"); collecting the click already set the page to working. 2. Run `git.mjs plan ` with the action's fields as flags. @@ -112,7 +112,7 @@ In the terminal the same stops are asked in prose, with the diff printed. - **Done on the board, with something done this session:** post `finish` with a headline, a `body` listing the commits with hashes, pushes, and branches created or deleted, no `command`, and `"dashboard": true`. Then keep waiting for the dashboard press (console-finish.md). - **Done with nothing done:** resume as the dashboard at once (`open --resume --no-open --workflow dashboard`, then read the dashboard skill, post its menu and follow its "Coming back from another skill"), with no finish screen. -- **A `__stop`:** a finish whose headline starts "Paused", with `"command": "/plan2code-git"`, then `stop`. +- **A `__stop`:** a Paused finish with the command `/plan2code-git`. - **Terminal:** the last state line is enough. Returning context: run `/plan2code-git` again for the next action. diff --git a/src/plan2code-handoff.md b/src/plan2code-handoff.md index a93dde3..a434acb 100644 --- a/src/plan2code-handoff.md +++ b/src/plan2code-handoff.md @@ -9,7 +9,7 @@ and can open files, but they cannot see this conversation. Write for them. ## Interface -The FIRST thing you do, before anything else in this file — before inferring the next task: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow handoff` before reading (: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-handoff/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/handoff.md. The next-task confirmation and any clarifying questions go through it, and the finished handoff lands on the page as a doc with the download the page offers. Switchable anytime. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console-launches.md), then the one hard rule. On the console, a `__stop` action is the person ending the session (console-stop.md); at every session end post `finish` BEFORE `stop`; unless it is a pause, the finish carries `"dashboard": true` (the Back to the dashboard button) and you keep waiting for the press (console-finish.md). +The FIRST thing you do, before anything else in this file — before inferring the next task: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow handoff` before reading (: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-handoff/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/handoff.md. The next-task confirmation and any clarifying questions go through it, and the finished handoff lands on the page as a doc with the download the page offers. Switchable anytime. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console-launches.md), then the one hard rule. ## The one hard rule: capture the next task, and confirm it with the user diff --git a/src/plan2code-init-update.md b/src/plan2code-init-update.md index 1e6a713..6fb9af9 100644 --- a/src/plan2code-init-update.md +++ b/src/plan2code-init-update.md @@ -14,7 +14,7 @@ Interactive Q&A flow to update an existing `AGENTS.md` with new learnings and pr ## Interface -The FIRST thing you do, before anything else in this file — before the Awareness Context: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow init-update` before reading (: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-init-update/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/init.md. Every question in the Q&A flow and the restructure offer go through it. Switchable anytime. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console-launches.md), then Awareness Context. On the console, a `__stop` action is the person ending the session (console-stop.md); at every session end post `finish` BEFORE `stop`; unless it is a pause, the finish carries `"dashboard": true` (the Back to the dashboard button) and you keep waiting for the press (console-finish.md). +The FIRST thing you do, before anything else in this file — before the Awareness Context: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow init-update` before reading (: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-init-update/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/init.md. Every question in the Q&A flow and the restructure offer go through it. Switchable anytime. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console-launches.md), then Awareness Context. ## Scripts @@ -131,7 +131,7 @@ Present the user with update options: > - **1. Commands** - Build, test, run, lint, how to run and view the app, or other CLI commands > - **2. Architecture** - How components interact, data flow, key patterns > - **3. Gotchas/Pitfalls** - Traps to avoid, non-obvious behaviors -> - **4. Testing** - Test patterns, how to run specific tests, fixtures +> - **4. Testing** - Test patterns, how to run specific tests, the test map and quick checks, fixtures > - **5. Environment/Config** - Setup quirks, env variables, configuration > - **6. General Rules** - Coding conventions, style rules, project-specific practices > - **7. Failure Log** - Record a mistake or correction in the Failure log @@ -153,7 +153,7 @@ Present the user with update options: | Commands | Purpose? Flags? Prerequisites? How to run and view the app? | | Architecture | Components? Interactions? Pattern? | | Gotchas | What was unexpected? Workaround? | -| Testing | Commands? Fixtures? Mocking? | +| Testing | Commands? Test map and quick checks stale? Fixtures? Mocking? | | Environment | Local/CI/deploy? Env vars/files? | | Rules | Project-wide or specific? Why? | | Failure Log | What went wrong? Correct behavior (imperative, one line)? Merge into an entry on the same topic if one exists; over 17 entries, propose what to prune (rule 7). | diff --git a/src/plan2code-init.md b/src/plan2code-init.md index a063776..6858d2a 100644 --- a/src/plan2code-init.md +++ b/src/plan2code-init.md @@ -14,7 +14,7 @@ Analyze this codebase and create `AGENTS.md` to guide future AI coding agents (C ## Interface -The FIRST thing you do, before anything else in this file — before exploring the codebase: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow init` before reading (: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-init/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/init.md. Every confirmation — the restructure offer, the AI-agent file-sync prompt — goes through it, and the finished AGENTS.md lands on the page as a doc marked `saved` (the file is already on disk — no download offered). Switchable anytime. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console-launches.md), then Content. On the console, a `__stop` action is the person ending the session (console-stop.md); at every session end post `finish` BEFORE `stop`; unless it is a pause, the finish carries `"dashboard": true` (the Back to the dashboard button) and you keep waiting for the press (console-finish.md). +The FIRST thing you do, before anything else in this file — before exploring the codebase: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow init` before reading (: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-init/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/init.md. Every confirmation — the restructure offer, the AI-agent file-sync prompt — goes through it, and the finished AGENTS.md lands on the page as a doc marked `saved` (the file is already on disk — no download offered). Switchable anytime. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console-launches.md), then Content. ## Scripts @@ -26,7 +26,7 @@ The FIRST thing you do, before anything else in this file — before exploring t ## Content -1. **Commands**: Build, lint, test, run single test, other common development tasks, and how to start the app and where to view it (URL or command), when it has one +1. **Commands**: Build, lint, test, run single test (and beside it a short **Test map**: `area -> tests or command` lines saying which tests cover which areas, plus a note of which checks are quick; omit it when the project has no tests), other common development tasks, and how to start the app and where to view it (URL or command), when it has one 2. **Architecture**: High-level "big picture" structure requiring multi-file context to understand 3. **How to Use This File**: A short paragraph explaining that sections below contain brief summaries and agents should follow the markdown links to `.agents-docs/` for full details — only read what's relevant to the current task. 4. **Failure Log**: running list of mistakes and/or corrections that went wrong via the AI Agent at least once. diff --git a/src/plan2code-quick-task.md b/src/plan2code-quick-task.md index a3bc347..285d460 100644 --- a/src/plan2code-quick-task.md +++ b/src/plan2code-quick-task.md @@ -41,6 +41,7 @@ Check for `./AGENTS.md` first: - Launched with a spec folder holding a `DIAGNOSIS-*.md`: read it first, as the bug's context (its cause and suggested fix are already found; re-run its reproduction before and after the fix). Once it passes, set the diagnosis `**Status:**` to `Fixed`; escalating, use that folder rather than asking for a name. Fixed, with nothing in the folder past the diagnosis (no `PLAN-CONVERSATION`, `PLAN-DRAFT`, `pathfinder/map.md` or `overview.md`)? It is done: run `node "/specs.mjs" archive --dry-run` from the project root (`` is `scripts/` beside this SKILL.md, `~/.agents/skills/plan2code-quick-task/scripts/` globally), show its `files`, ask "Archive it to `specs--completed/`? (yes / no)", and on yes run it without `--dry-run`. On no it stays on the dashboard as "Bug fixed". - Cause unclear or the fix big? Stop and suggest `/plan2code-diagnose`. - Read `references/building-habits.md` when the ask is a bug fix or a test fails unexpectedly, after a yes to "Write the test first?", and before a change meant to alter no behavior; follow it. +- Read `references/test-runs.md` before the first test run: run the tests covering the changed files, and offer the full suite at sign-off when the change touched shared ground. ``` ⋅ @@ -50,7 +51,7 @@ Check for `./AGENTS.md` first: ╰┬─┬╯ ``` -Ask what feature the user wants, then ask follow-up questions until 100% clear. Console: that first card carries `"templates": "idea"` (console.md → The kinds). +Ask what feature the user wants, then ask follow-up questions until 100% clear. Console: that first card carries `"templates": "idea"` (console.md → A patch). **Write the test first?** Ask it with the follow-ups (or on its own if there are none) only when the change alters behavior AND the project already has a test runner you can see (a `test` script in `package.json`, pytest config in `pytest.ini` or `pyproject.toml`, `go.mod` with `_test.go` files, or similar). Never for a pure refactor, a docs change, or a project with no runner. Console: one `confirm` card in the same batch as the other plan questions; terminal: one line in the same prompt. On yes, name the test spot in the plan's Verify section and follow the test-first habit. @@ -144,7 +145,7 @@ Then tell user: "Created `specs//PLAN-DRAFT-.md`. Start new 3. [Continue...] ### Verify -- [ ] [How to test/confirm] +- [ ] [Targeted: the command and the tests covering the changed files] - [ ] [Test first: the test spot, e.g. "test through `POST /votes`"] --- @@ -162,4 +163,4 @@ Ready to implement? (yes / modify / escalate / abort) Work summary — tell user: task name, plan delivered (or PLAN-DRAFT created if escalated). After a build, offer: "Reply `show me` to see it running." **Show me it working** (offered, never required): start the app as `AGENTS.md` Commands says (missing: work it out from `package.json` scripts, `Makefile` or `README` and, once it worked, offer the line for `AGENTS.md`; else ask), look at the change (a browser tool's screenshot, else the command's output), stop what you started, and add one line to the work summary: what was run and what was seen. Screenshots go on the web console page only. -**On the web console:** a `__stop` action in a send is the person ending the session: see console-stop.md. At every session end (built, escalated, aborted) post `finish` BEFORE `stop`, as notes/quick-task.md describes. After a build, keep waiting for the review button's answer before you stop. +**On the web console:** after a build, keep waiting for the review button's answer before you stop. diff --git a/src/plan2code-review.md b/src/plan2code-review.md index a7a4207..72447d7 100644 --- a/src/plan2code-review.md +++ b/src/plan2code-review.md @@ -8,7 +8,7 @@ Critical review specialist -- experienced senior engineer providing independent ## Interface -The FIRST thing you do, before anything else in this file — before the scope detection: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow review` before reading (: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-review/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/review.md. Scope questions, the findings report and the pick-what-gets-fixed menu all go through it; the report lands on the page as a doc. Switchable anytime. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console-launches.md), then Process. Read inside a build session for its review button? Skip this section — building-review.md's overrides govern, the session is already running. On the console, a `__stop` action is the person ending the session (console-stop.md); at every session end post `finish` BEFORE `stop`; unless it is a pause, the finish carries `"dashboard": true` (the Back to the dashboard button) and you keep waiting for the press (console-finish.md). +The FIRST thing you do, before anything else in this file — before the scope detection: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow review` before reading (: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-review/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/review.md. Scope questions, the findings report and the pick-what-gets-fixed menu all go through it; the report lands on the page as a doc. Switchable anytime. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console-launches.md), then Process. Read inside a build session for its review button? Skip this section — building-review.md's overrides govern, the session is already running. ## Scripts @@ -167,7 +167,7 @@ Run every finding through the false-positive detection shortcuts before presenti 1. **Plan** -- research best practices, investigate root cause, design optimal solution per fix. 2. **Apply** -- read target files completely, implement precisely, update related docs. Track: `**Fix Progress: X/Y addressed**`. -3. **Verify** -- build and test, re-read every modified file, check for introduced issues. +3. **Verify** -- build and run the tests covering the fixed files (per `references/test-runs.md`; ask the person when you cannot tell which tests cover a fix), re-read every modified file, check for introduced issues. > Reply **approved** to commit, or request changes. Never auto-approve. diff --git a/src/plan2code-xray.md b/src/plan2code-xray.md index 38ddb5a..188b5c4 100644 --- a/src/plan2code-xray.md +++ b/src/plan2code-xray.md @@ -8,7 +8,7 @@ Codebase guide. Two jobs, one card: **explain** how and why an area of the code ## Interface -The FIRST thing you do, before anything else in this file, before the mode question: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow xray` before reading (: references/web-console/ beside this SKILL.md (~/.agents/skills/plan2code-xray/references/web-console/ globally) or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/xray.md. The mode question, the answer or the ranked list, and the save offer all go through it. Switchable anytime. If the argument already says which (`--web` or `Use the web console for this session.`), take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open: resume it (console-launches.md), then Project Context. On the console, a `__stop` action is the person ending the session (console-stop.md); at every session end post `finish` BEFORE `stop`; unless it is a pause, the finish carries `"dashboard": true` (the Back to the dashboard button) and you keep waiting for the press (console-finish.md). +The FIRST thing you do, before anything else in this file, before the mode question: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow xray` before reading (: references/web-console/ beside this SKILL.md (~/.agents/skills/plan2code-xray/references/web-console/ globally) or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/xray.md. The mode question, the answer or the ranked list, and the save offer all go through it. Switchable anytime. If the argument already says which (`--web` or `Use the web console for this session.`), take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open: resume it (console-launches.md), then Project Context. ## Project Context (BLOCKING) diff --git a/src/plan2code.md b/src/plan2code.md index ffb28e6..f971765 100644 --- a/src/plan2code.md +++ b/src/plan2code.md @@ -21,15 +21,11 @@ If `open` fails outright, fall back without drama: list the skills in the termin The page draws the cards itself — you never send the list. It also knows the repo already: `open` scans `AGENTS.md` and `specs/` into `state.scan` (`{ hasAgents, isGit, specs: [{ dir, name, state, detail, touched }] }`), and the picker at the top enables or grays every card from it — the spec the person picks there is the target their launch carries. What you post is your judgment on top of that: -```jsonc -{ - "menu": { - "note": "one line under the title — what you made of the project", - "recommend": "plan2code-init", // a skill name, or omit - "details": { "plan2code-3-implement": "Phase 2 of 4 is next" } - } -} ``` +{ "menu": { "note": "one line under the title", "recommend": "plan2code-init", "details": { "plan2code-3-implement": "Phase 2 of 4 is next" } } } +``` + +`recommend` is a skill name, or omit it; `note` says what you made of the project. - No AGENTS.md → `recommend: "plan2code-init"`; the note says why. - A spec mid-pipeline → recommend its next step; that card's `details` names where it stands ("Plan drafted", "Phase 2 of 4 is next"). The picker pre-selects the most recently touched spec that is not `fixed` — recommend for THAT one. @@ -74,15 +70,7 @@ Ground truth for menu notes and Ask-tab answers. For anything beyond this table, ## A pick arrives -A card click is a send whose action carries the skill: - -```jsonc -{ "type": "submit", - "actions": [{ "i": "__launch", "type": "launch", - "skill": "plan2code-3-implement", "workflow": "implement", - "spec": "specs/lunch-vote" }], - "reply": "Start Implement (/plan2code-3-implement) for specs/lunch-vote, right here in this session." } -``` +A card click is a send whose action is `__launch`, carrying `skill`, `workflow` and, when a spec was picked, `spec`; the send also names `resume` (the command to run) and `skillFile`. `__launch` names no question; like `__stop` it is about the session. `spec` is the picker's selected spec dir — present only when the launched skill takes a spec (or is Quick Task on a `diagnosed` spec) and the person picked one; absent means "start from scratch". @@ -121,7 +109,7 @@ A handoff chip's **Pick it up here** sends `__pickup` with `resume`, `skillFile` ## A delete arrives -The ✕ on a picker chip asks for that spec to go, after a two-step confirm on the page: `{ "i": "__delete", "type": "delete", "spec": "specs/" }`. The page never deletes; you do, through the console's checked command, never your own `rm`: +The ✕ on a picker chip asks for that spec to go, after a two-step confirm on the page: a `__delete` action with `spec`. The page never deletes; you do, through the console's checked command, never your own `rm`: 1. `node "/console.mjs" delete-spec --spec ` from the project root. Exit 0 → `{ ok, removed }`. Exit 3 → refused, `message` says why (not `specs/`, a link, missing); nothing was touched. 2. `node "/console.mjs" open --resume --no-open --workflow dashboard`, which rescans `specs/`. @@ -138,5 +126,5 @@ You arrive here mid-conversation after a `__dashboard` press — from a finished ## While it waits - Bounded slices per console.md, using the longest safe slice: exit 10 → relay one line and immediately wait again — never end the turn after an arbitrary number of slices; exit 20 → `open --resume ` (no `--workflow` — it stays `dashboard` until a launch overwrites it); exit 30 → they canceled, ask in the terminal what they want. -- A `__stop` action is the person ending the session before picking: post `finish` (a headline that says paused, `"command": "/plan2code"`) then `stop`, per console-stop.md. +- A `__stop` action is the person ending the session before picking: its finish says paused, with the command `/plan2code`. - The console keeps `agent.status` honest: collecting a pick sets `working`, and waiting on the menu sets `waiting`. Post an `activity` while a launch becomes a skill. diff --git a/src/shared-references/test-runs.md b/src/shared-references/test-runs.md new file mode 100644 index 0000000..f04cfc6 --- /dev/null +++ b/src/shared-references/test-runs.md @@ -0,0 +1,33 @@ +# Choosing what to run +> Read by Document, Implement, Implement + Review, Quick Task, Review and Finalize before they write, run or offer tests. Never invoked as a skill. + +## Three tiers + +1. **Per task:** run the tests that cover what the task touched. +2. **Phase end:** run the phase file's `## Phase Testing` lines, plus tests for any other file the phase changed. +3. **Full suite:** only where the plan put it: a `Full suite:` line in a phase file, or Finalize's offer. A project's `AGENTS.md` saying "run `npm test`" (or any whole-suite command) does not put a full run in a phase. + +## Finding the tests that cover a file + +In this order: + +1. `AGENTS.md`'s test map and its "run single test" command. +2. Otherwise match by name, folder and imports of the changed files. + +A runner's own related-tests flag may be used when `AGENTS.md` records it. It is never required. + +## Quick checks + +Lint, a type check, a size check: run them at phase end only when the project or `AGENTS.md` shows them to be fast. + +## Shared ground + +A test helper or fixture, build or test config, a widely imported module, a shared type or schema. Touching any of these is the moment to offer a wider run: say what was touched and why it reaches wide, and let the person choose. + +## Ask when unsure + +When you cannot tell whether a check is fast, whether a change is shared ground, or which tests cover a file, ask the person. Never guess. + +## Record honestly + +Say which tests ran and which were skipped. Never report "tests pass" for a run that did not happen. diff --git a/src/skill-scripts/common.mjs b/src/skill-scripts/common.mjs index 836a0fc..c84d0d0 100644 --- a/src/skill-scripts/common.mjs +++ b/src/skill-scripts/common.mjs @@ -40,7 +40,7 @@ export function fail(exit, error, message, next, extra) { } export function out(obj) { - process.stdout.write(JSON.stringify(obj, null, 2) + "\n"); + process.stdout.write(JSON.stringify(obj) + "\n"); } /** diff --git a/src/statusline-claude/README.md b/src/statusline-claude/README.md index 98fd4e3..8010338 100644 --- a/src/statusline-claude/README.md +++ b/src/statusline-claude/README.md @@ -9,7 +9,7 @@ A persistent three-line status bar for Claude Code that displays model info, pro ``` ╭───╮ Opus 4.6 | High │ plan2code │ feature/statusline │ +12 -3 │ ★ │ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ - ╰┬─┬╯ 3h 5m ($4.62) │ ▰▰▰▰▰▱▱▱▱▱▱▱ 42% (84k) │ 5h: 28% · 7d: 61% + ╰┬─┬╯ 84k ⋅ ▰▰▰▰▰▱▱▱▱▱▱▱ 42% │ 5h: 28% · 7d: 61% | 3h 5m ($4.62) ``` **Enterprise / Bedrock / Vertex / PAYG** — session token counts (no `rate_limits` in stdin): @@ -17,7 +17,7 @@ A persistent three-line status bar for Claude Code that displays model info, pro ``` ╭───╮ Sonnet 4.5 | Medium │ plan2code │ main │ +12 -3 │ ★ │ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ - ╰┬─┬╯ 2m ($0.18) │ ▰▰▱▱▱▱▱▱▱▱▱▱ 18% │ 88k in · 3k out + ╰┬─┬╯ ▰▰▱▱▱▱▱▱▱▱▱▱ 18% │ 88k in · 3k out | 2m ($0.18) ``` **Git worktree** — session running in a linked worktree at `C:\git\plan2code-user-auth`: @@ -25,14 +25,14 @@ A persistent three-line status bar for Claude Code that displays model info, pro ``` ╭───╮ Opus 4.6 | High │ plan2code ⑂ │ feature/user-auth │ +12 -3 │ ★ │ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ - ╰┬─┬╯ 3h 5m ($4.62) │ ▰▰▰▰▰▱▱▱▱▱▱▱ 42% (84k) │ 5h: 28% · 7d: 61% + ╰┬─┬╯ 84k ⋅ ▰▰▰▰▰▱▱▱▱▱▱▱ 42% │ 5h: 28% · 7d: 61% | 3h 5m ($4.62) ``` **Line 1:** Planny icon | Model name + reasoning effort | Project name | Git branch | Uncommitted changes **Line 2:** Planny icon | Gray separator -**Line 3:** Planny icon | Session duration + cost | Context window bar (+ absolute tokens used, Pro/Max/Teams only) | Usage (rate limits or token counts) +**Line 3:** Planny icon | Context window bar (after absolute tokens used, Pro/Max/Teams only) | Usage (rate limits or token counts) | Session duration + cost -The context bar's absolute token count `(84k)` only appears on Pro/Max/Teams (rate-limit) accounts, where it's the only place total context tokens are shown. On Enterprise/Bedrock/Vertex/PAYG accounts, it's suppressed because the `in`/`out` token counts already cover it. +The absolute token count before the context bar (`84k ⋅`) only appears on Pro/Max/Teams (rate-limit) accounts, where it's the only place total context tokens are shown. On Enterprise/Bedrock/Vertex/PAYG accounts, it's suppressed because the `in`/`out` token counts already cover it. ## Installation @@ -97,7 +97,7 @@ Edit `~/.claude/statusline-config.json`: | `items.worktree` | `true` | Detect [git worktrees](https://git-scm.com/docs/git-worktree) and render the project segment as `repo ⑂ worktree` instead of just the worktree's directory name. See [Worktree Display](#worktree-display). Requires `items.project`. | | `items.branch` | `true` | Show current git branch (falls back to short SHA when detached HEAD) | | `items.contextBar` | `true` | Show context window usage bar with percentage | -| `items.contextTokens` | `true` | Append raw tokens used in the context window next to the percentage, e.g. `42% (84k)`. Reads `context_window.total_input_tokens` (the same input-token count `used_percentage` is derived from — excludes output tokens). Requires `items.contextBar` to also be enabled. Suppressed automatically on Enterprise/Bedrock/Vertex/PAYG accounts, where the `in`/`out` token usage segment already shows the same number. | +| `items.contextTokens` | `true` | Append raw tokens used in the context window before the bar, e.g. `84k ⋅ ▰▰▰▰▰▱▱▱▱▱▱▱ 42%`. Reads `context_window.total_input_tokens` (the same input-token count `used_percentage` is derived from — excludes output tokens). Requires `items.contextBar` to also be enabled. Suppressed automatically on Enterprise/Bedrock/Vertex/PAYG accounts, where the `in`/`out` token usage segment already shows the same number. | | `items.planUsage` | `true` | Show usage info: rate limits (Pro/Max) or token counts (Bedrock/Vertex/PAYG) | | `items.linesChanged` | `true` | Show uncommitted git diff stats (+added -removed) | | `items.duration` | `true` | Show session duration | diff --git a/src/statusline-claude/statusline.js b/src/statusline-claude/statusline.js index 320e4bd..8066ebf 100644 --- a/src/statusline-claude/statusline.js +++ b/src/statusline-claude/statusline.js @@ -106,6 +106,7 @@ const C = { const SEP = (config) => config.color ? `${C.gray} │ ${C.reset}` : ' │ '; const DOT = (config) => config.color ? `${C.gray} · ${C.reset}` : ' · '; +const PIPE = (config) => config.color ? `${C.gray} | ${C.reset}` : ' | '; // ============================================================================ // Git helpers @@ -291,15 +292,15 @@ function formatContextBar(percent, tokens, config, suppressTokens) { const emptyStr = '▱'.repeat(CONTEXT_BAR_LEN - filled); const showTokens = config.items.contextTokens && !suppressTokens && tokens != null; - const tokenStr = showTokens ? ` (${formatTokenCount(tokens)})` : ''; + const tokenStr = showTokens ? formatTokenCount(tokens) : ''; - if (!config.color) return `${filledStr}${emptyStr} ${clamped}%${tokenStr}`; + if (!config.color) return `${tokenStr ? `${tokenStr} ⋅ ` : ''}${filledStr}${emptyStr} ${clamped}%`; const barColor = clamped >= CONTEXT_THRESHOLDS.yellow ? C.barRed : clamped >= CONTEXT_THRESHOLDS.green ? C.barYellow : C.barGreen; - const tokenPart = tokenStr ? `${C.label}${tokenStr}${C.reset}` : ''; - return `${barColor}${filledStr}${C.gray}${emptyStr}${C.reset} ${barColor}${clamped}%${C.reset}${tokenPart}`; + const tokenPart = tokenStr ? `${C.label}${tokenStr}${C.reset}${C.gray} ⋅ ${C.reset}` : ''; + return `${tokenPart}${barColor}${filledStr}${C.gray}${emptyStr}${C.reset} ${barColor}${clamped}%${C.reset}`; } function formatLinesChanged(stdinData, config) { @@ -441,11 +442,6 @@ function formatLine1(stdinData, config) { function formatLine2(stdinData, config) { const segments = []; - if (config.items.duration) { - const dur = formatDuration(stdinData, config); - if (dur) segments.push(dur); - } - // Token usage ("X in / Y out") already surfaces total_input_tokens — suppress the // context bar's duplicate (XXk) in that case. Rate-limit accounts show no absolute // tokens elsewhere, so the bar's (XXk) stays as the only source there. @@ -464,7 +460,11 @@ function formatLine2(stdinData, config) { if (usage) segments.push(usage); } - return segments.join(SEP(config)); + // Duration + cost closes the line, set off with a plain pipe + const main = segments.join(SEP(config)); + const dur = config.items.duration ? formatDuration(stdinData, config) : null; + if (!dur) return main; + return main ? main + PIPE(config) + dur : dur; } // ============================================================================