Feature Lifecycle Kit

A documentation framework for AI-assisted feature development — from discovery to delivery in 5 structured phases.

🎯 What Is This?

A battle-tested process for building features using AI assistants (Claude, Cursor, ChatGPT, etc.). Instead of ad-hoc prompting, this framework guides you through:

1. Discovery — Clarifying requirements through structured Q&A
2. Design — Creating technical specifications
3. Contracts — Defining machine-readable interfaces (JSON schemas)
4. Execution — Parallel development with agent briefs
5. Merge — Integration, testing, and retrospectives

🚀 Quick Start

Option 1: Use Directly

1. Clone this repo into your project:

   git clone https://github.com/YOUR_USERNAME/feature-lifecycle-kit.git docs/AICompanion

2. Attach FEATURE_LIFECYCLE.md to your AI assistant

3. Tell the AI:

   "I want to build a user authentication system"

4. Follow the guided 5-phase process

Option 2: Copy What You Need

Download individual templates from the templates/ folder and adapt them.

📁 Repository Structure

feature-lifecycle-kit/
├── README.md                    # You're here
├── FEATURE_LIFECYCLE.md         # THE MAIN PROCESS DOCUMENT ⭐
├── CODING_CONVENTIONS.md        # Standards template (customize)
│
├── templates/                   # Templates for each phase
│   ├── MILESTONE_README_TEMPLATE.md
│   ├── PLANNING_QA_TEMPLATE.md       # Phase 1: Discovery
│   ├── DESIGN_DOC_TEMPLATE.md        # Phase 2: Design
│   ├── DATA_FLOW_TEMPLATE.md         # Phase 3: Contracts
│   ├── AGENT_BRIEF_TEMPLATE.md       # Phase 4: Execution
│   ├── E2E_VERIFICATION_TEMPLATE.md  # Phase 4: Verification
│   ├── MERGE_AGENT_BRIEF_TEMPLATE.md # Phase 5: Merge
│   └── RETROSPECTIVE_TEMPLATE.md     # Phase 5: Lessons learned
│
├── tickets/
│   └── TICKET_GUIDELINES.md     # How to write implementation tickets
│
├── contracts/
│   └── schemas/                 # Your JSON schemas go here
│
├── milestones/                  # Your features go here
│
├── merge-notes/                 # Agent outputs go here
│
└── examples/                    # Example completed documents

📋 The 5-Phase Process

┌────────────────────────────────────────────────────────────────────────────────────┐
│                         FEATURE LIFECYCLE                                          │
├────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                    │
│   Phase 1          Phase 2          Phase 3          Phase 4          Phase 5      │
│   DISCOVERY   →    DESIGN      →    CONTRACTS   →    EXECUTION   →    MERGE        │
│   (1-2 hours)      (2-4 hours)      (1-2 hours)      (multi-day)      (2-4 hours)  │
│                                                                                    │
│   ┌─────────┐      ┌─────────┐      ┌─────────┐      ┌─────────┐      ┌─────────┐  │
│   │ Q&A     │  →   │ Design  │  →   │ Schemas │  →   │ Agent   │  →   │ Merge   │  │
│   │ Session │      │ Doc     │      │ + Flow  │      │ Briefs  │      │ + Test  │  │
│   └─────────┘      └─────────┘      └─────────┘      └─────────┘      └─────────┘  │
│       ↓                ↓                ↓                ↓                ↓        │
│   PLANNING_QA.md   DESIGN.md       contracts/       agent briefs    retrospective  │
│                                    schemas/*.json   + tickets                      │
│                                                                                    │
└────────────────────────────────────────────────────────────────────────────────────┘

What Each Phase Produces

Phase	Input	AI Creates	Output Location
1. Discovery	Feature description	Q&A document	milestones/{feature}/
2. Design	Q&A decisions	Design document	milestones/{feature}/
3. Contracts	Design doc	JSON schemas + Data flow	contracts/schemas/
4. Execution	Design + Contracts	Agent briefs + Tickets	milestones/{feature}/briefs/
5. Merge	Agent outputs	Integration + Retrospective	merge-notes/

🤖 Using with AI Assistants

Starting a Feature

Attach FEATURE_LIFECYCLE.md to your conversation:

You: "I want to build a payment processing system"

AI: Will ask ~15 clarifying questions about:

• Primary use case and user journey
• Data storage requirements
• UI/UX expectations
• Integration points
• Error handling
• Performance requirements

Then creates structured documentation at each phase.

Parallel Development (Phase 4)

The framework supports multiple AI agents working in parallel:

1. AI creates separate briefs: AGENT1_BACKEND_BRIEF.md, AGENT2_FRONTEND_BRIEF.md
2. Open separate AI windows/sessions
3. Drop each brief into its own session
4. Agents work independently
5. Merge agent integrates the work

💡 Why This Works

Problem	How This Framework Solves It
Vague requirements	Phase 1 Q&A forces clarity
Integration mismatches	Phase 3 contracts define exact interfaces
"It works on my machine"	Phase 4 includes E2E verification
Knowledge silos	Phase 5 retrospectives capture learnings
Scope creep	Design doc defines what's IN and OUT

🛠️ Customization

Adapt for Your Stack

1. CODING_CONVENTIONS.md — Update naming conventions, folder structure
2. Templates — Add/remove sections for your workflow
3. Contracts — Define your event types, API patterns

Optional: Add Domain-Driven Design

For larger projects, add per-domain documentation:

backend/app/{domain}/
├── CONTEXT.md      # Purpose, scope, invariants
├── MODEL.md        # Entities, aggregates
├── PLAYBOOK.md     # How-to guides
└── AGENT_RULES.md  # What AI can edit

📖 Templates Overview

Template	Use When
PLANNING_QA_TEMPLATE	Starting any new feature
DESIGN_DOC_TEMPLATE	Defining technical architecture
DATA_FLOW_TEMPLATE	Complex backend ↔ frontend flows
AGENT_BRIEF_TEMPLATE	Parallel development with multiple agents
MERGE_AGENT_BRIEF_TEMPLATE	Integrating work from multiple sources
RETROSPECTIVE_TEMPLATE	After completing any feature

🏆 Best Practices

1. Don't skip phases — Each phase catches different issues
2. Create contracts early — JSON schemas prevent 75% of integration bugs
3. Use agent briefs — Parallel work dramatically speeds development
4. Do retrospectives — Compound learnings across features
5. Keep templates updated — Evolve based on what you learn

📄 License

MIT License — use freely, adapt for your needs.

🙏 Contributing

Found an improvement? PRs welcome!

• Add examples to examples/
• Improve templates
• Share your adaptations

---

Originally developed for the WellnessCompanion project