Use when managing design documents. Trigger with design search, validation, or creation requests.
How this skill is triggered — by the user, by Claude, or both
Slash command
/emasoft-architect-agent:eaa-design-managementThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill provides comprehensive tooling for managing design documents in the `design/` directory hierarchy. It covers creating documents from templates, searching with structured queries, and validating frontmatter compliance.
references/creating-documents.mdreferences/document-types.mdreferences/op-create-document-from-template.mdreferences/op-generate-guuid.mdreferences/op-search-design-documents.mdreferences/op-validate-frontmatter.mdreferences/searching-documents.mdreferences/troubleshooting.mdreferences/uuid-specification.mdreferences/validating-documents.mdThis skill provides comprehensive tooling for managing design documents in the design/ directory hierarchy. It covers creating documents from templates, searching with structured queries, and validating frontmatter compliance.
Before using this skill, ensure:
design/ directory structure exists in the project rootCopy this checklist and track your progress:
python scripts/eaa_design_create.py --type <type> --title "<title>"python scripts/eaa_design_search.py --type <type> --status <status>python scripts/eaa_design_validate.py --all| Output Type | Description | Example |
|---|---|---|
| Created Document | New markdown file with UUID-based filename and populated frontmatter | design/pdr/GUUID-20250129-0001-feature-name.md |
| Search Results JSON | JSON array of matching documents with metadata | [{"uuid": "GUUID-...", "title": "...", "status": "..."}] |
| Search Results Table | Human-readable table of matching documents | ASCII table with columns for UUID, Title, Status, Type |
| Validation Report | List of errors and warnings with file paths and line numbers | ERROR: design/pdr/doc.md:3 - Missing required field 'uuid' |
| Validation Summary | Count of files validated, errors found, and overall status | Validated 42 files: 40 passed, 2 failed |
Create a new design document (30 seconds):
python scripts/eaa_design_create.py --type pdr --title "My Feature Design"
Search existing documents:
python scripts/eaa_design_search.py --type pdr --status approved
Validate all documents:
python scripts/eaa_design_validate.py --all
This skill teaches design document management in the following order:
Each reference document focuses on a specific aspect of design management. Read them in order for initial learning, or jump directly to the relevant section when you need specific information.
Reference: references/uuid-specification.md
Use-Case TOC:
What you will learn:
Reference: references/document-types.md
Use-Case TOC:
What you will learn:
Reference: references/creating-documents.md
Use-Case TOC:
What you will learn:
eaa_design_create.py with required argumentsReference: references/searching-documents.md
Use-Case TOC:
What you will learn:
eaa_design_search.py with different filtersReference: references/validating-documents.md
Use-Case TOC:
What you will learn:
eaa_design_validate.py for single and bulk validationReference: references/troubleshooting.md
Use-Case TOC:
What you will learn:
Create documents:
# Create a PDR
python scripts/eaa_design_create.py --type pdr --title "Feature Design"
# Create with author
python scripts/eaa_design_create.py --type feature --title "OAuth" --author "John"
# Create with custom filename
python scripts/eaa_design_create.py --type spec --title "API Spec" --filename "api-v2"
Search documents:
# Search by UUID
python scripts/eaa_design_search.py --uuid GUUID-20250129-0001
# Search by type and status
python scripts/eaa_design_search.py --type pdr --status approved
# Search by keyword
python scripts/eaa_design_search.py --keyword "authentication"
# Table output
python scripts/eaa_design_search.py --type feature --format table
Validate documents:
# Validate single file
python scripts/eaa_design_validate.py design/pdr/my-design.md
# Validate all documents
python scripts/eaa_design_validate.py --all
# Validate specific type
python scripts/eaa_design_validate.py --all --type pdr
# Verbose output with warnings
python scripts/eaa_design_validate.py --all --verbose --format text
| Status | Meaning | Next Steps |
|---|---|---|
draft | Initial creation, work in progress | Complete content, request review |
review | Under review by stakeholders | Address feedback, approve or revise |
approved | Approved for implementation | Begin implementation |
implemented | Implementation complete | Monitor, update if needed |
deprecated | No longer current | Reference replacement document |
rejected | Not approved for implementation | Document reasons, archive |
Required fields:
---
uuid: GUUID-20250129-0001
title: "Document Title"
status: draft
created: 2025-01-29
updated: 2025-01-29
---
Optional fields:
---
type: pdr
author: "Author Name"
description: "Brief description"
tags: [api, security, v2]
related: [GUUID-20250128-0003, GUUID-20250127-0001]
---
design/
pdr/ - Product Design Reviews
spec/ - Technical Specifications
feature/ - Feature Documents
decision/ - Architecture Decision Records
architecture/ - System Architecture Documents
template/ - Reusable Templates
# Create a Product Design Review document
python scripts/eaa_design_create.py --type pdr --title "User Authentication Redesign"
# Output: Created design/pdr/GUUID-20250129-0001-user-authentication-redesign.md
# Find all approved PDRs
python scripts/eaa_design_search.py --type pdr --status approved --format table
# Validate all documents for frontmatter compliance
python scripts/eaa_design_validate.py --all --verbose
Skill Version: 1.0.0 Last Updated: 2025-01-29 Maintainer: Skill Development Team
npx claudepluginhub emasoft/emasoft-plugins --plugin emasoft-architect-agentTechnical design documents — problem analysis, solution exploration, architectural decisions. Invoke whenever task involves any interaction with design documents — creating, updating, reviewing, comparing options, or capturing architectural decisions.
Provides a standardized design document format with templates, guidelines, and an inter-agent coordination protocol for creating specifications and implementation plans.
Saves design documents from planning sessions with branch tracking, revision chains, and cross-session discoverability.