Use when creating, searching, or validating design documents. Trigger with document management or UUID generation request. Loaded by ai-maestro-architect-agent-main-agent
Manages design documents in the design/ directory. Covers creating documents from templates, searching with structured queries, and validating frontmatter compliance. Requires Python 3.10+.
design/ directory structure exists in the project rootamaa_design_create.pyamaa_design_validate.py --allamaa_design_search.pyCopy this checklist and track your progress:
python scripts/amaa_design_create.py --type <type> --title "<title>"python scripts/amaa_design_search.py --type <type> --status <status>python scripts/amaa_design_validate.py --all| Document | Description |
|---|---|
| uuid-specification.md | 1 UUID Format Definition, 2 Date Component Requirements, 3 Sequence Number Rules, 4 Manual UUID Generation, 5 UUID Validation Rules, 6 UUID Parsing |
| document-types.md | 1 Type Selection Guide, 2 PDR Documents (pdr/), 3 Spec Documents (spec/), 4 Feature Documents (feature/), 5 Decision Documents (decision/), 6 Architecture Documents (architecture/), 7 Template Documents (template/), 8 Directory Structure |
| creating-documents.md | 1 Basic Document Creation, 2 Required Arguments, 3 Optional Fields (author, description), 4 Custom Filenames, 5 Post-Creation Validation, 6 Creation Error Handling, 7 Script Reference |
| searching-documents.md | 1 UUID Search, 2 Type Filter, 3 Status Filter, 4 Keyword Search, 5 Glob Pattern Search, 6 Combined Filters, 7 Empty Results Handling, 8 Output Formats, 9 Script Reference |
# Create a PDR, then validate
python scripts/amaa_design_create.py --type pdr --title "Auth Redesign"
python scripts/amaa_design_validate.py --all
| Error | Cause | Fix |
|---|---|---|
| UUID generation fails | Date format or sequence conflict | Check date format YYYYMMDD, reset sequence |
| Document creation fails | Missing directory or permissions | Ensure design/<type>/ exists with write access |
| Search returns no results | Wrong filters or empty directory | Verify type/status values, check directory has files |
| Validation: malformed frontmatter | Invalid YAML syntax | Fix YAML delimiters (---) and field formatting |
| Files in wrong directory | Manual file placement error | Move file to correct design/<type>/ subdirectory |
See Reference Documents table above.
| Output | Format | Example |
|---|---|---|
| Created Document | Markdown file with UUID filename | design/pdr/GUUID-20250129-0001-feature.md |
| Search Results | JSON array or ASCII table | [{"uuid": "GUUID-...", "title": "..."}] |
| Validation Report | Error list with file paths and line numbers | ERROR: doc.md:3 - Missing field 'uuid' |