Produce an architecture design document for a complex change. Covers API contracts, DB schema, component architecture, security, and rollback plan. Use before implementation of any non-trivial change. Invoke with /design-arch.
Produce a complete design.md for a complex change before any implementation begins. Good design documents prevent architecture drift, miscommunication between frontend and backend, and unsafe migrations.
~/coding-projects/project-map.yamlopenspec/changes/<change-id>/proposal.md for requirements.ai/shared-memory/project-context.md and decision-log.mdDetermine which of these surfaces the change touches:
Create openspec/changes/<change-id>/design.md:
# Design: <change-id>
## Summary
<One paragraph: what is being built, why, and key design decisions>
## API Contract
| Method | Path | Request Body | Response | Status Codes | Auth |
|--------|------|-------------|----------|--------------|------|
| POST | /api/v1/... | `{ field: string }` | `{ id: string }` | 201, 400, 401 | Bearer |
## Database Schema Changes
```sql
-- Migration: <timestamp>_<name>
CREATE TABLE ... (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
...
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_... ON ...(...);
<FeaturePage>
├── <FeatureList> — fetches and renders list
│ └── <FeatureItem> — single item with actions
└── <FeatureForm> — create/edit form
<Step-by-step: how to safely revert this change if it goes wrong>
npm run migrate:downgcloud run services update-traffic ...| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Migration data loss | Low | High | Run on copy first; backup before apply |
| Decision | Rationale | Alternatives Rejected |
|---|---|---|
| Use REST not GraphQL | Existing codebase uses REST | GraphQL adds complexity |
### Step 4: Update decision-log
Add architecture decisions to `.ai/shared-memory/decision-log.md` for cross-cutting choices.
### Step 5: Hand off
Update `handoff.md`:
- Owner → `@dev-manager` or first implementation owner
- Status → design approved
- Next step → implementation
## Output
- `openspec/changes/<change-id>/design.md`
- Updated `.ai/shared-memory/decision-log.md` (for cross-cutting decisions)
- Updated `handoff.md`
## Done when
- [ ] API contracts are explicit with all methods, paths, request/response shapes, and status codes
- [ ] DB migrations are written (even if not applied)
- [ ] Component architecture is described
- [ ] Security considerations are addressed
- [ ] Rollback plan exists
- [ ] Decisions are documented with rationale
## Rules
| Rule | Why |
|------|-----|
| No implementation before design is approved | Prevents rework and architecture drift |
| All API changes explicit | QA and frontend need exact contracts |
| Rollback plan required | Every deploy must be reversible |
| Cross-cutting decisions in decision-log | Future developers need the rationale |