Initial commit: Clean DSS implementation
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
This commit is contained in:
Digital Production Factory
@@ -0,0 +1,135 @@
|
||||
---
|
||||
id: 001
|
||||
title: Use Markdown ADRs for Recording DSS Architecture Decisions
|
||||
date: 2025-12-08
|
||||
author(s): Claude Code + Gemini 3 Pro
|
||||
status: Accepted
|
||||
principles: [Knowledge Persistence, Single Source of Truth, Foundational Contracts]
|
||||
related:
|
||||
- doc: /docs/01_core/PRINCIPLES.md
|
||||
- doc: /.knowledge/adrs/000-template.md
|
||||
- ticket: DSS-Principles-Pilot
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The DSS project has defined 7 core principles that guide all architectural and governance decisions. However, principles are only as valuable as their adoption and application in real work. Without a lightweight, practical mechanism to capture why decisions were made, alternatives were considered, and consequences were evaluated, the principles become aspirational rather than operational.
|
||||
|
||||
Additionally, as the DSS evolves, decision rationale is often lost or scattered across commit messages, Slack discussions, or in developers' heads. This makes it difficult to:
|
||||
- Understand why a past decision was made
|
||||
- Know which decisions are still valid vs. need reconsideration
|
||||
- Onboard new team members who need to understand the system's evolution
|
||||
- Identify when to revisit or supersede past decisions
|
||||
|
||||
We needed a simple, version-control-friendly mechanism to record architectural decisions that would be low-friction (encouraging adoption) while remaining structured (enabling automated tooling later).
|
||||
|
||||
### Alternatives Considered
|
||||
|
||||
1. **JSON-only format** (.knowledge/decisions/adr-001.json)
|
||||
- Pros: Machine-readable from the start
|
||||
- Cons: Developers have to write JSON, which is tedious and error-prone; harder to edit in typical workflows
|
||||
- Rejected: Too much friction; would be skipped in favor of verbal discussions
|
||||
|
||||
2. **Database-backed ADR system** (MongoDB, PostgreSQL records)
|
||||
- Pros: Queryable, structured, supports automated workflows
|
||||
- Cons: Adds external dependencies; cannot be version-controlled; requires setup
|
||||
- Rejected: Over-engineered for Year 1; adds maintenance burden
|
||||
|
||||
3. **Markdown with YAML frontmatter** (this approach)
|
||||
- Pros: Humans love Markdown; YAML frontmatter is machine-parseable; works with git; requires zero setup
|
||||
- Cons: Requires manual curation (no automated queries yet); files need to be discovered manually
|
||||
- Selected: Best balance of ease-of-use and future-proofing
|
||||
|
||||
## Decision
|
||||
|
||||
We will record Architecture Decision Records (ADRs) as **Markdown files with YAML frontmatter** in the `.knowledge/adrs/` directory.
|
||||
|
||||
### Format
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: NNN
|
||||
title: Short descriptive title
|
||||
date: YYYY-MM-DD
|
||||
author(s): Name(s)
|
||||
status: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
|
||||
principles: [Relevant principles from PRINCIPLES.md]
|
||||
related:
|
||||
- doc: Documentation link
|
||||
- adr: Other ADR link
|
||||
- ticket: Issue/PR link
|
||||
---
|
||||
|
||||
# Markdown content here
|
||||
|
||||
## Context
|
||||
## Decision
|
||||
## Consequences
|
||||
## Related Principles
|
||||
```
|
||||
|
||||
### Process
|
||||
|
||||
1. **Create ADR during decision**: When a significant architectural decision is made, a team member creates a Markdown file following the template
|
||||
2. **Link from PRs**: PRs that implement a decision reference the ADR (`Implements ADR-NNN`)
|
||||
3. **Review in Code Review**: Reviewers validate that decision and consequences are clearly stated
|
||||
4. **Status Lifecycle**: ADRs start as `Proposed`, become `Accepted` after consensus, and can be marked `Deprecated` or `Superseded` as the system evolves
|
||||
5. **No Deletion**: ADRs are never deleted; superseded ADRs remain in place with status marked
|
||||
|
||||
### Scope
|
||||
|
||||
ADRs are for **significant architectural decisions** that:
|
||||
- Impact multiple components or systems
|
||||
- Involve trade-offs or alternatives
|
||||
- Will be referenced in future decisions
|
||||
- Need rationale captured for future developers
|
||||
|
||||
**Not** for every technical decision (e.g., "use this variable name" or "fix this bug").
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive:**
|
||||
- **Knowledge Capture**: Rationale is captured while fresh, not reconstructed later from git history
|
||||
- **Principle Alignment**: Forces explicit connection to DSS principles; strengthens principle adoption
|
||||
- **Onboarding**: New team members understand "why" decisions were made, not just "what"
|
||||
- **Traceability**: Decision → Implementation (PR) → Code → Testing forms a clear chain
|
||||
- **Future Guidance**: When reconsidering a decision, the old ADR shows what was tried and why
|
||||
- **Git-Friendly**: ADRs are version-controlled, reviewable in PRs, queryable via grep
|
||||
- **Low Friction**: Markdown is familiar; YAML is structured; zero infrastructure needed
|
||||
- **Extensible**: Can add structured queries, automation, or dashboards later without changing format
|
||||
|
||||
**Negative:**
|
||||
- **Manual Curation**: Someone must remember to create ADRs; no automatic enforcement (yet)
|
||||
- **File Discovery**: ADRs must be discovered manually or via grep (no centralized index yet)
|
||||
- **Status Drift**: Developers might forget to mark ADRs as `Superseded` when a decision changes
|
||||
- **Incomplete Coverage**: Not all past decisions will have ADRs (only going forward)
|
||||
|
||||
## Related Principles
|
||||
|
||||
- **Knowledge Persistence**: ADRs are the executable capture of architectural knowledge; they live in the graph and can be queried/analyzed
|
||||
- **Single Source of Truth**: Decision rationale is recorded once in the ADR; referenced (not duplicated) from code/docs/PRs
|
||||
- **Foundational Contracts**: ADRs that document API or architecture changes become part of the immutable Tier 1 contract
|
||||
- **Current State Transparency**: Status field (Accepted, Deprecated, Superseded) keeps the decision record truthful and current
|
||||
- **MCP First**: Future tooling (MCP tools) can query the ADR repository and suggest decisions based on project changes
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Pilot on dss_sync_figma** (Week 1-4 of December 2025)
|
||||
- Team will create 2-3 ADRs for foundational decisions
|
||||
- Gather feedback on process and template
|
||||
- Refine based on real-world use
|
||||
|
||||
2. **Retrospective** (Week 4)
|
||||
- Did ADRs help clarify decisions?
|
||||
- Was the process too heavy or too light?
|
||||
- What needs to change for broader adoption?
|
||||
|
||||
3. **Broader Rollout** (Month 2+)
|
||||
- Share learnings with broader team
|
||||
- Encourage ADRs on new features
|
||||
- Build tooling (queries, dashboards) based on feedback
|
||||
|
||||
---
|
||||
|
||||
**Status**: Ready for pilot implementation
|
||||
**Approved by**: DSS Core Principles Initiative
|
||||
Reference in New Issue
Block a user