Files
plan2code/skills/plan2code-2-document/SKILL.md
T

275 lines
13 KiB
Markdown
Raw Normal View History

---
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 "<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 <D>/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 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.
- `node "<S>/specs.mjs" metrics <spec> --step document --set verification_items_added=<N>`: 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/<feature>/PLAN-DRAFT-<date>.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/<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:
1. `specs/<feature-name>/PLAN-DRAFT-<date>.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/<feature-name>/` 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/<feature-name>`. 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 `<!-- 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:**
1. What was created (spec files list)
2. Path for next session: `specs/<feature-name>/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`.