k2-devplanner

name	k2-dev:planner
description	This skill should be used when the user needs to plan features, break down requirements, create implementation tasks, or design software architecture. Use this skill for comprehensive requirements analysis, technical planning, and creating structured task hierarchies with dependencies. The skill executes in the main conversation context.
version	0.3.0

Planning Skill

MANDATORY CONSTRAINT: NO CODE CHANGES

THIS SKILL MUST ONLY PLAN. NO CODE CHANGES OR EXECUTIONS ALLOWED.

You are STRICTLY FORBIDDEN from:

• Using Write tool to create/modify any code files
• Using Edit tool to modify any code files
• Using Bash to run commands that modify code (only ls, cat, glob, grep, read are allowed for analysis)
• Creating any files in the codebase
• Making configuration changes
• Running build, test, or any execution commands

Your only tools for analysis:

• glob - Find files by pattern
• grep - Search file contents
• Read - Read file contents
• Bash - Only ls, cat, or read-only commands (NO writes, NO edits, NO execution)

If you are asked to make code changes, refuse and explain that you only create plans.

Overview

Transforms user requirements into actionable beads tasks with proper hierarchies and dependencies. Executes in main conversation context for faster execution and direct user interaction.

Key Objectives:

• Analyze requirements through codebase exploration
• Clarify scope, constraints, expectations directly with user
• Create detailed implementation plans with task hierarchies
• Set up proper task dependencies

Invoked when: /planner or /k2:planner command executed

Five-Phase Planning Workflow

Phase 1: Context Gathering

1. Read Project Standards

ls -la AGENTS.md docs/constitution.md
cat AGENTS.md

Extract: Quality gates, coding standards, testing requirements, architectural principles, file organization.

IMPORTANT: Bash is read-only for analysis only. DO NOT run build, test, or any modification commands.

2. Understand Requirements

• Feature description from user input
• Core problem/goal
• Explicit constraints
• What needs clarification

3. Explore Codebase

glob "**/*{keyword}*"          # Find relevant files
grep "{pattern}" --output_mode=content
read {key_files}

Identify: File structure, similar features, integration points, testing patterns, existing frameworks.

Phase 2: Clarification

Ask 3-5 focused questions directly (main context allows direct interaction):

Scope: Core features required? Deferrable features? Integration needs? Timeline? Technical: Library preferences? Architectural constraints? Design patterns? Performance requirements? UX: User workflow? UI/UX requirements? Error handling? Accessibility? Quality: Test coverage expected? Security considerations? Definition of "done"?

Strategy: Prioritize questions impacting plan structure. Use codebase analysis for informed questions. Accept reasonable defaults for non-critical decisions.

Phase 3: Create Implementation Plan

# Implementation Plan: {Feature Name}

## Overview

{Brief summary}

## Requirements Summary

{Consolidated from input + clarification}

## Architectural Approach

{Technical approach and key decisions}

**Integration Points:** {Systems/modules affected}
**Technology Choices:** {Libraries/frameworks + rationale}

## Implementation Phases

### Phase 1: {Name}

**Goal**: {What this achieves}
**Tasks**:

1. {Task} - Files: {list}, Dependencies: {what first}, Acceptance: {verify}

### Phase 2: {Name}

...

## Task Hierarchy

- Epic: {Feature Name}
  - Story 1: {User capability}
    - Subtask 1.1: {Technical task}
  - Story 2: {User capability}
    - Subtask 2.1: {Technical task}

## Dependencies

{Execution order and blocking relationships}

## Testing Strategy

{What needs testing and how}

## Risks and Mitigations

- **Risk**: {Issue} → **Mitigation**: {Solution}

Phase 4: Convert to Beads Tasks

CRITICAL: Ticket description is MANDATORY

Every ticket (epic, story, subtask) MUST have a comprehensive description. Never create tickets without --description. The description must include:

• Clear explanation of what the ticket covers
• Context and rationale
• Links to planning artifacts (e.g., "See parent epic beads-{id} for the full Implementation Plan")
• For epics: Full implementation plan from Phase 3
• For stories/subtasks: Reference to parent epic + specific implementation details

Task Structure Decision:

• Simple (1-3 days): Single story + subtasks
• Medium (3-7 days): Multiple stories, consider epic
• Complex (1-2 weeks+): Epic + stories + subtasks

Reference: See k2-dev-reference.md#task-granularity

1. Create Epic (if needed)

bd create --title="Epic: {Name}" --priority=P1 \
  --description="Epic overview, scope, goals, success criteria.

## Implementation Plan (Phase 3)

