248 lines
7.5 KiB
YAML
248 lines
7.5 KiB
YAML
# BMAD Checkpoint Metadata Format
|
|
# Structured format for consistent, searchable, reusable checkpoints
|
|
|
|
checkpoint:
|
|
# === METADATA HEADER (Required) ===
|
|
metadata:
|
|
id: "checkpoint-{phase}-{timestamp}" # Unique identifier
|
|
version: "1.0.0" # Checkpoint format version
|
|
created_at: "2024-01-15T10:30:00Z" # ISO 8601 timestamp
|
|
created_by: "agent-role" # Agent who created checkpoint
|
|
phase: "architecture" # Current phase (requirements/architecture/implementation)
|
|
project: "project-name" # Project identifier
|
|
|
|
# Token metrics for optimization
|
|
tokens:
|
|
original: 4500 # Tokens before compression
|
|
compressed: 800 # Tokens after compression
|
|
savings_percent: 82 # Percentage saved
|
|
|
|
# Searchable tags for retrieval
|
|
tags:
|
|
- "authentication"
|
|
- "rest-api"
|
|
- "jwt"
|
|
- "postgresql"
|
|
|
|
# Dependencies on other checkpoints
|
|
dependencies:
|
|
- "checkpoint-requirements-20240114"
|
|
- "checkpoint-tech-stack-20240115"
|
|
|
|
# === DECISIONS SECTION (Required) ===
|
|
decisions:
|
|
# Technology decisions with rationale
|
|
technology_stack:
|
|
frontend:
|
|
framework: "Next.js 14"
|
|
rationale: "SSR needed for SEO, RSC for performance"
|
|
backend:
|
|
framework: "Fastify"
|
|
rationale: "High performance requirement (10k req/s)"
|
|
database:
|
|
primary: "PostgreSQL"
|
|
rationale: "Complex relationships, ACID compliance"
|
|
|
|
# Architecture patterns decided
|
|
patterns:
|
|
api_style: "REST"
|
|
auth_method: "JWT with refresh tokens"
|
|
state_management: "Zustand + React Query"
|
|
deployment: "Container-based on AWS ECS"
|
|
|
|
# Key constraints identified
|
|
constraints:
|
|
performance: "Sub-200ms p95 response time"
|
|
security: "OWASP Top 10 compliance required"
|
|
scale: "Support 10,000 concurrent users"
|
|
budget: "$5,000/month infrastructure"
|
|
|
|
# === ARTIFACTS SECTION (Required) ===
|
|
artifacts:
|
|
# Created files with paths and purpose
|
|
created:
|
|
- path: "docs/architecture/system-design.md"
|
|
type: "architecture-doc"
|
|
tokens: 1200
|
|
purpose: "Complete system architecture"
|
|
|
|
- path: "api/openapi-spec.yaml"
|
|
type: "api-specification"
|
|
tokens: 800
|
|
purpose: "REST API contract"
|
|
|
|
- path: "database/schema.sql"
|
|
type: "database-schema"
|
|
tokens: 600
|
|
purpose: "PostgreSQL schema with migrations"
|
|
|
|
# Modified files
|
|
modified:
|
|
- path: "README.md"
|
|
changes: "Added architecture section"
|
|
|
|
- path: "package.json"
|
|
changes: "Added core dependencies"
|
|
|
|
# Files to be created in next phase
|
|
pending:
|
|
- "src/services/auth.service.ts"
|
|
- "src/components/LoginForm.tsx"
|
|
- "src/api/routes/auth.routes.ts"
|
|
|
|
# === CONTEXT SUMMARY (Required) ===
|
|
summary:
|
|
# Executive summary (2-3 sentences max)
|
|
executive: |
|
|
Designed microservices architecture using Next.js frontend and Fastify backend.
|
|
JWT authentication with PostgreSQL database, deployed on AWS ECS.
|
|
|
|
# Key accomplishments
|
|
completed:
|
|
- "Technology stack selected and validated"
|
|
- "API specification designed (42 endpoints)"
|
|
- "Database schema with 15 tables defined"
|
|
- "Security architecture implemented"
|
|
|
|
# Critical information for next phase
|
|
critical_context:
|
|
- "API rate limiting: 100 req/min for free tier"
|
|
- "Database indexes needed on user.email and post.created_at"
|
|
- "Redis required for session management"
|
|
- "CORS configured for frontend domain only"
|
|
|
|
# Known issues or blockers
|
|
issues:
|
|
- description: "Payment provider not yet selected"
|
|
severity: "medium"
|
|
blocks: "checkout-flow"
|
|
|
|
- description: "Email service decision pending"
|
|
severity: "low"
|
|
blocks: "user-notifications"
|
|
|
|
# === NEXT STEPS (Required) ===
|
|
next_steps:
|
|
immediate:
|
|
- task: "Implement authentication service"
|
|
assigned_to: "node-backend-developer"
|
|
priority: "high"
|
|
|
|
- task: "Create login/register components"
|
|
assigned_to: "react-developer"
|
|
priority: "high"
|
|
|
|
parallel_work:
|
|
- "Frontend team: Build component library"
|
|
- "Backend team: Implement core API endpoints"
|
|
- "DevOps: Setup CI/CD pipeline"
|
|
|
|
dependencies_needed:
|
|
- "Finalize payment provider (blocks checkout)"
|
|
- "Obtain SSL certificates (blocks deployment)"
|
|
|
|
# === METRICS (Optional but recommended) ===
|
|
metrics:
|
|
# Quantifiable metrics for tracking
|
|
code_metrics:
|
|
files_created: 12
|
|
lines_of_code: 1847
|
|
test_coverage: 0 # Not yet implemented
|
|
|
|
# Performance benchmarks
|
|
performance:
|
|
api_response_time: null # To be measured
|
|
database_queries: null # To be optimized
|
|
bundle_size: null # To be analyzed
|
|
|
|
# Time tracking
|
|
time_spent:
|
|
architecture_design: "4 hours"
|
|
api_specification: "2 hours"
|
|
database_design: "3 hours"
|
|
documentation: "1 hour"
|
|
|
|
# === HANDOFF PROTOCOL (Required for phase transitions) ===
|
|
handoff:
|
|
from_agent: "js-solution-architect"
|
|
to_agents:
|
|
- "node-backend-developer"
|
|
- "react-developer"
|
|
- "api-developer"
|
|
|
|
handoff_message: |
|
|
Architecture complete. Backend team implement auth first.
|
|
Frontend team can start component library in parallel.
|
|
API developer please review and refine endpoint specs.
|
|
|
|
validation_checklist:
|
|
- "[x] All technology decisions documented"
|
|
- "[x] API specification complete"
|
|
- "[x] Database schema defined"
|
|
- "[x] Security requirements clear"
|
|
- "[x] Performance targets set"
|
|
- "[ ] Payment provider selected"
|
|
- "[ ] Email service configured"
|
|
|
|
# === CHECKPOINT USAGE EXAMPLES ===
|
|
|
|
# Example 1: Minimal checkpoint (requirements phase)
|
|
checkpoint_minimal:
|
|
metadata:
|
|
id: "checkpoint-requirements-20240115"
|
|
phase: "requirements"
|
|
tokens: { original: 2000, compressed: 400 }
|
|
|
|
decisions:
|
|
scope: "MVP with user auth, posts, and comments"
|
|
timeline: "8 weeks"
|
|
budget: "$50,000"
|
|
|
|
artifacts:
|
|
created:
|
|
- path: "docs/requirements.md"
|
|
|
|
summary:
|
|
executive: "MVP requirements gathered. Focus on core social features."
|
|
|
|
next_steps:
|
|
immediate:
|
|
- task: "Design system architecture"
|
|
|
|
# Example 2: Implementation checkpoint
|
|
checkpoint_implementation:
|
|
metadata:
|
|
id: "checkpoint-auth-implementation-20240120"
|
|
phase: "implementation"
|
|
tokens: { original: 3000, compressed: 600 }
|
|
|
|
decisions:
|
|
implementation_choices:
|
|
password_hashing: "bcrypt with 10 rounds"
|
|
token_storage: "httpOnly cookies"
|
|
session_length: "7 days"
|
|
|
|
artifacts:
|
|
created:
|
|
- path: "src/services/auth.service.ts"
|
|
- path: "src/middleware/auth.middleware.ts"
|
|
- path: "tests/auth.test.ts"
|
|
|
|
summary:
|
|
executive: "Authentication system fully implemented with JWT."
|
|
completed:
|
|
- "Login/logout endpoints"
|
|
- "Password reset flow"
|
|
- "Role-based access control"
|
|
|
|
next_steps:
|
|
immediate:
|
|
- task: "Implement user profile endpoints"
|
|
|
|
# === CHECKPOINT SEARCH QUERIES ===
|
|
# Checkpoints can be searched by:
|
|
# - metadata.tags: Find all checkpoints with specific tags
|
|
# - metadata.phase: Find checkpoints from specific phase
|
|
# - artifacts.created[].type: Find checkpoints that created specific artifact types
|
|
# - decisions.technology_stack: Find projects using specific technologies
|
|
# - metadata.created_by: Find all checkpoints from specific agent |