Files
plan2code/src/plan2code.md
T
2026-10-23 10:04:13 -07:00

13 KiB
Raw Blame History

🎛️ DASHBOARD MODE

Start all DASHBOARD MODE responses with '🎛️'

Role

The front door. One page in the person's browser lists every Plan2Code skill; their pick launches it right there — you resume the same console session as that skill and run it. No typing command names, no second window.

Interface

The console is the whole point of this skill — do not ask "browser or terminal"; open it, and open it FIRST. The person is looking at nothing until you do, so the page comes before any other reading or exploring.

  1. Your very first command: node "<D>/console.mjs" open --workflow dashboard, where <D> is references/web-console/ beside this SKILL.md (~/.agents/skills/plan2code/references/web-console/ globally, or the dir in ~/.plan2code/console/console-dir). No --title needed — it defaults to the folder name. The page is up and usable at once: the cards and the project scan come from the console itself.
  2. Now read /console.md and /console-launches.md (once per conversation — skip any you already read), then post the menu payload (below) with post --wait.
  3. Wait. The turn is console.md's, unchanged; every send here is a pick, a stop, or a message.
  4. On a pick, you BECOME that skill (below). Dashboard duties end there.

If open fails outright, fall back without drama: list the skills in the terminal as a numbered menu and run the pick's command.

The menu

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 greys 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:

{
  "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" }
  }
}
  • 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.
    • exploring ("Exploring"): Pathfinder is next.
    • mapped ("Ready to plan"): Plan is next.
    • planned ("Ready to document"): Document is next.
    • documented ("Ready to build"): Implement is next.
    • building ("Building"): Implement is next.
    • built ("Ready to finalize"): Finalize is next.
    • A documented or building spec whose [/] phase file holds a waiting **Plan change:** line in its Notes (Implement paused for a revision; (applied <date>): or (dropped <date>): means done): recommend Revise the plan instead, details "Plan change waiting from Phase N". The Revise card is lit on a built spec too (a change found in the last manual checks): recommend it there only for a waiting brief, and say so in note; otherwise Finalize stays the next step.
  • A spec that scans unrecognized ("files on disk") is input, not progress: its folder rides along on a Pathfinder or Plan launch as reference, and those are the only pipeline cards it lights. Read the files and recommend the fit — a settled design doc the person wrote is Plan's brief, loose notes are Pathfinder's. No skill generates such a doc; see the table below for what each one does write. Never flag Document or anything downstream of it for such a spec.
  • A diagnosed spec ("Bug diagnosed") is a bug Diagnose wrote up: recommend Quick Task, or Plan when its DIAGNOSIS-<date>.md sizes the fix as big; its folder rides along on either launch.
  • A fixed spec ("Bug fixed") is a diagnosed bug Quick Task fixed but did not archive: finished, so never recommend for it or name it in the note; the picker never pre-selects one and hides it while unavailable workflows are hidden. The person archives it (Quick Task offers that once the bug is fixed) or deletes it with the picker's ✕.
  • Nothing on disk, or only fixed specs → recommend: "plan2code-0-pathfinder"; the note invites the first idea.
  • A handoff in state.scan.handoffs newer than the most recently touched spec is usually the place to start: say so in note (the page has no card to recommend for it).
  • Recommend only what you would tell a person who asked "where do I start?". When in doubt, no flag and a neutral note — the page falls back to flagging the selected spec's own next step.
  • recommend must name a lit card for the initial selection. If the person switches specs or starts fresh, the page derives the suggestion and detail from its scan instead.

One line each for note and every details entry — they render inside cards.

What each skill reads and writes

Ground truth for menu notes and Ask-tab answers. For anything beyond this table, read the skill's SKILL.md. Paths are under specs/<feature>/ unless shown otherwise.

skill reads writes
init codebase, README, agent rule files AGENTS.md, .agents-docs/AGENTS-<section>.md; points CLAUDE.md etc. at AGENTS.md
init-update AGENTS.md, codebase AGENTS.md, .agents-docs/
0-pathfinder the idea, loose notes pathfinder/map.md, pathfinder/questions/NN-<slug>.md; cleared → PLAN-DRAFT-<date>.md
1-plan idea or PLAN-DRAFT PLAN-DRAFT-<date>.md, PLAN-CONVERSATION-<date>.md
1b-revise-plan overview.md, phase-X.md, a waiting **Plan change:** brief the same, revised; the brief marked applied or dropped
quick-task the ask; a DIAGNOSIS-*.md when launched on one code; the diagnosis set to Fixed, then the folder moved to specs--completed/ on a yes; escalated → PLAN-DRAFT-<date>.md
2-document PLAN-DRAFT, PLAN-CONVERSATION (optional) overview.md, phase-X.md
3-implement(-review) overview.md, phase-X.md code; [x] marks + completion summary in phase-X.md; paused for a revision, a **Plan change:** brief in its Notes
review spec, diff the fixes picked; no spec writes
4-finalize spec + code summary in overview.md; moves the spec to specs--completed/
handoff conversation, spec, git ~/.plan2code/handoffs/<id>.md, listed on the dashboard
changelog CHANGELOG.md, package.json, git history CHANGELOG.md entries, package.json version; no commits
git git status, branches, diffs, AGENTS.md commits, branches; optional .gitignore, push, publish; no spec writes
xray the codebase, git history, gh when present an answer; ARCHITECTURE-BRIEF-<date>.md or XRAY-<area>-<date>.md when asked
diagnose the bug, the codebase, references/building-habits.md DIAGNOSIS-<date>.md; no code changes

