plan-phase

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:

1. Parses task headings in PLAN.md
2. Generates tickets/T###.md files
3. Generates tickets/INDEX.md
4. 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

# Capture current state
git rev-parse HEAD          # Commit SHA
git status --short          # Working tree status

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

1. Present tense, actionable: "Add function X" not "Function X should be added"
2. File paths explicit: No "find the right place to put it"
3. One acceptance test per task: Single proof of correctness
4. No hand-waving: "Implement caching" → "Add Redis caching to src/cache.ts with get/set methods"
5. Depend on tasks, not people: "Depends on T001" not "Wait for backend team"
6. 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:

1. Ambiguity check: Could a JR developer understand every task without questions?
2. Completeness: Are all prerequisites and dependencies listed?
3. Executability: Does each task specify exact files and acceptance criteria?
4. Scope creep: Is ops/deploy work leaking into the plan?
5. 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.