mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-17 04:45:33 -08:00
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:
1 parent
b639c8945d
commit
3469a74cc1
12 files changed
+117
-25
No files matched your search
@@ -15,7 +15,7 @@ node install.js
|
|||||||
npm run build:skills
|
npm run build:skills
|
||||||
|
|
||||||
# Full check (about 70s): char limits, skills/ build, browser-module parse check,
|
# 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
|
npm test
|
||||||
|
|
||||||
# One web console or launcher test
|
# One web console or launcher test
|
||||||
|
|||||||
@@ -25,7 +25,7 @@ hand, or the reverse — the checkboxes are the only handoff.
|
|||||||
|
|
||||||
```bash
|
```bash
|
||||||
# From the plan2code root directory
|
# 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
|
## Run
|
||||||
|
|||||||
+1
-1
@@ -16,7 +16,7 @@ One thing to remember: **collect after every finished spec.** Everything else is
|
|||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Install once, from the plan2code root
|
# 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)
|
# After finishing a spec (steps 1–4)
|
||||||
cd your-project
|
cd your-project
|
||||||
|
|||||||
@@ -36,7 +36,7 @@ The icons down the left are Planny, the project mascot.
|
|||||||
## Install
|
## Install
|
||||||
|
|
||||||
```bash
|
```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
|
That copies the script to `~/.claude/plan2code-statusline.js`, writes a default config to
|
||||||
|
|||||||
+1
-1
@@ -19,7 +19,7 @@ Built for **maintainers**. If you're using Plan2Code to ship features, you don't
|
|||||||
## Install
|
## Install
|
||||||
|
|
||||||
```bash
|
```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
|
## Run
|
||||||
|
|||||||
@@ -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
|
## Session 1: Plan
|
||||||
|
|
||||||
Run `plan2code` in the project (or `/plan2code` inside your agent). The dashboard opens in your
|
Run `plan2code` in the project (or `/plan2code` inside your agent). The dashboard opens in your
|
||||||
|
|||||||
@@ -10,6 +10,8 @@ Plan2Code is a structured 4-step workflow methodology for AI-assisted software d
|
|||||||
**Author:** Justin Parker
|
**Author:** Justin Parker
|
||||||
**License:** MIT
|
**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
|
## 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/`.
|
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
@@ -1,13 +1,20 @@
|
|||||||
# Plan2Code Quick Reference
|
# 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
|
## Launch
|
||||||
|
|
||||||
The web console is the main way in: a local page where questions, documents, build progress and sign-offs live.
|
The web console is the main way in: a local page where questions, documents, build progress and sign-offs live.
|
||||||
|
|
||||||
| How | Command | What happens |
|
| How | Command | What happens |
|
||||||
| ------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
|
| ------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
|
||||||
| From your project (shell) | `plan2code` | Opens Claude Code or Devin on the dashboard (`--cli claude` / `--cli devin` to choose) |
|
| From your project (shell) | `plan2code` | Opens Claude Code, Devin or Codex on the dashboard (`--cli claude` / `devin` / `codex` to choose) |
|
||||||
| Inside any agent | `/plan2code` | Opens the dashboard: a card for every skill, launched on the same page |
|
| 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 |
|
| 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 |
|
| Straight into a skill | `/plan2code-1-plan --web` (any step) | Skips the "web console or terminal?" question and opens the page |
|
||||||
|
|
||||||
|
|||||||
@@ -30,8 +30,14 @@ The dashboard, in a project halfway through a build. It suggests the next step f
|
|||||||
|
|
||||||
## Install and start
|
## Install and start
|
||||||
|
|
||||||
Requires [Node.js](https://nodejs.org/) 18 or later and network access — installation runs through
|
### Before you start
|
||||||
the [skills CLI](https://skills.sh). To update, re-run the install command.
|
|
||||||
|
- **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
|
```bash
|
||||||
npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git
|
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 ║
|
║ INSTALL PLAN2CODE ║
|
||||||
╠═════════════════════════════════════════════════════════╣
|
╠═════════════════════════════════════════════════════════╣
|
||||||
║ I. INSTALL Install Plan2Code skills everywhere ║
|
║ I. INSTALL Install skills + the plan2code command ║
|
||||||
║ A. ALL Install Plan2Code + dev tools ║
|
║ U. UNINSTALL Remove everything Plan2Code installed ║
|
||||||
║ U. UNINSTALL Remove Plan2Code skills and dev tools ║
|
║ A. ADVANCED Project install, dev tools, and more ║
|
||||||
║ C. CUSTOM Advanced options ║
|
|
||||||
║ Q. QUIT Exit ║
|
║ Q. QUIT Exit ║
|
||||||
╚═════════════════════════════════════════════════════════╝
|
╚═════════════════════════════════════════════════════════╝
|
||||||
```
|
```
|
||||||
|
|
||||||
### Start
|
### Start
|
||||||
|
|
||||||
1. In any project, run `plan2code`. It starts Claude Code or Devin on the dashboard, and the
|
1. `cd` into your project, then run `plan2code`. It starts Claude Code, Devin or Codex on the dashboard,
|
||||||
dashboard opens in your browser.
|
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
|
2. In a project without an `AGENTS.md`, pick **Set up this project** first: Plan and Quick task
|
||||||
need it.
|
need it.
|
||||||
3. Pick a card.
|
3. Pick a card.
|
||||||
|
|
||||||
Already inside your agent? Type `/plan2code` instead.
|
Already inside your agent? Type `/plan2code` instead (`$plan2code` in Codex).
|
||||||
|
|
||||||
<details>
|
<details>
|
||||||
<summary>About the plan2code command</summary>
|
<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
|
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** or **Devin**. With both installed it asks which and
|
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` or `--cli devin` skips the question, and `--model <name>`
|
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
|
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
|
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); run
|
(`--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`),
|
`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.
|
which opens a folder picker first. Uninstalling (`U`) removes both.
|
||||||
</details>
|
</details>
|
||||||
|
|||||||
+24
-3
@@ -112,6 +112,11 @@ h3 { font-size: 1.45rem; margin: 8px 0; }
|
|||||||
.copy .tick { display: none; }
|
.copy .tick { display: none; }
|
||||||
.copy.-done .clip { display: none; }
|
.copy.-done .clip { display: none; }
|
||||||
.copy.-done .tick { display: block; }
|
.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; }
|
.then { margin: 12px 0 0; color: var(--ink-2); font-size: 15px; }
|
||||||
|
|
||||||
/* Hero: centered headline, then the dashboard at full width. */
|
/* Hero: centered headline, then the dashboard at full width. */
|
||||||
@@ -215,6 +220,14 @@ footer a { color: inherit; }
|
|||||||
</svg>
|
</svg>
|
||||||
<h1 id="hero-title">Plan and build with your AI agent, on one page.</h1>
|
<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>
|
<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">
|
<div class="cmd">
|
||||||
<pre id="install-cmd"><span aria-hidden="true">$ </span>npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git</pre>
|
<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">
|
<button class="copy" type="button" aria-label="Copy the install command">
|
||||||
@@ -223,7 +236,7 @@ footer a { color: inherit; }
|
|||||||
<span class="label">Copy</span>
|
<span class="label">Copy</span>
|
||||||
</button>
|
</button>
|
||||||
</div>
|
</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>
|
</div>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
@@ -356,7 +369,15 @@ footer a { color: inherit; }
|
|||||||
<section class="s alt close" id="install" aria-labelledby="install-title">
|
<section class="s alt close" id="install" aria-labelledby="install-title">
|
||||||
<div class="narrow">
|
<div class="narrow">
|
||||||
<h2 id="install-title">Install</h2>
|
<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">
|
<div class="cmd">
|
||||||
<pre><span aria-hidden="true">$ </span>npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git</pre>
|
<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">
|
<button class="copy" type="button" aria-label="Copy the install command">
|
||||||
@@ -365,7 +386,7 @@ footer a { color: inherit; }
|
|||||||
<span class="label">Copy</span>
|
<span class="label">Copy</span>
|
||||||
</button>
|
</button>
|
||||||
</div>
|
</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>
|
</div>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|||||||
+1
-1
@@ -8,7 +8,7 @@
|
|||||||
"scripts": {
|
"scripts": {
|
||||||
"prepare": "husky",
|
"prepare": "husky",
|
||||||
"build:skills": "node install.js --build-skills",
|
"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": {
|
"devDependencies": {
|
||||||
"husky": "^9.0.0"
|
"husky": "^9.0.0"
|
||||||
|
|||||||
@@ -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`);
|
||||||
|
});
|
||||||
|
}
|
||||||
Reference in new issue
Block a user