A pick arrives

A card click is a send whose action carries the skill:

{ "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." }

__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".

Never hand this to a skill-invocation tool. Open its SKILL.md with your own file-read tool instead. Every Plan2Code skill below the dashboard ships disable-model-invocation: true on purpose — it exists to be read and followed inline, not launched as a sub-skill — and calling one through a skill-invocation tool errors out and strands the hand-off mid-launch.

On it, in this turn:

  1. Resume the session as that skill — before reading anything, in one command: run the send's resume exactly as given. It is

    node "<D>/console.mjs" open --resume <sid> --no-open --workflow <its workflow> --spec <action.spec>
    

    <its workflow> is the action's workflow field (mapped below), and --spec is there only when the action carried one; --title is optional — post a real title once you know what the run is about. Never a fresh open — that strands the page they are watching on the dashboard's session. --no-open keeps the browser put: the page they already have IS the session, and this one command both reuses the server and turns it into the new skill's starting screen, while you read.

  2. Read the skill's file with your own file-read tool: the send's skillFile, or ~/.agents/skills/<skill>/SKILL.md — <skill> is the action's skill field. Do not read console.md again; read only the notes or building files its Interface names.

  3. Follow the skill file from the top. Its Interface step is already answered — the console is open, this is the session, you are mid-turn. Start where its real work starts: for most skills the AGENTS.md check; for pathfinder, Step 0's gate. When it tells you to open a console session, you already have: skip to its first post.

The page shows a getting-ready screen from the click until the resume lands, then the skill's own starting screen until its first payload — so resume first, and post before anything slow; an activity line says what you are doing meanwhile.

If skill is not in the table below, say so on the page and stay the dashboard.

skill workflow skill workflow
plan2code-init init plan2code-2-document document
plan2code-init-update init-update plan2code-3-implement implement
plan2code-0-pathfinder pathfinder plan2code-3-implement-review implement-review
plan2code-1-plan plan plan2code-review review
plan2code-1b-revise-plan revise-plan plan2code-4-finalize finalize
plan2code-quick-task quick-task plan2code-handoff handoff
plan2code-git git plan2code-changelog changelog
plan2code-xray xray plan2code-diagnose diagnose

A pick-up arrives

A handoff chip's Pick it up here sends __pickup with resume, skillFile and handoffFile (and fallback when the named skill or spec is gone, or the Handoff skill wrote it). Read console-launches.md → A pick-up, then do as a pick does: resume first, then the skill's file, then the handoff.

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/<name>" }. The page never deletes; you do, through the console's checked command, never your own rm:

  1. node "<D>/console.mjs" delete-spec --spec <action.spec> from the project root. Exit 0 → { ok, removed }. Exit 3 → refused, message says why (not specs/<name>, a link, missing); nothing was touched.
  2. node "<D>/console.mjs" open --resume <sid> --no-open --workflow dashboard, which rescans specs/.
  3. Post the menu again with --wait; the note says what was deleted, or why it was not. Stay the dashboard.

A fixed spec is deleted after one confirm on the page (its own Delete button, no name to type); your steps are the same.

A handoff's Delete is the same __delete with handoff (an id) instead of spec: run node "<D>/console.mjs" delete-handoff --handoff <action.handoff>, then steps 2 and 3.

Coming back from another skill

You arrive here mid-conversation after a __dashboard press — from a finished screen, or mid-workflow from the top bar's triangle once that skill saved its place — having already run open --resume <sid> --no-open --workflow dashboard (the send's resume; it cleared the last skill's page, its finish included — console-finish.md, console-stop.md). Skip Interface steps 1–2; your first job is the menu judgment, then post the menu with --wait: re-read state.scan, which the resume refreshed — the spec you just worked on is usually the most recently touched. Then the usual wait loop and launches.

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 <sid> (no --workflow — it stays dashboard until a launch overwrites it); exit 30 → they cancelled, 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.
  • 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.