276ed71f31
Migrated from design-system-swarm with fresh git history.
Old project history preserved in /home/overbits/apps/design-system-swarm
Core components:
- MCP Server (Python FastAPI with mcp 1.23.1)
- Claude Plugin (agents, commands, skills, strategies, hooks, core)
- DSS Backend (dss-mvp1 - token translation, Figma sync)
- Admin UI (Node.js/React)
- Server (Node.js/Express)
- Storybook integration (dss-mvp1/.storybook)
Self-contained configuration:
- All paths relative or use DSS_BASE_PATH=/home/overbits/dss
- PYTHONPATH configured for dss-mvp1 and dss-claude-plugin
- .env file with all configuration
- Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability
Migration completed: $(date)
🤖 Clean migration with full functionality preserved
102 lines
3.1 KiB
Markdown
102 lines
3.1 KiB
Markdown
# Architecture Decision Records (ADRs)
|
|
|
|
This directory contains Architecture Decision Records for the DSS project. ADRs capture the rationale behind significant architectural decisions, alternatives considered, and consequences of choices we make.
|
|
|
|
## Why ADRs?
|
|
|
|
ADRs serve the principles of **Knowledge Persistence** and **Single Source of Truth** from [PRINCIPLES.md](/docs/01_core/PRINCIPLES.md).
|
|
|
|
They answer the question: **"Why did we decide this way?"**
|
|
|
|
## How to Create an ADR
|
|
|
|
1. Copy `000-template.md` to `NNN-short-title.md` (e.g., `002-use-sqlite-for-local-cache.md`)
|
|
2. Fill out all sections
|
|
3. Reference relevant DSS principles
|
|
4. Link from PRs that implement the decision
|
|
5. Commit to git; it becomes part of the decision history
|
|
|
|
## Format
|
|
|
|
```yaml
|
|
---
|
|
id: NNN # Sequential number
|
|
title: Clear, descriptive title
|
|
date: YYYY-MM-DD # Decision date
|
|
author(s): Your Name # Who decided this?
|
|
status: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
|
|
principles: [Principle1, Principle2] # Which DSS principles does this support?
|
|
related:
|
|
- doc: Link to documentation
|
|
- adr: Link to related ADRs
|
|
- ticket: Link to issue/PR
|
|
---
|
|
```
|
|
|
|
## Status Lifecycle
|
|
|
|
- **Proposed**: Decision is being considered; not yet finalized
|
|
- **Accepted**: Team has consensus; decision is in effect
|
|
- **Deprecated**: We no longer recommend this approach but it may still be in use
|
|
- **Superseded by ADR-XXX**: This decision was replaced; see referenced ADR for current approach
|
|
|
|
**Important**: Never delete an ADR. Mark it as Superseded and leave it in place for historical reference.
|
|
|
|
## Examples
|
|
|
|
Current ADRs:
|
|
- `001-use-markdown-adrs-for-dss-architecture-decisions.md` - How we record decisions
|
|
|
|
## Tips for Good ADRs
|
|
|
|
✅ **Do**:
|
|
- Write while the decision is fresh
|
|
- Include context on why this decision matters
|
|
- Explain alternatives and why they were rejected
|
|
- Be concise but complete
|
|
- Link to related decisions and principles
|
|
|
|
❌ **Don't**:
|
|
- Write implementation details (that belongs in code comments/documentation)
|
|
- Make decisions in the ADR; use ADRs to record *already made* decisions
|
|
- Use ADRs for minor technical choices (use PRs/code comments instead)
|
|
- Delete or significantly rewrite an ADR after acceptance (mark as Superseded instead)
|
|
|
|
## Querying ADRs
|
|
|
|
Find ADRs related to a concept:
|
|
```bash
|
|
# Find all ADRs mentioning "Figma"
|
|
grep -r "Figma" .knowledge/adrs/
|
|
|
|
# Find all deprecated ADRs
|
|
grep -r "status: Deprecated" .knowledge/adrs/
|
|
|
|
# Find ADRs related to MCP principle
|
|
grep -r "MCP First" .knowledge/adrs/
|
|
```
|
|
|
|
## Integration with Code Review
|
|
|
|
When opening a PR that implements a significant decision:
|
|
|
|
```markdown
|
|
## DSS Principles Check
|
|
- **ADR Link**: Implements decision in ADR-NNN
|
|
- **Principle Alignment**: This work supports [Principle Name] by...
|
|
```
|
|
|
|
See the [updated PR template](#) for details.
|
|
|
|
## Future Tooling
|
|
|
|
Year 1: Manual ADR creation and discovery (this system)
|
|
Year 2: Automated queries and dashboards for ADR insights
|
|
Year 3: ADRs generate code contracts and test suites
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-12-08
|
|
**Pilot Project**: `dss_sync_figma`
|
|
**Next Review**: Week 4 of December 2025 (retrospective)
|