GigiKit Guides

The Planner Agent

The planner agent is the architect of every GigiKit feature implementation. It takes a task description and produces a structured set of phase files in ./plans/ that every downstream agent — developer, tester, reviewer — uses as their source of truth.

Role

The planner’s single responsibility is plan creation. It does not write code. It researches, designs a solution, breaks it into phases, and documents everything clearly enough that a junior developer could execute it.

When the Planner Is Invoked

The planner is spawned automatically by the /gk:cook skill after research completes. You can also invoke it directly:

/gk:plan "Add Stripe payment integration with webhooks"

Or via the /gk:cook pipeline with an explicit flag:

/gk:cook "Add Stripe payment integration" --fast

In --fast mode, cook goes directly to scout → plan → code, skipping the separate research phase.

Input the Planner Receives

When spawned as a sub-agent, the planner receives:

Task: [feature description]
Work context: /absolute/path/to/project
Reports: /path/to/plans/reports/
Plans: /path/to/plans/
Researcher reports: [paths to research/*.md files]
Scout report: [path to scout-report.md if available]

The researcher and scout reports give the planner real codebase context — existing patterns, file locations, dependencies already in use — so the plan is grounded in the actual project rather than generic assumptions.

Output: Plan Directory

The planner creates a timestamped directory under ./plans/:

plans/260305-0912-feature-name/
├── plan.md                          # Overview: phases, status, links
├── phase-01-setup.md
├── phase-02-implementation.md
├── phase-03-tests.md
└── research/
    └── researcher-01-report.md

plan.md Structure

The overview file stays under 80 lines and lists each phase with status:

# Feature: Stripe Payment Integration

## Status: In Progress

## Phases
- [ ] Phase 01: Database schema & models
- [ ] Phase 02: Stripe API integration
- [ ] Phase 03: Webhook handlers
- [ ] Phase 04: Tests & validation

## Key Dependencies
- Stripe SDK already in package.json
- Existing User model in src/models/

Phase File Structure

Each phase file contains everything a developer agent needs: requirements, architecture notes, file ownership, implementation steps, and a todo checklist.

## File Ownership
- src/services/stripe-service.ts (create)
- src/routes/payments.ts (create)
- src/models/payment.ts (create)

## Implementation Steps
1. Create Payment model with Prisma schema
2. Implement StripeService class with charge() method
3. Add POST /payments endpoint with validation
4. Handle webhook signature verification

## Todo
- [ ] Payment model + migration
- [ ] StripeService implementation
- [ ] Route handlers
- [ ] Error handling for failed charges

Task Hydration

After writing plan files, the planner creates Claude Tasks with dependency chains so cook can track progress:

TaskCreate: "Phase 01: Database models"     → pending
TaskCreate: "Phase 02: Stripe integration"  → pending, blockedBy: [phase-01]
TaskCreate: "Phase 03: Webhook handlers"    → pending, blockedBy: [phase-02]
TaskCreate: "Phase 04: Tests"              → pending, blockedBy: [phase-03]

Delegation Prompt Example

Here is how the orchestrator delegates to the planner:

Spawn planner sub-agent:

"Create an implementation plan for adding JWT authentication.

Work context: /Users/dev/my-app
Reports: /Users/dev/my-app/plans/reports/
Plans: /Users/dev/my-app/plans/

Researcher report: /Users/dev/my-app/plans/260305-0912-jwt-auth/research/researcher-01-report.md

Requirements:
- Login/logout endpoints returning JWT tokens
- Middleware to verify tokens on protected routes
- Token refresh mechanism
- Tests for all auth flows"

Next Steps