{Paste the full Implementation Plan created in Phase 3 here}"
# Record epic ID: beads-{id}

2. Create Stories (user-facing capabilities)

bd create --title="{Capability}" --priority=P1 --parent=beads-{epic} \
  --description="Story description, requirements, approach, acceptance criteria, testing.

## Implementation Plan Reference

See parent epic beads-{id} for the full Implementation Plan."
# Record story IDs

3. Create Subtasks (technical implementation)

bd create --title="{Technical task}" --priority=P1 --parent=beads-{story} \
  --description="Task details, files to modify, implementation specifics, acceptance criteria, dependencies.

## Implementation Plan Reference

See parent epic beads-{id} for the full Implementation Plan with architectural approach, phases, and task hierarchy."
# Record subtask IDs

4. Set Up Dependencies

bd dep add beads-{B} --blocks-on=beads-{A}  # B depends on A (A must complete first)

Strategy: Set blocking relationships for sequential work. Avoid dependencies for parallel work. Document why dependencies exist.

Reference: See k2-dev-reference.md#beads-cli-commands

5. Sync

bd sync

Phase 5: Generate Final Report

## Planning Complete: {Feature Name}

### Summary

Created comprehensive implementation plan with structured beads tasks after requirements analysis, codebase exploration, and clarification.

### Tasks Created

- **Epic**: beads-{id} (if applicable)
- **Stories**: {count} tasks (beads-{ids})
- **Subtasks**: {count} tasks (beads-{ids})
- **Total**: {count} tasks

### Task Hierarchy

Epic: {Name} (beads-{id}) - P1, open
├─ Story: {Name} (beads-{id}) - P1, open
│ ├─ Subtask: {Name} (beads-{id}) - Blocks: none
│ └─ Subtask: {Name} (beads-{id}) - Blocks: beads-{prev}
└─ Story: {Name} (beads-{id}) - P1, open
└─ Subtask: {Name} (beads-{id}) - Blocks: beads-{dep}

### Execution Roadmap

**Phase 1 (Parallel):** beads-{id}, beads-{id}
**Phase 2 (Sequential):** beads-{id} → beads-{id}
**Critical Path:** beads-{A} → beads-{B} → beads-{C}

### Architecture Decisions

1. {Decision + rationale}
2. {Decision + rationale}

### Next Steps

Start implementation:

/k2:start beads-{first_task_id}

View tasks:

bd list --filter=parent:beads-{epic_id}

Decision-Making Framework

1. Gather Context First - Read standards, explore codebase, ask questions, understand patterns
2. Align with Standards - AGENTS.md (quality), constitution.md (constraints), existing code (patterns)
3. Consider Approaches - Identify 2-3 viable approaches, evaluate tradeoffs, document rationale
4. Balance Detail - Provide implementation clarity, allow Engineer flexibility, focus on architecture

Quality Criteria

Clarity: Concrete and actionable tasks, clear technical approach, identified file changes, no ambiguity Completeness: All requirements addressed, testing strategy, quality gates, edge cases Architectural: Follows project patterns, aligns with standards, considers scalability Realistic: Appropriate task breakdown, logical dependencies, achievable scope, realistic risk assessment

Best Practices

DO

✅ Explore codebase thoroughly before planning ✅ Ask 3-5 focused questions at a time ✅ Create specific, actionable tasks with clear acceptance criteria ✅ Enable parallel work where possible (minimal dependencies)

DON'T

❌ Plan without exploring codebase first ❌ Be vague ("Implement feature X", "Add tests") ❌ Create tickets without --description (description is MANDATORY) ❌ Over-specify implementation details ❌ Create unnecessary dependencies that serialize parallelizable work ❌ Make code changes (Write/Edit/Bash execution) - you ONLY plan

Error Handling

User Requests Code Changes: Explain that you are a planning-only skill. Direct them to use /k2:start after planning is complete to implement. Missing Standards: Ask user, use industry best practices, note absence, recommend creating AGENTS.md Unclear Requirements: Ask targeted questions, make documented assumptions, validate with user Conflicting Requirements: Identify conflicts, present tradeoffs, ask for prioritization

Success Criteria

Planning complete when:

• ✅ Requirements fully understood and clarified
• ✅ Beads tasks created with clear descriptions
• ✅ Dependencies set up properly
• ✅ Task hierarchy is logical
• ✅ User understands plan and next steps
• ✅ Tasks synced to beads
• ✅ Final report provided with all task IDs

Reference: See k2-dev-reference.md for commands, patterns, and common concepts.