Creating Implementation Plans

Every non-trivial task in GigiKit begins with a plan. Plans live in ./plans, are created by the planner agent, and provide the single source of truth that all subsequent agents — implementers, testers, reviewers — follow.

Plan Directory Naming

Plan directories follow a timestamp-plus-slug format injected by the subagent-start hook:

plans/YYMMDD-HHMM-descriptive-slug/

# Examples
plans/260305-1034-stripe-webhook-integration/
plans/260305-1505-user-authentication-and-profile/
plans/260306-0900-database-migration-v2/

The timestamp is always the date and time the planning session began. The slug is kebab-case and describes the feature or task — long slugs are fine.

Directory Structure

plans/
└── 260305-1034-stripe-webhook-integration/
    ├── plan.md                              # Overview — entry point
    ├── phase-01-setup-dependencies.md       # Install and configure SDKs
    ├── phase-02-implement-webhook-handler.md
    ├── phase-03-implement-event-processors.md
    ├── phase-04-write-tests.md
    ├── research/
    │   ├── researcher-stripe-api-report.md
    │   └── researcher-security-report.md
    └── reports/
        ├── implementer-report.md
        ├── tester-report.md
        └── reviewer-report.md

The research/ subdirectory holds researcher agent outputs. The reports/ subdirectory accumulates agent completion reports throughout the implementation.

The plan.md Overview File

plan.md is the entry point for the entire plan. Keep it under 80 lines — it is a navigation document, not a specification.

# Plan: Stripe Webhook Integration

## Status
- Phase 01: Complete
- Phase 02: In Progress
- Phase 03: Not Started
- Phase 04: Not Started

## Phases
- [Phase 01 — Setup Dependencies](./phase-01-setup-dependencies.md)
- [Phase 02 — Webhook Handler](./phase-02-implement-webhook-handler.md)
- [Phase 03 — Event Processors](./phase-03-implement-event-processors.md)
- [Phase 04 — Tests](./phase-04-write-tests.md)

## Key Dependencies
- Phase 02 requires Phase 01 complete (SDK installed)
- Phase 03 requires Phase 02 complete (handler interface defined)
- Phase 04 requires Phase 02 and 03 complete

## Research
- [Stripe API Report](./research/researcher-stripe-api-report.md)
- [Security Report](./research/researcher-security-report.md)

Phase Files

Each phase file is a complete, self-contained specification for one slice of work. An agent assigned to a phase should be able to execute it without reading any other phase file.

Required sections in every phase file:

Section	Purpose
Context Links	Links to research reports, related docs, architecture docs
Overview	Priority, current status, brief description
Key Insights	Critical findings from research phase
Requirements	Functional and non-functional requirements
Architecture	System design, component interactions, data flow
File Ownership	Exact glob patterns this phase owns
Implementation Steps	Numbered, specific instructions
Todo List	Checkbox list for tracking progress
Success Criteria	Definition of done and validation method
Risk Assessment	Potential issues and mitigations
Security Considerations	Auth, data protection, input validation
Next Steps	Dependencies this phase unlocks

Updating Plan Status

As phases complete, the planner or lead updates plan.md to reflect current status. Agents must not update plan.md themselves — they report completion via TaskUpdate and a message to the lead, who updates the overview.

Research Before Planning

For unfamiliar domains, spawn researcher agents in parallel before creating the plan:

# Researcher 1
"Research Stripe webhook security best practices.
 Report to: /plans/reports/researcher-stripe-security-report.md"

# Researcher 2 (simultaneous)
"Research idempotency patterns for payment webhook handlers.
 Report to: /plans/reports/researcher-idempotency-report.md"

The planner reads both reports before writing phase files, ensuring implementation steps reflect real-world constraints.

Plan Templates & Conventions — copy-paste frontmatter and phase file templates
The 6-Step Development Workflow — where planning fits in the full pipeline
Agent Chaining Patterns — how the planner hands off to implementer agents