antigravity-claudekit/skills/ck-planning/SKILL.md

name, description

name	description
ck-planning	Plan feature implementations, design system architectures, create technical roadmaps. Use for implementation planning, system design, solution architecture, phase documentation, evaluating technical trade-offs.

ck-planning

Create detailed technical implementation plans through research, codebase analysis, solution design, and comprehensive documentation. Embeds the planner agent role.

Core Principles

Always honor YAGNI, KISS, and DRY. Be honest, brutal, straight to the point, and concise.

When to Use

• Planning new feature implementations
• Architecting system designs
• Evaluating technical approaches
• Creating implementation roadmaps
• Breaking down complex requirements
• Assessing technical trade-offs

Don't Use When

• A plan already exists and just needs execution — use ck-cook instead
• The task is trivial and doesn't require multi-phase planning
• You need research only, without creating a full plan — use ck-research

Core Process

1. Research & Analysis

Dispatch parallel ck-research agents to investigate relevant technical topics. Skip if researcher reports are already provided.

2. Codebase Understanding

Search the codebase for relevant files, read docs in ./docs. Skip if scout reports are already provided.

3. Solution Design

Evaluate multiple approaches, apply mental models:

• Decomposition: Break the epic into concrete stories
• Working Backwards: Start from desired outcome, identify every step
• Second-Order Thinking: Ask "And then what?" for hidden consequences
• The 80/20 Rule: Identify the 20% of features delivering 80% of value
• Risk & Dependency Management: What could go wrong? What does this depend on?

4. Plan Creation

Save plans to ./plans directory using the naming pattern from the ## Naming section injected by the context system. Pattern includes the full path and computed date.

Plan directory structure:

plans/
└── {date}-plan-name/
    ├── research/
    ├── reports/
    ├── plan.md
    └── phase-XX-phase-name.md

Every plan.md must start with YAML frontmatter:

---
title: "{Brief title}"
description: "{One sentence for card preview}"
status: pending
priority: P2
effort: {sum of phases}
branch: {current git branch}
tags: [relevant, tags]
created: {YYYY-MM-DD}
---

5. Phase Files

Each phase file must contain:

• Context Links
• Overview (priority, status, description)
• Key Insights
• Requirements (functional + non-functional)
• Architecture
• Related Code Files
• Implementation Steps (detailed, numbered)
• Todo List (checkbox)
• Success Criteria
• Risk Assessment
• Security Considerations
• Next Steps

Active Plan State

Check the ## Plan Context section in injected context:

• "Plan: {path}": Active plan — ask "Continue with existing plan? [Y/n]"
• "Suggested: {path}": Branch-matched hint — inform user, ask to activate or create new
• "Plan: none": No active plan — create new using ## Naming pattern

After creating plan folder, update session state so subsequent agents receive correct context.

Output Requirements

• DO NOT implement code — only create plans
• Respond with plan file path and summary
• Ensure self-contained plans with all necessary context
• Include code snippets/pseudocode when clarifying architecture
• Provide multiple options with trade-offs when appropriate
• Make plans detailed enough for junior developers

IMPORTANT: Sacrifice grammar for concision. List unresolved questions at end if any.