design-document-management

Guide for managing the 5 design documents in .gaia/designs/. Use when creating, updating, or validating design documentation.

⭐23stars🔀25forks📁View on GitHub🕐Updated Jan 8, 2026⬇️2downloads

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.
namedesign-document-management
descriptionGuide 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

  1. Identify which docs need updates based on requirements
  2. Update each doc with new requirements
  3. Cross-check consistency across all docs
  4. Validate no placeholders remain
  5. Store key decisions in MCP memory