design-document-management
Guide for managing the 5 design documents in .gaia/designs/. Use when creating, updating, or validating design documentation.
When & Why to Use This Skill
This Claude skill provides a structured framework for managing essential software design documentation within the .gaia/designs/ directory. It streamlines the creation, update, and validation of technical docs—including architecture, API contracts, database schemas, and security protocols—ensuring system-wide consistency and adherence to Clean Architecture principles across various SDLC tiers.
Use Cases
- Project Initialization: Automatically identifying and generating the necessary design documents (e.g., use-cases, architecture, API) based on the project's complexity tier (Micro, Small, Medium, or Large).
- Consistency Auditing: Cross-referencing API endpoints with database schemas and frontend patterns to ensure that terminology, data models, and contracts remain synchronized throughout the development lifecycle.
- Design Quality Enforcement: Validating documentation against strict quality rules, such as eliminating [TODO] placeholders and ensuring 100% requirement coverage before moving to the implementation phase.
- Architectural Memory Management: Using MCP memory commands to store and retrieve critical design decisions, ensuring that the AI agent maintains a persistent understanding of the project's structural evolution.
| name | design-document-management |
|---|---|
| description | Guide for managing the 5 design documents in .gaia/designs/. Use when creating, updating, or validating design documentation. |
Design Document Management
Design Documents (in .gaia/designs/)
| Document | Purpose | Required From |
|---|---|---|
use-cases.md |
Use cases, user flows, API/UI journeys | Micro+ |
architecture.md |
System design, components, patterns | Small+ |
api.md |
API endpoints, contracts, requests/responses | Small+ |
database.md |
Schema, models, relationships, migrations | Medium+ |
security.md |
Auth, authorization, RBAC, tokens | Large+ |
frontend.md |
UI/UX patterns, components, state | Large+ |
Tiered Requirements by SDLC
| SDLC Tier | Required Documents |
|---|---|
| Micro | use-cases.md (if needed) |
| Small | use-cases.md + architecture.md + api.md |
| Medium | + database.md |
| Large/Enterprise | All 6 documents |
Quality Rules
- ✅ No
[TODO]or[TBD]placeholders in required docs - ✅ Consistent terminology across all docs
- ✅ Every requirement maps to a design section
- ✅ Follow Clean Architecture / iDesign principles
Completion Checklist
Before creating tasks, verify:
- All required docs for SDLC tier exist
- No template placeholders remain
- Designs capture 100% of requirements
- Entity names match across docs
- API paths consistent
- Database schema aligns with API contracts
Store Design Decisions
mcp__gaia__remember("design", "use-cases", "[user flows and journeys]", "ProjectWide")
mcp__gaia__remember("design", "architecture", "[key decisions]", "ProjectWide")
mcp__gaia__remember("design", "api", "[endpoint designs]", "ProjectWide")
mcp__gaia__remember("design", "database", "[schema decisions]", "ProjectWide")
mcp__gaia__remember("design", "security", "[auth approach]", "ProjectWide")
mcp__gaia__remember("design", "frontend", "[component patterns]", "ProjectWide")
Document Update Process
- Identify which docs need updates based on requirements
- Update each doc with new requirements
- Cross-check consistency across all docs
- Validate no placeholders remain
- Store key decisions in MCP memory