From 3469a74cc193d05c6e9c113e58b2ec386c845e96 Mon Sep 17 00:00:00 2001 From: Justin Parker Date: Thu, 8 Oct 2026 17:02:40 -0700 Subject: [PATCH] Add a Before you start block to the newcomer docs and a test to keep them in step AI Assisted --- .agents-docs/AGENTS-development-commands.md | 2 +- .readme/autonomous-loop.md | 2 +- .readme/metrics.md | 2 +- .readme/status-line.md | 2 +- .readme/test-bot.md | 2 +- .readme/walkthrough.md | 11 +++++ AGENTS.md | 2 + QUICK-REFERENCE.md | 11 ++++- README.md | 33 ++++++++------- docs/index.html | 27 ++++++++++-- package.json | 2 +- scripts/test-getting-started.mjs | 46 +++++++++++++++++++++ 12 files changed, 117 insertions(+), 25 deletions(-) create mode 100644 scripts/test-getting-started.mjs diff --git a/.agents-docs/AGENTS-development-commands.md b/.agents-docs/AGENTS-development-commands.md index bdf29e3..e63fe3e 100644 --- a/.agents-docs/AGENTS-development-commands.md +++ b/.agents-docs/AGENTS-development-commands.md @@ -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 diff --git a/.readme/autonomous-loop.md b/.readme/autonomous-loop.md index 3401537..b5b914d 100644 --- a/.readme/autonomous-loop.md +++ b/.readme/autonomous-loop.md @@ -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 diff --git a/.readme/metrics.md b/.readme/metrics.md index 0b65956..5dbcd11 100644 --- a/.readme/metrics.md +++ b/.readme/metrics.md @@ -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 diff --git a/.readme/status-line.md b/.readme/status-line.md index 5847c3f..c513d4d 100644 --- a/.readme/status-line.md +++ b/.readme/status-line.md @@ -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 diff --git a/.readme/test-bot.md b/.readme/test-bot.md index ae78514..7f4e0f3 100644 --- a/.readme/test-bot.md +++ b/.readme/test-bot.md @@ -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 diff --git a/.readme/walkthrough.md b/.readme/walkthrough.md index 1e15800..c605eb4 100644 --- a/.readme/walkthrough.md +++ b/.readme/walkthrough.md @@ -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 diff --git a/AGENTS.md b/AGENTS.md index 22aa71f..13d5f26 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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/`. diff --git a/QUICK-REFERENCE.md b/QUICK-REFERENCE.md index c530012..f7ee595 100644 --- a/QUICK-REFERENCE.md +++ b/QUICK-REFERENCE.md @@ -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 | diff --git a/README.md b/README.md index e587faa..268220f 100644 --- a/README.md +++ b/README.md @@ -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).
About the plan2code command -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 ` +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 ` 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.
diff --git a/docs/index.html b/docs/index.html index 3cd4fa4..d4e4e7d 100644 --- a/docs/index.html +++ b/docs/index.html @@ -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; }

Plan and build with your AI agent, on one page.

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.

+
+

Before you start

+ +
npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git
-

then run plan2code in any project.

+

then, from your project, run plan2code (Claude Code, Devin or Codex), or type /plan2code in your agent ($plan2code in Codex).

@@ -356,7 +369,15 @@ footer a { color: inherit; }

Install

-

Needs Node.js 18 or later. Run it again any time to update.

+

Run it again any time to update.

+
+

Before you start

+
    +
  • Node.js 18 or newer. Check with node --version. No Node? Get it from 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.
  • +
  • No agent yet? Install Claude Code, Codex or Devin first.
  • +
+
npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git
-

then run plan2code in any project.

+

then, from your project, run plan2code (Claude Code, Devin or Codex), or type /plan2code in your agent ($plan2code in Codex).

diff --git a/package.json b/package.json index 9f3f711..9c2beae 100644 --- a/package.json +++ b/package.json @@ -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" diff --git a/scripts/test-getting-started.mjs b/scripts/test-getting-started.mjs new file mode 100644 index 0000000..3275379 --- /dev/null +++ b/scripts/test-getting-started.mjs @@ -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$|

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('') : 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`); + }); +}