Project 5: “The Plan Architect” — Spec-Driven Development

Attribute Value
File KIRO_CLI_MASTERY.md
Main Programming Language Natural Language
Coolness Level Level 3: Genuinely Clever
Difficulty Level 2: Intermediate
Knowledge Area Spec-Driven Development

What you’ll build: A small ToDo app built only after a /plan phase that outputs a tasks.md checklist.

Why it teaches Planning: Separates thinking from typing, reducing logic errors.

Success criteria:

  • A complete plan exists before execution starts.
  • Each task is checked off with verification notes.

Real World Outcome

You’ll build a complete ToDo application, but only after creating a detailed implementation plan using Kiro’s Planning agent (Shift+Tab or /plan). The planning phase produces a tasks.md checklist that guides implementation step-by-step.

Example Output:

$ mkdir todo-app && cd todo-app
$ kiro chat

You: "I want to build a simple todo app with React and Node.js backend"

Kiro: Let me help you plan this project. I'll enter planning mode to create a structured implementation plan.

  [Entering Planning Mode - Shift+Tab pressed]

Plan Agent: I'll ask you some questions to refine your requirements.

  **Question 1: Frontend Framework**
  Which React setup do you prefer?
  A) Create React App (simple, batteries-included)
  B) Vite + React (faster, modern tooling)
  C) Next.js (SSR, App Router)

  Your choice: B

  **Question 2: Backend API**
  What backend approach?
  A) REST API with Express
  B) GraphQL with Apollo
  C) tRPC (type-safe)

  Your choice: A

  **Question 3: Database**
  Which database?
  A) PostgreSQL (relational, production-ready)
  B) SQLite (simple, file-based)
  C) MongoDB (document-based)

  Your choice: B

  **Question 4: Authentication**
  Do you need user authentication?
  A) Yes, JWT-based
  B) Yes, session-based
  C) No, single-user app

  Your choice: C

  [Researching codebase... 0 existing files]
  [Analyzing requirements...]
  [Creating implementation plan...]

  Plan created: tasks.md

$ cat tasks.md

# Todo App Implementation Plan

## Overview
Building a single-user todo application with:
- **Frontend**: Vite + React + TypeScript
- **Backend**: Express + SQLite
- **Features**: Create, Read, Update, Delete todos; Mark complete/incomplete

## Architecture

┌─────────────────┐ ┌─────────────────┐ │ React App │ ◄─HTTP─►│ Express API │ │ (Port 5173) │ │ (Port 3000) │ └─────────────────┘ └─────────────────┘ │ ▼ ┌─────────────────┐ │ SQLite DB │ │ (todos.db) │ └─────────────────┘


## Task Breakdown

### Phase 1: Project Setup (30 minutes)
- [ ] Task 1.1: Initialize Vite React app with TypeScript
- [ ] Task 1.2: Set up Express server with TypeScript
- [ ] Task 1.3: Configure SQLite database with better-sqlite3
- [ ] Task 1.4: Create monorepo structure (frontend/, backend/)

### Phase 2: Backend API (1-2 hours)
- [ ] Task 2.1: Create database schema (todos table)
- [ ] Task 2.2: Implement GET /api/todos endpoint
- [ ] Task 2.3: Implement POST /api/todos endpoint
- [ ] Task 2.4: Implement PATCH /api/todos/:id endpoint (update)
- [ ] Task 2.5: Implement DELETE /api/todos/:id endpoint
- [ ] Task 2.6: Add CORS middleware for frontend

### Phase 3: Frontend UI (2-3 hours)
- [ ] Task 3.1: Create TodoList component
- [ ] Task 3.2: Create TodoItem component
- [ ] Task 3.3: Create AddTodo form component
- [ ] Task 3.4: Implement state management (useState + useEffect)
- [ ] Task 3.5: Add API client functions (fetch wrappers)
- [ ] Task 3.6: Style with Tailwind CSS or plain CSS

### Phase 4: Integration & Testing (1 hour)
- [ ] Task 4.1: Connect frontend to backend API
- [ ] Task 4.2: Test CRUD operations end-to-end
- [ ] Task 4.3: Handle loading states and errors
- [ ] Task 4.4: Add optimistic UI updates

## Demo Criteria
- User can add a todo with title and optional description
- User can mark todos as complete/incomplete (checkbox)
- User can delete todos
- Todos persist across page refreshes
- UI shows loading state during API calls

---

Plan Agent: This plan is ready for implementation. Would you like me to hand off to the execution agent? [Y/n]

You: Y

Kiro: [Exiting planning mode, entering execution mode]
  I'll implement the plan task-by-task. Starting with Task 1.1...

  [Implementation proceeds, checking off tasks in tasks.md as they complete]

The planning phase separated “what to build” from “how to build it,” reducing mistakes.

The Core Question You’re Answering

“How do I avoid jumping straight into coding without thinking through the architecture, leading to half-built features and refactoring nightmares?”

Before building this, understand: Most developers write code first, realize the design is flawed, and refactor. Kiro’s Planning agent inverts this: it asks clarifying questions, researches your codebase, and outputs a structured plan. This project teaches you spec-driven development—think deeply before typing.

Concepts You Must Understand First

