P11: Planning Agent Workflow (Structured Development)
P11: Planning Agent Workflow (Structured Development)
type: project id: P11 title: Planning Agent Workflow track: Kiro CLI Mastery difficulty: Intermediate time_estimate: 1 week prerequisites: [P01, P02, P03, P04, P05] knowledge_areas: [Planning Agents, Spec-Driven Development, Requirements Engineering] tools: [Kiro CLI] main_book: “The Pragmatic Programmer by Hunt & Thomas” —
Learning Objectives
By completing this project, you will:
- Understand the separation of planning and execution in AI-assisted development workflows
- Master the
/plancommand and its interactive questioning flow for requirements gathering - Learn to review, modify, and approve AI-generated implementation plans before any code changes
- Develop intuition for when to use planning mode versus direct execution
- Build habits that reduce rework by thinking before coding
Deep Theoretical Foundation
The Problem with “Just Start Coding”
In traditional development, we often jump directly into code. With AI assistants, this tendency is amplified - we prompt, the AI writes code, we accept. But this leads to:
- Misaligned implementations - The AI solved a different problem than intended
- Wasted context - Tokens spent on incorrect solutions
- Rework cycles - Delete, re-prompt, repeat
- Hidden assumptions - Neither human nor AI explicitly stated requirements
Spec-Driven Development: The Paradigm Shift
Spec-driven development (SDD) is one of 2025’s key new AI-assisted engineering practices. The core insight:
Instead of coding first and writing docs later, you start with a spec - a contract for how your code should behave that becomes the source of truth.
Traditional Flow:
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Prompt │ ──► │ Code │ ──► │ Fix │ ◄─┐
└──────────┘ └──────────┘ └──────────┘ │
│ │
└────────┘
(repeat)
Spec-Driven Flow:
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Gather │ ──► │ Plan │ ──► │ Approve │ ──► │ Execute │
│ Reqs │ │ │ │ │ │ │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
│ │ │
▼ ▼ ▼
[Questions] [Tasks] [Review]
answered generated complete
The Planning Agent Architecture
Kiro CLI separates “thinking” from “doing” through distinct agent modes:
┌─────────────────────────────────────────────────────────────────┐
│ KIRO CLI │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ PLANNING AGENT │ │ EXECUTION AGENT │ │
│ │ │ │ │ │
│ │ • Read-only │ ───► │ • Write access │ │
│ │ • Questions │ plan │ • Implements │ │
│ │ • Research │ handoff │ • Tests │ │
│ │ • Plan tasks │ │ • Iterates │ │
│ └─────────────────┘ └─────────────────┘ │
│ ▲ │
│ │ Shift+Tab or /plan │
│ │ │
│ ┌───────┴───────┐ │
│ │ Normal Mode │ (default execution) │
│ └───────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Why Separation Matters
The planning agent has a fundamentally different purpose:
| Aspect | Planning Agent | Execution Agent |
|---|---|---|
| File Access | Read-only | Read-write |
| Goal | Understand, clarify | Implement, test |
| Output | Task list | Code changes |
| Risk | Zero (no modifications) | Changes files |
| Interactivity | High (questions) | Lower (doing) |
Real-World Analogy: The Architect and Builder
Consider building a house:
- Without planning: You show up with materials and start building. Halfway through, you realize the bathroom is in the wrong place.
- With planning: An architect creates blueprints. You review them. Only then does construction begin.
The planning agent is your architect. It asks questions, considers the existing structure (codebase), and produces blueprints (task list) before any construction begins.
Historical Context: From Waterfall to Agile to AI-Assisted
1970s Waterfall: Requirements ──► Design ──► Code ──► Test
(months of documentation before coding)
2000s Agile: Sprint [Requirements + Design + Code + Test]
(faster iteration, less upfront planning)
2025 AI-Assisted: Plan Mode ──► Approved Tasks ──► AI Execution
(structured thinking, rapid implementation)
AI-assisted development brings back structured planning but at a different timescale - minutes instead of months, with the AI handling both planning and execution.
Book Reference
“The Pragmatic Programmer” by Hunt & Thomas emphasizes “Tracer Bullets” and “Prototypes” - methods to validate understanding before full implementation. The planning agent is the AI-era equivalent: validate the approach before committing to execution.
Complete Project Specification
What You’re Building
A comprehensive spec-driven development workflow using Kiro’s Planning Agent that:
- Enters plan mode via
/plancommand or Shift+Tab shortcut - Gathers requirements through interactive questioning
- Researches the codebase to understand existing patterns
- Generates a structured implementation plan with clear tasks
- Supports plan modification before approval
- Hands off to execution only after explicit approval
Expected Behavior
$ kiro-cli chat
> /plan
[Planning Agent] Entering plan mode. I will:
1. Gather requirements through questions
2. Research the codebase for context
3. Generate an implementation plan
4. Wait for your approval before executing
What would you like to build?
> "Add user authentication with OAuth2"
[Planning Agent] I have questions to clarify your requirements:
1. Authentication Provider(s):
○ Google only
● Google + GitHub [Recommended for dev audiences]
○ Custom list (specify)
2. Session Management:
● JWT tokens (stateless)
○ Server-side sessions
○ Let me decide based on codebase
3. New Users:
● Auto-create on first login
○ Require pre-registration
○ Admin approval workflow
[Select options or type responses]
> 1:Google+GitHub, 2:JWT, 3:Auto-create
[Planning Agent] Researching codebase...
├── Found: src/routes/auth.ts (existing auth)
├── Found: src/middleware/requireAuth.ts
├── Found: prisma/schema.prisma (User model)
└── Analyzing patterns...
IMPLEMENTATION PLAN:
┌─────────────────────────────────────────────────────────────┐
│ Phase 1: Dependencies and Configuration │
│ Task 1.1: Install OAuth libraries │
│ Task 1.2: Add environment variables for OAuth secrets │
│ Task 1.3: Update .env.example with new variables │
│ │
│ Phase 2: Database Changes │
│ Task 2.1: Add OAuth fields to User model │
│ Task 2.2: Create migration │
│ Task 2.3: Update Prisma client │
│ │
│ Phase 3: OAuth Routes │
│ Task 3.1: Create /auth/google routes │
│ Task 3.2: Create /auth/github routes │
│ Task 3.3: Implement callback handlers │
│ │
│ Phase 4: JWT Integration │
│ Task 4.1: Create JWT utility functions │
│ Task 4.2: Update auth middleware │
│ Task 4.3: Add refresh token logic │
│ │
│ Phase 5: Frontend (if applicable) │
│ Task 5.1: Add OAuth login buttons │
│ Task 5.2: Handle redirect callbacks │
│ │
│ Estimated: 12 files modified, 3 new files │
└─────────────────────────────────────────────────────────────┘
Options:
[y] Approve and execute
[n] Cancel
[m] Modify plan
[?] Ask questions about the plan
Solution Architecture
Component Overview
┌─────────────────────────────────────────────────────────────────┐
│ PLANNING WORKFLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ User Input │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ /plan Entry │ Shift+Tab shortcut │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ REQUIREMENTS GATHERING │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Question │◄──►│ Answer │ │ │
│ │ │ Generator │ │ Collector │ │ │
│ │ └─────────────┘ └─────────────┘ │ │
│ │ │ │ │ │
│ │ └────────┬─────────┘ │ │
│ │ ▼ │ │
│ │ ┌─────────────────┐ │ │
│ │ │ Requirements │ │ │
│ │ │ Document │ │ │
│ │ └─────────────────┘ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ CODEBASE RESEARCH │ │
│ │ │ │
│ │ • File discovery (related code) │ │
│ │ • Pattern extraction (coding style) │ │
│ │ • Dependency analysis │ │
│ │ • Test coverage check │ │
│ └──────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ PLAN GENERATION │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Task List (ordered, with dependencies) │ │ │
│ │ │ ├── Phase 1: Foundation │ │ │
│ │ │ │ ├── Task 1.1: ... │ │ │
│ │ │ │ └── Task 1.2: ... │ │ │
│ │ │ ├── Phase 2: Core │ │ │
│ │ │ │ └── Task 2.1: ... │ │ │
│ │ │ └── Phase 3: Polish │ │ │
│ │ │ └── Task 3.1: ... │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ APPROVAL WORKFLOW │ │
│ │ │ │
│ │ [Approve] [Modify] [Cancel] [Ask Questions] │ │
│ │ │ │ │ │ │ │
│ │ ▼ ▼ ▼ ▼ │ │
│ │ Execute Edit Plan Exit Clarify │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Data Flow
User Request
│
▼
┌─────────────────┐
│ Parse Intent │ ──► What is the user trying to build?
└────────┬────────┘
│
▼
┌─────────────────┐
│ Generate Qs │ ──► What clarifications are needed?
└────────┬────────┘
│
▼
┌─────────────────┐
│ Collect Answers │ ◄── User provides selections/answers
└────────┬────────┘
│
▼
┌─────────────────┐
│ Search Codebase │ ──► Find related files, patterns
└────────┬────────┘
│
▼
┌─────────────────┐
│ Generate Plan │ ──► Create phased task list
└────────┬────────┘
│
▼
┌─────────────────┐
│ Present Plan │ ──► Show to user for review
└────────┬────────┘
│
┌────┴────┐
│ │
Approve Modify
│ │
▼ ▼
Execute Edit & Re-present
Key Interfaces
| Interface | Purpose | Example |
|---|---|---|
/plan |
Enter planning mode | /plan or Shift+Tab |
| Question UI | Gather requirements | Multi-select, text input |
| Plan Display | Show generated tasks | Boxed task list |
| Approval | Confirm execution | y/n/m/? options |
| Task Format | Structured output | Phase > Task > Details |
Technology Choices
- Kiro CLI chat mode: Primary interface
- Planning Agent: Built into Kiro, activated via
/plan - Task storage: Internal state (or JSON for persistence)
- Codebase access: Read-only during planning
Phased Implementation Guide
Phase 1: Foundation - Understanding Plan Mode
Goal: Learn to enter and use planning mode effectively.
Step 1.1: Activate Planning Mode
# Start Kiro CLI
$ kiro-cli chat
# Enter plan mode (two methods)
> /plan
# OR press Shift+Tab
Hint: The Planning Agent announces itself with “Entering plan mode” and explains what it will do.
Step 1.2: Practice with a Simple Request
Start with something small:
> /plan
> "Add a health check endpoint that returns server status"
Observe:
- What questions does it ask?
- What files does it research?
- How is the plan structured?
Hint: The Planning Agent is read-only. It cannot modify files - that’s the key safety feature.
Step 1.3: Understand the Question Types
The Planning Agent asks different types of questions:
Single Choice: ○ Option A
● Option B [Selected]
○ Option C
Multiple Choice: [x] Feature 1
[x] Feature 2
[ ] Feature 3
Free Text: Enter database name: ___________
Confirmation: Proceed with detected pattern? (y/n)
Hint: Answer concisely. The agent uses your answers to refine the plan.
Phase 2: Core Functionality - Working with Plans
Goal: Master plan review, modification, and execution.
Step 2.1: Review Generated Plans
When a plan is generated, examine:
IMPLEMENTATION PLAN:
┌─────────────────────────────────────────────────────────────┐
│ Phase 1: [Name] │
│ Task 1.1: [Description] │
│ Task 1.2: [Description] │
│ │
│ Phase 2: [Name] │
│ ... │
│ │
│ Estimated: X files modified, Y new files │
└─────────────────────────────────────────────────────────────┘
Questions to ask yourself:
- Does this match my understanding?
- Are there missing steps?
- Is the order logical?
Hint: Use ? to ask questions about specific tasks before approving.
Step 2.2: Modify Plans Before Approval
If the plan isn’t quite right:
Options: [y] Approve [n] Cancel [m] Modify [?] Questions
> m
What would you like to change?
> "Add error logging to each task"
# OR
> "Skip the frontend tasks - I'll handle those manually"
# OR
> "Break Phase 2 into smaller steps"
The agent regenerates the plan with your modifications.
Hint: Modification is cheap. It’s better to fix the plan than fix the code.
Step 2.3: Approve and Execute
When satisfied:
> y
[Planning Agent] Handing off to Execution Agent...
[Execution Agent] Executing Phase 1, Task 1.1...
Observe how tasks execute sequentially, following the plan.
Hint: The plan becomes a checklist. You can interrupt if something goes wrong.
Phase 3: Polish and Edge Cases
Goal: Handle complex scenarios and optimize your workflow.
Step 3.1: Multi-Feature Planning
For complex requests spanning multiple features:
> /plan
> "Refactor the payment module: add Stripe support, implement
subscription billing, and add webhook handling"
The agent should:
- Recognize multiple features
- Ask questions about each
- Create a phased plan addressing all features
Hint: Complex requests benefit most from planning. The agent breaks down complexity.
Step 3.2: Plan with Existing Context
If you’ve been working in a codebase:
# Already in a Kiro session with context...
> /plan
> "Now add unit tests for the module we just built"
The Planning Agent uses existing conversation context.
Hint: Context carries over. The agent knows what you’ve been working on.
Step 3.3: Handling Ambiguity
When your request is ambiguous:
> /plan
> "Make it faster"
[Planning Agent] I need more context:
1. What specifically needs optimization?
○ Database queries
○ API response times
○ Frontend rendering
○ Build process
2. What's the current performance baseline?
The agent asks clarifying questions rather than guessing.
Hint: Ambiguous prompts get questions, not assumptions. This is a feature.
Testing Strategy
Functional Testing
| Test Case | Expected Behavior |
|---|---|
Enter /plan |
Agent announces plan mode |
| Simple request | Questions generated |
| Answer questions | Codebase research begins |
| Plan generated | Phased task list displayed |
| Approve plan | Execution begins |
| Modify plan | Plan regenerated |
| Cancel plan | Returns to normal mode |
Quality Metrics
- Plan accuracy: Does execution match the plan?
- Question relevance: Are questions useful, not excessive?
- Task granularity: Are tasks appropriately sized?
- Context awareness: Does the plan respect existing code?
Validation Checklist
[ ] Can enter plan mode via /plan
[ ] Can enter plan mode via Shift+Tab
[ ] Questions are relevant to the request
[ ] Codebase research finds related files
[ ] Plan has clear phases and tasks
[ ] Can modify plan before approval
[ ] Can ask questions about the plan
[ ] Execution follows the approved plan
[ ] Can cancel at any point
Common Pitfalls & Debugging
Pitfall 1: Skipping Plan Mode for “Simple” Tasks
Problem: Developers bypass planning for tasks they think are simple, then discover complexity.
Solution: Default to planning. The cost is low (minutes), the benefit is high (avoid rework).
# Instead of:
> "Add a button"
# Use:
> /plan
> "Add a button that triggers the export workflow"
Pitfall 2: Over-Answering Questions
Problem: Providing more detail than asked, confusing the agent.
Solution: Answer only what’s asked. The agent will ask follow-ups if needed.
# Bad:
> "Use JWT tokens and store them in localStorage with a 24-hour
expiration and also use refresh tokens with rotation and..."
# Good:
> "JWT tokens"
# (Agent will ask about storage, expiration, refresh separately)
Pitfall 3: Approving Without Reading
Problem: Rubber-stamping plans without review leads to unwanted changes.
Solution: Always read the plan. Use ? to ask about unfamiliar tasks.
> ?
> "What will Task 2.3 actually change?"
Debugging Tips
# If the plan seems off:
> m
> "Show me what files you found during research"
# If questions don't make sense:
> "I don't understand question 3. Can you rephrase?"
# If execution diverges from plan:
# (Check if codebase changed during planning)
> /plan
> "Re-analyze the current state"
Extensions & Challenges
Extension 1: Plan Templates
Create reusable plan templates for common tasks:
# Save a "New API Endpoint" template
# Reuse with: /plan --template api-endpoint
Extension 2: Plan Versioning
Track plan versions when modifying:
Plan v1: 5 phases, 12 tasks
▼ (modified)
Plan v2: 4 phases, 10 tasks
▼ (modified)
Plan v3: 4 phases, 11 tasks [APPROVED]
Extension 3: Team Plan Sharing
Export plans for team review:
> /plan export plan-oauth.md
# Share with team
> /plan import reviewed-plan-oauth.md
Challenge: Complex Refactoring
Use planning mode for a major refactoring task:
- Request a database migration with schema changes
- Navigate the extensive questioning
- Review a 20+ task plan
- Modify to add rollback steps
- Execute with checkpoints
Real-World Connections
How Professionals Use This
At AWS: The Kiro team used spec-driven development with planning agents to complete an 18-month project in 76 days with 6 developers.
At Large Enterprises: Planning agents are integrated into sprint planning - developers generate implementation plans during backlog refinement.
In Open Source: Maintainers use planning mode to understand contribution impact before approving PRs.
Industry Trends
- GitHub Spec-Kit: Open-source toolkit for spec-driven development
- JetBrains Junie: AI assistant with explicit planning phases
- Anthropic Claude: Plan mode and structured reasoning
Key Insight
“In planning mode, you’re not asking the AI to start coding yet - you’re asking it to think first.” - GitHub Engineering Blog
Self-Assessment Checklist
Conceptual Understanding
- Can you explain why separating planning from execution reduces errors?
- What makes the Planning Agent “read-only” and why does that matter?
- How does spec-driven development differ from traditional workflows?
- When should you use plan mode versus direct execution?
Practical Skills
- Can you enter plan mode using both
/planand Shift+Tab? - Can you navigate multi-choice and free-text questions effectively?
- Can you modify a generated plan before approval?
- Can you use
?to ask clarifying questions about plan tasks?
Advanced Competency
- Can you use planning mode for complex, multi-feature requests?
- Can you leverage existing conversation context in planning?
- Can you recognize when a plan needs modification versus approval?
- Can you articulate the plan to a teammate for review?
Mastery Indicators
- You default to planning mode for non-trivial tasks
- You read and understand every task before approving
- You modify plans proactively rather than fixing code reactively
- You can explain your implementation approach before any code is written
- Your execution matches your plans with minimal divergence
Summary
The Planning Agent transforms AI-assisted development from reactive coding to proactive design. By separating “thinking” from “doing,” you:
- Catch misunderstandings before they become code
- Reduce rework and wasted context
- Build confidence in AI-generated implementations
- Create documentation as a byproduct of planning
Master this workflow, and you’ll wonder how you ever coded without it.
Next Project: P12: Kiro Powers Creator - Package and share Kiro capabilities