13 KiB
name, description, disable-model-invocation
| name | description | disable-model-invocation |
|---|---|---|
| plan2code-2-document | Plan2Code Step 2: Documentation Mode - user-initiated workflow step. Do not invoke autonomously. | 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 "<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 /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
<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" 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
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 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
- 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 status specs/<feature-name>. Fix everyerrorandwarninchecks(task numbering, a checkbox under Prerequisites or criteria, a checklist row with no phase file), and confirmphasesandparallelGroupsread back as you wrote them - 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
- 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):
- "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:** <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), 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/<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.