The FIRST thing you do, before anything else in this file — before Auto-Discovery: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "<D>/console.mjs" open --workflow document` before reading (<D>: references/web-console/ beside this SKILL.md, or the dir in ~/.plan2code/console/console-dir; `--spec` once known), then read <D>/console.md and <D>/notes/document.md. Switchable anytime. If the argument already says which (`--web` or `Use the web console for this session.`), take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open: resume it (console-launches.md), then Auto-Discovery.
`<S>` is `scripts/` beside this SKILL.md (`~/.agents/skills/plan2code-2-document/scripts/` globally). Run from the project root; each prints one JSON object, and on a non-zero exit `next` says what to do.
-`node "<S>/specs.mjs" list`: every active spec with its `planDrafts` (file and **Status:** line).
-`node "<S>/specs.mjs" status <spec>`: once written, the phases, task counts, goals, parallel groups and `checks` the files produce.
When your tool can start helpers (subagents) and they are not switched off for this run (on the web console a `Subagents:` block says which, console-subagents.md):
- **Lookups while you write:** the files, seams and sizes behind the work a task names, so the details a builder needs rest on the real code; one lookup per helper, each returning facts with `file:line`.
Keep with you: the breakdown, the task writing and every question. Strength and effort per references/helper-strength.md. No helpers? Do the same work yourself.
| Time-boxed | 15-60 min. Split if 5+ logic branches, 2+ integration points, or shared interface mutation. Combine adjacent trivial tasks that form a cohesive unit. |
**Code references:** never use line numbers as primary references; they go stale as earlier tasks modify files. Name the function or class (`UserService.createUser()`, `AuthConfig`), or describe the code ("the JWT verification logic", "the switch statement handling request types").
**Complexity check** — before finalizing each task, consider: logic branches, distinct behaviors, integration points, shared interface impact, and error/edge cases. Tasks that are complex on 3+ of these signals should be split.
| "Set up the database" | "Create `src/db/schema.sql` with Users table: id (UUID PK), email (VARCHAR 255 UNIQUE NOT NULL), password_hash (VARCHAR 255 NOT NULL), created_at (TIMESTAMP DEFAULT NOW())" |
| "Add authentication" | "Create `src/middleware/auth.ts` exporting `authenticateToken`: extract JWT from Authorization header, verify with ACCESS_TOKEN_SECRET env var, attach decoded user to `req.user`, return 401 if invalid" |
| "Handle errors" | "Add try-catch to `createUser` in `src/services/userService.ts`: catch duplicate email (code 23505), throw `EmailAlreadyExistsError`" |
8a. **Check the structure:**`specs.mjs check specs/<feature-name>`. Fix every error before step 9 and the sign-off; fix each warning or explain it in the summary. `status` should read `phases` and `parallelGroups` back as written
9.**Verify** all PLAN-DRAFT requirements covered (Documentation Verification below)
**Group phases with no conflicts:** If Phases 2-3 conflict-free, Group A: 2,3. If Phase 4 depends on 3, new sequence. If Phases 5-6 conflict-free, Group B: 5,6.
- Read `references/test-runs.md` before writing the testing blocks. When you cannot tell which tests cover a file, or whether a check is fast, ask the person.
- "Targeted per phase" (or the old "Run after each phase"): end EVERY phase with a `## Phase Testing` block: ``- [ ] Targeted: `<command>` (covers <files or area>)`` naming the tests that cover that phase's files (from `AGENTS.md`'s test map, else from the code), and ``- [ ] Quick checks: `<command>` `` only for checks known to be fast.
- Full Suite: add ``- [ ] Full suite: `<command>` `` only to the phase named by "At Phase N"; none for "Offered at Finalize" or "Never" (under "Dedicated phase only", the testing phase carries it when it is Phase N). A draft with no Full Suite row: ask which they want before writing phase files.
-`| Approach | Test first |` in 2.4: in every phase, order each task's test before its code and put a plain sub-bullet ` - Test: <where the test drives the behavior>` directly under the task line (no checkbox, so the loop's task count is unchanged), for example `` - Test: through `POST /votes` ``
**Large Projects (6+ phases):** Group under milestones in overview.md, add milestone indicators (e.g., "Phase 3: User Auth [Milestone 1]"). Suggest sub-projects if >8-10 phases.
Header: Title, Created date, Source (PLAN-DRAFT path), Status on its own line as `**Status:** <value>` (Not Started | In Progress | Complete), then the format marker on its own line, `<!-- plan2code-format: 2 -->` (it makes `specs.mjs check` hold this spec to the current format rules as errors).
Header: Phase name, Status on its own line as `**Status:** <value>` (Not Started | In Progress | Complete; `specs.mjs mark` updates it), Estimated Tasks count.
Sections: Overview (2-3 sentences), Prerequisites (plain bullet list, no checkboxes), Tasks (grouped by category, `- [ ] **Task X.N:** [Description]` with File path and details, plus a ` - Test:` sub-bullet under each task when the approach is Test first), Phase Testing (if enabled: the Targeted, Quick checks and Full suite lines above), Acceptance Criteria (plain bullet list, no checkboxes), Notes, Phase Completion Summary (filled after implementation: date, implementer, what was done, files changed, issues).
Paste the `comment` from `specs.mjs metrics specs/<feature-name> --step document --set verification_items_added=<N>`, where N is the Added column total of your Verification Summary. It counts the tasks, phases and parallel groups from the files.
**Phase Overview** — present a table from `status`'s `phases`: phase name, task count (`tasks.total`), one-sentence goal (`goal`, tightened if it runs long; write one yourself when it is null). Helps the user plan sessions and identify review gates.
In the terminal, end with `NEXT STEP: start a NEW conversation and run /plan2code-3-implement-review --web` (or `/plan2code-3-implement --web` for implementation without the review gate). The web console's finish carries it, so print nothing there.