Files
plan2code/src/plan2code.md
T

126 lines
11 KiB
Markdown
Raw Normal View 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 <D>/console.md and <D>/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:
```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" }
}
}
```
- 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.
- 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.
- 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` | the same, revised |
| 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` |
| 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 | `<timestamp>-handoff.md` (OS temp or `handoffs/`) |
| 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:
```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." }
```
`__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 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.
## 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.