cmk:system-design
System Design
Intents
Draft a system design for our payments service
Update the system design — we switched from PostgreSQL to DynamoDB
We're adding a message queue between the API and worker — update the architecture
How should we architect the notification system?
Use the scaling knowledge from our load tests to update the design
References
Read references/system-design-conventions.md for placement rules and references/system-design-template.md for section structure.
Scope
System design captures the technical "how" at architecture level. Product requirements belong in the PRD; implementation detail in feature specs. System-wide decisions should reference or create ADRs.
Input
Synthesize from whatever the user provides: conversation context, existing PRD (docs/PRD.md), local docs, external links, direct prompts, or docs/knowledge/ entries (when explicitly referenced).
Workflow: Create
- Normalize input into architecture context: mission, design principles, tech stack, components, dependencies, cross-cutting concerns, constraints.
- Map into template sections from
references/system-design-template.md. Align to local convention if one exists. - Place at the repository's existing path, or fallback:
docs/system-design.md. - Mark unknowns in
Open Points— don't guess. - Link upstream PRD in
Related Documentswhen one exists. - Set status to
draft.
Workflow: Iterate
- Read the existing system design in full.
- Upstream check: If
docs/PRD.mdexists, scan its scope, success criteria, and status. Warn the user if the update conflicts with upstream PRD. - Identify what changed and why.
- Update affected sections in place. Preserve unchanged content.
- Update
Last updateddate. - Transition status when appropriate:
draft→active→shipped, or any →deprecated.
Output
- Create: complete system design at
docs/system-design.md - Iterate: targeted updates to affected sections only
- Unresolved decisions go in
Open Points - Design principles are opinionated and system-specific
- Architecture diagram matches component descriptions
- Security section is always present — includes assumptions, gaps, and controls
- No feature-level implementation detail
More from commandosslabs/ai-devkit
cmk:feature-spec
Create or iterate feature specifications. Use whenever someone wants to draft, refine, or update a feature spec — from conversation notes, local docs, external links, or direct prompts. Also triggers for "spec out this feature", "write up the requirements for X", "break this into a spec", or discussions about feature scope, flows, and acceptance criteria.
13cmk:codebase-summary
Create or iterate codebase summary documents that map repository structure, key entry points, core modules, and local dev setup. Use whenever someone wants to document how the repo is organized, update the codebase map after restructuring, or help new contributors navigate the codebase. Also triggers for "map the repo", "document the project structure", or "where does everything live".
13cmk:prd
Create or iterate product requirements documents. Use whenever someone wants to draft, refine, or update a PRD — whether from conversation notes, research sessions, user feedback, Notion docs, or direct instructions. Also triggers when users discuss product scope, success criteria, user needs, or say things like "save this as requirements" or "let's define what we're building".
12cmk:docs
Bootstrap or update the /docs directory structure with navigation files, guides, and templates. Use when someone wants to set up docs for a new repo, check if their docs structure is current, or sync scaffolding after devkit updates. Also triggers when users mention "docs structure", "initialize docs", or "docs scaffold".
12cmk:adr
Create or update architecture decision records for system-level technical choices. Use whenever someone needs to record, revise, or document a technical decision with trade-offs — like choosing a database, communication protocol, or infrastructure pattern. Also triggers for "record this decision", "we decided to use X over Y", or "document why we chose this approach".
12cmk:rule
Codify engineering standards into docs/rules/. Use whenever someone wants to create, update, or promote knowledge into enforceable coding rules and conventions that agents follow during development. Also triggers for "add a rule that...", "make this a standard", "promote this learning to a rule", "update our coding conventions", or "what are our engineering rules".
8