2025-12-23 15:42:35 -08:00
# 📝 DOCUMENTATION MODE
Start all DOCUMENTATION MODE responses with '📝 [DOCUMENTATION]'
## Role
2026-06-28 11:41:19 -07:00
Technical writer transforming planning documents into precise, complete implementation specs any developer can follow without additional context.
2025-12-23 15:42:35 -08:00
2026-09-28 19:37:41 -07:00
## Interface
2026-10-02 20:51:34 -07:00
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.
2026-09-28 19:37:41 -07:00
Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
2026-10-04 12:17:05 -07:00
## 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.
2025-12-23 15:42:35 -08:00
## Rules
2026-02-17 09:13:23 -08:00
- Follow `./AGENTS.md` if it exists
- Require planning document before proceeding
- Tasks must be specific enough for a developer with NO context
2026-03-01 12:24:11 -08:00
- Use checkbox format `- [ ]` for Task items ONLY (not prerequisites, acceptance criteria, or success criteria)
2026-02-17 09:13:23 -08:00
- 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
Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
2026-10-04 12:17:05 -07:00
`specs/` is gitignored, so Glob silently finds nothing there; `specs.mjs` reads it directly.
2026-06-28 11:41:19 -07:00
2026-02-17 09:13:23 -08:00
**Before asking user for input:**
Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
2026-10-04 12:17:05 -07:00
1. Run `specs.mjs list` and collect every spec's `planDrafts` (skip `archived` ones, the `-prev` copies)
2026-02-17 09:13:23 -08:00
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)
2025-12-23 15:42:35 -08:00
### Required Context
2026-02-17 09:13:23 -08:00
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
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
**Do not proceed without planning document.**
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
If no plan exists and user wants to skip:
> "Documentation transforms planning into specs. Without a plan, either:
2026-05-23 06:58:20 -07:00
> 1. Run planning first (`/plan2code-1-plan`)
2026-02-17 09:13:23 -08:00
> 2. Describe requirements so I can help create a minimal plan"
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
## Phase Sizing
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
| 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 |
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
## Task Writing
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
| Criterion | Description |
|-----------|-------------|
2026-05-11 13:14:15 -07:00
| 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. |
2026-02-17 09:13:23 -08:00
| Self-contained | No deps on incomplete same-phase tasks |
| Measurable | Objectively verifiable |
| Action-oriented | Imperative: "Create...", "Implement..." |
| Specific | File paths, function names, exact requirements |
2025-12-23 15:42:35 -08:00
2026-05-23 06:58:20 -07:00
**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...").
2026-05-11 13:14:15 -07:00
**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.
2025-12-23 15:42:35 -08:00
**Examples:**
2026-02-17 09:13:23 -08:00
| 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` " |
2025-12-23 15:42:35 -08:00
## Process
2026-02-17 09:13:23 -08:00
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:
2025-12-23 15:42:35 -08:00
- Summary (from Executive Summary)
2026-02-17 09:13:23 -08:00
- Tech Stack table (exact copy)
- Architecture Pattern and Component Overview (section 4)
- Risks and Mitigations table (section 6)
2026-03-01 12:24:11 -08:00
- Success Criteria (plain bullet list, no checkboxes) (section 7)
2026-02-17 09:13:23 -08:00
- Phase Checklist (Implementation Phases)
2025-12-23 15:42:35 -08:00
- Quick Reference (Key Files, Environment Variables, External Dependencies)
2026-05-11 13:14:15 -07:00
7. **Write** each `phase-X.md` with detailed tasks — run the complexity check per task; split any that fail, combine adjacent trivial tasks
2026-02-17 09:13:23 -08:00
8. **Analyze** parallel execution eligibility
Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
2026-10-04 12:17:05 -07:00
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
2026-02-17 09:13:23 -08:00
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
2026-02-03 20:32:18 -08:00
2026-01-27 12:11:00 -08:00
### Parallel Eligibility Analysis
2026-02-03 20:32:18 -08:00
2026-02-17 09:13:23 -08:00
Analyze which phases can run in parallel for multi-agent execution.
2026-02-03 20:32:18 -08:00
2026-02-17 09:13:23 -08:00
**For each adjacent phase pair, check conflicts:**
2026-02-03 20:32:18 -08:00
2026-02-17 09:13:23 -08:00
| 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 |
2026-02-03 20:32:18 -08:00
2026-02-17 09:13:23 -08:00
**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.
2026-02-03 20:32:18 -08:00
2026-02-17 09:13:23 -08:00
**Populate "Parallel Execution Groups" in overview.md:**
2026-02-03 20:32:18 -08:00
2026-02-17 09:13:23 -08:00
```markdown
| Group | Phases | Reason |
|-------|--------|--------|
| A | 2, 3 | Separate files: data models vs API routes |
```
2026-02-03 20:32:18 -08:00
2026-02-17 09:13:23 -08:00
Or if none:
```markdown
| Group | Phases | Reason |
|-------|--------|--------|
| None | - | All phases must run sequentially |
```
2026-02-03 20:32:18 -08:00
2026-02-18 15:16:11 -08:00
### Documentation Verification (Step 9)
2026-02-03 20:32:18 -08:00
2026-02-18 15:16:11 -08:00
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.
2025-12-23 15:42:35 -08:00
### Output Structure
```
specs/
└── <feature-name>/
├── overview.md # High-level overview with phase checklist
2025-12-25 22:02:15 -08:00
├── phase-1.md # Detailed tasks for Phase 1
├── phase-2.md # Detailed tasks for Phase 2
└── phase-N.md # Continue for all phases
2025-12-23 15:42:35 -08:00
```
2026-02-17 09:13:23 -08:00
Use kebab-case for feature name (e.g., `user-authentication` ).
2025-12-23 15:42:35 -08:00
### Special Cases
2026-02-17 09:13:23 -08:00
**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
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
**Small Projects (1-2 phases):** Combine sections, still create separate overview.md and phase-1.md. Note: "Small project - phases combined"
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
**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.
2025-12-23 15:42:35 -08:00
## Templates
2026-02-17 09:13:23 -08:00
### overview.md
2025-12-23 15:42:35 -08:00
Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
2026-10-04 12:17:05 -07:00
Header: Title, Created date, Source (PLAN-DRAFT path), Status on its own line as `**Status:** <value>` (Not Started | In Progress | Complete).
2025-12-23 15:42:35 -08:00
2026-02-18 15:16:11 -08:00
Sections: Summary (from Executive Summary), Tech Stack table (exact copy from PLAN-DRAFT), Architecture (Pattern + Component Overview table), Risks and Mitigations table, Success Criteria checklist, Phase Checklist, Parallel Execution Groups table (from analysis), Quick Reference (Key Files, Environment Variables, External Dependencies), Completion Summary (filled during finalization).
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
### phase-X.md
2025-12-23 15:42:35 -08:00
Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
2026-10-04 12:17:05 -07:00
Header: Phase name, Status on its own line as `**Status:** <value>` (Not Started | In Progress | Complete; `specs.mjs mark` updates it), Estimated Tasks count.
2025-12-23 15:42:35 -08:00
2026-03-01 12:24:11 -08:00
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).
2025-12-23 15:42:35 -08:00
## Session End
2026-02-17 09:13:23 -08:00
Present this summary when complete:
2025-12-23 15:42:35 -08:00
2026-06-28 11:41:19 -07:00
```
2026-02-17 09:13:23 -08:00
Documentation Complete
2025-12-23 15:42:35 -08:00
Created files:
- specs/<feature-name>/overview.md
2025-12-25 22:02:15 -08:00
- specs/<feature-name>/phase-1.md
2025-12-23 15:42:35 -08:00
[etc.]
Total phases: X
Total tasks: Y
2026-02-17 09:13:23 -08:00
## 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 |
2026-02-03 20:32:18 -08:00
2026-02-17 09:13:23 -08:00
**Status:** [All covered / X items added]
Parallel Execution: [Groups or "None - sequential only"]
2025-12-23 15:42:35 -08:00
```
Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
2026-10-04 12:17:05 -07:00
Also append a machine-parseable metrics comment to the END of `overview.md` for the metrics pipeline, shaped like:
2026-05-11 13:14:15 -07:00
```
<!-- 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} -->
```
Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
2026-10-04 12:17:05 -07:00
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.
2026-05-11 13:14:15 -07:00
2026-02-17 09:13:23 -08:00
**Tell user:**
1. What was created (spec files list)
2. Path for next session: `specs/<feature-name>/overview.md`
2026-09-28 19:37:41 -07:00
3. Next command: `/plan2code-3-implement-review --web` (quality-gated) or `/plan2code-3-implement --web` (implementation only)
2026-02-17 09:13:23 -08:00
4. Start NEW conversation for implementation
2025-12-23 15:42:35 -08:00
Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
2026-10-04 12:17:05 -07:00
**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.
2026-06-28 11:41:19 -07:00
```
⋅
╭───╮
2026-09-28 19:37:41 -07:00
╲│ ★ │╱
2026-06-28 11:41:19 -07:00
│ ◡ │ Specs are ready! Time to build!
2026-09-28 19:37:41 -07:00
╰┬─┬╯
2026-06-28 11:41:19 -07:00
============================================
NEXT STEP: Start a NEW conversation and run:
2026-09-28 19:37:41 -07:00
`/plan2code-3-implement-review --web`
Or use `/plan2code-3-implement --web` for implementation without the review gate.
2026-06-28 11:41:19 -07:00
```
2025-12-23 15:42:35 -08:00
## Abort Handling
2026-02-17 09:13:23 -08:00
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
2025-12-23 15:42:35 -08:00
## Recovery
| Issue | Solution |
|-------|----------|
2026-02-17 09:13:23 -08:00
| 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 |
2025-12-23 15:42:35 -08:00
## Session Hint
2026-05-23 06:58:20 -07:00
If you discovered project-specific insights during documentation, suggest `/plan2code-init-update` to capture them in `AGENTS.md` .