mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-17 04:45:33 -08:00
Sync upstream v2.4.0 (web console, dashboard skill, implement-review, global launcher) with 24 review fixes and a look-around wake-up for Planny
AI Assisted
This commit is contained in:
1 parent
eefa7082ed
commit
0d7c2e140b
523 files changed
+339802
-401
No files matched your search
@@ -13,6 +13,7 @@ produces are unchanged.
|
||||
| Approach | Best for |
|
||||
|----------|----------|
|
||||
| `/plan2code-3-implement` | Interactive control, reviewing each phase, logic that needs your judgment |
|
||||
| `/plan2code-3-implement-review` | The same interactive control, with a focused review and its fixes applied before you approve the phase |
|
||||
| `plan2code-loop` | Straightforward implementations, batch work, overnight runs |
|
||||
|
||||
The loop reads the same `overview.md` and phase files. You can start with the loop and finish by
|
||||
|
||||
@@ -15,18 +15,18 @@ background processes.** Optional, and unrelated to the workflow itself.
|
||||
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%
|
||||
╭───╮ Opus 5 / high │ plan2code │ feature/pathfinder-github-iss │ +12 -3
|
||||
│ ★ │ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
|
||||
╰┬─┬╯ 3h 5m ($4.62) │ ▰▰▰▰▰▱▱▱▱▱▱▱ 42% (84K) │ 5h: 28% · 7d: 61%
|
||||
```
|
||||
|
||||
On Enterprise / Bedrock / Vertex / pay-as-you-go, where they aren't, the last segment becomes session
|
||||
token counts instead:
|
||||
|
||||
```
|
||||
◦ ◦ Sonnet 5 │ plan2code │ main │ +12 -3
|
||||
╭●╮ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
|
||||
├■┤ 2m ($0.18) │ ▰▰▱▱▱▱▱▱▱▱▱▱ 18% │ 88k in · 3k out
|
||||
╭───╮ Sonnet 5 │ plan2code │ main │ +12 -3
|
||||
│ ★ │ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
|
||||
╰┬─┬╯ 2m ($0.18) │ ▰▰▱▱▱▱▱▱▱▱▱▱ 18% │ 88k in · 3k out
|
||||
```
|
||||
|
||||
The icons down the left are Planny, the project mascot.
|
||||
|
||||
+1
-1
@@ -19,7 +19,7 @@ Built for **maintainers**. If you're using Plan2Code to ship features, you don't
|
||||
## Install
|
||||
|
||||
```bash
|
||||
node install.js # I (everything) — or C → B (bot only)
|
||||
node install.js # A (everything + dev tools) — or C → B (bot only)
|
||||
```
|
||||
|
||||
## Run
|
||||
|
||||
@@ -5,6 +5,11 @@ conversation** — that's the whole trick.
|
||||
|
||||
← [Back to README](../README.md)
|
||||
|
||||
> **Prefer a page to a terminal?** Every skill can run in your browser — start at the
|
||||
> `/plan2code` dashboard, add `--web` to a direct command (e.g. `/plan2code-1-plan --web`),
|
||||
> or choose the console when offered. Questions, sign-offs and build progress stay on the page.
|
||||
> See [web-console.md](web-console.md).
|
||||
|
||||
---
|
||||
|
||||
## Session 1 — Plan
|
||||
@@ -73,7 +78,7 @@ Repeat. New conversation each time. It always finds the next open phase itself.
|
||||
When you reach a parallel group, it offers you the choice — open a second agent, take the other
|
||||
phase, and the `[/]` marks keep them from colliding.
|
||||
|
||||
**Optional, any time:** `/plan2code-review` for an independent second opinion on what just landed.
|
||||
Use `/plan2code-3-implement-review` instead when review should run automatically before phase approval. `/plan2code-review` remains available for an independent second opinion at any other time.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,380 @@
|
||||
# Plan2Code Web Console: design proposal
|
||||
|
||||
**Status:** implemented in v2.4.0. Kept as the design record, because it explains
|
||||
*why* the thing is shaped the way it is. For how to use it, see
|
||||
[web-console.md](./web-console.md); for where the code lives, see
|
||||
[AGENTS-architecture.md](../.agents-docs/AGENTS-architecture.md).
|
||||
**Date:** 2026-09-20
|
||||
**Scope:** an optional local browser UI that `plan2code-0-pathfinder` and `plan2code-1-plan` can offer at startup, built as a shared component other workflow steps can adopt later.
|
||||
|
||||
---
|
||||
|
||||
## 1. Why this is smaller than it looks
|
||||
|
||||
Pathfinder is already written against a *delivery-channel abstraction*. Its rules say:
|
||||
|
||||
> AskUserQuestion when available; prose Q blocks only as fallback.
|
||||
|
||||
and `grilling.md` specifies the question object in full: a plain two-or-three-word header, the probe with its why-it-matters, two to four genuine options each described by its trade-off with exactly one named as the recommendation, plus an automatic `Other` escape hatch.
|
||||
|
||||
That is a form. The console is not a new workflow, it is a **third delivery channel** alongside the structured tool and prose. The methodology, the file formats, the gates and the rules are untouched.
|
||||
|
||||
Plan is the opposite: pure prose Q and A with seven phases and four named approval gates. But every one of its gates already resolves to a literal typed token (`approved`, `needs changes`, `approve / refine / abort`). That gives us the second half of the idea.
|
||||
|
||||
### The keystone: answers map back to the literal token
|
||||
|
||||
Every console request carries two extra fields:
|
||||
|
||||
| Field | Purpose |
|
||||
| --- | --- |
|
||||
| `fallbackText` | the exact terminal phrasing the prompt would have printed |
|
||||
| `token` | what each button resolves to: `approved`, `H`, `A`, `S 1,3,5`, `yes`, `skip` |
|
||||
|
||||
Clicking **Approve** in the browser is then byte-identical to typing `approved` in the terminal. No prompt logic ever forks. If the console is absent, refused, or times out, the agent prints `fallbackText` and the session continues in the terminal with nothing lost. Mid-session switching in either direction is free, because the markdown files under `specs/` remain the only source of truth.
|
||||
|
||||
This one decision is what keeps the integration from metastasising across twelve prompt files.
|
||||
|
||||
---
|
||||
|
||||
## 2. Hard constraints found during research
|
||||
|
||||
These are verified, not assumed. They shape everything below.
|
||||
|
||||
### 2.1 The character limit is the binding constraint
|
||||
|
||||
`scripts/validate-char-count.js` caps every flat `src/plan2code-*.md` at 11,000 characters, enforced by a husky pre-commit hook. Measured today:
|
||||
|
||||
```
|
||||
10995 5 plan2code-0-pathfinder.md <- 5 characters of headroom
|
||||
10676 324 plan2code-1-plan.md
|
||||
10835 165 plan2code-2-document.md
|
||||
```
|
||||
|
||||
Neither target prompt can absorb the integration inline. **Trimming pathfinder by roughly 250 characters is a prerequisite task, not a nice-to-have.** Reference files are exempt from the limit, so all of the console contract lives in one.
|
||||
|
||||
### 2.2 Packaging needs zero installer code changes
|
||||
|
||||
`computeExpectedSkills()` in `install.js` copies `additionalReferences` directories verbatim through `listFilesRecursive()`, which has no extension filter. The initial implementation fanned one shared source directory into two skills; the current installer fans it into every skill.
|
||||
|
||||
Current packaging constraints:
|
||||
|
||||
- Reference files are copied as `Buffer`s, so binary assets are supported; the shipped MP3 chimes exercise this path. Browser-served assets must also be added to the server's `SERVABLE` allow-list and covered by a test.
|
||||
- `skills/` is generated build output (committed, and checked for drift by `npm test`) and `buildSkills()` prunes files it doesn't expect. Assets must originate in `src/` and never be hand-placed.
|
||||
|
||||
### 2.3 `specs/` is gitignored, which is an argument *for* the server
|
||||
|
||||
Three prompts repeat the warning that Glob silently fails on `specs/` and only a shell listing works. A Node server enumerating candidate spec directories server-side and handing the page a list is strictly better than either a terminal listing or a browser file input.
|
||||
|
||||
### 2.4 Formats that must round-trip byte for byte
|
||||
|
||||
- `<!-- METRICS_JSON {...} -->` comments
|
||||
- the `## User Feedback` table (exact field names `Rating`, `Reason`, `Went Well`, `Went Poorly`, pipes escaped as `\|`)
|
||||
- the five-state checkbox alphabet `[ ]` `[/]` `[x]` `[?]` `[!]`, with the invariant "never reset `[/]` to `[ ]`"
|
||||
- the handoff string `**Status:** Phase 3 Complete - Resume at Phase 4`, plain ASCII hyphen, single spaces
|
||||
|
||||
The console carries all of these as opaque strings and never reformats them.
|
||||
|
||||
### 2.5 Two regex landmines
|
||||
|
||||
- `plan2code-metrics` scrapes confidence with patterns like `/[Rr]equirements?[:\s|]+(\d{1,2})/` that **do not require a percent sign**. Nothing the console writes under `specs/` may contain bare `Requirements` / `Feasibility` / `Integration` / `Risk` followed by a number.
|
||||
- The loop parses `TASK_COMPLETE`, `PHASE_COMPLETE` and friends. Pathfinder already forbids these tokens under `specs/`.
|
||||
|
||||
Both are cheap to enforce mechanically in the server's write path.
|
||||
|
||||
---
|
||||
|
||||
## 3. Architecture
|
||||
|
||||
### 3.1 Placement
|
||||
|
||||
```
|
||||
src/web-console/
|
||||
console.mjs CLI: open | post | wait | status | stop
|
||||
server.mjs the HTTP server (spawned detached by `open`)
|
||||
lib.mjs paths, atomic writes, patch merge, validate()
|
||||
console.md the agent-facing contract
|
||||
public/index.html markup shell only
|
||||
public/app.js the client (no inline script, see CSP below)
|
||||
public/app.css
|
||||
public/render.js markdown tokens to DOM nodes
|
||||
public/vendor/marked.esm.js pinned 15.0.7, MIT, lexer only
|
||||
```
|
||||
|
||||
Wired in with one data entry per consumer:
|
||||
|
||||
```js
|
||||
{
|
||||
source: 'plan2code-0-pathfinder.md',
|
||||
// ...
|
||||
additionalReferences: [{ source: 'web-console', target: 'web-console' }]
|
||||
}
|
||||
```
|
||||
|
||||
Lands at `~/.agents/skills/<skill>/references/web-console/` on all ~28 target agents. The server finds its own siblings via `path.dirname(fileURLToPath(import.meta.url))`.
|
||||
|
||||
The agent needs an absolute path to invoke it. `ai-assist-git-pr` already establishes the convention, proven on Windows, and we reuse its wording:
|
||||
|
||||
> `<SKILL_ROOT>` = the directory containing this `SKILL.md` (its install location). Use the absolute path you loaded it from.
|
||||
|
||||
### 3.2 The transport, which is the genuinely hard part
|
||||
|
||||
A turn-based agent must wait up to twenty minutes for a human. Claude Code's Bash tool caps at 600s and **harness-managed background tasks are not a safe place to wait**: there are open issues documenting them being killed at 5 to 20 minutes, killed on compaction, killed when a new prompt arrives, and leaked with no handle when spawned by subagents. Detached processes are explicitly immune.
|
||||
|
||||
So: **split into two processes with deliberately different lifetimes.**
|
||||
|
||||
```
|
||||
# once, at handoff
|
||||
node <SKILL_ROOT>/references/web-console/console.mjs open --file request.json
|
||||
-> spawns server.mjs DETACHED, prints URL + session id, exits in under 300ms
|
||||
|
||||
# repeatedly, until done
|
||||
node ... console.mjs wait --seconds 240
|
||||
exit 0 -> stdout is the result JSON. Done.
|
||||
exit 10 -> {"status":"waiting","elapsed":"6m12s","answered":3,"total":7,...}
|
||||
Agent relays one line to the user and calls wait again.
|
||||
exit 20 -> server is dead. Agent restarts it, re-reports the URL.
|
||||
exit 30 -> human hit Cancel.
|
||||
```
|
||||
|
||||
Why bounded rather than a single long block:
|
||||
|
||||
- The deadline lives in our code, not the harness's. `--seconds 240` covers a 20-minute session in five turns. Drop to `--seconds 90` for harnesses with a 120s default (Cursor auto-backgrounds and cannot be told not to).
|
||||
- Every return is a free heartbeat: "still waiting, 3 of 7 answered, 6 minutes in" beats silence.
|
||||
- Interruption is survivable. Ctrl-C the agent, compact the context, restart: the next `wait` re-attaches, because state is on disk.
|
||||
|
||||
The waiter uses `fs.watch` on the session **directory** (watching a file breaks on Windows when the file is replaced by rename) with a 500ms `stat` fallback as the authority, and pings `/health` every 5s for liveness. The result is delivered **through the filesystem**, not HTTP, which decouples the waiter from the server and is also the resumability story.
|
||||
|
||||
**Optional push accelerator, Claude Code only:** at `start`, also fire a backgrounded `until [ -f <dir>/result.json ]; do sleep 2; done`. If it survives, submit-to-agent latency drops to near zero. If it gets killed, nothing breaks, because the poll loop is the source of truth.
|
||||
|
||||
### 3.3 Port, lifecycle, security
|
||||
|
||||
| Concern | Decision |
|
||||
| --- | --- |
|
||||
| Port | `listen(0, '127.0.0.1')`, handle file in `os.tmpdir()/<tool>/<sha1(cwd).slice(0,8)>/`. This is Jupyter's `jpserver-<pid>.json` pattern and RFC 8252 §7.3. A fixed port is fatal here: you run git worktrees, so two agents in two checkouts of one repo is routine, and a fixed port makes that silently wrong. |
|
||||
| Bind | the literal `127.0.0.1`, never `0.0.0.0`, never the string `localhost` (which may resolve to `::1` and produce the classic "server is up but the browser gets ECONNREFUSED" bug on Windows). |
|
||||
| Auto-open | best-effort, never fatal. Skip when `DISPLAY` and `WAYLAND_DISPLAY` are both unset, or `SSH_CONNECTION` / `REMOTE_CONTAINERS` is set. Honour `BROWSER=` and `--no-open`. |
|
||||
| Orphan prevention | a **server-side idle deadline** (30 min, bumped by any authenticated request) is the mechanism, not a nicety. Windows has no real SIGTERM, and a detached server with no console never sees `SIGINT`, so signal handlers cannot be relied on. Plus a 4h absolute cap, a `pagehide` beacon, an explicit `stop`, and a reap sweep on every `start`. |
|
||||
| Liveness test | `process.kill(pid, 0)` **and** a `/health` check whose returned session id matches the handle. PID reuse is real; the sid match is what disambiguates. |
|
||||
|
||||
Security, six controls, about 60 lines:
|
||||
|
||||
1. Bind `127.0.0.1`.
|
||||
2. **`Host` header allowlist.** This is the DNS-rebinding defence and the highest-value line in the server. Vite shipped GHSA-vg6x-rcgg-rjx6 for exactly this omission.
|
||||
3. 128-bit token **in the URL path**, not the query string. Path placement also kills the Windows `cmd /c start` `&`-injection hazard, because the URL then contains no `&`.
|
||||
4. First `GET /s/<token>/` sets `HttpOnly; SameSite=Strict` cookie and 302s to `/`. Token leaves the address bar, history and pasted screenshots; CSRF protection comes free.
|
||||
5. `Origin` check on every mutating request.
|
||||
6. Strict CSP with no `unsafe-inline`, which is why JS and CSS are separate files rather than one inlined HTML.
|
||||
|
||||
**On whether XSS matters here.** The tempting argument is "it is the user's own machine and the model would not write `<script>`". That misses the real risk. The page is same-origin with a server that reads and writes the user's files and holds the session token, so script in that page can post arbitrary answers back to the agent, which then acts on them with the agent's full tool permissions. And the markdown is only nominally agent-authored: in practice the agent is summarising a dependency README, a scraped page, a PR description, a log. Treat it as attacker-controlled.
|
||||
|
||||
The structural fix, rather than a filter: **vendor `marked` for `lexer()` only and render tokens to the DOM with `createElement` and `textContent`.** No HTML string is ever produced, so there is nothing for a sanitiser bypass to bypass, and the strict CSP holds. Roughly 120 lines of renderer. Hand-rolling the parser instead is a trap: hand-rolled markdown fails exactly where agent-authored technical documents live (a table inside a list item, a fenced block containing backticks) and its failure mode is usually an injection hole.
|
||||
|
||||
### 3.4 Browser transport
|
||||
|
||||
SSE primary (about fifteen lines on Node's built-in `http`), with automatic fallback to 3s interval polling after three consecutive errors. **Exactly one `EventSource` per page, ever**: browsers cap HTTP/1.1 at ~6 connections per origin, and a second stream per tab across three tabs wedges the origin with no error and no timeout. Multiplex everything through one stream with a `type` field.
|
||||
|
||||
The page shows the **agent's** liveness, not the server's. If the agent's turn crashed, the server is still happily up and a naive spinner lies forever. Stamp `agentLastSeen` on every waiter ping; when stale past two minutes the page says so plainly: "The agent has not checked in for 4 minutes. Your answers are saved. Check your terminal."
|
||||
|
||||
### 3.5 State on disk
|
||||
|
||||
The filesystem is the database and the result transport.
|
||||
|
||||
```
|
||||
~/.plan2code/console/sessions/<sid>/
|
||||
session.json sid, cwd, workflow, title, phase
|
||||
request-<rev>.json the agent's payload, immutable per revision
|
||||
draft.json in-progress answers, debounced ~500ms write
|
||||
result.json written ATOMICALLY on submit (temp + fsync + rename)
|
||||
events.ndjson append-only, doubles as SSE Last-Event-ID replay
|
||||
```
|
||||
|
||||
Deliberately **not** under `specs/`: that keeps the console clear of the metrics scraper and the loop's marker parser, and survives a `git clean`.
|
||||
|
||||
Draft persistence is the highest-value feature in the tool and among the cheapest. Twenty minutes of a product manager's structured answers must never be lost to a closed tab. Server-side debounced write plus a `localStorage` mirror keyed by `sid + rev`.
|
||||
|
||||
Recovery matrix:
|
||||
|
||||
| Failure | Recovery |
|
||||
| --- | --- |
|
||||
| Tab closed or browser crashed | Reopen the URL, draft restored, agent never notices |
|
||||
| Server died, agent alive | `wait` returns exit 20, agent runs `start --resume <sid>`, new port, same session dir |
|
||||
| **Agent session died, human still working** | Human submits, `result.json` lands on disk. A fresh session runs `status`, finds the unconsumed result, picks up where it left off |
|
||||
| Machine rebooted | Handle file is gone (correct), session dir survives, `--resume` works |
|
||||
|
||||
---
|
||||
|
||||
## 4. The interaction contract
|
||||
|
||||
### 4.1 Item envelope
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"id": "i7", "topic": "t2", "kind": "choice",
|
||||
"title": "Export format", // PLAIN 2-4 words, never internal jargon
|
||||
"body": "markdown: the probe plus its why-it-matters",
|
||||
"options": [ { "k": "A", "text": "CSV", "detail": "trade-off", "recommended": true } ],
|
||||
"allowOther": true,
|
||||
"required": true,
|
||||
"status": "open",
|
||||
"answer": null,
|
||||
"thread": [],
|
||||
"fallbackText": "the exact terminal phrasing",
|
||||
"token": { "A": "a", "B": "b" } // maps a click back to the literal reply
|
||||
}
|
||||
```
|
||||
|
||||
Note `recommended` is **optional per option**. Handoff explicitly wants its inferred task offered as the recommendation; the `.gitignore` question in handoff explicitly does not ("present it, don't force it").
|
||||
|
||||
### 4.2 Primitives
|
||||
|
||||
Tier 1, needed for pathfinder and plan, build now:
|
||||
|
||||
| Kind | Covers |
|
||||
| --- | --- |
|
||||
| `choice` | Step 0 intent gate, all six destination probes, the 14 frontier axes, plan's coverage and scope questions |
|
||||
| `multi` | plan's testing types (Unit / Integration / E2E / None) |
|
||||
| `text` | sacrificial boundary, the embarrassment question, kebab-case feature name **with live pattern validation the terminal cannot do** |
|
||||
| `confirm` | the Tier-2 sketch gate, the lock offer, abort confirmations |
|
||||
| `recap` | the recap-and-confirm turn. Non-skippable by design |
|
||||
| `review` | plan's four approval gates, `1b`'s spec-update gate, paper-sketch reactions |
|
||||
| `checklist` | `legwork · HITL`: numbered steps plus Done / Blocked / Need help / Defer plus a values field |
|
||||
| `menu` | the fork menu: up to three takeable questions plus Start fresh, one recommended, with the resume command as copy-to-clipboard |
|
||||
| `list` | orderable and editable rows, for plan Phase 6's implementation phases |
|
||||
|
||||
Tier 2, design the schema to admit them but do not build yet: `findings-triage`, `table-review`, `form`, `path-picker`, `command-handoff`, `notice`, `progress`.
|
||||
|
||||
### 4.3 Rules the server enforces mechanically
|
||||
|
||||
Several prose rules become checks, which is the quiet advantage of routing through a server at all:
|
||||
|
||||
- **Reject a patch leaving more than three open required items.** Grilling says "the cap is three regardless of what the environment allows. The ceiling is the human's attention, not the tool's schema." A web UI tempts you to show ten. Make the rule mechanical.
|
||||
- **Reject internal jargon in `title`**: `grill`, `frontier`, `fog`, `HITL`, `Locked:`, `Blocked by:`. There is an explicit do-not-say list in `grilling.md`; this is where to enforce it.
|
||||
- **One authoritative gate per session.** `plan2code-3-implement-review` proves several prompts each carry an approval gate while only one may fire when composed. A `gate: { id, authoritative }` field plus a server guard.
|
||||
- **Defer is a third verb**, distinct from reject.
|
||||
- Reject forbidden tokens and bare confidence-word-plus-number patterns in anything written under `specs/`.
|
||||
- Stamp every timestamp server-side. Models do not reliably know the time.
|
||||
|
||||
---
|
||||
|
||||
## 5. The UI
|
||||
|
||||
Three panes, plus view tabs, closer to pathfinder's own vocabulary than to a grilling UI.
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────────┐
|
||||
│ 🧭 audit-export · Pathfinder · Working 4 of 9 cleared ▓▓▓▓░░░░░ │
|
||||
│ ● Waiting on you · 3 questions [Questions] [Map] [Draft] │
|
||||
├───────────────┬──────────────────────────────┬───────────────────────┤
|
||||
│ THE MAP │ What you end up with │ DISCUSSION │
|
||||
│ │ │ │
|
||||
│ ✓ Destination │ Why this matters: ... │ thread on this item │
|
||||
│ ✓ Codebase │ │ │
|
||||
│ ● Export fmt │ ○ A CSV, ... │ │
|
||||
│ ○ Size cap │ ◉ B Parquet RECOMMENDED │ │
|
||||
│ ⊘ Retention │ ○ C Both, ... │ │
|
||||
│ │ ○ Something else ______ │ │
|
||||
│ NOT YET CLEAR │ │ │
|
||||
│ · fog item │ Not sure, skip for now │ │
|
||||
├───────────────┴──────────────────────────────┴───────────────────────┤
|
||||
│ 2 staged · Export format → B · +1 comment ⌘↩ [Send to Agent] │
|
||||
└──────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### What to take from grill-with-ui
|
||||
|
||||
- **Batch staging with one explicit Send.** Everything is local and reversible until one deliberate press. For a non-technical user this removes the terror of "did I just commit to that?"
|
||||
- **The three-tier commitment vocabulary**: staged (amber, removable) → sent and pending (dashed, spinner) → recorded (green check). Honoured consistently on every surface.
|
||||
- **The whole stuck-agent apparatus**: live elapsed counter, disabled Send while working, a five-minute grace that re-enables Send with an explanation, server-gone detection with self-reconnect. About 40 lines, and more honest about agent latency than most commercial agent UIs.
|
||||
- **Assumed regions.** The best idea in that repo: the generated artifact marks regions that depend on still-open questions with a dashed outline and "assumed, pending Q3". This transplants directly onto a plan taking shape.
|
||||
- **Versioned artifacts with a staleness flag** and a one-line change note.
|
||||
- `withInputs()` focus preservation, raw-string diffing before re-render, and the `prefers-reduced-motion` handling that keeps progress indicators legible rather than freezing them.
|
||||
|
||||
### What to change
|
||||
|
||||
- **Topics, not rounds.** Grill groups the nav by round, which is a temporal artifact: "questions the agent happened to ask on turn 4". Its own sample data has one round containing three unrelated subjects. Product people cannot use that. Group by topic, stable and nameable.
|
||||
- **Show real progress.** Grill has no "N of M" counter at all. Pathfinder's trail footer already computes `4/9 cleared` and a plain-English confidence line. Put both in the header. In a 45-minute session with a PM, "how much longer is this" is the first question asked.
|
||||
- **Recommendations become optional.** Grill always leads with one, which is right when the agent has an opinion and you are pushing on it. In discovery the agent frequently should not have an opinion, and pre-filling one anchors a PM into rubber-stamping. Neutral mode: no `rec`, or reframed as "what similar products do".
|
||||
- **Real, accessible form controls.** Grill's options are `<li>` with `onclick`, so they are unreachable by keyboard and invisible to screen readers. Non-negotiable to fix if non-technical stakeholders are in scope.
|
||||
- **Markdown actually renders.** Grill escapes everything and sets `white-space: pre-line`; there is no markdown at all. A plan document cannot be shown that way.
|
||||
- **Rename everything.** "Grill", "durable", "Defer", "Reopen", "Why A." is a vocabulary for interrogating an engineer who already has a plan.
|
||||
- **Do not dim rejected options to 45%.** In discovery the rejected options are often the most valuable thing in the room, and an engineer joining late needs to see why B lost.
|
||||
|
||||
### Two things the console unlocks that the terminal cannot
|
||||
|
||||
- **Tier-2 UI sketches.** `resolve.md` already sanctions building 3 to 5 structurally different UI variants switched by "a URL search param plus a small floating bar". The console can host them in a sandboxed iframe with a proper variant switcher. This is already in the methodology and currently awkward.
|
||||
- **Anchored reactions.** `resolve.md` insists every sketch probe "names its row or element". With `anchors: { "row5": "b3" }`, clicking the probe highlights the row. That is the inline-commenting capability, scoped to something the methodology already demands.
|
||||
|
||||
### Room-screen polish (v2.4.0)
|
||||
|
||||
Built for a mixed product and engineering room reading one screen together.
|
||||
|
||||
- **One width variable.** `--card-width` on `:root` in `app.css` sets the column the card, the pager and the document tabs share (`max-width: min(var(--card-width), 100%)`, so a narrow window still wins); no fixed `720px` column rule is left outside a media query. Three presets, picked under *Card width* in the looks panel and saved as `looks.width`: `narrow` 720px, `comfortable` 880px (the default, and the variable's own value), `wide` 1080px, applied as `:root[data-width="…"]`. `CARD_WIDTHS` in `palette.js` is the same list for the page's validation and the server's first-paint `data-width`; **`palette.js` and `app.css` must agree**, which is the one place the number is written twice. The dashboard keeps its own 860px layout. Inside the card the `62ch` / `68ch` measure caps come off (`.card .md, .card .prompt { max-width: none; }`) so a wider card is not a narrow column in a wide frame; documents keep `.md`'s 68ch.
|
||||
- **One box grows.** On the primary card, the answer box that is being typed in — a `text` question's box, a choice's *Something else* box once picked, or the note under a verdict / confirm / recap once shown — is `textarea.grow`, and the card takes the column's full height above the pager (`.card.is-primary.has-grow { flex: 1 1 auto; }`). `fitGrowBox()` in `app.js` writes the card's free height as the box's `min-height`, **never under 160px**; a `ResizeObserver` watches the main column rather than the box, so the box growing can never retrigger it, and it writes only on a change over 1px. `resize: vertical` with that moving floor makes the handle taller-only; past the fill the card scrolls. Every other box keeps its ordinary size, and the notes panel is untouched.
|
||||
- **A switch per sound.** Every cue is an event in `SOUND_EVENTS` (`palette.js`), each naming its file and rank: `startSkill` (`start-skill.mp3`, played once the dashboard's **Start** is accepted) 5, `bootup` 4, `sessionStart` / `sessionEnd` (`start-stop.mp3`) 3, `question` / `skillReady` / `chatReply` (`next.mp3`) 2, `newTab` (`insert.mp3`) 1, `snore` (`sleeping.mp3`, looped by the wake-up outside the queue) 0. The queue, the held slot and the one-at-a-time rule in `app.js` work on events, one `Audio` per file shared by the events that use it. User Preferences shows a *Play sounds* master (`looks.sound`) over one box per event, saved flat as `sound<Event>` (`soundStartSkill`, …) because `looks.json` only holds flat values; `soundPrefs()` turns any missing or non-boolean switch on, so a file from before the switches keeps every sound. A cue plays only while the master and its own switch are both on; the master off greys the boxes but keeps their ticks, and ticking a box plays it.
|
||||
- **Send breathes.** `#btn-send:not(:disabled)` runs `send-pulse`, a soft accent ring that spreads and fades every 2.4s; a disabled Send is still, and reduced motion switches it off.
|
||||
- **Per-tab scroll memory.** An in-memory `Map` keyed by view id holds the scroller's position (the main column on a document or the Overview, the card on the questions view, with the item it belonged to), restored when the tab comes back. Page-local, never persisted, cleared when the session turns into or out of the dashboard.
|
||||
- **The Overview tab.** Appears only while `GET /overview` returns a file for the session's spec (on the dashboard: the picker's spec; gone for *start from scratch*), fetched with `no-store` on load, on a spec change and on every tab click, so it always shows the file as it is on disk. Rendered through the same DOM-only markdown path as every doc, captioned read-only. It never becomes a doc: the page is not the record.
|
||||
- **The footer slot.** The workspace label sits centred in the footer's middle track, 12px and muted: `footerLabel()` in `public/workspace.js` builds `folder · branch` (from the workspace's original folder and `state.branch`), or `folder + N folders · branch` once folders are added, and `renderWhere()` steps down through its narrower tiers (`FOOTER_TIERS`) until the text fits. A warning dot marks a missing or unreadable folder. A click opens the Workspace dialog (`#workspace-modal`), where each folder has its own **Copy path**. The notification pill is fixed over the same spot and covers it while it shows, on purpose: nothing there needs pressing while the pill is up. The dashboard keeps the footer for this label alone: `renderFooter()` puts `is-dash` on it, which hides the summary and Send (and on a narrow screen keeps the label, the one thing left in the bar); the footer only disappears there when there is no label to show.
|
||||
- **The wake-up.** A fresh dashboard (`state.wake`, plus a per-sid `sessionStorage` guard) plays Planny powering on centre stage, as proven in `pathfinder/sketch-01`. The wake layer hides the dashboard behind a solid `var(--bg)` backdrop (`.wake::before`, so it follows the theme) whose opacity fades out over the same 0.6s as the glide, revealing the menu as he lands; the notification pill (`.banner`, z-index 46) stays above the layer (45). Before the first click or key he sleeps there on loop under a "Click to wake Planny" hint (`.wake.dormant`): Z's rising, slow breathing, slack arms swaying out of step, his feet pulsing like a standby light. While he sleeps the page tries to loop `sleeping.mp3` (browsers usually refuse until the first click, so this is normally silent). That click fades the hint and nudges him (`.wake.stirring`): he rocks gently about his feet (`wake-nudge`) while exactly one snore plays from the top, via the `stir()` callback `playWake()` awaits — timed by the snore's `ended`, capped at 6s, or a 2.6s timer when sounds are off or refused. Then the boot starts to `bootup.mp3` (in place of the opening chime; outranked only by the Start-skill cue, which cannot coincide with it because the wake layer swallows every click and key until the run ends), which fades out over 0.5s the moment the run ends or is aborted. The boot pops the Z's outward: 0.4s power-on and his feet blink · 1.35s feet plant · 1.5s / 1.9s arms lift off his sides · 2.5s the star opens lit, with a scan · 2.85s he glances left, right, then ahead · 3.2s smile · 3.6s hop and a cheer, star back to ink · 4.3s a 0.6s glide into the rail, measured once by `boot.js` and handed to CSS as `--wake-glide` · the menu groups rise in 60ms apart as he lands, and the note types in. Done by 5s (a fallback timer covers a hidden tab whose transition never fires). The beats are CSS keyframes on delays under `.wake.booting`, all inside `@media (prefers-reduced-motion: no-preference)`; there is no skip: from the waking click on, clicks and plain keys (no Ctrl/Meta/Alt) are swallowed so the nudge, boot and sound always play out; only a launch mid-run aborts it (snore stopped, boot-up faded), and under reduced motion `playWake()` resolves at once and the awake dashboard is simply there.
|
||||
|
||||
---
|
||||
|
||||
## 6. The startup question
|
||||
|
||||
Both prompts open with one ask. Pathfinder already uses `AskUserQuestion`, so this costs almost nothing:
|
||||
|
||||
> Run this session in the **web console** (a local page in your browser, better for walking through decisions with someone) or **here in the terminal**?
|
||||
|
||||
Recommended default is an open decision (see §8). Because the markdown files stay the source of truth, the user can switch either way mid-session at no cost, and the prompt should say so.
|
||||
|
||||
---
|
||||
|
||||
## 7. Work plan
|
||||
|
||||
| # | Task | Notes |
|
||||
| --- | --- | --- |
|
||||
| 0 | **Trim `plan2code-0-pathfinder.md` by ~250 characters** | Hard prerequisite. 5 characters of headroom today. Candidates: the `grilling.md` fallback blockquote, the Rules list. |
|
||||
| 1 | `src/web-console/` skeleton: `console.mjs` start/wait/status/stop, detached spawn, handle file, reap sweep | The transport is the risky part, build and prove it first |
|
||||
| 2 | `server.mjs`: the six security controls, SSE, atomic result write with Windows `EPERM` retry | |
|
||||
| 3 | `index.html` + `app.js` + `app.css` + vendored `marked` lexer, token-to-DOM renderer | |
|
||||
| 4 | Tier 1 primitives, staging, drafts, Send | |
|
||||
| 5 | `console.md`: the agent contract | The only file the prompts point at |
|
||||
| 6 | `SOURCE_PROMPTS` entries + `npm run build:skills` + commit `skills/` | Zero installer code changes |
|
||||
| 7 | Pathfinder integration: startup ask, channel rule, `Read` line | ~250 chars, funded by task 0 |
|
||||
| 8 | Plan integration | 324 chars headroom, fits, trim ~150 for margin |
|
||||
| 9 | CHANGELOG + `version.json` + `package.json` in lockstep | `plan2code-publish` refuses to release on mismatch |
|
||||
|
||||
### Three things most likely to bite during implementation
|
||||
|
||||
1. **Forgetting `windowsHide: true` on the detached spawn.** It defaults to `false`, and `detached` on Windows forces a console window that "once enabled, cannot be disabled". Every handoff flashes a black box at the user.
|
||||
2. **`fs.rename` `EPERM` from antivirus and search indexers on Windows.** Intermittent, unreproducible on demand, looks exactly like a logic bug. Retry three times with backoff from day one.
|
||||
3. **Relying on `SIGTERM` for cleanup on Windows.** It does not arrive. Build the idle deadline first, not last, and comment why.
|
||||
|
||||
### Non-obvious portability notes
|
||||
|
||||
- grill-with-ui's heredoc idiom (`patch <<'EOF'`) is **not portable to PowerShell**, which is the default shell for Claude Code on Windows. Use a `--file <path>` form as the primary documented interface.
|
||||
- `nohup ... &` is bash-only. Backgrounding happens inside `console.mjs start`, never in the shell command the agent writes.
|
||||
- Always emit `node "<abs>/console.mjs"` quoted. Install paths contain spaces.
|
||||
|
||||
---
|
||||
|
||||
## 8. Open decisions
|
||||
|
||||
1. **Default channel.** Terminal (lower ceremony for an engineer working solo) or console (better for the cross-functional sessions that motivated this)? Recommendation: console marked as recommended in the ask, terminal as the low-ceremony alternative.
|
||||
2. **Vendoring `marked`.** It is MIT and dependency-free, but it is the first vendored third-party code in the repo, against a house style of "Node built-ins only". The alternative, a hand-rolled parser, is materially worse on both correctness and security. Recommendation: vendor it, pin the version, record the SHA-256.
|
||||
3. **Single-driver or multi-user.** Everything above assumes one browser, one driver, no identity or attribution. A facilitated workshop with one person at the keyboard works fine. Two people answering independently is a different product and reaches into the state model. Recommendation: single-driver for v1, say so explicitly.
|
||||
4. **Third consumer.** After pathfinder and plan, `/plan2code-review` is the strongest case: two of its rules exist only because output goes to a terminal ("for 15+ findings, present top 10", "output tables as direct markdown, NOT inside code blocks") and a browser deletes both. Its `S 1,3,5` fix selection is literally a checkbox list compressed into a CLI token, and one findings UI serves both `/plan2code-review` and `/plan2code-3-implement-review`.
|
||||
|
||||
---
|
||||
|
||||
## 9. Honest assessment of size
|
||||
|
||||
This is not a weekend. Rough shape: `console.mjs` plus `server.mjs` around 700 to 900 lines, the client around 900 to 1,200, the contract file 300 to 400 lines of prose, plus the prompt trims and build wiring. The transport and lifecycle work (tasks 1 and 2) is where the risk concentrates, and it is worth proving end to end on one primitive before building the other eight.
|
||||
|
||||
A smaller first cut that still tests the whole idea: pathfinder only, `choice` and `text` and `recap` only, no artifact pane. That exercises the transport, the token mapping, the fallback path and the three-probe cap, which are the parts most likely to be wrong.
|
||||
|
||||
---
|
||||
|
||||
## Credits
|
||||
|
||||
The architecture owes a large debt to `grill-with-ui`, whose file-ownership model, staged-then-send interaction, commitment tiers and assumed-region idea are all borrowed here. The implementation is independent.
|
||||
@@ -0,0 +1,672 @@
|
||||
# The Web Console
|
||||
|
||||
A local page in your browser for working through a Plan2Code session instead
|
||||
of answering everything in the terminal. Every skill has one — and `/plan2code`
|
||||
is the front door: it opens a dashboard of all of them, and whichever you pick
|
||||
starts right there on the same page.
|
||||
|
||||
It exists because the hardest part of adopting Plan2Code is not the engineering.
|
||||
It is getting the person who actually knows what the product should do into the
|
||||
room. Pathfinder and Planning are the two steps where that person matters most,
|
||||
and they were the two steps that looked like a wall of terminal text.
|
||||
|
||||
---
|
||||
|
||||
## What you get
|
||||
|
||||
- **Every question laid out**, with the trade-offs written next to each option
|
||||
instead of scrolling past in your history.
|
||||
- **A progress bar.** "4 of 9 settled" answers the first thing anybody asks.
|
||||
- **Previous and Next under each card**, walking the questions still waiting, so
|
||||
the list on the left is somewhere to jump from rather than the only way round.
|
||||
- **An example you can accept.** Where a question comes with one, an *Autofill
|
||||
suggestion* button puts it in the box as a real answer for you to edit. It
|
||||
disappears as soon as you have typed anything of your own.
|
||||
- **Answers you have settled read as answers**, not as a form you might still be
|
||||
able to change: what you chose, stated in words, with everything else locked.
|
||||
- **A question you have sent is held** until Plan2Code answers it, showing
|
||||
what you sent. The rest of the page carries on working, so you can read ahead
|
||||
or answer the next question while you wait.
|
||||
- **The document taking shape**, in a tab, with the parts that are still guesses
|
||||
clearly marked as guesses.
|
||||
- **A brief, on demand** (Pathfinder). Press *Write a brief*, choose how far back,
|
||||
and what comes back is a plain-English report of what has been decided, what is
|
||||
still open and what happens next, in its own tab with Print and Save buttons.
|
||||
It is the thing you take to a meeting.
|
||||
- **Nothing is sent until you press Send.** Everything before that is local and
|
||||
reversible, so nobody has to worry about committing to something by accident.
|
||||
- **Nothing gets lost.** Close the tab, reload, restart your machine: your
|
||||
half-typed answers are still there. Once you press Send, what you sent is
|
||||
held until Plan2Code actually collects it, so it cannot be written over.
|
||||
- **It tells you when the other half stops listening.** The terminal and this
|
||||
page are two programs that fail separately, and a page that sat there saying
|
||||
"one moment" forever was the worst way to find that out. Now it says so, and
|
||||
says what to do: answering anyway still works, because what you send is held
|
||||
on disk until something comes for it.
|
||||
- **Starters picked for your role.** Tell *User Preferences* what you do
|
||||
(engineer, product lead, architect, designer, QA, engineering manager) and
|
||||
the starter templates on an idea card and the starter questions on the Ask
|
||||
tab put the most useful ones first. It changes the order, never the
|
||||
questions a skill asks (see *Your role* below).
|
||||
- **Light or dark, and a highlight color you pick.** The swatch button at the
|
||||
top right opens *User Preferences*: your role first, then these. It follows
|
||||
your system by default; set it to one or the other if
|
||||
you would rather it stayed put. Remembered on your machine, so it carries
|
||||
over to every session.
|
||||
- **A card as wide as you want it.** The same swatch panel has a *Card width*
|
||||
setting — **Narrow** (720px), **Comfortable** (880px, the default) or
|
||||
**Wide** (1080px) — that widens the question card, the Previous / Next pager
|
||||
and the document tabs together. The dashboard keeps its own layout, and on a
|
||||
small window the column simply fits the window. Remembered with the colors,
|
||||
so it follows you into every session.
|
||||
- **Text that uses the card.** A question's text runs the full width of the
|
||||
card rather than stopping in a narrow column, and the answer box you are
|
||||
typing in grows to fill the card's free height: the box of a text question,
|
||||
the *Something else* box once you pick it, or the note under a verdict,
|
||||
yes/no or recap once it shows. Other boxes stay small. Drag the handle to
|
||||
make it taller; it never shrinks below the space it was given, and on a short
|
||||
window the card scrolls instead of squeezing the box under 160px.
|
||||
- **Send tells you it is ready.** While there is something to send, the Send
|
||||
button pulses gently; it goes still when there is nothing to send.
|
||||
- **Each tab remembers where you were.** Scroll halfway down a document,
|
||||
jump to the questions, come back: you are where you left off. The same goes
|
||||
for a long question card. It lasts as long as the tab is open.
|
||||
- **The spec's overview, one click away.** When the session is working on a
|
||||
spec that has an `overview.md`, an **Overview** tab shows it — read-only,
|
||||
and read fresh from disk each time you open the tab, so an edit shows up
|
||||
straight away. No file, no tab. On the dashboard it follows the spec picked
|
||||
at the top, and disappears for *start from scratch*.
|
||||
- **Where you are, at the bottom.** The footer names the folder the session
|
||||
was launched from and its git branch (`plan2code · feature/…`), muted in
|
||||
the middle. Click it to open the Workspace dialog (see *Your workspace*).
|
||||
Outside a git repo it shows only the folder.
|
||||
- **A chime when it's your turn.** The page plays a sound when new questions
|
||||
arrive, when a new tab (a document, the overview) joins the strip, and when
|
||||
the session opens or closes, so you can look away without missing your cue.
|
||||
Starting a skill from the dashboard plays its own sound too. The same panel
|
||||
has a *Play sounds* switch for all of them, and a box per moment (Planny
|
||||
snoring, Planny waking up, starting a skill, session opens, skill is ready,
|
||||
session ends, new questions, a reply on Ask, a new tab), so you can keep only
|
||||
the ones you want. Ticking a box plays its sound; everything is remembered
|
||||
like the colors.
|
||||
- **Files in your notes.** Show instead of describe: attach a screenshot, a
|
||||
photo or a document to any note or quick question (see *Attachments in notes
|
||||
and questions* below).
|
||||
- **A nudge when it might be waiting on you.** Your agent may stop in the
|
||||
terminal to ask permission for something, and the page cannot see that. So
|
||||
the dashboard and every starting screen carry a one-line tip about hands-off
|
||||
modes (`auto` mode in Claude Code, `smart` mode in Devin) that can cut down
|
||||
on those stops, though they may still need your attention, and when the agent
|
||||
has been working and silent for about 30 seconds, Planny's line asks
|
||||
*"Still working, or waiting on an approval in your terminal?"* — well before
|
||||
the three-minute "has not checked in" message.
|
||||
- **The tab icon says whose turn it is.** A bar along the bottom of Planny's
|
||||
favicon follows the line beside him: dashed amber while Plan2Code is
|
||||
working or picking up your answers, solid green when it is your move, solid
|
||||
red when it has gone quiet or the connection is lost (busy is dashed so the
|
||||
states differ by pattern, not only color). A finished session goes back to
|
||||
the plain icon, so a console left in a background tab can be checked at a
|
||||
glance.
|
||||
- **Help.** The **?** at the top right opens a Help dialog with 16 topics,
|
||||
one per tab down the left (across the top on a narrow window), opening on
|
||||
the one for where you are. It is part of the page itself, so it still reads
|
||||
fully when the page has lost its program.
|
||||
- Works offline, on your own machine only. No account, no install, no network.
|
||||
|
||||
## Using it
|
||||
|
||||
The easy way in is the dashboard:
|
||||
|
||||
```
|
||||
/plan2code
|
||||
```
|
||||
|
||||
A page opens with every skill laid out as cards — the setup pair, the pipeline
|
||||
in order, and the utilities alongside — with a note about what it made of your
|
||||
project (no AGENTS.md yet, a spec waiting on Phase 2) and a *Suggested* flag on
|
||||
the card it would pick. Click one and Planny flies while it gets ready; a few
|
||||
seconds later the same page is that skill's console, already running. No
|
||||
command names to remember.
|
||||
|
||||
A freshly opened dashboard starts with Planny asleep in the middle of the page.
|
||||
Click to wake him: he snores once while he gets a gentle shake side to side,
|
||||
then about five seconds of him powering on to a boot-up sound (arms lifting
|
||||
off his sides, his star opening, a hop and a cheer) before he glides into his spot at
|
||||
the top and the menu rises in. (Browsers stay silent until your first click,
|
||||
so the snoring usually starts with it; with *Sounds* off, the same wake-up
|
||||
plays without audio.)
|
||||
It plays only on a fresh `/plan2code`: not on a reload, not when you come
|
||||
back with **Back to the dashboard**, and not after a launch. Once he is
|
||||
stirring, another click or any key skips straight to the menu, and with reduced
|
||||
motion switched on in your system settings you get the awake dashboard at once.
|
||||
|
||||
Or start any step directly, as usual:
|
||||
|
||||
```
|
||||
/plan2code-init
|
||||
/plan2code-init-update
|
||||
/plan2code-0-pathfinder
|
||||
/plan2code-1-plan
|
||||
/plan2code-1b-revise-plan
|
||||
/plan2code-2-document
|
||||
/plan2code-3-implement
|
||||
/plan2code-3-implement-review
|
||||
/plan2code-quick-task
|
||||
/plan2code-review
|
||||
/plan2code-4-finalize
|
||||
/plan2code-handoff
|
||||
```
|
||||
|
||||
The first thing it asks is how you would like to work:
|
||||
|
||||
> **How would you like to work through this?**
|
||||
>
|
||||
> - **In your browser** (suggested)
|
||||
> - **Here in the terminal**
|
||||
|
||||
Pick the browser and a page opens at a `127.0.0.1` address, straight away:
|
||||
opening the page is the first thing the skill does, before it reads your
|
||||
project, so for the first few seconds you see a starting screen naming the step
|
||||
("Starting Pathfinder") while it gets its bearings — for the core steps, with
|
||||
Planny acting that step out. The questions replace it the
|
||||
moment they are ready. Answer what is there, press **Send to Plan2Code**, and
|
||||
it carries on. You can switch back to the
|
||||
terminal at any point by saying so: the files under `specs/` are the same either
|
||||
way, and neither side owns them.
|
||||
|
||||
While the page is open, the agent's messages in the terminal end with a
|
||||
pointer back to it — `→ Look at the web console: http://127.0.0.1:…` — and
|
||||
while it is waiting on you it says so in those words: *Waiting on your answer
|
||||
in the web console*. Glance at the terminal, and it always tells you where to
|
||||
look.
|
||||
|
||||
Know you want the page already? Pass `--web` with the command —
|
||||
`/plan2code-1-plan --web plan a lunch voting app` — and it opens the console
|
||||
without asking. The flag is dropped before the rest of the argument is read, so
|
||||
it never becomes part of the request.
|
||||
|
||||
Sharing the link with a colleague on another machine will not work, and that is
|
||||
deliberate. It is bound to your own machine only. To work through a session
|
||||
together, share your screen.
|
||||
|
||||
For the same reason, the browser page is only offered when the agent is running
|
||||
on your own machine. An agent working in a cloud VM, a container or over SSH
|
||||
stays in the terminal: a `127.0.0.1` link from somewhere else is a link you
|
||||
cannot open.
|
||||
|
||||
### Your role
|
||||
|
||||
The first control in *User Preferences* (the swatch button) is **Role**:
|
||||
Engineer, Product lead / PM, Architect / tech lead, Designer (UX), QA / test
|
||||
engineer, Engineering manager, or **Not set / none of these**, the default.
|
||||
It only reorders things: the starter templates on an idea card and the starter
|
||||
questions on the Ask tab. It never changes what a skill asks or does. It is
|
||||
kept in `looks.json` with your colors, so it follows you into every session,
|
||||
and **Back to default** sets it back to *Not set*.
|
||||
|
||||
Until you have chosen, the dashboard shows a one-line banner at the top —
|
||||
*Pick your role to get starter templates ordered for you.* — with **Set up
|
||||
preferences** and **Not now**. Choosing any role, *Not set* included, or
|
||||
pressing *Not now* puts it away for good.
|
||||
|
||||
### Starter templates
|
||||
|
||||
The first "What's the idea?" box in Pathfinder, Plan and Quick Task has a row
|
||||
of starter templates above it: **Blank** first, then outlines to fill in (an
|
||||
engineering spec, product requirements, a design decision, a bug
|
||||
investigation, and so on), in the order your role puts
|
||||
them. With a role chosen, the first one carries a *For your role* pill. Pick
|
||||
one and the box fills with editable text, `[blanks]` marked; if you have
|
||||
already typed something, a strip asks **Replace** or **Keep mine** first.
|
||||
Only what is in the box is sent, exactly as if you had typed it.
|
||||
|
||||
The templates live in the page (`public/starters.js`), not in the prompts. A
|
||||
skill only marks its fresh-idea card with `"templates": "idea"`, and `post`
|
||||
refuses that flag on anything but a `text` card. A resumed map or plan asks
|
||||
no idea question, so it shows no templates, and the terminal never has them.
|
||||
|
||||
### Leave for later (Pathfinder)
|
||||
|
||||
Pathfinder's scope question is **Leave for later** — *"Which of these features
|
||||
are we leaving out this time?"* It is a tick-any list of 3–5 features someone
|
||||
might expect, each ending with what leaving it out means ("Scheduled exports
|
||||
(Leaving this out = someone runs each export by hand)"), with a recommended
|
||||
set to tick in one go. The features you tick become the first lines of the
|
||||
map's *Out of scope*. Every option names a feature, never a rule to keep, so a
|
||||
tick always means "not this time".
|
||||
|
||||
### Skipping a question
|
||||
|
||||
**Skip this one**, on an optional question, now moves you straight on: the card
|
||||
reads *Skipped* for a beat (about a quarter of a second) and the next open
|
||||
question comes up. On the last one, focus goes to **Send to Plan2Code**
|
||||
instead. A click or a key press in that beat cancels the move. **Do not skip**
|
||||
on a skipped card brings it back.
|
||||
|
||||
### Your workspace
|
||||
|
||||
The folder label in the middle of the footer — `shop · main`, or
|
||||
`shop + 2 folders · main` once you have added some (shorter on a narrow
|
||||
window) — opens the **Workspace** dialog: the folders the agent uses as
|
||||
context for this console session.
|
||||
|
||||
- **The folder you started in** is always first. It can be renamed and given a
|
||||
description, but not removed.
|
||||
- **Add a folder** by pasting a path (`../shared-ui` counts from the folder
|
||||
you started in; `~` is your home folder) or with **Browse…**, which opens
|
||||
your system's own folder picker. Browse… is hidden when the page looks like
|
||||
it is being reached from another machine (SSH, a dev container, a
|
||||
Codespace). A path that is not a folder, one already in the list, and a name
|
||||
already taken are each refused with a message (a taken name comes with a
|
||||
**Use @name-2** button); a folder inside another one in the list is
|
||||
accepted, with a note.
|
||||
- **Every folder has an `@name`** (lowercase letters, numbers and hyphens) and
|
||||
an optional one-line *What is it?*. Type `@` in the Ask box, a note or a
|
||||
typed answer and a list of names pops up; the agent reads `@shared-ui` as
|
||||
that folder.
|
||||
- **What the agent does with them.** It is told the list when its session
|
||||
opens and each change once after that. Added folders are read-only
|
||||
reference: it reads them, reads each one's `AGENTS.md` (or `CLAUDE.md`)
|
||||
before first using it, and changes one only if you ask. Your harness may
|
||||
ask permission the first time it reads outside the project.
|
||||
- **Marks.** *This folder no longer exists* when it is gone from disk; *The
|
||||
agent can't read this yet* when the agent reported a failed read (in Claude
|
||||
Code with a copyable `/add-dir <path>` to run); *Inside another folder in
|
||||
the list* for a nested one.
|
||||
|
||||
The workspace carries across skills you start from the dashboard and back. A
|
||||
new console session starts with just the folder you started in.
|
||||
|
||||
### Session meter
|
||||
|
||||
A small ring pill in the top bar — **Session: fresh** (green), **Session:
|
||||
getting long** (yellow), **Session: time for a fresh start** (red) — counts the
|
||||
work this console session has done. Click it for the count and a **What is
|
||||
this?** link to Help.
|
||||
|
||||
Each skill run adds points (`WEIGHTS` in `public/meter.js`): Plan, Document,
|
||||
Review, Init and Init update 2; Revise plan, Quick task and Finalize 1; a
|
||||
Pathfinder map 2 and each question it resolves 1; an Implement phase 2, an
|
||||
Implement + Review phase 3; Handoff and the dashboard 0. A review run on the
|
||||
page after a quick task or a phase sign-off counts as a Review too. Green is
|
||||
under 4, yellow from 4, red from 6, and the ring is full at 8. At red the dashboard
|
||||
also shows a banner: starting a **new console session** keeps the agent sharp
|
||||
(resuming this one carries the count along). It is a rule of thumb, not a
|
||||
reading of the agent's real context, and it never blocks anything.
|
||||
|
||||
### While something is being built
|
||||
|
||||
Implementation, Implement + Review and a Quick Task spend most of their time
|
||||
building rather than asking, so the page shows the build instead:
|
||||
|
||||
- **What it is doing right now**, beside Planny ("Task 5 of 9: the rate
|
||||
limiter"), and the progress bar counting tasks done. Tasks are counted
|
||||
within the phase, to match the bar — the phase is already named in the
|
||||
headline — so you never see "Task 4.2 of 6"; the page rewrites that form if
|
||||
an agent still sends it.
|
||||
- **The phase's task list** in its own tab, ticking as each task lands on
|
||||
disk, and **the phase file itself** (`phase-3.md`) rendered in the next —
|
||||
the prerequisites and task specs, not just the checklist.
|
||||
- **Any question the build needs answered** (which phase, a spec conflict,
|
||||
failing tests) appears as an ordinary question, and the sign-off is a
|
||||
**Completion report** tab with an *Approve this phase* card.
|
||||
- A long task is not mistaken for a stall. The build says how long it may go
|
||||
quiet, and the page only calls it stuck after that.
|
||||
|
||||
### Review before you approve
|
||||
|
||||
The *Approve this phase* card carries a **Review the code first** button beside
|
||||
the approval. Press it and the same session runs a focused code review of
|
||||
exactly the files the phase changed, before you are asked to approve anything.
|
||||
The findings come back as a tab, and a *Which to fix* card lists every one with
|
||||
its severity: tick the ones to fix (or use the *Critical and warnings* / *All
|
||||
of them* quick picks), press Send, and it fixes and re-checks them before the
|
||||
approval card comes back.
|
||||
|
||||
A quick task has no approval step, so its offer sits on the finished screen
|
||||
instead: a large **Review it now** button above the next step, with **No
|
||||
thanks, I am done** beside it. If the session has already closed, the button
|
||||
turns into the `/plan2code-review` command to run in the terminal.
|
||||
|
||||
Implement + Review shows neither: it reviews every phase before sign-off
|
||||
already.
|
||||
|
||||
### When a session ends
|
||||
|
||||
A finished session says so, and ends in one of three shapes:
|
||||
|
||||
- **A next step.** What happened, and the exact command to run next (with a
|
||||
Copy button) — the next phase, Finalize, a commit.
|
||||
- **All done.** Nothing is left to run, so there is no command to copy:
|
||||
*"All done, nothing left to run."* Init, Init update and Handoff end this
|
||||
way, and so do Review and Finalize when nothing landed that needs committing.
|
||||
- **Paused.** You pressed *Stop session*. The card names what was saved and
|
||||
gives the command that picks it up later. Nothing else is offered.
|
||||
|
||||
The first two also carry a **Back to the dashboard** button (beside the next
|
||||
step, or as the main button under "All done"). Press it and the same page turns
|
||||
back into the skill menu, in the same conversation, so the next skill starts
|
||||
right there. The agent keeps listening for it for about ten minutes after the
|
||||
session ends; after that, or once the session has closed, the button turns into
|
||||
the `/plan2code` command instead. That command is on both of these screens
|
||||
anyway, for starting the dashboard in a fresh conversation — the better choice
|
||||
after a long skill, since a fresh conversation starts with a clean context.
|
||||
|
||||
You don't have to finish first. On every skill but the dashboard itself, a
|
||||
small **triangle** pointing left, in your highlight color, sits beside *Stop
|
||||
session*. Press it, confirm, and the agent saves your place exactly as a stop
|
||||
would, with any answers you have ready going along. Then the page turns into
|
||||
the dashboard instead of showing a finish card. Pick the same skill again to
|
||||
carry on, or pick another one. Like Stop, it only works on your turn, and where
|
||||
nothing is saved yet (early in a plan) the confirm says what would be lost.
|
||||
|
||||
### Attachments in notes and questions
|
||||
|
||||
Any note, and any quick question on the Ask tab, can carry files, three ways:
|
||||
|
||||
- the **+ Attach file** button beside the box (pick one or more files),
|
||||
- **paste** a screenshot or a copied file straight into the box,
|
||||
- **drag and drop** files onto the notes panel or the Ask composer.
|
||||
|
||||
Two kinds are allowed:
|
||||
|
||||
- **Images.** Each is shrunk and re-encoded in your browser (JPEG, 2000 px on
|
||||
the long edge at most, phone-photo rotation kept) and shows as a thumbnail.
|
||||
- **Documents**: text, code and PDF (`.md`, `.txt`, `.json`, `.yaml`, `.csv`,
|
||||
`.log`, `.js`, `.ts`, `.py`, `.sql`, `.pdf` and the like), up to 10 MB each.
|
||||
They upload exactly as they are and show as a chip with the file type, name
|
||||
and size. The server checks the contents match the type (a PDF header, or
|
||||
UTF-8 text with no NUL bytes), and a document is never opened from the page.
|
||||
|
||||
Up to 5 attachments per note and 5 per question, images and documents counted
|
||||
together. Anything else (`.docx`, a file over 10 MB, a dotfile such as `.env`)
|
||||
picked or dropped is refused with a message naming the file; a paste only
|
||||
picks up the files it can attach, and leaves any text to paste as usual. Each
|
||||
file uploads straight away while you carry on typing, and sits in a tray with a
|
||||
remove button; removing one deletes its file. A failed upload offers retry or
|
||||
remove and holds back only that note, so the rest of your answers still send.
|
||||
|
||||
The files are stored with the session, in
|
||||
`~/.plan2code/console/sessions/<id>/uploads/`, never in your project, under a
|
||||
random name the server picks. When you send, each note is followed by one line
|
||||
per attachment:
|
||||
|
||||
```
|
||||
Note on Header row: Please keep the header row.
|
||||
Image: /home/sam/.plan2code/console/sessions/<id>/uploads/<uuid>.jpg (header.png)
|
||||
File: /home/sam/.plan2code/console/sessions/<id>/uploads/<uuid>.pdf (api-spec.pdf)
|
||||
```
|
||||
|
||||
and the agent opens those paths with its own file reader. Uploads from sessions
|
||||
untouched for 30 days are swept away the next time a session opens.
|
||||
|
||||
**Keeping the ones a spec cites.** When the agent is about to write a file
|
||||
under `specs/<idea>/` that links to one of your note attachments (a plan, the
|
||||
overview, a phase file, a Pathfinder question or the map), it first copies the
|
||||
attachment into `specs/<idea>/attachments/` with `console.mjs keep` and links
|
||||
the copy, so the spec still shows it after the session is swept. The copy is
|
||||
named `<slug of your file name>-<8 characters of the upload id>.<ext>`, so
|
||||
keeping the same upload twice reuses it. Attachments nothing cites stay in the
|
||||
session, and quick-question attachments are never kept. `keep` is run by the
|
||||
agent, in its own shell; the server itself still never writes into your
|
||||
project.
|
||||
|
||||
### Ask a quick question
|
||||
|
||||
The **Ask** tab, always the last tab, on the dashboard and in every skill,
|
||||
opens a **Quick question** chat. Ask anything about the project's files, or
|
||||
anything at all, without waiting for a card. The agent running the skill
|
||||
answers at its next check-in (in a build, after the task it is on), and the
|
||||
workflow carries on meanwhile. Asking never holds up a card send, and a card
|
||||
send never holds up a question.
|
||||
|
||||
- **Context only when you add it.** A question starts with no context, so it
|
||||
reads as a general question. **+ Add context**, beside *+ Attach file*,
|
||||
lists the last 3 places you visited (question cards, document sections, a
|
||||
spec picked on the dashboard) plus *This spec*; pick one and an *About: …*
|
||||
chip sits above the box. × removes it, and it clears after the question is
|
||||
sent.
|
||||
- **Starter questions.** An empty conversation offers a few questions to start
|
||||
from, chosen for the skill you are in and ordered by your role; the ones
|
||||
that need context appear once you have added some. Clicking one fills the
|
||||
box without sending it.
|
||||
- **Pictures.** The same as notes: the button, paste, or drag and drop, up to 5
|
||||
per question.
|
||||
- **Ten questions per conversation.** The `N of 10` counter is always in view.
|
||||
After the tenth is answered, **New conversation** starts a clean one. So does
|
||||
switching skills through the dashboard.
|
||||
- **Edits need your approval.** Ask for a change to a file and the agent
|
||||
replies with a summary and the list of files it would touch, with
|
||||
**Approve** and **Decline**. Nothing changes until you approve. Afterwards
|
||||
it lists what changed, with line counts, and nothing is committed. It never
|
||||
edits the running skill's own files under `specs/`, and a chat message never
|
||||
answers a card or moves the workflow on: that is what the cards are for.
|
||||
- **When you cannot send.** Two different lines explain it: "That's 10
|
||||
questions in this conversation" means start a new one, and "No agent is
|
||||
connected right now" means the session has finished or the agent has gone
|
||||
quiet, so resume it to ask. Either way the conversation above stays
|
||||
readable.
|
||||
|
||||
A reply that lands while you are on another tab puts a dot on **Ask** and
|
||||
chimes once (if sounds are on).
|
||||
|
||||
### Keyboard
|
||||
|
||||
| Key | Does |
|
||||
| --- | --- |
|
||||
| `Ctrl` + `Enter` (`⌘` + `Enter` on a Mac) | Send |
|
||||
| `Tab` / `Space` | Move between options and pick one |
|
||||
| In the Ask box: `Enter` / `Ctrl` + `Enter` (`⌘` + `Enter`) | `Enter` is a new line; `Ctrl` + `Enter` sends the quick question, never the cards |
|
||||
| `Esc` | Closes whichever dialog is open; on the dashboard, backs out of a pick |
|
||||
| In Help: arrow keys, `Home`, `End` | Move between topics (the arrows wrap). `Ctrl` + `Enter` does nothing inside Help |
|
||||
|
||||
Every control is a real button, radio or checkbox, so screen readers and
|
||||
keyboard-only navigation work.
|
||||
|
||||
---
|
||||
|
||||
## How it works
|
||||
|
||||
Nothing is installed. The skills ship a small zero-dependency Node server
|
||||
(`references/web-console/`), and the workflow step starts it when you say yes.
|
||||
|
||||
```
|
||||
agent server (detached) your browser
|
||||
| | |
|
||||
|-- open (binds the port, starts ->| |
|
||||
| the server AND the browser) ---|---------------------------->|
|
||||
|<-- http://127.0.0.1:PORT/s/TOK/ |<---- the page, first state -|
|
||||
| | already inside it |
|
||||
|-- post the first questions ----->|---- pushed to the page ---->|
|
||||
|-- wait --seconds 240 ----------->| |
|
||||
| (returns every 4 minutes with | |
|
||||
| progress, then waits again) |<---- you press Send --------|
|
||||
|<-- your answers -----------------| |
|
||||
```
|
||||
|
||||
The server runs detached rather than as a background task of the agent, because
|
||||
agent background tasks get killed at various timeouts, and that would take your
|
||||
half-finished answers with them.
|
||||
|
||||
**It is built to show you something fast.** A browser takes most of a second to
|
||||
turn up after it is asked, so `open` binds the page's port itself and sends the
|
||||
browser there before the server has even finished starting; the server takes
|
||||
the port over a moment later, and the browser's request waits for it rather
|
||||
than being refused. The page arrives with the session already inside it, so it
|
||||
draws the real screen without asking for anything first, in your own theme and
|
||||
colors from the first frame. On a Windows laptop the page is in front of you in
|
||||
roughly the time the browser itself takes to open.
|
||||
|
||||
**It stays up while the page is open.** The page pings it every few seconds, so
|
||||
the idle clock never runs down while you are there. Close the tab and it shuts
|
||||
itself down about two minutes later; it stops after four hours regardless, and
|
||||
the agent stops it outright when the session ends.
|
||||
|
||||
That also means **the server routinely outlives the agent**. It is the agent, not
|
||||
the server, that reads your answers, and the two fail separately. The page tells
|
||||
the two apart: the **?** button at the top right opens Help, whose *What this
|
||||
page is* tab says which halves are talking right now (and *When something
|
||||
looks stuck* covers what to check), and Planny stops looking busy once
|
||||
nothing is listening rather than spinning at you indefinitely.
|
||||
|
||||
**State lives in three places**, and none of them is your repository (the one
|
||||
exception being the note attachments the agent keeps for a spec, above):
|
||||
|
||||
| Where | What | Survives |
|
||||
| --- | --- | --- |
|
||||
| `~/.plan2code/console/sessions/<id>/` | the questions, your draft, your answers | 30 days after the session was last touched |
|
||||
| `~/.plan2code/console/sessions/<id>/workspace.json`, `ledger.ndjson`, `workspace-cursor.json` | the workspace's folders (paths, names, descriptions — never their contents), the session meter's events, and how far the agent has been told of workspace changes. Kept beside the session, so they outlive every dashboard hop | with the session |
|
||||
| `~/.plan2code/console/sessions/<id>/uploads/` | images and documents attached to notes and quick questions | 30 days after the session was last touched |
|
||||
| `~/.plan2code/console/looks.json` | your role, theme, colors, sounds and card width | always |
|
||||
| your system temp directory | the port, process id and session token | until reboot |
|
||||
|
||||
Each of the workspace and meter files has exactly one writer: the server owns
|
||||
`workspace.json` (the page changes it only through the `/workspace` routes
|
||||
under Security), and `console.mjs` owns `ledger.ndjson` and
|
||||
`workspace-cursor.json`. The meter's count is never stored; it is folded from
|
||||
the ledger every time (`public/meter.js`), so a repeated `post` never counts
|
||||
twice. The logic lives in small pure modules the tests import directly —
|
||||
`public/workspace.js` (names, the footer label, the change lines the agent
|
||||
reads), `public/meter.js` and `public/mentions.js` (the `@name` popover) — and
|
||||
**Browse…** runs the per-OS picker in `picker.mjs`, copied from the
|
||||
`plan2code` launcher and kept in step with it by a test.
|
||||
|
||||
**Old sessions clean themselves up.** Each time a session opens, whole session
|
||||
folders nobody has touched for 30 days are deleted — questions, drafts,
|
||||
answers, uploads and all, paused or not — along with stray scratch files
|
||||
(`.json` / `.mjs`) left at the top of `~/.plan2code/console/` for as long.
|
||||
Your `looks.json` and the `console-dir` pointer are never touched, and neither
|
||||
is the session being opened. Nothing of value goes with them: the page is
|
||||
never the record, `specs/` in your project is.
|
||||
|
||||
### Recovering from things going wrong
|
||||
|
||||
| What happened | What to do |
|
||||
| --- | --- |
|
||||
| You closed the tab | Open the link again. Everything is where you left it. |
|
||||
| The link stopped working | Tell the agent. It restarts the session and gives you a new link. |
|
||||
| Your agent session died while you were mid-answer | Press Send anyway. Your answers are written to disk and are never discarded, including when the session is restarted. The next session picks them up. |
|
||||
| The page says Plan2Code is not running | It has not checked in for a few minutes. Look at the terminal: it may have finished its turn, hit an error, or be waiting on you there. Answering here still works, and what you send is held for it. |
|
||||
| You are not sure anything is connected | The **?** at the top right opens Help. Its *What this page is* tab says what keeps the page alive and whether both halves are talking at that moment, and *When something looks stuck* covers what to check. |
|
||||
| You would rather use the terminal after all | Say so. Nothing is lost. |
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
It is a local dev server that reads files in your project (never writing to it)
|
||||
and keeps its own state in your home folder, so it is built to be boring about
|
||||
this:
|
||||
|
||||
- Bound to `127.0.0.1` only, never `0.0.0.0`. Not reachable from your network.
|
||||
- A `Host` header allow-list, which is what stops a website you happen to be
|
||||
visiting from talking to it through a DNS rebinding trick.
|
||||
- A 128-bit token in the link, swapped for an `HttpOnly; SameSite=Strict` cookie
|
||||
on first load so it leaves your address bar, your history and any screenshot.
|
||||
- A strict Content Security Policy with no inline script allowed.
|
||||
- Markdown written by the agent is turned into page elements directly and never
|
||||
into an HTML string, so a document that quotes a hostile README cannot run
|
||||
anything. It shows up as text, which is what it is.
|
||||
- Uploads are named by the server (`<uuid>.jpg`, or `<uuid>.<ext>` with the
|
||||
extension taken from the allow-list, via `crypto.randomUUID()`), never by the
|
||||
file name you sent, and live only under the session's own `uploads/`. The
|
||||
server checks the bytes: a JPEG header for images (4 MB cap), and for
|
||||
documents a `%PDF-` header or strict UTF-8 with no NUL byte (10 MB cap).
|
||||
Documents are never served back to the browser. A send may only point at
|
||||
uploads inside that session's `uploads/`, images in `images` and documents
|
||||
in `files`.
|
||||
|
||||
### Routes
|
||||
|
||||
The upload routes, the send, the overview read and the workspace. Like every page route, they are on `127.0.0.1`
|
||||
behind the session cookie, and the ones that write also check the request's
|
||||
origin.
|
||||
|
||||
| Route | Does |
|
||||
| --- | --- |
|
||||
| `POST /upload` | Raw bytes, original name in `x-p2c-name`. `Content-Type: image/jpeg`: writes `uploads/<uuid>.jpg` and answers `{ ok, id, kind: "image", path, url, name, size }`; not a JPEG → 415, over 4 MB → 413. `Content-Type: application/octet-stream`: a document, its extension from the name's allow-listed extension; writes `uploads/<uuid>.<ext>` and answers `{ ok, id, kind: "file", path, name, size }` with no `url`; not an allowed extension or contents that do not match → 415 `type`, over 10 MB → 413. Any other content type → 415. |
|
||||
| `GET /uploads/<id>.jpg` | Serves an uploaded image (for the thumbnail after a reload). Only `<uuid>.jpg` names under `uploads/`; documents are never served (404). |
|
||||
| `DELETE /uploads/<id>.<ext>` | Deletes an image or document removed before sending. 204, or 404 if it is not there. |
|
||||
| `POST /submit` | The Send. A note may carry `images` and `files`, each `[{ path, name }]`: at most 5 together, images in `images` and documents in `files`, every path inside this session's `uploads/`, otherwise 400. |
|
||||
| `POST /chat` | A Quick question `{ text, about?, images?, files?, conversation }`, or `{ reset: true, conversation }` for New conversation. Appended to the session's `chat.ndjson`. 400 `too-long` (over 4,000 characters), `image`, `file` or `bad`; 409 `offline`, `stale` or `limit` (10 per conversation). Never refused because a card send is still uncollected. |
|
||||
| `POST /chat/decision` | Approve or Decline on an edit the agent proposed: `{ re, decision, text?, conversation }`. Once per proposal; does not count toward the 10. |
|
||||
| `GET /overview?spec=specs/<name>` | The Overview tab's read of `<spec>/overview.md`, as `text/markdown` with `cache-control: no-store`. On the dashboard `spec` must be one of the scanned specs; elsewhere the session's own spec is used. The file's real path must stay inside the project, so `../`, absolute paths and symlinks pointing out all get 404. |
|
||||
| `GET /workspace` | The Workspace dialog's list: folders, `missing`, `remote` and the agent's folder `issues`. `?check=1` re-checks every folder on disk first. |
|
||||
| `POST /workspace/add` | `{ path, name?, description? }`. The path is resolved against the folder the session started in (`~` expanded) and must be a folder: 400 `not-a-folder`, `duplicate` (with its `name`; compared case-insensitively on Windows and macOS), `bad-name`, or `name-taken` with a `suggest`. Answers the new entry, `nested: true` when it sits inside another folder in the list. |
|
||||
| `POST /workspace/edit` | `{ id, name?, description? }`. Renames or re-describes one folder: 400 `bad-name` / `name-taken`, 404 `unknown`. |
|
||||
| `POST /workspace/remove` | `{ id }`. 400 `original` for the folder the session started in, 404 `unknown`. |
|
||||
| `POST /workspace/browse` | Opens the system folder picker and answers `{ path }` or `{ cancelled: true }`; never adds anything itself. 409 `busy` while one is open, 404 `no-picker` when the session looks remote or no picker exists. |
|
||||
|
||||
## For maintainers
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Source | `src/web-console/` |
|
||||
| Ships as | `skills/<every skill>/references/web-console/` |
|
||||
| Wiring | one `additionalReferences` entry per skill in `install.js`; the dashboard's menu lives in `public/answers.js` (`SKILL_CATALOG`) |
|
||||
| Agent contract | `src/web-console/console.md`, plus `building.md` for the build steps |
|
||||
| Tests | `node --test scripts/test-web-console.mjs`, also run by `npm test` |
|
||||
| Start-up benchmark | `node scripts/bench-web-console.mjs` (needs `puppeteer-core` and a local Chrome or Edge for the paint columns; `--browser-delay 900` models a real browser launch, `--roundtrip` times Send→agent and post→page) |
|
||||
| Dependencies | none at runtime. `marked` 15.0.7 (MIT) is vendored for its lexer only |
|
||||
|
||||
Edit `src/` only. `skills/` is a committed build artifact: regenerate it with
|
||||
`npm run build:skills` and commit it with the source change, since `npm test`
|
||||
(via `--verify-skills`) fails when it drifts from `src/`.
|
||||
|
||||
### Driving it by hand
|
||||
|
||||
You do not need an agent to poke at the console. Point `PLAN2CODE_CONSOLE_HOME`
|
||||
somewhere disposable first, so you never touch a real session:
|
||||
|
||||
```bash
|
||||
export PLAN2CODE_CONSOLE_HOME=/tmp/p2c-play # Windows: $env:PLAN2CODE_CONSOLE_HOME
|
||||
|
||||
cat > /tmp/payload.json <<'JSON'
|
||||
{ "workflow": "pathfinder", "title": "Playing about",
|
||||
"items": [ { "id": "q1", "kind": "choice", "title": "Export format",
|
||||
"body": "Pick one.",
|
||||
"options": [ { "k": "A", "text": "CSV", "recommended": true },
|
||||
{ "k": "B", "text": "Excel" } ],
|
||||
"token": { "A": "a", "B": "b" } } ],
|
||||
"agent": { "status": "waiting" } }
|
||||
JSON
|
||||
|
||||
node src/web-console/console.mjs open --file /tmp/payload.json # prints the URL, opens the browser
|
||||
node src/web-console/console.mjs wait --session <sid> --seconds 60
|
||||
node src/web-console/console.mjs stop --all
|
||||
```
|
||||
|
||||
`node src/web-console/console.mjs help` prints the same command summary an
|
||||
agent gets when it finds the binary before the docs.
|
||||
|
||||
`wait` exits `0` with the answers, `10` if nobody has finished yet, `20` if the
|
||||
server died, `30` on Cancel. Pick `--seconds` to sit under whatever your harness
|
||||
allows a single command: it is a poller, so killing it costs nothing, and a
|
||||
collected result is printed before it is marked collected, which means an
|
||||
interrupted handover can only repeat itself, never lose an answer. `status`
|
||||
lists sessions and flags any whose answers were submitted but never collected.
|
||||
|
||||
When something misbehaves, the session directory is the whole story:
|
||||
`state.json` (what the agent published), `draft.json` (what the person has typed
|
||||
but not sent), `result.json` (what they sent), `events.ndjson` (an append-only
|
||||
log you can `cat`), and `server.log`.
|
||||
|
||||
Set `--idle-ms 60000` on `open` if you want the server to shut itself down
|
||||
quickly while experimenting.
|
||||
|
||||
Two environment variables help when the start is what you are looking at:
|
||||
|
||||
| Variable | Does |
|
||||
| --- | --- |
|
||||
| `PLAN2CODE_CONSOLE_TRACE=1` | `open` prints a timeline of its steps to stderr (roots found, server spawned, port bound, browser sent, state written, server listening). |
|
||||
| `PLAN2CODE_BROWSER` | The command that opens the link instead of the system default, run through the shell with the link appended, e.g. `PLAN2CODE_BROWSER='firefox --new-tab'`. |
|
||||
|
||||
Every `console.mjs` invocation also writes its own directory to
|
||||
`$PLAN2CODE_CONSOLE_HOME/console-dir` (or `~/.plan2code/console/console-dir`
|
||||
when the override is unset): it is how an agent finds the console on a later
|
||||
session without searching the skill install dirs.
|
||||
|
||||
The vendored file is `src/web-console/public/vendor/marked.esm.js`,
|
||||
sha256 `7a7d9a521ac9384e0c3a075120a7c486cbd0c3c32cc5601bbb79a23e97403690`.
|
||||
Only `marked.lexer()` is used; the rendering is ours, in `public/render.js`, and
|
||||
builds DOM nodes rather than HTML so nothing needs sanitising.
|
||||
Reference in new issue
Block a user