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
131
.knowledge/adrs/PRINCIPLES_CORE_REFERENCE.md
Normal file
131
.knowledge/adrs/PRINCIPLES_CORE_REFERENCE.md
Normal file
@@ -0,0 +1,131 @@
|
||||
# DSS Core Principles Reference
|
||||
|
||||
**Quick lookup table for all 7 DSS governance principles**
|
||||
|
||||
Use this document during decision-making, PR reviews, and ADR creation. For detailed elaboration, see `/docs/01_core/PRINCIPLES.md`.
|
||||
|
||||
---
|
||||
|
||||
## Principles Reference Table
|
||||
|
||||
| # | Principle | Core Rule | When to Apply | Red Flag |
|
||||
|---|-----------|-----------|---------------|----------|
|
||||
| 1 | **Single Source of Truth** | One version of critical data lives in one canonical location | Before creating new storage, cache, or replica | Multiple conflicting versions; people asking "which one is right?" |
|
||||
| 2 | **Foundational Contracts** | Core APIs & contracts are versioned and immutable; versioning gates changes | Before changing APIs, data models, tool specs | Breaking changes without version bump; contract changes that silently affect users |
|
||||
| 3 | **Current State Transparency** | Status always reflects production reality; no lying docstrings | During documentation updates and status reports | Outdated docs treated as truth; stale status messages in code |
|
||||
| 4 | **Progressive Detail** | Start simple; add complexity only when needed; expose it via layers | When designing APIs or documentation structure | Forcing users to parse complexity they don't need; overloading simple concepts |
|
||||
| 5 | **Phase Agnostic** | Work is independent of development phases; phases don't live in code/docs | When planning releases and documentation | Phase-specific code/docs that become orphaned; "this is only for MVP" comments |
|
||||
| 6 | **Knowledge Persistence** | Architectural decisions captured in queryable form; rationale never lost | When making significant decisions; at PR review | Decision rationale in Slack only; "we used to do it this way but I forget why" |
|
||||
| 7 | **MCP First** | Design system tools are first-class citizens; tools expose all operations | When building features or APIs | Manual operations that bypass tools; tool-hidden features; undocumented MCP gaps |
|
||||
|
||||
---
|
||||
|
||||
## Application Checklist (for ADRs and PRs)
|
||||
|
||||
Before finalizing a decision, verify:
|
||||
|
||||
- [ ] **Single Source of Truth**: Is there only one canonical source for this data/concept?
|
||||
- [ ] **Foundational Contracts**: If this affects APIs/specs, is the change versioned?
|
||||
- [ ] **Current State**: Does documentation reflect actual production state?
|
||||
- [ ] **Progressive Detail**: Can this be explained simply first, with complexity as optional layers?
|
||||
- [ ] **Phase Agnostic**: Will this work the same way next quarter? Does it have "this is only for MVP" language?
|
||||
- [ ] **Knowledge Persistence**: Have we captured the *why* in a queryable form (ADR)?
|
||||
- [ ] **MCP First**: Are tools the first-class way to do this? Are we hiding anything from the API?
|
||||
|
||||
---
|
||||
|
||||
## Conflict Resolution Order
|
||||
|
||||
When principles conflict, prioritize in this order:
|
||||
|
||||
1. **Foundational Contracts** — Breaking immutable contracts is catastrophic; this trumps all others
|
||||
2. **Single Source of Truth** — Data integrity is foundational; resolve conflicts here first
|
||||
3. **Current State Transparency** — Users deserve to know what's real
|
||||
4. **Knowledge Persistence** — Capture the decision and tradeoff
|
||||
5. **MCP First** — Use tools as the primary interface
|
||||
6. **Progressive Detail** — Simplify when possible without breaking contracts
|
||||
7. **Phase Agnostic** — Long-term thinking; least critical in conflicts
|
||||
|
||||
**Example**: If MCP-First conflicts with Foundational Contracts, honor the contract and document the tool limitation in an ADR.
|
||||
|
||||
---
|
||||
|
||||
## Enforcement Mechanisms
|
||||
|
||||
**Who enforces?**
|
||||
- Code reviewers: Check PR descriptions for principle alignment (via PR template's DSS Principles Check section)
|
||||
- Architecture review: Monthly check of new ADRs for principle alignment
|
||||
- Team retrospectives: Quarterly reflection on principle adoption
|
||||
|
||||
**Red flags that trigger intervention:**
|
||||
- ❌ New storage layer created without SSoT analysis
|
||||
- ❌ API changes without version increment
|
||||
- ❌ Documentation older than last code change
|
||||
- ❌ Decision rationale only in Slack/chat, not in ADR
|
||||
- ❌ Tool functionality that's not MCP-exposed
|
||||
- ❌ Phase-specific code that persists after phase ends
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
Track adoption quarterly:
|
||||
|
||||
- **Single Source of Truth**: Number of competing data sources for same concept (target: 0)
|
||||
- **Foundational Contracts**: API versions in use; breaking changes per release (target: 0)
|
||||
- **Current State**: Docs staleness (% of docs updated in last quarter; target: 100%)
|
||||
- **Progressive Detail**: Layer adoption in docs (quick ref → guides → detailed specs)
|
||||
- **Phase Agnostic**: Phase-specific code post-phase (target: 0)
|
||||
- **Knowledge Persistence**: ADRs created per decision (target: 1 ADR per major decision)
|
||||
- **MCP First**: Tool coverage (% of operations exposed via MCP; target: >95%)
|
||||
|
||||
---
|
||||
|
||||
## Quick Decision Tree
|
||||
|
||||
**I'm about to...**
|
||||
|
||||
- **Change an API** → Check Foundational Contracts. Version it. Create ADR-XXX.
|
||||
- **Store new data** → Check Single Source of Truth. Where should this live? Who owns it?
|
||||
- **Update documentation** → Check Current State. Is this actually how it works in production?
|
||||
- **Design a feature** → Check MCP First. What's the tool interface? What's the REST/API wrapper?
|
||||
- **Make a big decision** → Check Knowledge Persistence. Create an ADR capturing the why.
|
||||
- **Write code for a feature** → Check Phase Agnostic. Will this still make sense next quarter?
|
||||
- **Simplify something** → Check Progressive Detail. Can users opt into complexity rather than force it?
|
||||
|
||||
---
|
||||
|
||||
## How This Connects to ADRs
|
||||
|
||||
Each ADR should:
|
||||
- **Link back to 1-3 principles** that motivate the decision (use `principles:` field in YAML frontmatter)
|
||||
- **Explain tradeoffs** with respect to these principles
|
||||
- **Show conflict resolution** if principles were in tension
|
||||
|
||||
**Example ADR header:**
|
||||
```yaml
|
||||
---
|
||||
id: 005
|
||||
title: Use SQLite for Local Caching
|
||||
date: 2025-12-08
|
||||
status: Accepted
|
||||
principles: [Single Source of Truth, Knowledge Persistence, MCP First]
|
||||
---
|
||||
```
|
||||
|
||||
Then explain: "Why SQLite? Because it creates a single source of truth for local state (Principle 1). We're documenting the caching strategy here (Principle 6). And all query operations go through MCP tools, not direct DB access (Principle 7)."
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
- **Full elaboration**: `/docs/01_core/PRINCIPLES.md` (1,372 lines)
|
||||
- **Knowledge graph**: `.knowledge/adrs/ADR_KNOWLEDGE_MAP.md`
|
||||
- **ADR template**: `.knowledge/adrs/000-template.md`
|
||||
- **How to create ADRs**: `.knowledge/adrs/README.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-08
|
||||
**Status**: Ready for use in decision-making and PR reviews
|
||||
**Audience**: All DSS team members
|
||||
Reference in New Issue
Block a user