Writing Plans

Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

Announce at start: "I'm using the writing-plans skill to create the implementation plan."

Save plans to: .claude/plans/YYYY-MM-DD-<feature-name>.md

Workflow

See examples/workflow-definition.yml for complete workflow with all decision points.

Key steps:

1. Check upstream context (from brainstorming or GitHub issue)
2. Gather requirements
3. Choose detail level (comprehensive/standard/outline)
4. Write plan with code-architect agent
5. Validate structure
6. Create/link GitHub issue
7. Offer execution choice (subagent/parallel/later)

Plan Structure

Document Header

See examples/plan-template.md for complete template.

Every plan must include:

• Goal: One sentence describing what this builds
• Architecture: 2-3 sentences about approach
• Tech Stack: Key technologies/libraries

Task Breakdown

Bite-sized tasks (2-5 minutes each):

• Write failing test
• Run to verify failure
• Implement minimal code
• Run to verify pass
• Commit

Each task specifies:

• Files: Exact paths to create/modify/test
• Steps: Numbered with complete code examples
• Commands: Exact commands with expected output

Template: See examples/plan-template.md for full task structure.

Context Integration

Check Upstream Context

Before creating plan, check for context from previous skills (brainstorming, GitHub issues).

Implementation: See examples/context-handling.md

Key points:

• Load skill_context to check for design documents
• Reuse decisions already made
• Don't re-ask questions answered in brainstorming

Save Context Output

Save plan context for downstream skills (executing-plans, subagent-driven).

Implementation: See examples/context-handling.md

Includes:

• Plan file path
• Task count
• GitHub issue number
• Link to workflow

GitHub Integration

After plan created, integrate with GitHub for tracking:

Search for existing issue:

gh issue list --search "<topic>" --state open --json number,title --limit 5

Offer choices via AskUserQuestion:

• Create new issue with plan summary and task checklist
• Link to existing issue number
• Skip GitHub tracking

Issue creation: See examples/context-handling.md for template.

Execution Handoff

After saving plan, use AskUserQuestion to offer execution choice:

Options:

1. Subagent-Driven: Execute in this session with fresh subagent per task
2. Parallel Session: Open new session with executing-plans skill
3. Later: Save for manual execution

NEVER present as plain text like "1. Subagent, 2. Parallel... type 1 or 2". Always use AskUserQuestion tool.

If Subagent-Driven chosen:

• Use subagent-driven-development skill
• Stay in this session
• Fresh subagent per task + code review
• Context automatically passed

If Parallel Session chosen:

• Guide user to open new session in worktree
• New session uses executing-plans skill
• Context available via .popkit/context/current-workflow.json

Quality Guidelines

Always include:

• Exact file paths (not "add to utils folder")
• Complete code examples (not "add validation")
• Exact commands with expected output
• Reference relevant skills with @ syntax

Principles:

• DRY (Don't Repeat Yourself)
• YAGNI (You Aren't Gonna Need It)
• TDD (Test-Driven Development)
• Frequent commits (after each passing test)

Related Skills

• pop-brainstorming: Upstream - provides design document input
• pop-executing-plans: Downstream - executes plan task-by-task
• pop-subagent-driven: Downstream - executes with fresh subagent per task
• pop-code-architect: Called internally - writes the actual plan

Examples

See examples/ directory for:

• Complete workflow definition
• Plan document template
• Task structure template
• Context handling code
• GitHub integration examples

---

Version: 1.0.0 Category: Development Workflow Tier: Core