| name | plan-phase |
| description | Generate execution-ready implementation plans (PLUS per-task ticket files) from research docs — planning ONLY, no fixing or verifying. North Star is whether a JR developer can execute the work with zero additional context. |
| writes-to | .artifacts/plan/ |
| allowed-tools | ["Read","Edit","Write","Bash(git:*)","Bash(grep:*)","Bash(sed:*)","Bash(awk:*)","Bash(jq:*)","Bash(date:*)","Bash(find:*)","Bash(python3:*)"] |
| hard-guards | ["NO code modifications during planning","NO fixes or verification","Focus ONLY on generating clear executable plans","Every task must be unambiguous to a JR developer"] |
Plan Phase
Overview
Generate execution-ready, coding-only implementation plans from research documents.
New output shape: the Plan phase now produces a plan bundle directory containing:
- a single master plan (
PLAN.md)
- individual ticket files (
tickets/T001.md, tickets/T002.md, …)
This makes it easy to execute task-by-task and/or paste tickets into an issue tracker.
North Star Rule
If a JR developer picked this up, could they start coding immediately?
If the answer is "no" or "they'd need to ask clarifying questions," the plan is incomplete.
When to Use
- User asks to "create a plan from research"
- User references a research doc in
.artifacts/research/
- User wants "implementation steps" from findings
- User asks to "break down into tasks" a researched topic
What This Skill Does NOT Do
| ❌ DON'T | ✅ DO INSTEAD |
|---|
| Fix code issues | Document them as tasks to fix |
| Verify implementations | Plan verification steps |
| Run tests | Plan what tests to write |
| Deploy anything | Plan deployment as a task |
| Make code changes | Document exactly what changes to make |
Output Layout (Plan Bundle)
Create ONE directory per plan:
.artifacts/plan/YYYY-MM-DD_HH-MM-SS_<topic>/
PLAN.md
tickets/
INDEX.md
T001.md
T002.md
...
PLAN.md is the master document.
tickets/*.md are the per-task tickets.
tickets/INDEX.md is generated by the ticket script.
Helper Script: plan → tickets
This skill ships with a helper script:
scripts/plan_to_tickets.py
Note: this script is bundled with the skill (not your repo). Invoke it by path — Step 5 shows a portable find command to locate it.
It:
- Parses task headings in
PLAN.md
- Generates
tickets/T###.md files
- Generates
tickets/INDEX.md
- Optionally updates
PLAN.md between markers:
<!-- TICKET_INDEX:START -->
<!-- TICKET_INDEX:END -->
Task heading formats the script recognizes (##..######):
### T001: <title>
### Task T001: <title>
## Task T001 - <title>
#### T001 – <title>
Planning Workflow
1) Read Research Doc
Read from: .artifacts/research/<topic>.md
Extract: scope, constraints, target files, unresolved questions, proposed solutions
2) Verify Git Freshness
git rev-parse HEAD
git status --short
3) Create Plan Bundle Directory
Create:
.artifacts/plan/YYYY-MM-DD_HH-MM-SS_<topic>/
.artifacts/plan/YYYY-MM-DD_HH-MM-SS_<topic>/tickets/
4) Write the Master Plan (PLAN.md)
Save as:
.artifacts/plan/YYYY-MM-DD_HH-MM-SS_<topic>/PLAN.md
Use this structure:
---
title: "<topic> implementation plan"
link: "<topic>-plan"
type: implementation_plan
ontological_relations:
- relates_to: [[<research-link>]]
tags: [plan, <topic>, coding]
uuid: "<uuid>"
created_at: "<ISO-8601 timestamp>"
parent_research: ".artifacts/research/<file>.md"
git_commit_at_plan: "<short_sha>"
---
## Goal
- ONE singular coding-focused outcome
- Explicitly state what is OUT of scope (ops, deploy, excessive testing)
## Scope & Assumptions
- IN scope: (technical items only)
- OUT of scope: (what we're NOT doing)
- Assumptions: (frameworks, environments, libraries)
## Deliverables
- Source code modules, functions, or APIs
- Documentation limited to developer-level notes (not user docs)
## Readiness
- Preconditions: repos, libs, data schemas, sample inputs
- What must exist before starting
## Milestones
- M1: Skeleton & architecture setup
- M2: Core logic & data flow
- M3: Feature completion & refinement
- M4: Basic test(s) & integration hooks
## Ticket Index
<!-- TICKET_INDEX:START -->
<!-- TICKET_INDEX:END -->
## Work Breakdown (Tasks)
For EACH task, include a task heading + the required fields.
**REQUIRED heading format (for script parsing):**
- `### T001: <task title>`
Then include these fields (any order is OK, but ALL must exist):
- **Summary**
- **Owner**
- **Estimate**
- **Dependencies**
- **Target milestone**
- **Acceptance test** (exactly ONE)
- **Files/modules touched** (exact paths)
### T001: <task title>
**Summary**: <...>
**Owner**: <...>
**Estimate**: <...>
**Dependencies**: <none|T000,T002>
**Target milestone**: <M1|M2|M3|M4>
**Acceptance test**: <exactly one proof>
**Files/modules touched**:
- path/to/file.ext
- path/to/other.ext
**Steps**:
1. <step>
2. <step>
### T002: <task title>
...
## Risks & Mitigations
Keep technical:
- Library stability issues
- API version drift
- Schema mismatch risks
- Breaking changes in dependencies
## Test Strategy
At most ONE new test per task, only for validating main coding work.
Focus on proving correctness, not coverage.
## References
- Research doc sections
- Key code references (file:line format)
## Final Gate
- **Output summary**: plan dir path, milestone count, ticket count
- **Next step**: proceed to execute-phase with the generated plan path
5) Generate Individual Ticket Files (scripted)
Run the ticket generator against the master plan.
Portable invocation (works whether the skill pack is installed globally or project-local):
PLAN_FILE=".artifacts/plan/YYYY-MM-DD_HH-MM-SS_<topic>/PLAN.md"
TICKETIZER="$(find ~/.pi .pi -type f -path '*/plan-phase/scripts/plan_to_tickets.py' -print -quit 2>/dev/null)"
test -n "$TICKETIZER" || { echo "ERROR: could not find plan_to_tickets.py" >&2; exit 1; }
python3 "$TICKETIZER" "$PLAN_FILE"
This produces:
.artifacts/plan/.../tickets/T001.md, .artifacts/plan/.../tickets/T002.md, …
.artifacts/plan/.../tickets/INDEX.md
- Updates the
## Ticket Index section in PLAN.md if the markers exist.
Task Writing Guidelines
✅ Good Task
### T003: Add user authentication middleware
**Summary**: Add JWT auth middleware and apply it to /api/* routes
**Owner**: backend
**Estimate**: 2h
**Dependencies**: T001
**Target milestone**: M2
**Acceptance test**: curl /api/users returns 401 without header, 200 with valid token
**Files/modules touched**:
- src/middleware/auth.ts
- src/app.ts
**Steps**:
1. Create src/middleware/auth.ts with verifyToken() function
2. Import in src/app.ts and apply to /api/* routes
❌ Bad Task
T003: Fix auth
- Handle the auth stuff properly
- Make sure it works
Rules for Tasks
- Present tense, actionable: "Add function X" not "Function X should be added"
- File paths explicit: No "find the right place to put it"
- One acceptance test per task: Single proof of correctness
- No hand-waving: "Implement caching" → "Add Redis caching to src/cache.ts with get/set methods"
- Depend on tasks, not people: "Depends on T001" not "Wait for backend team"
- Heading format is mandatory:
### T###: ... so tickets can be generated
Git Freshness Check
Always capture and include:
COMMIT_SHA=$(git rev-parse --short HEAD)
STATUS=$(git status --short)
If research doc mentions specific commits/branches and they've changed:
- Mark affected tasks for re-verification
- Note the discrepancy in plan frontmatter
Issue Opening (When Available)
If planning reveals blockers or prerequisites that need tracking:
- Check for Gitea/GitHub availability
- Open issues ONLY for:
- External dependencies
- Prerequisites that aren't in scope
- Decisions needed before execution
- Link issue IDs to relevant tasks
Validation Questions
Before finalizing, ask:
- Ambiguity check: Could a JR developer understand every task without questions?
- Completeness: Are all prerequisites and dependencies listed?
- Executability: Does each task specify exact files and acceptance criteria?
- Scope creep: Is ops/deploy work leaking into the plan?
- Ticket generation: Do the tickets exist for every task ID?
Output Format
After plan generation, output:
✓ Plan bundle written to: .artifacts/plan/YYYY-MM-DD_HH-MM-SS_<topic>/
✓ Master plan: .artifacts/plan/YYYY-MM-DD_HH-MM-SS_<topic>/PLAN.md
✓ Tickets: N (see tickets/INDEX.md)
✓ Milestones: 4
✓ Git state: <short_sha>
Next step: Execute phase using .artifacts/plan/YYYY-MM-DD_HH-MM-SS_<topic>/PLAN.md
Subagent Usage (Sparingly)
Only spawn subagents if:
- Research doc is large (>500 lines)
- Need to map tasks to existing codebase structure
- Need parallel analysis of multiple subsystems
Typical subagents:
codebase-analyzer: Find where new code fits
context-synthesis: Extract structured tasks from prose research
Default: Don't use subagents. Trust the research doc.
Handoff
After writing the plan bundle to .artifacts/plan/, proceed to execute-phase if the next step is the Execute phase.