Stop and research these before starting:

  1. Planning vs Execution Modes
    • What’s the difference between the Plan agent and the main chat agent?
    • Why does the Plan agent run in read-only mode?
    • How do you transition from planning to execution?
    • Reference: Subagents and Plan Agent Changelog
  2. Requirements Elicitation
    • How does the Plan agent ask clarifying questions?
    • What happens if you give vague requirements (“build an app”)?
    • How do multiple-choice questions improve plan quality?
    • Book Reference: “The Pragmatic Programmer” by Hunt & Thomas - Ch. 2 (A Pragmatic Approach)
  3. Task Decomposition
    • What makes a good task? (specific, measurable, testable)
    • How granular should tasks be? (30 min vs 4 hours)
    • How do you organize tasks into phases?
    • Book Reference: “Clean Architecture” by Robert C. Martin - Ch. 22 (The Clean Architecture)

Questions to Guide Your Design

Before entering planning mode, think through these:

  1. Project Scope
    • Is this a prototype (2-3 days) or a production app (2-3 weeks)?
    • What’s the minimum viable feature set?
    • What can be added later vs must be included now?
  2. Plan Granularity
    • Should tasks be 30 minutes each, or 2 hours each?
    • How many phases should the plan have?
    • Should you plan the entire app or just the first iteration?
  3. Verification Strategy
    • How do you verify each task is “done”?
    • What constitutes a passing demo for each phase?
    • Should tasks include tests, or is manual verification OK?

Thinking Exercise

Exercise: Evaluate a Bad Plan vs Good Plan

Compare these two plans for the same todo app:

Bad Plan:

- [ ] Build frontend
- [ ] Build backend
- [ ] Connect them
- [ ] Test everything

Good Plan:

Phase 1: Backend API
- [ ] Create SQLite schema (todos table: id, title, completed, createdAt)
- [ ] Implement GET /api/todos (return JSON array)
- [ ] Test with curl: `curl http://localhost:3000/api/todos`

Phase 2: Frontend
- [ ] Create TodoList component (displays array of todos)
- [ ] Fetch todos from API on mount (useEffect)
- [ ] Test: Should show hardcoded test todos from backend

Questions while comparing:

  • Which plan could a junior developer execute without asking questions?
  • Which plan has measurable success criteria for each task?
  • Which plan allows you to verify progress incrementally?
  • Which plan would survive a week-long break and still be understandable?

The Interview Questions They’ll Ask

  1. “What are the benefits of separating planning from execution in software development?”
  2. “How does Kiro’s Plan agent differ from the main execution agent?”
  3. “What makes a good task in an implementation plan?” (Give 3 characteristics)
  4. “How would you handle a plan that’s too granular (100 tiny tasks) vs too vague (5 huge tasks)?”
  5. “When would you skip the planning phase and just start coding?”
  6. “How do you verify that a plan is complete before starting implementation?”

Hints in Layers

Hint 1: Start with Clear Requirements Don’t enter planning mode with “build an app.” Be specific: “Build a React todo app with Express backend, SQLite database, and no authentication.” The Plan agent needs constraints to create a useful plan.

Hint 2: Answer Questions Thoughtfully When the Plan agent asks multiple-choice questions, don’t rush. Each choice affects the entire plan. Choosing “Next.js” vs “Vite + React” changes 10+ tasks.

Hint 3: Review the Plan Before Executing After the Plan agent generates tasks.md, read it fully. Ask: “Is anything missing? Are tasks too vague? Are dependencies clear?” Edit the plan before handing off to execution.

Hint 4: Check Off Tasks as You Go Treat tasks.md like a real checklist. Mark tasks complete with ✓, add notes for deviations, and reference git commits. This creates an audit trail.

Books That Will Help

Topic Book Chapter
Requirements engineering “The Pragmatic Programmer” by Hunt & Thomas Ch. 2: A Pragmatic Approach
Task decomposition “Clean Architecture” by Robert C. Martin Ch. 22: The Clean Architecture
Agile planning “User Stories Applied” by Mike Cohn Ch. 3: Writing Stories

Common Pitfalls & Debugging

Problem 1: “Plan is too vague to execute”

  • Why: Requirements given to Plan agent were generic (“build a web app”)
  • Fix: Provide specific constraints: “React + Node.js, single-user, CRUD operations, no auth”
  • Quick test: Hand the plan to a teammate—can they implement it without asking questions?

Problem 2: “Plan includes 50+ micro-tasks”

  • Why: Asked for extreme detail or Plan agent over-decomposed
  • Fix: Group related micro-tasks into larger tasks (e.g., “Set up database” instead of 5 separate schema tasks)
  • Quick test: Each task should take 30 mins - 2 hours, not 5 minutes

Problem 3: “Implementation deviates from plan”

  • Why: Discovered new requirements or constraints during coding
  • Fix: Update tasks.md as you go—add new tasks, mark others as skipped, document why
  • Quick test: At end of project, tasks.md should reflect what actually happened

Problem 4: “Plan agent suggested wrong tech stack”

  • Why: Didn’t answer clarifying questions carefully or gave conflicting requirements
  • Fix: Re-enter planning mode, explicitly state tech stack: “Must use PostgreSQL, not SQLite”
  • Quick test: Read the plan’s “Overview” section—does it match your actual requirements?

Definition of Done

  • Entered planning mode with Shift+Tab or /plan
  • Answered all clarifying questions from Plan agent
  • Received a tasks.md file with at least 10 specific tasks
  • Tasks are organized into logical phases (setup, backend, frontend, integration)
  • Each task has a clear success criterion or demo requirement
  • Reviewed plan and verified no major features are missing
  • Handed off to execution agent and implemented at least 3 tasks
  • Checked off completed tasks in tasks.md as work progressed