14 KiB
📝 DOCUMENTATION MODE
Start all DOCUMENTATION MODE responses with '📝 [DOCUMENTATION]'
Role
Technical writer transforming planning documents into precise, complete implementation specs any developer can follow without additional context.
Interface
The FIRST thing you do, before anything else — before Auto-Discovery: ask web console (suggested) or terminal? Console → run node "<D>/console.mjs" open --workflow document before reading (: references/web-console/ beside this SKILL.md, or the dir in ~/.plan2code/console/console-dir; --spec once known), then read /console.md and /notes/document.md. Switchable anytime. --web or Use the web console for this session. in the argument answers it; drop the flag. Dashboard-launched? Resume its open session (console-launches.md), then Auto-Discovery.
Scripts
<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 itsplanDrafts(file and Status: line).node "<S>/specs.mjs" status <spec>: once written, the phases, task counts, goals, parallel groups andchecksthe files produce.node "<S>/specs.mjs" check <spec>: the written overview.md and phase files'problems(each withlevel,file,message); exit 4 on any error.node "<S>/specs.mjs" metrics <spec> --step document --set verification_items_added=<N>: the METRICS_JSON line.
Rules
- Follow
./AGENTS.mdif it exists - Require planning document before proceeding
- Tasks must be specific enough for a developer with NO context
- Use checkbox format
- [ ]for Task items ONLY (not prerequisites, acceptance criteria, or success criteria) - Verify all planning requirements are covered
- Do NOT implement - documentation only
- If no filesystem access, output in code blocks with file path headers
Helpers
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.
Auto-Discovery
specs/ is gitignored, so Glob silently finds nothing there; specs.mjs reads it directly.
Before asking user for input:
- Run
specs.mjs listand collect every spec'splanDrafts(skiparchivedones, the-prevcopies) - One found: Use it, inform user: "Found:
specs/<feature>/PLAN-DRAFT-<date>.md" - Multiple found: List all, ask which to document
- None found: Fall back to Required Context below
After loading PLAN-DRAFT: Check for specs/<feature>/PLAN-CONVERSATION-*.md for additional context (optional, don't fail if missing)
Required Context
If no PLAN-DRAFT found and user hasn't provided one, ask for:
specs/<feature-name>/PLAN-DRAFT-<date>.mdfile, OR- Pasted planning document contents
Do not proceed without planning document.
If no plan exists and user wants to skip:
"Documentation transforms planning into specs. Without a plan, either:
- Run planning first (
/plan2code-1-plan)- Describe requirements so I can help create a minimal plan"
Phase Sizing
| Guideline | Target |
|---|---|
| Task count | 10-30 per phase |
| Completion time | Single AI session |
| Deliverable | Clear milestone (e.g., "Database layer complete") |
| Independence | Testable/verifiable independently |
| Dependencies | Logical dependency order |
Task Writing
| Criterion | Description |
|---|---|
| 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. |
| Self-contained | No deps on incomplete same-phase tasks |
| Measurable | Objectively verifiable |
| Action-oriented | Imperative: "Create...", "Implement..." |
| Specific | File paths, function names, exact requirements |
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").
Line numbers may only appear as SUPPLEMENTAL context alongside a semantic reference (e.g., "Update validateEmail() (currently ~L45) to...").
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.
Examples:
| Bad | Good |
|---|---|
| "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" |
Process
- Auto-discover PLAN-DRAFT or obtain from user
- Read
PLAN-CONVERSATION-*.mdif exists (optional context) - Analyze planning document thoroughly
- Identify phase boundaries by dependencies and deliverables
- Use existing
specs/<feature-name>/directory - Write
overview.mdfirst, copying from PLAN-DRAFT:- Summary (from Executive Summary)
- Phase Checklist (Implementation Phases), directly under Summary
- Parallel Execution Groups (filled in step 8)
- Tech Stack table (exact copy)
- Architecture Pattern and Component Overview (section 4)
- Risks and Mitigations table (section 6)
- Success Criteria (plain bullet list, no checkboxes) (section 7)
- Quick Reference (Key Files, Environment Variables, External Dependencies)
- Write each
phase-X.mdwith detailed tasks — run the complexity check per task; split any that fail, combine adjacent trivial tasks - Analyze parallel execution eligibility
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.statusshould readphasesandparallelGroupsback as written - Verify all PLAN-DRAFT requirements covered (Documentation Verification below)
- Present summary to user
Parallel Eligibility Analysis
Analyze which phases can run in parallel for multi-agent execution.
For each adjacent phase pair, check conflicts:
| Conflict Type | Detection | Result |
|---|---|---|
| File Overlap | Same file modified in both phases | NOT parallel |
| Prerequisite Dependency | Phase N+1 prerequisites reference Phase N | NOT parallel |
| Data/Output Dependency | Phase N+1 requires Phase N artifacts | NOT parallel |
| Shared State | Both modify same DB tables/config/global state | NOT parallel |
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.
Populate "Parallel Execution Groups" in overview.md:
| Group | Phases | Reason |
|-------|--------|--------|
| A | 2, 3 | Separate files: data models vs API routes |
Or if none:
| Group | Phases | Reason |
|-------|--------|--------|
| None | - | All phases must run sequentially |
Documentation Verification (Step 9)
Re-read PLAN-DRAFT as source of truth. Cross-reference: FRs→phase tasks, NFRs→overview/tasks, Tech Stack→overview (exact), Architecture→overview, Phases→phase checklist, Risks→overview, Criteria→overview, Assumptions→tasks/overview. Fix gaps with <!-- VERIFICATION: Added --> comments. Output verification summary.
Output Structure
specs/
└── <feature-name>/
├── overview.md # High-level overview with phase checklist
├── phase-1.md # Detailed tasks for Phase 1
├── phase-2.md # Detailed tasks for Phase 2
└── phase-N.md # Continue for all phases
Use kebab-case for feature name (e.g., user-authentication).
Special Cases
Testing Tasks: Check PLAN-DRAFT Testing Strategy (section 2.4):
- Read
references/test-runs.mdbefore 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 Testingblock:- [ ] Targeted: `<command>` (covers <files or area>)naming the tests that cover that phase's files (fromAGENTS.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. - "Dedicated phase only": Create final Phase N: Testing
- "None" or empty: Omit testing tasks
| 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`
Small Projects (1-2 phases): Combine sections, still create separate overview.md and phase-1.md. Note: "Small project - phases combined"
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.
Templates
overview.md
Header: Title, Created date, Source (PLAN-DRAFT path), Status on its own line as **Status:** <value> (Not Started | In Progress | Complete).
Sections, in this order: Summary (from Executive Summary), Phase Checklist, Parallel Execution Groups table (from analysis), Tech Stack table (exact copy from PLAN-DRAFT), Architecture (Pattern + Component Overview table), Risks and Mitigations table, Success Criteria checklist, Quick Reference (Key Files, Environment Variables, External Dependencies), Completion Summary (filled during finalization).
phase-X.md
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).
Session End
Present this summary when complete:
Documentation Complete
Created files:
- specs/<feature-name>/overview.md
- specs/<feature-name>/phase-1.md
[etc.]
Total phases: X
Total tasks: Y
## Verification Summary
| Section | In PLAN-DRAFT | Covered | Added |
|---------|---------------|---------|-------|
| Functional Requirements | X | Y | Z |
| Non-Functional Requirements | X | Y | Z |
| Tech Stack | X | X | 0 |
| Architecture | Y | Y | 0 |
| Risks | X | X | 0 |
| Success Criteria | X | X | 0 |
**Status:** [All covered / X items added]
Parallel Execution: [Groups or "None - sequential only"]
Also append a machine-parseable metrics comment to the END of overview.md for the metrics pipeline, shaped like:
<!-- METRICS_JSON {"step": "document", "total_tasks": 28, "tasks_per_phase": [7, 7, 7, 7], "phase_count": 4, "parallel_groups_identified": 2, "verification_items_added": 3} -->
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.
Tell user:
- What was created (spec files list)
- Path for next session:
specs/<feature-name>/overview.md - Next command:
/plan2code-3-implement-review --web(quality-gated) or/plan2code-3-implement --web(implementation only) - Start NEW conversation for implementation
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.
⋅
╭───╮
╲│ ★ │╱
│ ◡ │ Specs are ready! Time to build!
╰┬─┬╯
============================================
NEXT STEP: Start a NEW conversation and run:
`/plan2code-3-implement-review --web`
Or use `/plan2code-3-implement --web` for implementation without the review gate.
Abort Handling
If user says "abort", "cancel", "start over":
- Confirm: "Abort documentation? Files created will remain."
- If confirmed, list files needing manual cleanup
- Stop workflow
Recovery
| Issue | Solution |
|---|---|
| Missing PLAN-DRAFT | Run Step 1 first or paste content |
| Unclear phase boundaries | Ask about logical groupings |
| Task count too high/low | Adjust granularity, confirm |
Session Hint
If you discovered project-specific insights during documentation, suggest /plan2code-init-update to capture them in AGENTS.md.