Use when creating, reviewing, or archiving design documents. Manages design lifecycle from draft to archival. Trigger with design creation, review, or archival requests.
npx claudepluginhub emasoft/emasoft-plugins --plugin emasoft-architect-agentThis skill uses the workspace's default tool permissions.
This skill manages the complete lifecycle of design documents from creation through approval, implementation, and archival.
references/README.mdreferences/adr-templates.mdreferences/handoff-format.mdreferences/judgment-guidelines.mdreferences/op-approve-design.mdreferences/op-archive-design.mdreferences/op-create-design-document.mdreferences/op-generate-design-uuid.mdreferences/op-manage-state-transitions.mdreferences/op-submit-design-review.mdreferences/op-track-implementation.mdreferences/rule-14-enforcement.mdreferences/success-criteria.mdreferences/workflow-checklists.mdtemplates/design-template.mdGenerates architecture/design documents from approved SRS docs when no prior design exists, proposing 2-3 approaches with trade-offs and securing section-by-section approval.
Collaboratively brainstorms architecture, approaches, and trade-offs from specs, proposes options, gets section-by-section approval, then writes design.md. Use for 'design this' or 'brainstorm approaches'.
Guides architecture design via Socratic questioning, generates technical docs like overview.md, domain-model.md, and ADR for new features, systems, or project structuring.
Share bugs, ideas, or general feedback.
This skill manages the complete lifecycle of design documents from creation through approval, implementation, and archival.
templates/design-template.mddesign/requirements/index.jsonCopy this checklist and track your progress:
docs_dev/design/| Output Type | Format | Location |
|---|---|---|
| Design document | Markdown | docs_dev/design/ |
| Requirements doc | Markdown | docs_dev/design/requirements.md |
| Architecture doc | Markdown | docs_dev/design/architecture.md |
| Module specs | Markdown | docs_dev/design/modules/ |
| Handoff document | Markdown | docs_dev/design/handoff-{uuid}.md |
| Design index entry | JSON | design/requirements/index.json |
| Completion report | Markdown | docs_dev/design/completed/ |
| State | Description | Transitions |
|---|---|---|
| DRAFT | Initial creation | → REVIEW |
| REVIEW | Under review | → APPROVED / → DRAFT |
| APPROVED | Ready for implementation | → IMPLEMENTING |
| IMPLEMENTING | Being implemented | → COMPLETED |
| COMPLETED | Fully implemented | → ARCHIVED |
| ARCHIVED | Historical reference | (terminal) |
Located at: templates/design-template.md
design/requirements/index.json
User: I need to build a real-time collaborative document editor similar to
Google Docs. Can you help design the architecture?
EAA (You): Starting architecture design for real-time collaborative document
editor.
Phase 1 - Research:
- Researched collaborative editing technologies (OT vs CRDT)
- Analyzed requirements (concurrent editing, conflict resolution, persistence)
- Gathered information about WebSocket libraries and document storage
Phase 2 - Requirements:
- Created requirements.md documenting user specifications
- Covered: real-time sync, multiple cursors, revision history
Phase 3 - Architecture:
- Selected Y.js CRDT library and Socket.io for WebSocket handling
- Designed components:
* WebSocket server (Node.js)
* CRDT sync engine (Y.js)
* Document store (PostgreSQL + Redis)
* Client library (TypeScript)
Phase 4 - Module Breakdown:
- Created 5 core modules:
* Connection manager
* CRDT resolver
* Persistence layer
* Auth service
* Client SDK
Phase 5 - Handoff:
- Generated handoff document for EOA with implementation phases
- Included dependency graph
Files created:
- docs_dev/design/requirements.md
- docs_dev/design/architecture.md
- docs_dev/design/modules/
- docs_dev/design/handoff-abc123.md
User: We need to integrate Stripe payments into our existing e-commerce platform.
EAA (You): Analyzing Stripe integration requirements for e-commerce platform.
Phase 1 - Research:
- Read existing codebase to understand current payment flow
- Researched Stripe API capabilities (payments, subscriptions, webhooks)
- Analyzed existing order system to identify integration points
Phase 2 - Architecture:
- Recommended three components:
* Payment Gateway module (wraps Stripe API)
* Webhook Handler service (processes Stripe events)
* Order State Manager (coordinates payment status with fulfillment)
Phase 3 - Security:
- Documented webhook signature verification requirements
- PCI compliance considerations
Phase 4 - Modules:
- Created module specifications with clear interfaces
- Included error handling strategies
Phase 5 - Handoff:
- Created handoff document with 3 implementation phases:
1. Payment Gateway module
2. Webhook integration
3. Order system integration
- Included risk assessment (webhook delivery failures, idempotency)
- Added testing strategy
Files created:
- docs_dev/design/stripe-integration-architecture.md
- docs_dev/design/modules/payment-gateway.md
- docs_dev/design/handoff-def456.md
1. Generate UUID: design-auth-20260130-abc123
2. Create design from template
3. Set state: DRAFT
4. Register in design/requirements/index.json
5. Complete design content
6. Validate completeness checklist
7. Update state: REVIEW
8. Assign reviewers
1. Verify all review comments resolved
2. Update state: APPROVED
3. Create GitHub Issues for implementation tasks
4. Notify implementers
5. Monitor implementation progress
6. Document any deviations
| Error | Cause | Solution |
|---|---|---|
| Invalid state transition | Attempted DRAFT → APPROVED | Must go through REVIEW first |
| Missing UUID | Design document lacks identifier | Generate UUID before registration |
| Index conflict | Duplicate design ID | Use unique timestamp-based UUIDs |
| Review comments unresolved | Attempting approval too early | Resolve all comments first |
| Missing template | Template file not found | Restore template from backup |
The following scripts automate design lifecycle operations:
| Script | Purpose | Usage |
|---|---|---|
eaa_design_lifecycle.py | Manage design document state transitions | python scripts/eaa_design_lifecycle.py --uuid <UUID> --transition <STATE> |
eaa_design_transition.py | Validate and execute state transitions | python scripts/eaa_design_transition.py --from <STATE> --to <STATE> |
eaa_design_uuid.py | Generate GUUIDs for new design documents | python scripts/eaa_design_uuid.py --type <DOC_TYPE> |
eaa_design_version.py | Track document versions | python scripts/eaa_design_version.py --uuid <UUID> --bump |
eaa_design_export.py | Export design documents to various formats | python scripts/eaa_design_export.py --uuid <UUID> --format <FORMAT> |
eaa_design_handoff.py | Generate handoff documents for EOA | python scripts/eaa_design_handoff.py --design <UUID> --target eoa |
eaa_init_design_folders.py | Initialize design folder structure | python scripts/eaa_init_design_folders.py --project-root <PATH> |
All scripts are located at ../../scripts/ relative to this skill.
Detailed reference documentation for design lifecycle operations:
| Reference | Description |
|---|---|
| rule-14-enforcement.md | RULE 14: User Requirements Are Immutable - enforcement guidelines |
| judgment-guidelines.md | Architecture judgment guidelines for design decisions |
| success-criteria.md | Design success criteria and validation checklist |
| workflow-checklists.md | Design workflow checklists for each lifecycle phase |
| adr-templates.md | Architecture Decision Record templates and examples |
| handoff-format.md | Design handoff format specification |
templates/design-template.md - Design document templatedesign/requirements/index.json - Design index location