Plan Templates & Conventions

This guide provides copy-paste templates for every artifact in a GigiKit plan directory. Use these as starting points — the planner agent follows these exact structures.

Naming Conventions

plan.md Template

# Plan: {Feature Name}

## Status
- Phase 01: Not Started
- Phase 02: Not Started
- Phase 03: Not Started

## Phases
- [Phase 01 — {Name}](./phase-01-{slug}.md)
- [Phase 02 — {Name}](./phase-02-{slug}.md)
- [Phase 03 — {Name}](./phase-03-{slug}.md)

## Key Dependencies
- Phase 02 requires Phase 01 complete ({reason})
- Phase 03 requires Phase 02 complete ({reason})

## Research
- [{Topic} Report](./research/researcher-{topic}-report.md)

## Notes
{Any critical constraints, decisions, or scope boundaries}

Keep plan.md under 80 lines. It is a navigation document — all detail lives in phase files.

Phase File Template

# Phase NN: Phase Name

## Context Links
- Plan overview: [plan.md](./plan.md)
- Related research: [researcher-topic-report.md](./research/researcher-topic-report.md)
- Architecture docs: [system-architecture.md](../../docs/system-architecture.md)

## Overview
- **Priority:** High / Medium / Low
- **Status:** Not Started / In Progress / Complete
- **Description:** One-sentence summary of what this phase accomplishes.

## Key Insights
- Critical finding from research that affects implementation
- Edge case or constraint to keep in mind

## Requirements

### Functional
- What the feature must do

### Non-Functional
- Performance, security, scalability requirements

## Architecture
System design, component interactions, data flow — use ASCII or Mermaid diagrams

## File Ownership
Glob patterns this phase exclusively owns:
- `src/module/*.ts`
- `src/module/types.ts`

Do NOT edit files outside this list.

## Implementation Steps
1. First concrete action — specific file, function, or command
2. Second action
3. Run compile check: `npm run build`
4. Continue...

## Todo List
- [ ] Task one
- [ ] Task two
- [ ] Run compile check
- [ ] Update plan.md status to Complete

## Success Criteria
- [ ] Measurable outcome — e.g. "All unit tests pass"
- [ ] Integration point verified — e.g. "Webhook endpoint returns 200 for valid payload"
- [ ] No TypeScript errors: `npm run typecheck`

## Risk Assessment
| Risk | Likelihood | Mitigation |
|---|---|---|
| Risk description | High/Med/Low | How to handle it |

## Security Considerations
- Auth/authorization concerns
- Input validation requirements
- Data protection obligations

## Next Steps
- Phase NN+1 is unblocked after this phase completes
- Notify lead via TaskUpdate and SendMessage when done

Research Report Template

# Research Report: Topic

**Date:** YYYY-MM-DD
**Researcher:** agent name or session ID

## Summary
2-3 sentence executive summary of findings

## Key Findings
1. Finding with source or evidence
2. Finding with source or evidence

## Recommendations
- Actionable recommendation for the planner

## References
- URL or doc path

## Unresolved Questions
- Any open questions the planner should address

Agent Report Template

# Role Report: Slug

**Phase:** phase-NN-name
**Status:** completed / blocked / partial

## Files Modified
- `src/path/file.ts` (+42 lines)

## Tasks Completed
- [x] Task one
- [x] Task two

## Tests Status
- Type check: pass / fail
- Unit tests: pass / fail (N tests, N% coverage)

## Docs Impact
none / minor / major

## Issues Encountered
Any conflicts, blockers, or deviations from the phase plan

## Unresolved Questions
- Any open questions for the lead

Frontmatter Reference

Phase files are Markdown, not MDX — they do not use frontmatter. The plan.md overview also has no frontmatter. Only guide files (like this one) in src/data/guides/ use MDX frontmatter:

---
title: "Human-readable title"
description: "One-sentence SEO description of what this guide covers."
category: "plans"   # workflows | rules | hooks | teams | plans | skills | agents
order: 1            # display order within the category
---

Related Guides

• Creating Implementation Plans — full explanation of plan directory structure and phase file sections
• Agent Chaining Patterns — how agents hand off between phases using plan outputs
• Multi-Agent Team Orchestration — how the lead uses plan files to assign tasks to teammates