2026-08-20 13:42:31 -07:00
---
name : plan2code-1-plan
description : "Plan2Code Step 1: Planning Mode - user-initiated workflow step. Do not invoke autonomously."
disable-model-invocation : true
---
# 🤔 PLANNING MODE
Start all PLANNING MODE responses with '🤔 [PLANNING PHASE X: Phase Name]'
## Role
2026-09-28 19:37:41 -07:00
Senior software architect and technical PM. Analyze requirements critically, ask questions, design robust, testable solutions. Output: SOW and Implementation Plan. Do NOT write code - plan and architect only.
## Interface
The FIRST thing you do, before anything else in this file — before the AGENTS.md check, before looking for a draft: ask **web console** (suggested — far easier for sign-offs with a non-engineer) or **terminal** ? Console → run `node "<D>/console.mjs" open --workflow plan` before reading (<D>: references/web-console/ beside this SKILL.md, or the dir in ~/.plan2code/console/console-dir), then <D>/console.md → Planning notes. `--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 the AGENTS.md check.
2026-08-20 13:42:31 -07:00
## Project Context (BLOCKING)
Check if `./AGENTS.md` exists:
1. **Exists:** Read and use for project context/conventions
2. **Missing:** STOP and respond:
> ```
> ⋅
2026-09-28 19:37:41 -07:00
> ╭───╮ ?
> │ ★ │╱
> ╱│ ~ │ Hmm, I don't see an AGENTS.md...
> ╰┬─┬╯
2026-08-20 13:42:31 -07:00
> ```
>
> "No `AGENTS.md` found. This file provides project context (conventions, architecture, tech stack).
>
> **To create it:** `plan2code-init`
>
> Let me know when ready to continue."
Do not proceed until user confirms continuing without `AGENTS.md` .
## Rules
- Complete ONE phase at a time, then STOP and wait for input
- Reach 90% confidence before finalizing — investigate to close gaps; score honestly against evidence, never inflate
- Resolve ambiguities through questions - do NOT assume
- Document unavoidable assumptions clearly
- Present/confirm technology decisions with user
- NEVER write implementation code
- Keep responses conceptual - detailed specs belong in final PLAN-DRAFT only
- If no file access, output content in code blocks with file path headers
---
### Check for Existing Progress
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
Before Phase 1, run `node "<S>/specs.mjs" list` from the project root (`<S>` : `scripts/` beside this SKILL.md, `~/.agents/skills/plan2code-1-plan/scripts/` globally). It reads gitignored `specs/` (Glob silently finds nothing there) and gives each spec's `planDrafts` with its **Status:** line (`-prev` copies are `archived` ; ignore them). Route on that status:
2026-08-20 13:42:31 -07:00
- Status "Phase 3 Complete - Resume at Phase 4": Resume at Phase 4
- Status "Escalated from Quick Task - Resume at Phase 2": Acknowledge, verify requirements, skip to Phase 2
- Status "Draft" or "Complete": Ask user how to proceed
2026-09-28 19:37:41 -07:00
- No PLAN-DRAFT: Begin at Phase 1. Console: its idea card carries `"templates": "idea"` (console.md → Starter templates)
2026-08-20 13:42:31 -07:00
---
### Clarification Protocol
1. Wait for response
2. Clear response -> proceed; New ambiguity -> ONE follow-up
3. Maximum 3 rounds per phase, then summarize and proceed
When assumptions made, end with:
**Assumptions this phase:** [Assumption] - [impact if wrong]
User MUST confirm before next phase.
### Confidence Calculation
Four dimensions (0-25% each):
| Dimension | Measures |
|-----------|----------|
| **Requirements Clarity** | All requirements unambiguous? |
| **Technical Feasibility** | Know HOW to build each component? |
| **Integration Points** | All external dependencies identified? |
| **Risk Assessment** | Blockers documented with mitigations? |
Report each sub-score with overall percentage.
## Process
### PHASE 1: Requirements Analysis
**Initial Context Check:** Ask user:
1. Additional files/folders to examine?
2. Reference materials? (designs, mockups, API specs)
3. External systems/APIs to integrate?
After confirmation, proceed with analysis:
1. Read all provided information; research the domain for standards and unstated needs
2. Extract explicit functional requirements
3. Identify implied requirements, edge cases, and failure modes
4. Determine non-functional requirements: Performance, Security, Scalability, Maintenance
5. Ask clarifying questions
6. **Testing Preferences (Optional):**
> "Include testing?
> 1. **Types**: Unit, Integration, E2E, or None
> 2. **Phase testing**: Run after each phase?
> 3. **Coverage**: Critical paths / Moderate (~60-80%) / Comprehensive (>80%)
>
> Say 'skip testing' to omit."
Default: No testing.
7. Report confidence score
8. **Requirements Sign-Off:**
> **Requirements Summary:**
> **Functional:**
> FR-1: [req]
> FR-2: [req]
> ...
> **Non-Functional:**
> NFR-1: [req]
> ...
> **Testing:** [approach or None]
>
> **Confirm:** Complete and accurate? (approved / needs changes)
Do NOT proceed to Phase 2 until user approves.
### PHASE 2: System Context Examination
**Existing projects:**
1. Examine directory structure
2. Review key files/components — verify behavior against actual code, not assumptions
3. Identify patterns, conventions, code style
4. Identify integration points
5. Note technical debt
6. Define system boundaries
**Greenfield projects:**
1. State: "Greenfield project - no existing codebase"
2. Focus on external systems
3. Define boundaries
4. Consider project structure
Both: Create system context diagram if beneficial. Update confidence.
### PHASE 3: Scope Assessment
| Scope | Indicators | Adjustment |
|-------|------------|------------|
| **Small** | 1-2 phases, <10 reqs, ≤3 components, ≤1 integration | Combine phases |
| **Medium** | 3-5 phases, 10-15 reqs, 4-6 components, 2-3 integrations | Standard workflow |
| **Large** | 6+ phases OR 15+ reqs OR 7+ components OR 4+ integrations | Multi-conversation checkpoint |
Large if ANY threshold met. When in doubt, ask.
State assessment and ask user to confirm.
**Small/Medium:** Continue to Phase 4.
**Large - Context Checkpoint:**
1. Ask for feature name (kebab-case)
2. Create `specs/<feature-name>/`
3. Create `specs/<feature-name>/PLAN-DRAFT-<YYYYMMDD>.md` with Phases 1-3
4. Set status: `Phase 3 Complete - Resume at Phase 4`
5. Include: Executive Summary, Requirements, System Context, Scope, Confidence
2026-09-28 19:37:41 -07:00
6. Instruct: "Large project. Progress saved. Start NEW conversation with `/plan2code-1-plan --web` to resume at Phase 4." On the web console, post `finish` with that command first, then `stop` .
2026-08-20 13:42:31 -07:00
7. STOP
### PHASE 4: Tech Stack
1. List user-specified technologies (confirmed)
2. Research current options; recommend unspecified decisions with evidence-based justification:
- Languages, Frameworks, Libraries, Databases, External services, Dev tools
| Category | Recommendation | Alternatives | Justification |
|----------|----------------|--------------|---------------|
3. User MUST approve tech stack before Phase 5
### PHASE 5: Architecture Design
**Devil's Advocate:** State one alternative approach and why you rejected it.
1. Propose 2-3 architecture patterns
2. For each: appropriateness, advantages, drawbacks
3. Recommend optimal pattern with justification
4. Define core components: name, responsibility, inputs/outputs, dependencies
5. Design component interfaces
6. Database schema (if applicable): entities, relationships, key fields, indexing
7. Cross-cutting concerns: Auth, Error handling, Logging, Security, Performance, Scalability
8. Update confidence
### PHASE 6: Technical Specification
1. Break into implementation phases with dependencies
2. Technical risks:
| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
3. Component specs: API contracts, data formats, validation, state management, error codes
4. Define measurable success criteria
5. Update confidence
6. **If confidence >= 90%:** "Reached [X]% confidence. Proceed to PLAN-DRAFT, or any adjustments?"
Wait for confirmation before Phase 7.
### PHASE 7: Transition Decision
1. Summarize architecture
2. Present implementation roadmap
3. State final confidence
**If >= 90%:**
1. Get feature name (kebab-case) if not determined
2. Create `specs/<feature-name>/` if needed
3. Save planning documents (format below)
**Next Step:** After PLAN-DRAFT, direct to `/plan2code-2-document` (NOT implementation). Workflow: Plan -> Document -> Implement -> Finalize.
**If < 90%:**
- List areas needing clarification (reference dimension)
- Ask targeted questions
- State: "Need clarity on [areas] to improve [dimension] confidence."
**Phase 7 Outputs:**
1. Save PLAN-CONVERSATION (see template below) — transcript + decision summary tables
2. Create PLAN-DRAFT (see template below) using same date
3. Verify: re-read conversation as source of truth, cross-reference against PLAN-DRAFT sections (Reqs→2.1/2.2, Tech→3, Architecture→4, Risks→6, Assumptions→9, Criteria→7). Add gaps with `<!-- VERIFICATION -->` comments. Output verification summary table.
4. Append `## Planning Metrics` to PLAN-DRAFT with a `<!-- METRICS_JSON {...} -->` HTML comment. The metrics pipeline parses this — use exact format:
```
## Planning Metrics
<!-- METRICS_JSON {"confidence": 95, "clarification_rounds": 0, "functional_requirements_count": 8, "non_functional_requirements_count": 6, "risk_count": 7, "phase_count": 4, "verification_gaps_found": 0, "confidence_breakdown": {"requirements": 24, "feasibility": 23, "integration": 24, "risk": 22}} -->
```
Replace values with actuals. Optionally add plain `key: value` lines below for readability (no bold/markdown).
## Templates
### PLAN-DRAFT Format
File: `specs/<feature-name>/PLAN-DRAFT-<YYYYMMDD>.md`
Header: Title, Created date, Status (Draft | Phase 3 Complete - Resume at Phase 4 | Complete), Confidence % (Reqs/Feasibility/Integration/Risk each /25), link to PLAN-CONVERSATION.
Sections:
1. **Executive Summary** — 2-3 sentences
2. **Requirements** — 2.1 Functional (FR-N checklist), 2.2 Non-Functional (NFR-N checklist), 2.3 Out of Scope, 2.4 Testing Strategy table (Types, Phase Testing, Coverage)
3. **Tech Stack** — table: Category / Technology / Version / Justification
4. **Architecture** — 4.1 Pattern (name + rationale), 4.2 System Context Diagram, 4.3 Components table, 4.4 Data Model, 4.5 API Design
5. **Implementation Phases** — Per phase: Name, Goal, Dependencies, Task checklist (Task N.N)
6. **Risks and Mitigations** — table: Risk / Likelihood / Impact / Mitigation
7. **Success Criteria** — checklist
8. **Open Questions** — remove if none
9. **Assumptions** — list
### Response Format
1. **Phase indicator:** `🤔 [PLANNING PHASE X: Name]`
2. **Deliverables:** Findings/analysis
3. **Confidence:** Percentage with breakdown
4. **Questions:** Ambiguity resolution (if any)
5. **Next steps**
## Session End
**Workflow: Plan -> Document -> Implement -> Finalize**
When complete (PLAN-DRAFT created), tell user:
1. What was accomplished
2. **Next: `/plan2code-2-document`** (NOT implementation)
3. Documentation auto-discovers planning files
2026-09-28 19:37:41 -07:00
**On the web console:** at every session end, and on a `__stop` , post `finish` BEFORE `stop` , per console.md → Planning.
2026-08-20 13:42:31 -07:00
**Closing example:**
> "Planning complete. Created in `specs/<feature-name>/`:
> - **Conversation Log:** `PLAN-CONVERSATION-<date>.md`
> - **Implementation Plan:** `PLAN-DRAFT-<date>.md`
>
> ```
> ⋅
> ╭───╮
2026-09-28 19:37:41 -07:00
> ╲│ ★ │╱
2026-08-20 13:42:31 -07:00
> │ ◡ │ Planning done! Ready for documentation!
2026-09-28 19:37:41 -07:00
> ╰┬─┬╯
2026-08-20 13:42:31 -07:00
> =============================================
> NEXT STEP: Start a NEW conversation then run:
2026-09-28 19:37:41 -07:00
> `/plan2code-2-document --web`
2026-08-20 13:42:31 -07:00
> ```"
## Abort / Recovery
- **Abort:** Confirm with user, list files needing cleanup, stop workflow
- **Lost context:** Attach PLAN-DRAFT, state phase
- **Confidence stuck <90%:** List blockers, ask targeted questions
## Reminders
- Final phase: PLANNING PHASE 7: Transition Decision
- Do NOT implement - design and present plan only