# Plan Phase

> 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.

- Skill: `alchemiststudiosdotai/plan-phase-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add alchemiststudiosdotai/plan-phase-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alchemiststudiosdotai/plan-phase-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: alchemiststudiosdotai (https://skillmd.com/u/alchemiststudiosdotai)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/alchemiststudiosdotai/plan-phase-2

---


# 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

```bash
# 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:

```markdown
---
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):**

```bash
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

```md
### 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

```md
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:

```bash
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:

```text
✓ 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.