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
237
docs/DOCUMENTATION_GUIDE.md
Normal file
237
docs/DOCUMENTATION_GUIDE.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# Documentation Governance & Anti-Bloat Rules
|
||||
|
||||
This guide prevents the documentation chaos from recurring.
|
||||
|
||||
---
|
||||
|
||||
## The Rule of One
|
||||
|
||||
**Every piece of information must exist in exactly ONE place.** No duplicates, no "also documented in...".
|
||||
|
||||
### Documentation Categories
|
||||
|
||||
#### TIER 1: Foundational Contracts (`docs/01_core/`)
|
||||
- **API_CONTRACTS.md** → API endpoints, status codes, authentication
|
||||
- **ARCHITECTURE.md** → System design, technology choices, boundaries
|
||||
- **PRINCIPLES.md** → Design philosophy, core values, invariants
|
||||
|
||||
**These files:**
|
||||
- Change only via semantic versioning (major.minor.patch)
|
||||
- Must include "Version X.Y.Z" at the top
|
||||
- Should never contradict each other
|
||||
- Are the single source of truth for their domain
|
||||
|
||||
#### TIER 2: Current State (`docs/02_status/`)
|
||||
- **PROJECT_STATUS.md** → Deployment status, roadmap, open bugs, current phase
|
||||
- **IMPLEMENTATION_SUMMARY.md** → Inventory of completed features (phases 1-5C)
|
||||
- **README.md** (root) → Quick start, project overview
|
||||
|
||||
**These files:**
|
||||
- Update frequently (daily/weekly)
|
||||
- Always reflect production reality
|
||||
- Include "Last Updated: YYYY-MM-DD" timestamp
|
||||
- Are curated (old status removed, new status added)
|
||||
|
||||
#### TIER 3: Reference Guides (`docs/03_reference/`)
|
||||
- **INTEGRATION_GUIDE.md** → How to use DSS in external projects
|
||||
- **MIGRATION_GUIDE.md** → How to migrate from legacy systems
|
||||
- **MCP_TOOLS_SPEC.md** → Model Context Protocol tool specifications
|
||||
- **PRODUCTION_READINESS.md** → Deployment checklist, monitoring
|
||||
|
||||
**These files:**
|
||||
- Change when guidance needs updating
|
||||
- Include examples and common patterns
|
||||
- Link to Tier 1 for architectural context
|
||||
|
||||
#### TIER 4: Archive (`docs/archive/`)
|
||||
- **pre_optimization/** → Phase reports, old deployment guides
|
||||
- Snapshot files from past sprints
|
||||
|
||||
**These files:**
|
||||
- Are READ-ONLY (append dates, don't modify)
|
||||
- Serve historical context only
|
||||
- Are NEVER loaded for current work
|
||||
- Prefixed with date: `2025-12-08_PHASE_5C_COMPLETION.md`
|
||||
|
||||
---
|
||||
|
||||
## The Anti-Bloat Process
|
||||
|
||||
### When a Phase Ends
|
||||
1. ✅ Update `docs/02_status/PROJECT_STATUS.md` with new baseline
|
||||
2. ✅ Merge architectural patterns into `docs/01_core/ARCHITECTURE.md`
|
||||
3. ✅ Update `docs/02_status/IMPLEMENTATION_SUMMARY.md` with new features
|
||||
4. ⛔ DO NOT create `PHASE_X_COMPLETION_REPORT.md` (this bloats docs)
|
||||
5. ⛔ DO NOT keep "Phase X Final Report" in root (archive it immediately)
|
||||
|
||||
**Example**: Instead of creating `PHASE_5C_FINAL_REPORT.md`, update:
|
||||
```
|
||||
docs/02_status/PROJECT_STATUS.md → "Phase 5C complete: X, Y, Z features"
|
||||
docs/02_status/IMPLEMENTATION_SUMMARY.md → "Phase 5C: Added endpoints A, B, C"
|
||||
```
|
||||
|
||||
Then archive the phase-specific planning doc:
|
||||
```bash
|
||||
mv PHASE_5C_PLANNING.md docs/archive/pre_optimization/2025-12-08_PHASE_5C_PLANNING.md
|
||||
```
|
||||
|
||||
### When Adding a New Feature
|
||||
1. ✅ Update `docs/01_core/API_CONTRACTS.md` with new endpoint(s)
|
||||
2. ✅ Update `docs/01_core/ARCHITECTURE.md` if design changed
|
||||
3. ✅ Update `docs/02_status/IMPLEMENTATION_SUMMARY.md` with feature inventory
|
||||
4. ⛔ DO NOT create `NEW_FEATURE_IMPLEMENTATION_NOTES.md`
|
||||
5. ⛔ DO NOT add "Feature X Details" to root
|
||||
|
||||
**Example**: For new `POST /api/projects` endpoint:
|
||||
```
|
||||
docs/01_core/API_CONTRACTS.md → Add full endpoint spec
|
||||
docs/01_core/ARCHITECTURE.md → Update "Project Management" section if needed
|
||||
docs/02_status/IMPLEMENTATION_SUMMARY.md → "Phase 6: Added project persistence"
|
||||
```
|
||||
|
||||
### When Fixing a Bug
|
||||
1. ✅ Update `docs/02_status/PROJECT_STATUS.md` under "Open Issues" or "Fixed"
|
||||
2. ⛔ DO NOT create `BUG_FIX_SUMMARY.md`
|
||||
3. ⛔ DO NOT add "Fixed: ..." to root
|
||||
|
||||
### When Documenting a Decision
|
||||
1. ✅ Add rationale to `docs/01_core/ARCHITECTURE.md` or `docs/01_core/PRINCIPLES.md`
|
||||
2. ✅ If complex, store decision record in `.knowledge/decisions/ADR-NNN.json`
|
||||
3. ⛔ DO NOT create `DECISION_LOG.md` or `WHY_WE_CHOSE_X.md`
|
||||
|
||||
---
|
||||
|
||||
## Red Flags: Files That Shouldn't Exist in Root
|
||||
|
||||
If you see any of these, move them to `docs/archive/` immediately:
|
||||
|
||||
| Pattern | Why Bad | What To Do |
|
||||
|---|---|---|
|
||||
| `DEPLOYMENT_*.md` | Dated snapshots | Move to archive, update PROJECT_STATUS instead |
|
||||
| `*_COMPLETE.md` | Historical (Phase is done) | Move to archive |
|
||||
| `*_REPORT.md` | Phase snapshots | Move to archive |
|
||||
| `WEEK_*_SUMMARY.md` | Time-based clutter | Move to archive |
|
||||
| `MVP*_*.md` | Obsolete after Phase 1-2 | Move to archive |
|
||||
| `PHASE_*_*.md` | Temporary planning docs | Move to archive |
|
||||
| `TODO.md` | Should be in PROJECT_STATUS | Merge + delete |
|
||||
| `TASKS.md` | Should be in PROJECT_STATUS | Merge + delete |
|
||||
| `ROADMAP.md` | Should be in PROJECT_STATUS | Merge + delete |
|
||||
|
||||
---
|
||||
|
||||
## File Lifecycle
|
||||
|
||||
```
|
||||
CREATED (in working branch)
|
||||
↓
|
||||
Is it a phase/deployment snapshot?
|
||||
YES → Merge value into Tier 2, archive source
|
||||
NO → Continue
|
||||
↓
|
||||
Is it a permanent guide?
|
||||
YES → Place in Tier 3, reference from relevant Tier 1 files
|
||||
NO → Continue
|
||||
↓
|
||||
Is it a specification/principle?
|
||||
YES → Add to Tier 1, ensure it doesn't duplicate existing content
|
||||
NO → This file may not be needed
|
||||
↓
|
||||
MERGED & COMMITTED
|
||||
|
||||
6 MONTHS LATER
|
||||
↓
|
||||
Is this still actively used?
|
||||
YES → Keep in docs/
|
||||
NO → Archive it
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Maintenance Checklist
|
||||
|
||||
Every month, run this command to audit documentation:
|
||||
|
||||
```bash
|
||||
# Find markdown files in root older than 30 days
|
||||
find . -maxdepth 1 -name "*.md" -mtime +30 -type f
|
||||
|
||||
# Any files here should be reviewed for archival
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Hierarchy in One Picture
|
||||
|
||||
```
|
||||
AI Agent starts session
|
||||
↓
|
||||
Read: QUICK_REFERENCE.md (this file's companion)
|
||||
↓
|
||||
Context loaded: Tier 1 + Tier 2
|
||||
↓
|
||||
Working on feature? Load relevant Tier 3 guide
|
||||
↓
|
||||
Historical research? Only then access Tier 4 archive
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Questions This Answers
|
||||
|
||||
**"Where do I document this?"**
|
||||
- Principles → `docs/01_core/PRINCIPLES.md`
|
||||
- API changes → `docs/01_core/API_CONTRACTS.md`
|
||||
- Architecture changes → `docs/01_core/ARCHITECTURE.md`
|
||||
- Current bugs → `docs/02_status/PROJECT_STATUS.md`
|
||||
- How-to guide → `docs/03_reference/`
|
||||
- Phase snapshot → `docs/archive/` (after extracting value)
|
||||
|
||||
**"Can I create a new file for X?"**
|
||||
- If X belongs in an existing Tier file → NO, add to that file
|
||||
- If X is a new guide type → MAYBE, add to Tier 3 and update QUICK_REFERENCE.md
|
||||
- If X is temporary → NO, update PROJECT_STATUS instead
|
||||
|
||||
**"How old can docs be?"**
|
||||
- Tier 1 files → Should be current (versioned if changed)
|
||||
- Tier 2 files → Must be current (updated weekly minimum)
|
||||
- Tier 3 files → Can be older, but should note "Last Verified: DATE"
|
||||
- Tier 4 files → Frozen in time, append dates
|
||||
|
||||
---
|
||||
|
||||
## Governance Rule Enforcement
|
||||
|
||||
### For PR Reviews
|
||||
Check that no PR adds files matching these patterns to root:
|
||||
- `*_REPORT.md`
|
||||
- `*_COMPLETE.md`
|
||||
- `PHASE_*.md`
|
||||
- `DEPLOYMENT_*.md`
|
||||
- `MVP_*.md`
|
||||
- `TODO.md`, `TASKS.md`, `ROADMAP.md`
|
||||
|
||||
If found, request refactor: "Please move this to docs/archive/ or merge value into docs/02_status/"
|
||||
|
||||
### For Session Start
|
||||
Load ONLY:
|
||||
1. QUICK_REFERENCE.md (this directs you)
|
||||
2. docs/02_status/PROJECT_STATUS.md (current state)
|
||||
3. docs/01_core/PRINCIPLES.md (philosophy)
|
||||
|
||||
Everything else is on-demand.
|
||||
|
||||
---
|
||||
|
||||
## Victory Metrics
|
||||
|
||||
- ✅ Root directory has <15 markdown files (down from 40+)
|
||||
- ✅ docs/ subdirectories organized by Tier
|
||||
- ✅ No deprecated files in root
|
||||
- ✅ New docs automatically placed in correct Tier
|
||||
- ✅ QUICK_REFERENCE.md is the single entry point
|
||||
- ✅ Context window reduced from ~50k to ~15k lines
|
||||
|
||||
---
|
||||
|
||||
Last Updated: 2025-12-08
|
||||
Approved By: Gemini 3 Pro, Deep Think Analysis
|
||||
Reference in New Issue
Block a user