--- name: plan2code-2-document description: "Plan2Code Step 2: Documentation Mode - user-initiated workflow step. Do not invoke autonomously." disable-model-invocation: true --- # 📝 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 "/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 /console.md → Documentation. 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.md → Launches), then Auto-Discovery. `__stop` ends it; post `finish` BEFORE `stop` at every end. ## Scripts `` 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 "/specs.mjs" list`: every active spec with its `planDrafts` (file and **Status:** line). - `node "/specs.mjs" status `: once written, the phases, task counts, goals, parallel groups and `checks` the files produce. - `node "/specs.mjs" metrics --step document --set verification_items_added=`: the METRICS_JSON line. ## Rules - Follow `./AGENTS.md` if 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 ## Auto-Discovery `specs/` is gitignored, so Glob silently finds nothing there; `specs.mjs` reads it directly. **Before asking user for input:** 1. Run `specs.mjs list` and collect every spec's `planDrafts` (skip `archived` ones, the `-prev` copies) 2. **One found:** Use it, inform user: "Found: `specs//PLAN-DRAFT-.md`" 3. **Multiple found:** List all, ask which to document 4. **None found:** Fall back to Required Context below **After loading PLAN-DRAFT:** Check for `specs//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: 1. `specs//PLAN-DRAFT-.md` file, OR 2. 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: > 1. Run planning first (`/plan2code-1-plan`) > 2. 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 become stale as earlier tasks modify files. Instead, reference code by: - Function/method names: `authenticateToken()`, `UserService.createUser()` - Class/interface names: `UserRepository`, `AuthConfig` - Semantic descriptions: "the JWT verification logic", "the error handler for duplicate emails" - Code patterns: "the switch statement handling request types", "the validation block for email format" 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 1. **Auto-discover** PLAN-DRAFT or obtain from user 2. **Read** `PLAN-CONVERSATION-*.md` if exists (optional context) 3. **Analyze** planning document thoroughly 4. **Identify** phase boundaries by dependencies and deliverables 5. **Use existing** `specs//` directory 6. **Write** `overview.md` first, 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) 7. **Write** each `phase-X.md` with detailed tasks — run the complexity check per task; split any that fail, combine adjacent trivial tasks 8. **Analyze** parallel execution eligibility 8a. **Check the structure:** `specs.mjs status specs/`. Fix every `error` and `warn` in `checks` (task numbering, a checkbox under Prerequisites or criteria, a checklist row with no phase file), and confirm `phases` and `parallelGroups` read back as you wrote them 9. **Verify** all PLAN-DRAFT requirements covered: - 9A: Re-read PLAN-DRAFT as source of truth - 9B: Cross-reference each section against docs - 9C: Fix gaps, update documentation - 9D: Output verification summary 10. **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:** ```markdown | Group | Phases | Reason | |-------|--------|--------| | A | 2, 3 | Separate files: data models vs API routes | ``` Or if none: ```markdown | 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 `` comments. Output verification summary. ### Output Structure ``` specs/ └── / ├── 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): - "Run after each phase": Add testing task block at end of EVERY phase - "Dedicated phase only": Create final Phase N: Testing - "None" or empty: Omit testing tasks **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:** ` (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:** ` (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), Phase Testing (if enabled), 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//overview.md - specs//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: ``` ``` Paste the `comment` from `specs.mjs metrics specs/ --step document --set verification_items_added=`, where N is the Added column total of your Verification Summary. It counts the tasks, phases and parallel groups from the files. **Tell user:** 1. What was created (spec files list) 2. Path for next session: `specs//overview.md` 3. Next command: `/plan2code-3-implement-review --web` (quality-gated) or `/plan2code-3-implement --web` (implementation only) 4. 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": 1. Confirm: "Abort documentation? Files created will remain." 2. If confirmed, list files needing manual cleanup 3. 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`.