Refresh agent docs, README and quick reference for v2.4.x: document plan2code-bot, launcher model menu, test/dev env vars, full npm test pipeline, GitHub-issues pathfinder backend, and dedupe command lists in favor of the README

AI Assisted
This commit is contained in:
jparkerweb committed 2026-10-03 09:38:55 -07:00
1 parent 4a5f759173
commit 47c6129315
9 files changed
+144 -159

No files matched your search

+21 -66
View File
@@ -31,7 +31,7 @@ The dashboard, in a project halfway through a build. It suggests the next step f
## Install and start
Requires [Node.js](https://nodejs.org/) 18 or later and network access — installation runs through
the [skills CLI](https://skills.sh). Re-run any time to update.
the [skills CLI](https://skills.sh). To update, re-run the install command.
```bash
npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git
@@ -41,7 +41,7 @@ This fetches the installer to a temp directory, builds the workflow as Agent Ski
installation to `skills add`, and cleans up after itself. The installed skills work independently
from then on.
Either route lands you on the same menu:
The installer opens this menu (cloning and running `node install.js`, below, opens the same one):
```
╔═════════════════════════════════════════════════════════╗
@@ -59,7 +59,9 @@ Either route lands you on the same menu:
1. In any project, run `plan2code`. It starts Claude Code or Devin on the dashboard, and the
dashboard opens in your browser.
2. Pick a card.
2. In a project without an `AGENTS.md`, pick **Set up this project** first: Plan and Quick task
need it.
3. Pick a card.
Already inside your agent? Type `/plan2code` instead.
@@ -81,7 +83,7 @@ GitHub Copilot · Windsurf · Codex · Continue · Codeium · Zed · Amp · Open
Gemini CLI · Cline · Roo · Kilo · Goose · Trae · Qwen Code.
The installer keeps one canonical copy of each skill under `~/.agents/skills/` and links it into
agents that maintain their own directory. Update later with `npx skills update -g`.
agents that maintain their own directory. To update, re-run the install command.
Use the installer rather than calling `skills add` against the repository root: recursive discovery
would also find maintainer-only skills under `.claude/skills/`. The installer targets `skills/`
@@ -149,7 +151,7 @@ step in the same session.
```
┌╴╴╴╴╴╴╴╴╴╴╴╴┐
╎0 PATHFINDER╎ optional · new in 2.0 · for an idea too big or unclear to plan
╎0 PATHFINDER╎ optional · for an idea too big or unclear to plan
└╴╴╴╴╴╴┬╴╴╴╴╴┘
▼
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌╴╴╴╴╴╴╴╴╴╴╴╴┐ ┌────────────┐
@@ -204,42 +206,12 @@ what you meant.
## What lands in your repo
```
your-project/
├── specs/
│ └── task-api/ ← in progress
│ ├── pathfinder/ ← only if you charted it in Step 0
│ │ ├── map.md the destination, the decisions, the fog
│ │ ├── questions/NN-<slug>.md one decision per file
│ │ └── briefs/brief-<date>.md plain-English decision summaries
│ ├── PLAN-DRAFT-20260804.md ← Step 1: the verified plan
│ ├── PLAN-CONVERSATION-*.md ← Step 1: how you got there
│ ├── overview.md ← Step 2: phase list + parallel groups
│ └── Phase 1.md … Phase N.md ← Step 2: one-point tasks, self-contained
├── specs--completed/
│ └── auth-refresh/ ← Step 4 files finished work here
└── ...your code
```
Each feature gets a folder under `specs/` (the plan, the overview and one file per phase), and Step 4
moves it to `specs--completed/`. The layout and progress marks are on the
[quick reference](QUICK-REFERENCE.md#file-structure).
`specs/` is gitignored by default — it's your working drawing, not a deliverable. Share a folder
deliberately with `git add -f` when you want to.
### Progress marks
| Mark | Status | Meaning |
|------|--------|---------|
| `[ ]` | Open | Unclaimed. Any agent picks it up cold. |
| `[/]` | In progress | Claimed right now — which is how two agents run parallel phases without colliding. |
| `[x]` | Done | Built, self-reviewed against the spec, approved by you. |
```markdown
## Phases
- [x] Phase 1: Project setup
- [x] Phase 2: Data model
- [/] Phase 3: API endpoints ← an agent is on this now
- [ ] Phase 4: Authentication ← next available
```
Add `specs/` to your project's `.gitignore` (`plan2code-loop` adds it for you): it's your working
drawing, not a deliverable. Share a folder deliberately with `git add -f` when you want to.
Step 2 marks which phases don't share files. Open a second agent on one of those, and the `[/]` marks
keep the two out of each other's way.
@@ -251,7 +223,7 @@ keep the two out of each other's way.
Each step is its own run, and the specs on disk are the only thing carried from one to the next.
Chain a small one onto the last, or start a fresh session for a big one (rule 1).
### 0 · Pathfinder 🧭 — optional, new in 2.0
### 0 · Pathfinder 🧭 (optional)
On the page: one question at a time with the options and their trade-offs, the map growing in its own
tab, and a **Write a brief** button for a printable summary.
@@ -290,9 +262,10 @@ sub-issues) → `PLAN-DRAFT-<date>.md`. The draft is always a local file — tha
On the page: questions in batches of up to three, the phase breakdown as a list you can reorder and
edit, and a sign-off at each stage.
The agent works as a senior architect through six phases, stopping for you after each: requirements
analysis · system context (reading your actual codebase) · tech stack (needs your explicit sign-off) ·
architecture design · technical specification · transition decision.
The agent works as a senior architect through seven phases, stopping for you after each: requirements
analysis · system context (reading your actual codebase) · scope assessment (a large project saves and
resumes in a fresh session) · tech stack (needs your explicit sign-off) · architecture design ·
technical specification · transition decision.
It won't finalize below **90% confidence**, and every assumption it makes is written into the draft.
@@ -304,13 +277,13 @@ On the page: a question only where the plan leaves something open, each phase fi
own tab as it is written, and one sign-off at the end.
The plan becomes the drawing. One `overview.md` with the phase checklist, plus one file per phase of
one-story-point tasks. Each phase is **self-contained** — an agent opening `Phase 3.md` cold needs
one-story-point tasks. Each phase is **self-contained** — an agent opening `phase-3.md` cold needs
nothing else to build it. Unit and E2E tests are excluded unless you ask for them.
The overview also identifies the **parallel execution groups**: phases with no shared files or
dependencies, safe to run in separate agents at once.
**In:** the `PLAN-DRAFT`. **Out:** `overview.md` + `Phase 1…N.md`
**In:** the `PLAN-DRAFT`. **Out:** `overview.md` + `phase-1…N.md`
### 3 · Implement ⚡
@@ -355,19 +328,6 @@ like this.
---
## What to bring to each step
| Step | Required input |
|------|----------------|
| 0 · Pathfinder | Nothing to start — just describe the idea. To continue: the feature name; it finds its own map |
| 1 · Plan | Nothing — describe the feature |
| 2 · Document | `specs/<feature>/PLAN-DRAFT-<date>.md`, or the planning conversation |
| 3 · Implement | `specs/<feature>/overview.md` — it detects the phase itself |
| Review | Scope guidance, e.g. "the last two phases", "just the auth module", "the whole PR". Auto-detects if you give none |
| 4 · Finalize | `specs/<feature>/overview.md` |
---
## Prefer the terminal?
Every skill also runs right in the terminal. Each one asks at the start whether you want the web
@@ -417,17 +377,12 @@ the requirements.
**Too many or too few phases.** Fix it in Step 2 — a phase should be a logical grouping of work, not
a fixed size.
**The page says it lost contact with Plan2Code.** Nothing you typed is lost, and the page reconnects
by itself. If the link has stopped working, tell the agent: it restarts the session and gives you a
new link.
**The agent runs on another machine, or over SSH.** The page is served on `127.0.0.1` of the machine
the agent runs on, so your browser can only reach it there. A forwarded port often works; otherwise
work in the terminal, which loses nothing.
**You closed the tab.** Open the link again. Everything is where you left it, including answers you
had typed but not sent. The page's program stops about two minutes after the last tab closes, so
after that, ask the agent to resume the session for a new link.
**Web console problems** (lost contact, a closed tab, a dead link): see
[.readme/web-console.md](.readme/web-console.md#troubleshooting).
---