Add a Before you start block to the newcomer docs and a test to keep them in step

AI Assisted
This commit is contained in:
jparkerweb committed 2026-10-08 17:02:40 -07:00
1 parent b639c8945d
commit 3469a74cc1
12 files changed
+117 -25

No files matched your search

+1 -1
View File
@@ -15,7 +15,7 @@ node install.js
npm run build:skills
# Full check (about 70s): char limits, skills/ build, browser-module parse check,
# dashboard skill-table check, web console + launcher node:test suites
# dashboard skill-table check, web console + launcher + getting-started node:test suites
npm test
# One web console or launcher test
+1 -1
View File
@@ -25,7 +25,7 @@ hand, or the reverse — the checkboxes are the only handoff.
```bash
# From the plan2code root directory
node install.js # A (everything + dev tools) — or C → O (loop only)
node install.js # A → E (everything + dev tools) or A → O (loop only)
```
## Run
+1 -1
View File
@@ -16,7 +16,7 @@ One thing to remember: **collect after every finished spec.** Everything else is
```bash
# Install once, from the plan2code root
node install.js # A (everything + dev tools) — or C → M (metrics only)
node install.js # A → E (everything + dev tools) or A → M (metrics only)
# After finishing a spec (steps 1–4)
cd your-project
+1 -1
View File
@@ -36,7 +36,7 @@ The icons down the left are Planny, the project mascot.
## Install
```bash
node install.js # A (everything + dev tools) — or C → S (status line only)
node install.js # A → E (everything + dev tools) or A → S (status line only)
```
That copies the script to `~/.claude/plan2code-statusline.js`, writes a default config to
+1 -1
View File
@@ -19,7 +19,7 @@ Built for **maintainers**. If you're using Plan2Code to ship features, you don't
## Install
```bash
node install.js # A (everything + dev tools) — or C → B (bot only)
node install.js # A → E (everything + dev tools) or A → B (bot only)
```
## Run
+11
View File
@@ -7,6 +7,17 @@ Each session stays short, and the specs on disk carry everything from one sessio
---
## Before you start
- **Node.js 18 or newer.** Check with `node --version`. No Node? Get it from [nodejs.org](https://nodejs.org/) (the LTS download), or run `winget install OpenJS.NodeJS.LTS` on Windows, `brew install node` on macOS, or use `nvm` on Linux. Then open a new terminal.
- **Start from your project.** Open your terminal in the project you want to work on (`cd` into it) before you run anything. Plan2Code works on the folder you start it in.
- **Ways in.** `plan2code` (Claude Code, Devin or Codex), or type `/plan2code` in your agent (`$plan2code` in Codex).
- **No agent yet?** Install Claude Code, Codex or Devin first.
Not installed yet? The install steps are in the [README](../README.md#install-and-start).
---
## Session 1: Plan
Run `plan2code` in the project (or `/plan2code` inside your agent). The dashboard opens in your
+2
View File
@@ -10,6 +10,8 @@ Plan2Code is a structured 4-step workflow methodology for AI-assisted software d
**Author:** Justin Parker
**License:** MIT
Plan2Code is started from the project the person works in (`cd` into it, then run `plan2code`), not from this repository; every newcomer doc says so, next to the Node.js 18+ requirement.
## How to Use This File
This file is an index — each section below contains a brief summary and a link to a detail file in `.agents-docs/`. Read only the sections relevant to your current task. Full details (commands, tables, file lists) are in the linked files. The sections "Project Overview", "How to Use This File", "Mascot", and "Keeping this file current" / "Failure log" are fully inline here and are never split into `.agents-docs/`.
+9 -2
View File
@@ -1,13 +1,20 @@
# Plan2Code Quick Reference
## Before you start
- **Node.js 18 or newer.** Check with `node --version`. No Node? Get it from [nodejs.org](https://nodejs.org/) (the LTS download), or run `winget install OpenJS.NodeJS.LTS` on Windows, `brew install node` on macOS, or use `nvm` on Linux. Then open a new terminal.
- **Start from your project.** Open your terminal in the project you want to work on (`cd` into it) before you run anything. Plan2Code works on the folder you start it in.
- **Ways in.** `plan2code` (Claude Code, Devin or Codex), or type `/plan2code` in your agent (`$plan2code` in Codex).
- **No agent yet?** Install Claude Code, Codex or Devin first.
## Launch
The web console is the main way in: a local page where questions, documents, build progress and sign-offs live.
| How | Command | What happens |
| ------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
| From your project (shell) | `plan2code` | Opens Claude Code or Devin on the dashboard (`--cli claude` / `--cli devin` to choose) |
| Inside any agent | `/plan2code` | Opens the dashboard: a card for every skill, launched on the same page |
| From your project (shell) | `plan2code` | Opens Claude Code, Devin or Codex on the dashboard (`--cli claude` / `devin` / `codex` to choose) |
| Inside any agent | `/plan2code` (`$plan2code` in Codex) | Opens the dashboard: a card for every skill, launched on the same page |
| Install / update | `npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git` | Installs the skills and the `plan2code` command; re-run it to update |
| Straight into a skill | `/plan2code-1-plan --web` (any step) | Skips the "web console or terminal?" question and opens the page |
+19 -14
View File
@@ -30,8 +30,14 @@ 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). To update, re-run the install command.
### Before you start
- **Node.js 18 or newer.** Check with `node --version`. No Node? Get it from [nodejs.org](https://nodejs.org/) (the LTS download), or run `winget install OpenJS.NodeJS.LTS` on Windows, `brew install node` on macOS, or use `nvm` on Linux. Then open a new terminal.
- **Start from your project.** Open your terminal in the project you want to work on (`cd` into it) before you run anything. Plan2Code works on the folder you start it in.
- **Ways in.** `plan2code` (Claude Code, Devin or Codex), or type `/plan2code` in your agent (`$plan2code` in Codex).
- **No agent yet?** Install Claude Code, Codex or Devin first.
Installation needs network access and runs through 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
@@ -47,33 +53,32 @@ The installer opens this menu (cloning and running `node install.js`, below, ope
╔═════════════════════════════════════════════════════════╗
║ INSTALL PLAN2CODE ║
╠═════════════════════════════════════════════════════════╣
║ I. INSTALL Install Plan2Code skills everywhere ║
║ A. ALL Install Plan2Code + dev tools ║
║ U. UNINSTALL Remove Plan2Code skills and dev tools ║
║ C. CUSTOM Advanced options ║
║ I. INSTALL Install skills + the plan2code command ║
║ U. UNINSTALL Remove everything Plan2Code installed ║
║ A. ADVANCED Project install, dev tools, and more ║
║ Q. QUIT Exit ║
╚═════════════════════════════════════════════════════════╝
```
### Start
1. In any project, run `plan2code`. It starts Claude Code or Devin on the dashboard, and the
dashboard opens in your browser.
1. `cd` into your project, then run `plan2code`. It starts Claude Code, Devin or Codex on the dashboard,
and the dashboard opens in your browser.
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.
Already inside your agent? Type `/plan2code` instead (`$plan2code` in Codex).
<details>
<summary>About the plan2code command</summary>
The installer adds `plan2code` as a global command (Custom `C` → `D` adds just the command). Run it from any project and the Plan2Code
dashboard opens right there, in **Claude Code** or **Devin**. With both installed it asks which and
remembers your pick; `plan2code --cli claude` or `--cli devin` skips the question, and `--model <name>`
Install (`I`) adds `plan2code` as a global command (Advanced `A` → `D` adds just the command). Run it from any project and the Plan2Code
dashboard opens right there, in **Claude Code**, **Devin** or **Codex**. With more than one installed it asks which and
remembers your pick; `plan2code --cli claude`, `--cli devin` or `--cli codex` skips the question, and `--model <name>`
chooses the model. It works in cmd, PowerShell, Git Bash, macOS and Linux shells, and needs the
Claude Code or Devin CLI on your `PATH`. It starts the agent with permission prompts off
(`--permission-mode bypassPermissions` in Claude Code, `--permission-mode bypass` in Devin); run
Claude Code, Devin or Codex CLI on your `PATH`. It starts the agent with permission prompts off
(`--permission-mode bypassPermissions` in Claude Code, `--permission-mode bypass` in Devin, `--dangerously-bypass-approvals-and-sandbox` in Codex); run
`claude /plan2code` yourself if you want prompts. The installer then offers a desktop shortcut (answer `y`),
which opens a folder picker first. Uninstalling (`U`) removes both.
</details>
+24 -3
View File
@@ -112,6 +112,11 @@ h3 { font-size: 1.45rem; margin: 8px 0; }
.copy .tick { display: none; }
.copy.-done .clip { display: none; }
.copy.-done .tick { display: block; }
.before { margin: 0 auto 20px; max-width: 640px; text-align: left; background: var(--panel); border: 1px solid var(--rule-2); border-radius: var(--radius); padding: 14px 18px; font-size: 15px; }
.before h3 { font-size: 1.05rem; margin: 0 0 8px; }
.before ul { margin: 0; padding-left: 20px; color: var(--ink-2); }
.before li { margin: 4px 0; }
.before strong { color: var(--ink); }
.then { margin: 12px 0 0; color: var(--ink-2); font-size: 15px; }
/* Hero: centered headline, then the dashboard at full width. */
@@ -215,6 +220,14 @@ footer a { color: inherit; }
</svg>
<h1 id="hero-title">Plan and build with your AI agent, on one page.</h1>
<p class="lede">Plan2Code asks the questions, drafts the plan and builds it one phase at a time. You answer and approve in your browser, and the specs land in your repo.</p>
<div class="before" id="before-start">
<h3>Before you start</h3>
<ul>
<li><strong>Node.js 18 or newer.</strong> Check with <code>node --version</code>. No Node? Get it from <a href="https://nodejs.org/">nodejs.org</a> (the LTS download), or run <code>winget install OpenJS.NodeJS.LTS</code> on Windows, <code>brew install node</code> on macOS, or use <code>nvm</code> on Linux. Then open a new terminal.</li>
<li><strong>Start from your project.</strong> Open your terminal in the project you want to work on (<code>cd</code> into it) before you run anything. Plan2Code works on the folder you start it in.</li>
<li><strong>No agent yet?</strong> Install Claude Code, Codex or Devin first.</li>
</ul>
</div>
<div class="cmd">
<pre id="install-cmd"><span aria-hidden="true">$ </span>npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git</pre>
<button class="copy" type="button" aria-label="Copy the install command">
@@ -223,7 +236,7 @@ footer a { color: inherit; }
<span class="label">Copy</span>
</button>
</div>
<p class="then">then run <code>plan2code</code> in any project.</p>
<p class="then">then, from your project, run <code>plan2code</code> (Claude Code, Devin or Codex), or type <code>/plan2code</code> in your agent (<code>$plan2code</code> in Codex).</p>
</div>
</section>
@@ -356,7 +369,15 @@ footer a { color: inherit; }
<section class="s alt close" id="install" aria-labelledby="install-title">
<div class="narrow">
<h2 id="install-title">Install</h2>
<p class="muted">Needs Node.js 18 or later. Run it again any time to update.</p>
<p class="muted">Run it again any time to update.</p>
<div class="before" id="before-start-2">
<h3>Before you start</h3>
<ul>
<li><strong>Node.js 18 or newer.</strong> Check with <code>node --version</code>. No Node? Get it from <a href="https://nodejs.org/">nodejs.org</a> (the LTS download), or run <code>winget install OpenJS.NodeJS.LTS</code> on Windows, <code>brew install node</code> on macOS, or use <code>nvm</code> on Linux. Then open a new terminal.</li>
<li><strong>Start from your project.</strong> Open your terminal in the project you want to work on (<code>cd</code> into it) before you run anything. Plan2Code works on the folder you start it in.</li>
<li><strong>No agent yet?</strong> Install Claude Code, Codex or Devin first.</li>
</ul>
</div>
<div class="cmd">
<pre><span aria-hidden="true">$ </span>npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git</pre>
<button class="copy" type="button" aria-label="Copy the install command">
@@ -365,7 +386,7 @@ footer a { color: inherit; }
<span class="label">Copy</span>
</button>
</div>
<p class="then">then run <code>plan2code</code> in any project.</p>
<p class="then">then, from your project, run <code>plan2code</code> (Claude Code, Devin or Codex), or type <code>/plan2code</code> in your agent (<code>$plan2code</code> in Codex).</p>
</div>
</section>
+1 -1
View File
@@ -8,7 +8,7 @@
"scripts": {
"prepare": "husky",
"build:skills": "node install.js --build-skills",
"test": "node scripts/validate-char-count.js && node install.js --build-skills && node scripts/parse-check.mjs && node scripts/check-skill-table.mjs && node --test scripts/test-web-console.mjs scripts/test-launcher.mjs scripts/test-skill-scripts.mjs scripts/test-script-pathfinder.mjs scripts/test-script-finalize.mjs scripts/test-script-handoff.mjs scripts/test-script-git-commit.mjs scripts/test-script-changelog.mjs"
"test": "node scripts/validate-char-count.js && node install.js --build-skills && node scripts/parse-check.mjs && node scripts/check-skill-table.mjs && node --test scripts/test-web-console.mjs scripts/test-launcher.mjs scripts/test-getting-started.mjs scripts/test-skill-scripts.mjs scripts/test-script-pathfinder.mjs scripts/test-script-finalize.mjs scripts/test-script-handoff.mjs scripts/test-script-git-commit.mjs scripts/test-script-changelog.mjs"
},
"devDependencies": {
"husky": "^9.0.0"
+46
View File
@@ -0,0 +1,46 @@
// Keeps the "Before you start" guidance identical in meaning across the newcomer docs.
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
const DOCS = ['README.md', 'docs/index.html', 'QUICK-REFERENCE.md'];
const EM_DASH = String.fromCharCode(0x2014);
function read(file) {
return readFileSync(join(ROOT, file), 'utf8');
}
// The first "Before you start" block: from its heading to the next heading (Markdown)
// or the end of its container (HTML).
function blockOf(file) {
const text = read(file);
const start = text.search(/^#{2,3} Before you start$|<h3>Before you start<\/h3>/m);
assert.ok(start >= 0, `${file} has no "Before you start" block`);
const rest = text.slice(start);
const body = rest.indexOf('\n') + 1;
const next = file.endsWith('.html') ? rest.indexOf('</div>') : rest.slice(body).search(/^#{1,3} /m);
const end = file.endsWith('.html') ? next : next < 0 ? -1 : body + next;
return end > 0 ? rest.slice(0, end) : rest;
}
for (const file of DOCS) {
test(`${file} tells a newcomer how to get started`, () => {
const text = read(file);
const block = blockOf(file);
for (const needle of ['Node.js 18', 'node --version', 'nodejs.org', '/plan2code', '$plan2code']) {
assert.ok(text.includes(needle), `${file} is missing "${needle}"`);
}
assert.match(block, /project you want to (work on|work in)/, `${file} does not say to start from your project`);
assert.ok(!block.includes(EM_DASH), `${file} has an em dash in its "Before you start" block`);
});
test(`${file} puts the guidance before the install command`, () => {
const text = read(file);
const guide = text.indexOf('Before you start');
const install = text.indexOf('npx --allow-git');
assert.ok(guide >= 0 && install >= 0 && guide < install, `${file}: "Before you start" must come before the npx line`);
});
}