Major cleanup: Remove redundant code, consolidate knowledge base
- Delete redundant directories: demo/, server/, orchestrator/, team-portal/, servers/ - Remove all human-readable documentation (docs/, .dss/*.md, admin-ui/*.md) - Consolidate 4 knowledge JSON files into single DSS_CORE.json - Clear browser logs (7.5MB), backups, temp files - Remove obsolete configs (.cursorrules, .dss-boundaries.yaml, .ds-swarm/) - Reduce project from 20MB to ~8MB Kept: tools/, admin-ui/, cli/, dss-claude-plugin/, .dss/schema/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
218
.knowledge/DSS_CORE.json
Normal file
218
.knowledge/DSS_CORE.json
Normal file
@@ -0,0 +1,218 @@
|
||||
{
|
||||
"$schema": "dss-core-v1",
|
||||
"version": "1.0.0",
|
||||
"last_updated": "2025-12-10",
|
||||
"purpose": "Single source of truth for AI agents working with DSS",
|
||||
|
||||
"meta": {
|
||||
"schema_ref": "https://sofi.internal/dss/schemas/dss-core-v1.json",
|
||||
"compat": {
|
||||
"min_admin_ui": "0.6.0",
|
||||
"min_cli": "0.4.0",
|
||||
"min_mcp_server": "0.3.0"
|
||||
},
|
||||
"status": "stable",
|
||||
"owners": ["dss-core@sofi.com"],
|
||||
"tags": ["design-system", "tokens", "figma", "storybook", "mcp"]
|
||||
},
|
||||
|
||||
"what_is_dss": {
|
||||
"description": "Design System Server - monolithic platform for design token management",
|
||||
"core_function": "Ingest tokens from multiple sources, normalize to canonical format, generate outputs",
|
||||
"philosophy": "DSS structure is sacred - external systems adapt TO DSS, not reverse"
|
||||
},
|
||||
|
||||
"canonical_structure": {
|
||||
"tokens": ["colors", "spacing", "typography", "borders", "shadows", "motion"],
|
||||
"components": ["Button", "Input", "Card", "Badge", "Toast", "..."],
|
||||
"patterns": ["forms", "navigation", "layouts"],
|
||||
"rule": "This structure NEVER changes. All inputs normalize to this."
|
||||
},
|
||||
|
||||
"key_concepts": {
|
||||
"translation_dictionaries": {
|
||||
"what": "Per-project mappings from external systems to DSS canonical tokens",
|
||||
"flow": "Source tokens -> Translation layer -> DSS canonical -> Output"
|
||||
},
|
||||
"custom_props": {
|
||||
"what": "Client-specific properties outside DSS core",
|
||||
"namespace": "color.brand.{client}.*",
|
||||
"rule": "Never modify DSS core - add to custom namespace"
|
||||
},
|
||||
"merge_strategies": {
|
||||
"FIRST": "Keep first occurrence",
|
||||
"LAST": "Override with latest",
|
||||
"PREFER_FIGMA": "Prioritize Figma source",
|
||||
"PREFER_CODE": "Prioritize CSS/SCSS",
|
||||
"PREFER_SPECIFIC": "Prefer concrete values over references",
|
||||
"MERGE_METADATA": "Combine metadata, use latest value"
|
||||
}
|
||||
},
|
||||
|
||||
"architecture": {
|
||||
"layers": {
|
||||
"router": "MCP Server (36 tools), REST API (34 endpoints), CLI",
|
||||
"messaging": "Circuit breaker, Activity log, Event emitter",
|
||||
"workflows": "Figma client, Token ingestion, Storybook generator, Analysis engine, Context compiler, Storage (SQLite)"
|
||||
},
|
||||
"ports": {
|
||||
"rest_api": 3456,
|
||||
"mcp_server": 3457
|
||||
},
|
||||
"dependencies": {
|
||||
"python": ">=3.10",
|
||||
"node": ">=18",
|
||||
"db": "sqlite3",
|
||||
"services": ["figma-api", "storybook", "nginx"]
|
||||
}
|
||||
},
|
||||
|
||||
"mcp_tools_categories": {
|
||||
"project_management": ["dss_analyze_project"],
|
||||
"token_ingestion": ["dss_extract_tokens", "dss_transform_tokens", "dss_resolve_token"],
|
||||
"utilities": ["dss_generate_theme", "dss_list_themes", "dss_get_status", "dss_find_quick_wins", "dss_validate_manifest", "dss_list_skins"],
|
||||
"analysis": ["dss_audit_components", "browser_accessibility_audit"],
|
||||
"storybook": ["dss_setup_storybook"],
|
||||
"figma_integration": ["dss_sync_figma"],
|
||||
"browser_tools": ["devtools_launch", "devtools_connect", "devtools_console_logs", "devtools_screenshot", "..."],
|
||||
"context_compiler": ["dss_get_resolved_context", "dss_get_compiler_status"]
|
||||
},
|
||||
|
||||
"context_compiler": {
|
||||
"cascade": "Base Skin -> Extended Skin -> Project Overrides = Final Context",
|
||||
"caching": "mtime-based invalidation",
|
||||
"security": "Path traversal prevention, input validation",
|
||||
"lifecycle": {
|
||||
"states": ["idle", "building", "ready", "stale", "error"],
|
||||
"transitions": {
|
||||
"idle->building": "trigger build",
|
||||
"building->ready": "build success",
|
||||
"ready->stale": "source mtime changed",
|
||||
"any->error": "uncaught exception"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"file_paths": {
|
||||
"mcp_server": "dss-claude-plugin/servers/dss-mcp-server.py",
|
||||
"rest_api": "tools/api/server.py",
|
||||
"token_parsers": "tools/ingest/",
|
||||
"analysis": "tools/analyze/",
|
||||
"database": ".dss/dss.db",
|
||||
"schemas": ".dss/schema/",
|
||||
"admin_ui": "admin-ui/",
|
||||
"skills": "dss-claude-plugin/skills/",
|
||||
"commands": "dss-claude-plugin/commands/",
|
||||
"logs": ".dss/logs/",
|
||||
"cache": ".dss/cache/"
|
||||
},
|
||||
|
||||
"coding_rules_summary": {
|
||||
"web_components": "Shadow DOM required, lifecycle management, data-action event delegation",
|
||||
"styles": "No inline styles, use CSS custom properties",
|
||||
"events": "No inline handlers, use data-action pattern",
|
||||
"accessibility": "WCAG 2.1 AA, semantic HTML, ARIA attributes",
|
||||
"state": "Context store for global, component state for local, no direct DOM manipulation",
|
||||
"errors": "Use logger utility, structured error codes (E1xxx-E5xxx, S1xxx)"
|
||||
},
|
||||
|
||||
"error_codes": {
|
||||
"E1xxx": "User errors",
|
||||
"E2xxx": "Validation errors",
|
||||
"E3xxx": "API errors",
|
||||
"E4xxx": "System errors",
|
||||
"E5xxx": "Integration errors",
|
||||
"S1xxx": "Success codes"
|
||||
},
|
||||
|
||||
"supported_sources": {
|
||||
"tokens": ["Figma", "CSS", "SCSS", "Tailwind", "JSON"],
|
||||
"output_formats": ["CSS", "SCSS", "JSON", "JS", "Storybook theme"]
|
||||
},
|
||||
|
||||
"capabilities": {
|
||||
"ingestion": ["figma", "css", "scss", "tailwind", "json"],
|
||||
"normalization": ["resolve references", "merge metadata", "de-duplicate"],
|
||||
"generation": ["css vars", "scss maps", "json manifests", "storybook themes"],
|
||||
"analysis": ["component audit", "accessibility audit", "quick wins"],
|
||||
"integration": ["mcp tools", "rest api", "cli", "admin-ui"],
|
||||
"governance": ["translation dictionaries", "custom namespaces", "merge strategies"]
|
||||
},
|
||||
|
||||
"interfaces": {
|
||||
"rest": {
|
||||
"base": "/api/v1",
|
||||
"endpoints": [
|
||||
{"path": "/tokens/ingest", "method": "POST", "desc": "Ingest tokens"},
|
||||
{"path": "/tokens/export", "method": "GET", "desc": "Export normalized tokens"},
|
||||
{"path": "/context", "method": "GET", "desc": "Resolved context"},
|
||||
{"path": "/themes", "method": "GET", "desc": "List available themes"}
|
||||
]
|
||||
},
|
||||
"cli": {
|
||||
"commands": ["dss ingest", "dss generate", "dss analyze", "dss context"]
|
||||
},
|
||||
"events": {
|
||||
"emitted": ["ingestion.completed", "context.ready", "theme.generated", "audit.completed"],
|
||||
"subscribed": ["figma.sync", "repo.changed", "cache.invalidate"]
|
||||
}
|
||||
},
|
||||
|
||||
"metrics": {
|
||||
"ingestion_time_ms": {"p50": 500, "p95": 2000},
|
||||
"context_build_ms": {"p50": 800, "p95": 2500},
|
||||
"cache_hit_rate": {"target": 0.8},
|
||||
"error_rate": {"target": 0.01}
|
||||
},
|
||||
|
||||
"security": {
|
||||
"input_validation": true,
|
||||
"path_sanitization": true,
|
||||
"allowed_sources": ["figma", "filesystem", "repo"],
|
||||
"secrets": {
|
||||
"env": ["FIGMA_TOKEN", "STORYBOOK_TOKEN"],
|
||||
"store": "keychain (macOS) or env"
|
||||
}
|
||||
},
|
||||
|
||||
"governance": {
|
||||
"change_control": "PR required for canonical changes",
|
||||
"reviewers": ["design-systems", "frontend-arch"],
|
||||
"versioning": {
|
||||
"core": "semver",
|
||||
"tokens": "schema-tagged versions",
|
||||
"skins": "named releases"
|
||||
}
|
||||
},
|
||||
|
||||
"validation": {
|
||||
"schema_checks": ["tokens.json schema", "theme.json schema"],
|
||||
"lint": ["naming conventions", "namespace rules"],
|
||||
"tests": ["ingestion", "merge", "context"]
|
||||
},
|
||||
|
||||
"operational": {
|
||||
"logging": {
|
||||
"level": "info",
|
||||
"path": ".dss/logs/dss.log"
|
||||
},
|
||||
"performance": {
|
||||
"max_workers": 4,
|
||||
"debounce_ms": 250
|
||||
},
|
||||
"storage": {
|
||||
"db": ".dss/dss.db",
|
||||
"cache": ".dss/cache"
|
||||
}
|
||||
},
|
||||
|
||||
"examples": {
|
||||
"custom_namespace": "color.brand.acme.primary",
|
||||
"merge_strategy": "PREFER_FIGMA",
|
||||
"cli": "dss ingest --source figma --file tokens.json"
|
||||
},
|
||||
|
||||
"changelog": [
|
||||
{"version": "1.0.0", "date": "2025-12-10", "notes": "Initial core definition"}
|
||||
]
|
||||
}
|
||||
@@ -1,40 +0,0 @@
|
||||
# DSS Knowledge Base
|
||||
|
||||
This directory contains structured data schemas for AI agent knowledge about the Design System Server project.
|
||||
|
||||
## Files
|
||||
|
||||
### Core Architecture
|
||||
- **dss-architecture.json** - Three-tier enterprise architecture (Router, Messaging, Workflows)
|
||||
- Module specifications
|
||||
- Design patterns applied
|
||||
- Performance metrics
|
||||
|
||||
### Design Principles
|
||||
- **dss-principles.json** - Immutable core principles governing DSS
|
||||
- Monolithic structure definition
|
||||
- Translation dictionary patterns
|
||||
- Custom props strategy
|
||||
- Multi-system ingestion flow
|
||||
- UI library normalization rules
|
||||
|
||||
### MCP Tools
|
||||
- **mcp-tools.json** - MCP-first tool specifications
|
||||
- 6 Project Management Tools
|
||||
- 5 Context Compiler Tools
|
||||
- Tool inputs, outputs, and operations
|
||||
- Architecture benefits
|
||||
|
||||
## Usage
|
||||
|
||||
These JSON schemas are designed to be:
|
||||
1. **Machine-readable** - AI agents can parse and query efficiently
|
||||
2. **Version-controlled** - Track changes to project knowledge
|
||||
3. **Single source of truth** - Eliminate redundant documentation
|
||||
4. **Queryable** - Enable semantic search and analysis
|
||||
|
||||
## MCP Memory Graph
|
||||
|
||||
The knowledge in these files is also synchronized to the MCP memory graph for cross-session persistence and relationship mapping.
|
||||
|
||||
See the main [README.md](../README.md) for project overview and natural language documentation.
|
||||
@@ -1,58 +0,0 @@
|
||||
# ADR Template - Copy This File to Create New ADRs
|
||||
|
||||
Copy this file and rename to `NNN-short-title.md` where NNN is the next sequential number.
|
||||
|
||||
---
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: NNN
|
||||
title: Short, descriptive title of the decision
|
||||
date: YYYY-MM-DD
|
||||
author(s): Your Name
|
||||
status: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
|
||||
principles: [List relevant principles from PRINCIPLES.md]
|
||||
related:
|
||||
- doc: Link to related documentation
|
||||
- adr: Link to related ADRs
|
||||
- ticket: Link to related issue/ticket
|
||||
---
|
||||
```
|
||||
|
||||
## Context
|
||||
|
||||
Describe the issue or problem that motivated this decision. Include:
|
||||
- What is the problem?
|
||||
- Why does it matter?
|
||||
- What constraints or requirements are we working under?
|
||||
- What alternatives were considered and why were they rejected?
|
||||
|
||||
## Decision
|
||||
|
||||
State the decision clearly and concisely.
|
||||
- What did we decide to do?
|
||||
- Why this specific approach?
|
||||
|
||||
Include implementation details if relevant:
|
||||
```python
|
||||
# Example code or pseudocode here
|
||||
```
|
||||
|
||||
## Consequences
|
||||
|
||||
Describe the implications of this decision.
|
||||
|
||||
**Positive:**
|
||||
- List expected benefits
|
||||
- List advantages
|
||||
|
||||
**Negative:**
|
||||
- List trade-offs
|
||||
- List expected costs
|
||||
|
||||
## Related Principles
|
||||
|
||||
How does this decision support or reinforce the DSS Core Principles?
|
||||
- [Principle Name]: Explain connection
|
||||
- [Principle Name]: Explain connection
|
||||
|
||||
@@ -1,135 +0,0 @@
|
||||
---
|
||||
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
|
||||
@@ -1,140 +0,0 @@
|
||||
# ADR-006: Role-Based Access Control for Admin Principles
|
||||
|
||||
**Status**: Accepted
|
||||
**Date**: 2025-12-08
|
||||
**Deciders**: DSS Architecture Team (via Zen Swarm 3-Cycle Analysis)
|
||||
**Related**: ADMIN_PRINCIPLES.md v2.0.0, PRINCIPLES.md v2.2.0
|
||||
|
||||
## Context
|
||||
|
||||
The DSS Admin layer requires team-specific access control to enable role-based dashboards and one-click operations. Four distinct teams need different capabilities:
|
||||
|
||||
- **Admin Team**: System configuration, project creation, user/role management
|
||||
- **UI Team**: Figma sync, QuickWins analysis, regression tools
|
||||
- **UX Team**: Component/token/icon management, Figma plugin customization
|
||||
- **QA Team**: Component testing, ESRE, issue creation
|
||||
|
||||
The existing role system (`admin`, `designer`, `developer`, `viewer`) was generic and didn't align with team-specific workflows described in Admin Principle #6 (Role-Based Configuration & Visibility).
|
||||
|
||||
## Decision
|
||||
|
||||
We implemented a comprehensive RBAC layer with:
|
||||
|
||||
### 1. Team-Aligned Role System
|
||||
- Replaced generic roles with team-specific roles: `admin`, `ui_team`, `ux_team`, `qa_team`
|
||||
- Added `team_id` field to User model for multi-team organization support
|
||||
- Default role: `ui_team` (safest non-admin default)
|
||||
|
||||
### 2. Granular Permission Model
|
||||
Created `TeamPermissions` table with:
|
||||
- **Triple**: (role, resource, action) with unique constraint
|
||||
- **Actions**: CRUD (create, read, update, delete)
|
||||
- **Resources**: figma, components, tokens, icons, analysis, metrics, issues, testing
|
||||
- **Admin Bypass**: Admins have implicit all-permissions without database checks
|
||||
|
||||
### 3. Middleware Architecture
|
||||
- `authenticateToken`: JWT validation (existing)
|
||||
- `authorizeRole(allowedRoles)`: Simple role checking (existing, updated)
|
||||
- `requirePermission(resource, action)`: Granular permission checking (new)
|
||||
|
||||
### 4. Admin API Endpoints
|
||||
Four new endpoints in `/api/admin/roles/`:
|
||||
- `POST /assign`: Assign role to user (admin-only)
|
||||
- `GET /permissions/:role`: View role permissions (self or admin)
|
||||
- `PUT /permissions/:role`: Enable/disable permissions (admin-only)
|
||||
- `GET /users/:user_id/permissions`: View effective user permissions (self or admin)
|
||||
|
||||
### 5. Database Migration Strategy
|
||||
Used temporary column pattern to safely migrate PostgreSQL ENUMs:
|
||||
```
|
||||
Users.role (old enum) → Users.role_new (new enum) → drop old → rename new → set constraints
|
||||
```
|
||||
This avoids casting errors and allows atomic rollback.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative 1: Attribute-Based Access Control (ABAC)
|
||||
**Rejected**: Too complex for current needs. RBAC with granular permissions provides sufficient flexibility.
|
||||
|
||||
### Alternative 2: Single Admin Role with Feature Flags
|
||||
**Rejected**: Doesn't support team-specific audit trails or permission boundaries required by Admin Principle #3 (Accountability).
|
||||
|
||||
### Alternative 3: External Authorization Service (e.g., Ory Keto, Casbin)
|
||||
**Rejected**: Adds operational complexity and external dependency. In-database RBAC is sufficient for DSS scale.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- **Team Alignment**: Roles now match organizational structure
|
||||
- **Granular Control**: Permissions can be toggled per team without code changes
|
||||
- **Audit Trail**: TeamPermissions changes logged in database
|
||||
- **Migration Safety**: Temporary column pattern allows zero-downtime deployment
|
||||
- **Admin Lockout Prevention**: Admin bypass ensures system recoverability
|
||||
|
||||
### Negative
|
||||
- **Performance**: N+1 query on every `requirePermission` check (see Mitigation)
|
||||
- **Complexity**: Additional table and migration logic
|
||||
- **Language Mismatch**: Implemented in JavaScript instead of TypeScript (technical debt)
|
||||
|
||||
### Neutral
|
||||
- **Breaking Change**: Old roles mapped to new roles during migration (graceful upgrade path)
|
||||
|
||||
## Mitigation Strategies
|
||||
|
||||
### Critical: Redis Caching (Next Step)
|
||||
To address the N+1 performance issue, Track 1.5 will implement:
|
||||
- Redis cache for permissions: `rbac:permissions:{role}` (TTL: 1 hour)
|
||||
- Cache invalidation on permission updates
|
||||
- Fallback to database on cache miss
|
||||
|
||||
### Security Hardening
|
||||
- Remove hardcoded JWT secret fallback (`process.env.JWT_SECRET || 'your-secret-key'`)
|
||||
- Throw error on app startup if JWT_SECRET undefined
|
||||
|
||||
### TypeScript Migration (Future)
|
||||
- Convert models and middleware to TypeScript for type safety
|
||||
- Add `.d.ts` definitions for Sequelize models
|
||||
|
||||
## Implementation Details
|
||||
|
||||
**Files Modified:**
|
||||
- `server/src/models/User.js`: Added role enum and team_id field
|
||||
- `server/src/middleware/auth.js`: Added requirePermission middleware
|
||||
|
||||
**Files Created:**
|
||||
- `server/src/models/TeamPermissions.js`: Permission model
|
||||
- `server/src/routes/admin/roles.js`: Role management API
|
||||
- `server/migrations/20251208000000-add-rbac.js`: Database migration
|
||||
|
||||
**Default Permissions Seeded:**
|
||||
- **ui_team**: sync_figma, view_figma, quickwins, regression, view_metrics
|
||||
- **ux_team**: view/update components/tokens/icons, customize_figma_plugin, view_metrics
|
||||
- **qa_team**: test_components, create_issue, view_metrics, run_esre
|
||||
|
||||
## Validation
|
||||
|
||||
**Cycle 1 (ThinkDeep)**: Architecture validated with "almost_certain" confidence
|
||||
**Cycle 2 (Gemini 3 Pro)**: Code generation completed
|
||||
**Cycle 3 (Gemini 3 Pro Review)**: Security, architecture, performance, code quality validated
|
||||
|
||||
**Review Findings:**
|
||||
- ✅ Migration strategy: Excellent
|
||||
- ✅ Database design: Solid (unique constraints, transactions)
|
||||
- ✅ API design: RESTful, consistent response format
|
||||
- ⚠️ Performance: Redis caching required
|
||||
- ⚠️ Security: Remove hardcoded secret fallback
|
||||
- ⚠️ Architecture: TypeScript conversion recommended
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Track 1.5**: Implement Redis caching for permissions (immediate)
|
||||
2. **Track 2**: Configuration Schema (system/project/user tiers)
|
||||
3. **Track 3**: Component Registry (automatic discovery)
|
||||
4. **Track 4**: OAuth Integration (Figma/Atlassian)
|
||||
|
||||
## References
|
||||
|
||||
- [ADMIN_PRINCIPLES.md](../../docs/01_core/ADMIN_PRINCIPLES.md) - Principle #6
|
||||
- [API_CONTRACTS.md](../../docs/01_core/API_CONTRACTS.md) - Admin endpoints
|
||||
- [PRINCIPLES.md](../../docs/01_core/PRINCIPLES.md) - Core principle #5 (Operations as Tools)
|
||||
- Zen Swarm Analysis: ThinkDeep 3-step workflow (2025-12-08)
|
||||
@@ -1,278 +0,0 @@
|
||||
# ADR Knowledge Map
|
||||
|
||||
**Visual and textual guide to how DSS architecture connects principles → decisions → implementation**
|
||||
|
||||
Use this to understand the knowledge graph and trace decisions back to foundational principles.
|
||||
|
||||
---
|
||||
|
||||
## Knowledge Graph Structure
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ PRINCIPLES.md (Tier 1) │
|
||||
│ 7 governance principles that guide all architectural decisions │
|
||||
└────────────────────┬────────────────────────────────────────────┘
|
||||
│
|
||||
│ "Linked via ADR principles: field"
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ .knowledge/adrs/ (Architecture Decisions) │
|
||||
│ │
|
||||
│ ADR-001: Use Markdown ADRs for DSS Architecture Decisions │
|
||||
│ ├─ Principles: [Knowledge Persistence, SSoT] │
|
||||
│ ├─ Status: Accepted │
|
||||
│ └─ Implementation: This ADR system itself │
|
||||
│ │
|
||||
│ ADR-002+: [Future decisions captured here] │
|
||||
│ ├─ Each linked to 1-3 principles │
|
||||
│ ├─ Traces to specific PRs via PR template │
|
||||
│ └─ Becomes searchable knowledge graph │
|
||||
└────────┬────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ "Linked via PR template: Implements ADR-NNN"
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Pull Requests & Code Review │
|
||||
│ │
|
||||
│ PR #123: Implement caching strategy (ADR-002) │
|
||||
│ └─ "Implements ADR-002" │
|
||||
│ └─ "Supports [Single Source of Truth]" │
|
||||
│ │
|
||||
│ PR #124: Add API versioning (ADR-003) │
|
||||
│ └─ "Implements ADR-003" │
|
||||
│ └─ "Supports [Foundational Contracts]" │
|
||||
└────────┬────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ "Code implements the decision"
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Code & Implementation │
|
||||
│ │
|
||||
│ src/cache/sqlite.ts — Implements caching from ADR-002 │
|
||||
│ src/api/v2/... — Implements versioning from ADR-003 │
|
||||
│ server/routes/mcp.js — All MCP tools expose operations │
|
||||
│ │
|
||||
│ Everything traceable back to: Which principle? Which decision? │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How to Trace a Decision
|
||||
|
||||
**Starting from a principle:**
|
||||
1. Which ADRs link to this principle? (Search: `grep -r "principles:" .knowledge/adrs/`)
|
||||
2. Which PRs implement those ADRs? (Search PR descriptions for "Implements ADR-NNN")
|
||||
3. Which code files are changed in those PRs? (Check the PR diff)
|
||||
4. **Result**: You have the full chain from principle to code
|
||||
|
||||
**Example trace:**
|
||||
```
|
||||
Principle: "Single Source of Truth"
|
||||
↓
|
||||
ADR-002: "Use SQLite for local caching" (links to SSoT)
|
||||
↓
|
||||
PR #98: "Implement caching layer" (Implements ADR-002)
|
||||
↓
|
||||
Files: src/cache/sqlite.ts, src/cache/manager.ts, tests/cache.test.ts
|
||||
```
|
||||
|
||||
**Starting from code:**
|
||||
1. What PR changed this file? (Git log or GitHub blame)
|
||||
2. What ADR does the PR reference? (Check PR description)
|
||||
3. What principles motivated this ADR? (Check ADR frontmatter)
|
||||
4. **Result**: You understand the "why" behind the code
|
||||
|
||||
---
|
||||
|
||||
## Current State (Pilot Phase)
|
||||
|
||||
### Established ADRs
|
||||
|
||||
| ID | Title | Principles | Status | Implementation |
|
||||
|---|---|---|---|---|
|
||||
| 001 | Use Markdown ADRs for DSS Architecture Decisions | Knowledge Persistence, Single Source of Truth | Accepted | This system |
|
||||
|
||||
### In Progress / To Be Created
|
||||
|
||||
During the dss_sync_figma pilot (Weeks 2-4 of December 2025):
|
||||
|
||||
- **ADR-002**: Figma API authentication strategy (Phase 5A decision)
|
||||
- **ADR-003**: Caching strategy for Figma data
|
||||
- **ADR-004**: Async library choice for Python operations
|
||||
- **ADR-005+**: Additional dss_sync_figma decisions
|
||||
|
||||
Each will:
|
||||
- Be created by the pilot team as significant decisions are made
|
||||
- Link to 1-3 DSS principles
|
||||
- Be referenced in PRs via PR template
|
||||
- Become part of the queryable knowledge graph
|
||||
|
||||
---
|
||||
|
||||
## Querying the Knowledge Graph
|
||||
|
||||
### Find ADRs by Principle
|
||||
|
||||
```bash
|
||||
# Find all ADRs mentioning "Single Source of Truth"
|
||||
grep -r "Single Source of Truth" .knowledge/adrs/
|
||||
|
||||
# Find all ADRs related to MCP First
|
||||
grep -r "MCP First" .knowledge/adrs/
|
||||
|
||||
# Find all deprecated ADRs
|
||||
grep -r "status: Deprecated" .knowledge/adrs/
|
||||
```
|
||||
|
||||
### Find Code by ADR
|
||||
|
||||
```bash
|
||||
# Find PRs implementing ADR-002
|
||||
git log --all --grep="ADR-002" --oneline
|
||||
|
||||
# Find code files changed in ADR-002's PRs
|
||||
git log --all --grep="ADR-002" --name-only
|
||||
```
|
||||
|
||||
### Find Principles in Code
|
||||
|
||||
```bash
|
||||
# Find comments referencing a principle
|
||||
grep -r "Single Source of Truth" src/
|
||||
|
||||
# Find TODOs about principle compliance
|
||||
grep -r "TODO.*SSoT" .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example: Complete Trace
|
||||
|
||||
### Scenario: "Why do we cache Figma data this way?"
|
||||
|
||||
**Step 1: Find the ADR**
|
||||
```bash
|
||||
$ grep -r "cache" .knowledge/adrs/ --ignore-case
|
||||
.knowledge/adrs/ADR-002-figma-caching-strategy.md
|
||||
→ ADR-002 explains: Use in-memory cache with SQLite persistence
|
||||
```
|
||||
|
||||
**Step 2: Read the ADR**
|
||||
```markdown
|
||||
---
|
||||
id: 002
|
||||
title: Figma Data Caching Strategy
|
||||
principles: [Single Source of Truth, Knowledge Persistence]
|
||||
---
|
||||
|
||||
## Decision
|
||||
Cache Figma data in memory with periodic SQLite persistence.
|
||||
Prevents API rate limiting and supports offline mode.
|
||||
|
||||
## Consequences
|
||||
- Positive: Fast queries, resilience to API outages
|
||||
- Negative: Stale data window (up to 5 minutes between syncs)
|
||||
```
|
||||
|
||||
**Step 3: Find the implementation PR**
|
||||
```bash
|
||||
$ git log --all --grep="ADR-002"
|
||||
Commit: "Implement Figma caching (Implements ADR-002)"
|
||||
```
|
||||
|
||||
**Step 4: Find the code**
|
||||
```bash
|
||||
$ git show <commit> --name-only
|
||||
src/services/figma-cache.ts
|
||||
src/models/figma-cache.model.ts
|
||||
tests/figma-cache.test.ts
|
||||
```
|
||||
|
||||
**Step 5: Read the code**
|
||||
```typescript
|
||||
// src/services/figma-cache.ts
|
||||
// Implements: ADR-002 Figma Data Caching Strategy
|
||||
// Principles: Single Source of Truth (one cache per resource),
|
||||
// Knowledge Persistence (decisions captured in ADR-002)
|
||||
```
|
||||
|
||||
**Result**: You understand not just *how* (the code) but *why* (the principle), *what alternatives* were considered (the ADR), and *who made the decision* (the PR).
|
||||
|
||||
---
|
||||
|
||||
## Building Your Own Traces
|
||||
|
||||
### For Decision-Makers
|
||||
|
||||
When you face a decision:
|
||||
1. Check if a similar ADR already exists
|
||||
2. If yes: read it; understand the tradeoff; apply same pattern if appropriate
|
||||
3. If no: create a new ADR linking to relevant principles
|
||||
4. Record your decision while fresh, before implementation
|
||||
|
||||
### For Code Reviewers
|
||||
|
||||
When reviewing a PR:
|
||||
1. Check the PR template's "DSS Principles Check" section
|
||||
2. Verify the ADR referenced actually exists and is relevant
|
||||
3. Verify principle alignment claims are justified
|
||||
4. Ask: "Does this PR implement a decision that should have an ADR?"
|
||||
|
||||
### For New Team Members
|
||||
|
||||
To onboard:
|
||||
1. Read `/docs/01_core/PRINCIPLES.md` (the constitution)
|
||||
2. Read `.knowledge/adrs/001-use-markdown-adrs-for-dss-architecture-decisions.md` (explains the system)
|
||||
3. Grep the ADRs for decisions related to your area
|
||||
4. Follow traces from ADRs → PRs → code to understand the "why"
|
||||
|
||||
---
|
||||
|
||||
## Knowledge Graph Evolution
|
||||
|
||||
**Year 1 (Current)**:
|
||||
- Manual ADR creation and discovery
|
||||
- Grep-based queries
|
||||
- Cross-links in Markdown
|
||||
|
||||
**Year 2 (Planned)**:
|
||||
- Automated ADR discovery dashboard
|
||||
- Principle adoption metrics
|
||||
- Visual knowledge graph with node queries
|
||||
|
||||
**Year 3 (Vision)**:
|
||||
- ADRs generate code contracts (TypeScript types from architecture)
|
||||
- ADRs auto-validate code against recorded constraints
|
||||
- ML-based decision suggestions ("You've made similar decisions before")
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
- **Principles**: `/docs/01_core/PRINCIPLES.md`
|
||||
- **Core Reference**: `.knowledge/adrs/PRINCIPLES_CORE_REFERENCE.md`
|
||||
- **ADR Template**: `.knowledge/adrs/000-template.md`
|
||||
- **ADR Guide**: `.knowledge/adrs/README.md`
|
||||
- **Example ADR**: `.knowledge/adrs/001-use-markdown-adrs-for-dss-architecture-decisions.md`
|
||||
|
||||
---
|
||||
|
||||
## Quick Links for Pilot Phase
|
||||
|
||||
During dss_sync_figma pilot (Weeks 1-4):
|
||||
|
||||
- **Kickoff materials** (archived): `.knowledge/adrs/archived/operational/KICKOFF_AGENDA.md`
|
||||
- **PR template update** (archived): `.knowledge/adrs/archived/operational/PR_TEMPLATE_UPDATE.md`
|
||||
- **Facilitator guide** (archived): `.knowledge/adrs/archived/operational/FACILITATOR_GUIDE.md`
|
||||
- **Slack announcement** (archived): `.knowledge/adrs/archived/operational/SLACK_ANNOUNCEMENT_TEMPLATE.md`
|
||||
- **Execution checklist** (archived): `.knowledge/adrs/archived/operational/EXECUTION_CHECKLIST.md`
|
||||
|
||||
All archived files are still available for reference; they're just not in the main working directory.
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-08
|
||||
**Purpose**: Navigate the DSS knowledge graph
|
||||
**Audience**: All DSS team members, Zen chat context
|
||||
@@ -1,131 +0,0 @@
|
||||
# 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
|
||||
@@ -1,101 +0,0 @@
|
||||
# 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)
|
||||
@@ -1,276 +0,0 @@
|
||||
# DSS Principles Pilot - Execution Checklist
|
||||
|
||||
**Status**: All operational documents ready for customization and execution
|
||||
**Target Launch**: This week (by Friday 12/12/2025)
|
||||
**Pilot Project**: dss_sync_figma
|
||||
**Pilot Duration**: 4 weeks (Week 1-4 of December 2025)
|
||||
|
||||
---
|
||||
|
||||
## ✅ Phase 1: Preparation (You Are Here)
|
||||
|
||||
All foundational documents have been created and are ready for customization with your team-specific details.
|
||||
|
||||
### Documents in `.knowledge/adrs/`:
|
||||
|
||||
**Core Resources** (no customization needed):
|
||||
- [x] `000-template.md` - Reusable ADR template with YAML frontmatter
|
||||
- [x] `001-use-markdown-adrs-for-dss-architecture-decisions.md` - Meta-ADR explaining the decision to use ADRs
|
||||
- [x] `README.md` - Team guide on creating and using ADRs
|
||||
|
||||
**Operational Execution Documents** (customize with [PLACEHOLDERS]):
|
||||
- [x] `SLACK_ANNOUNCEMENT_TEMPLATE.md` - Two versions (short & long) ready to post
|
||||
- [x] `KICKOFF_AGENDA.md` - 30-minute meeting script with full talking points
|
||||
- [x] `FACILITATOR_GUIDE.md` - Detailed guide for running the kickoff meeting
|
||||
- [x] `PR_TEMPLATE_UPDATE.md` - How to add DSS Principles Check to your PR template
|
||||
|
||||
**This Checklist**:
|
||||
- [x] `EXECUTION_CHECKLIST.md` - You are here
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Customization (What You Do Next)
|
||||
|
||||
Before launching the pilot, customize these documents with your team-specific details:
|
||||
|
||||
### Step 1: Prepare Team Information
|
||||
- [ ] **Identify pilot team members**: Who are the 3 people on dss_sync_figma who'll be test partners?
|
||||
- Person 1: [NAME]
|
||||
- Person 2: [NAME]
|
||||
- Person 3: [NAME]
|
||||
|
||||
- [ ] **Schedule kickoff meeting**: Pick a time this week
|
||||
- **Day**: [DAY - e.g., Thursday]
|
||||
- **Date**: [DATE - e.g., Dec 12]
|
||||
- **Time**: [TIME - e.g., 2:00 PM] (30 minutes)
|
||||
- **Location**: [LOCATION - Zoom link or conference room]
|
||||
|
||||
### Step 2: Customize Slack Announcement
|
||||
- [ ] Open `SLACK_ANNOUNCEMENT_TEMPLATE.md`
|
||||
- [ ] Fill in all [PLACEHOLDERS]:
|
||||
- `[YOUR_TEAM_SLACK_CHANNEL]` - Where to post the message
|
||||
- `[PILOT_TEAM_MEMBER_1], [PILOT_TEAM_MEMBER_2], [PILOT_TEAM_MEMBER_3]` - Actual names
|
||||
- `[DAY], [DATE], [TIME]` - Your kickoff meeting details
|
||||
- [ ] **Post to Slack**: 24-48 hours before kickoff meeting
|
||||
- Suggested: Post on Tuesday 12/10 if kickoff is Thursday 12/12
|
||||
- Use short version (150 words) unless team prefers detailed context
|
||||
- [ ] Copy-paste the post-kickoff follow-up message somewhere safe for use after meeting
|
||||
|
||||
### Step 3: Customize Kickoff Agenda
|
||||
- [ ] Open `KICKOFF_AGENDA.md`
|
||||
- [ ] Fill in [PLACEHOLDERS]:
|
||||
- `[DATE]` - Kickoff date
|
||||
- `[TIME]` - Start and end time
|
||||
- `[LOCATION]` - Zoom link or room number
|
||||
- `[PILOT TEAM NAMES]` - Your 3 pilot team members
|
||||
- `[FACILITATOR NAME]` - Person running the meeting
|
||||
- [ ] Print this or keep it open on a separate screen during the meeting (it's your reference)
|
||||
|
||||
### Step 4: Prepare Facilitator Guide
|
||||
- [ ] Open `FACILITATOR_GUIDE.md`
|
||||
- [ ] Fill in [PLACEHOLDERS]:
|
||||
- `[YOUR NAME]` - Your name as facilitator
|
||||
- `[TEAM MEMBERS]` - Names of pilot team
|
||||
- `[DATE & TIME]` - Meeting details
|
||||
- `[TEAM MEMBERS]` - (again in places)
|
||||
- [ ] **Read through the entire guide** (2,500+ lines)
|
||||
- Special focus on:
|
||||
- Pre-Meeting Checklist (line 11-25) — Complete all items before meeting
|
||||
- Section 3: The "First Pancake" (line 145-179) — This is the meeting centerpiece
|
||||
- Common Concerns table (line 218-227) — Prepare your responses
|
||||
- [ ] Set up screen share tools and test them (if running meeting remotely)
|
||||
- [ ] Have `.knowledge/adrs/` directory open and ready to screen share
|
||||
|
||||
### Step 5: Update PR Template
|
||||
- [ ] Open `PR_TEMPLATE_UPDATE.md`
|
||||
- [ ] Locate your project's PR template (likely `.github/pull_request_template.md`)
|
||||
- [ ] Copy the "DSS Principles Check" section from PR_TEMPLATE_UPDATE.md
|
||||
- [ ] Add it to your PR template **before the Checklist section**
|
||||
- [ ] Commit the change to git
|
||||
- [ ] Verify it appears on a test PR draft (optional, but recommended)
|
||||
|
||||
### Step 6: Pre-Meeting Checklist (Run Day-of or Day-Before)
|
||||
|
||||
From `FACILITATOR_GUIDE.md` lines 11-25:
|
||||
|
||||
- [ ] Review `KICKOFF_AGENDA.md` (this is your script)
|
||||
- [ ] Have `.knowledge/adrs/` open and ready to screen share
|
||||
- [ ] Open three key files in editor tabs:
|
||||
- `000-template.md` (the template)
|
||||
- `001-use-markdown-adrs-for-dss-architecture-decisions.md` (the meta-ADR)
|
||||
- Your project's updated PR template
|
||||
- [ ] Have 2-3 example decisions in mind from dss_sync_figma (for "First Pancake" fallback):
|
||||
- Example 1: [DECISION - e.g., "How will you handle Figma API token storage?"]
|
||||
- Example 2: [DECISION - e.g., "What's your caching strategy for Figma data?"]
|
||||
- Example 3: [DECISION - e.g., "Which async library will you use in Python?"]
|
||||
- [ ] Test your screen share setup (Zoom, Teams, or in-person projector)
|
||||
- [ ] Print or open the agenda for reference
|
||||
- [ ] Set a 30-minute timer (hard stop—don't let this run over)
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Execution (Week 1 of Pilot)
|
||||
|
||||
### Day 1-2: Announcement
|
||||
- [ ] Post customized Slack announcement to team channel
|
||||
- Tag the pilot team members to notify them
|
||||
- Include link to `.knowledge/adrs/README.md`
|
||||
|
||||
### Day 2-3: Pre-Meeting Prep
|
||||
- [ ] Send meeting invite to pilot team with:
|
||||
- Date/time/location
|
||||
- Zoom link (if remote)
|
||||
- Calendar note: "30-minute kickoff for ADR pilot — we'll write your first ADR together"
|
||||
- [ ] Complete "Pre-Meeting Checklist" (above)
|
||||
- [ ] Mentally prepare your talking points
|
||||
|
||||
### Day 3-4: Kickoff Meeting
|
||||
- [ ] Run the 30-minute kickoff meeting using `KICKOFF_AGENDA.md` + `FACILITATOR_GUIDE.md`
|
||||
- Section 1: The "Why" (5 min)
|
||||
- Section 2: The "How" (10 min) — Live demo
|
||||
- Section 3: The "First Pancake" (10 min) — Write ADR together
|
||||
- Section 4: The "Ask" & Next Steps (5 min)
|
||||
- [ ] Capture the "First Pancake" ADR (save as `002-[title].md` if consensus reached)
|
||||
- [ ] Note any concerns or questions raised
|
||||
|
||||
### Day 4-5: Post-Meeting Followup
|
||||
- [ ] Send post-meeting Slack message (template in `SLACK_ANNOUNCEMENT_TEMPLATE.md`, lines 98-114)
|
||||
- Recap what you covered
|
||||
- Remind about next steps (create 1-3 ADRs)
|
||||
- Offer to answer questions
|
||||
- [ ] Create calendar invites for:
|
||||
- Week 2-3 check-ins (informal, async or 15-min sync)
|
||||
- Week 4 retrospective (30 minutes)
|
||||
- [ ] Add pilot team to optional Slack thread or workspace for async updates
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Piloting (Weeks 2-4)
|
||||
|
||||
### Weeks 2-3: ADR Creation
|
||||
- [ ] Pilot team creates 1-3 ADRs for significant dss_sync_figma decisions
|
||||
- They use `000-template.md` as reference
|
||||
- They link ADRs in PRs using updated PR template
|
||||
- [ ] **Facilitator check-in** (informal):
|
||||
- Week 2: Brief message asking "How's it going? Any friction?"
|
||||
- Week 3: Follow-up if there were concerns
|
||||
|
||||
### Week 4: Retrospective
|
||||
- [ ] Schedule 30-minute retrospective with pilot team
|
||||
- [ ] Use retrospective questions:
|
||||
- ✅ What worked? Did ADRs help capture decisions?
|
||||
- ❌ What didn't work? Did it feel burdensome?
|
||||
- 🔄 What should change before we roll this out broader?
|
||||
- 💡 Would you recommend this for other teams?
|
||||
- [ ] Document feedback
|
||||
- [ ] Decide: Refine, expand, or pause the ADR approach?
|
||||
|
||||
---
|
||||
|
||||
## Critical Success Factors
|
||||
|
||||
### For the Kickoff Meeting:
|
||||
- ✅ **Live demo**: Don't just talk about templates; show them on screen
|
||||
- ✅ **"First Pancake" exercise**: Write an ADR together in real-time (10 min)
|
||||
- ✅ **Keep it brief**: Template is tiny; process is lightweight; avoid over-explaining
|
||||
- ✅ **Honest tone**: "We're experimenting together"—not "here's the new mandate"
|
||||
- ✅ **Respect their time**: 30 minutes, period. Don't run over
|
||||
|
||||
### For Adoption:
|
||||
- ✅ **Lightness**: ADRs should take 15 minutes max
|
||||
- ✅ **Clarity**: Only significant decisions (not every PR)
|
||||
- ✅ **Autonomy**: "Create 1-3 ADRs" is invitation, not requirement
|
||||
- ✅ **Feedback culture**: Gather honest feedback; be willing to adjust
|
||||
|
||||
---
|
||||
|
||||
## Contingencies
|
||||
|
||||
### If Team is Skeptical During Meeting:
|
||||
- Reference the Common Concerns table in `FACILITATOR_GUIDE.md` (lines 218-227)
|
||||
- Use concrete examples from dss_sync_figma
|
||||
- Emphasize: "We're testing this. Your honest feedback is what makes it work."
|
||||
|
||||
### If Time Runs Short:
|
||||
From `FACILITATOR_GUIDE.md` (lines 240-246):
|
||||
|
||||
Priorities (in order):
|
||||
1. **Never skip the "First Pancake"** (Section 3) — This is the proof point
|
||||
2. Cut "Show the meta-ADR" if needed — Just say "look at 001 in the repo"
|
||||
3. Keep "Why" concise — Move to the demo
|
||||
4. **End on time** — Respect their calendar
|
||||
|
||||
### If Pilot Team Doesn't Create ADRs:
|
||||
- This is valid feedback: the process might be too heavy or not solving a real problem
|
||||
- Don't force it; capture the feedback in retrospective
|
||||
- Use Week 4 retro to understand why and adjust
|
||||
|
||||
---
|
||||
|
||||
## File Location Quick Reference
|
||||
|
||||
All ADR-related files are in: **`.knowledge/adrs/`**
|
||||
|
||||
| File | Purpose | Who Reads? |
|
||||
|------|---------|-----------|
|
||||
| `000-template.md` | ADR template to copy | Pilot team (when creating ADRs) |
|
||||
| `001-use-markdown-adrs-for-dss-architecture-decisions.md` | Meta-ADR explaining why we use ADRs | Pilot team (during kickoff) |
|
||||
| `README.md` | Guide on creating & using ADRs | Anyone creating ADRs |
|
||||
| `SLACK_ANNOUNCEMENT_TEMPLATE.md` | Message to post to team | You (customize & post) |
|
||||
| `KICKOFF_AGENDA.md` | Meeting agenda + talking points | You + Facilitator (reference during meeting) |
|
||||
| `FACILITATOR_GUIDE.md` | Detailed facilitator script | Facilitator (read fully before meeting) |
|
||||
| `PR_TEMPLATE_UPDATE.md` | How to integrate ADRs into PRs | You (customize your PR template) |
|
||||
| `EXECUTION_CHECKLIST.md` | This document | You (reference as you prep) |
|
||||
|
||||
---
|
||||
|
||||
## Sign-Off Checklist
|
||||
|
||||
Before claiming you're ready to launch:
|
||||
|
||||
- [ ] All pilot team members identified and briefed
|
||||
- [ ] Kickoff meeting scheduled
|
||||
- [ ] Slack announcement customized and saved (ready to post)
|
||||
- [ ] Kickoff agenda & facilitator guide reviewed and customized
|
||||
- [ ] PR template updated and committed to git
|
||||
- [ ] Pre-meeting checklist items planned (screen share, tabs, timer, etc.)
|
||||
- [ ] Example dss_sync_figma decisions identified for "First Pancake" fallback
|
||||
- [ ] Calendar invites created for retrospective (Week 4)
|
||||
|
||||
---
|
||||
|
||||
## What Happens Next (After Pilot)
|
||||
|
||||
**Month 1 Outcome** (Week 4 Retrospective):
|
||||
- You'll have real feedback on whether ADRs are valuable
|
||||
- You'll understand what needs to change for broader adoption
|
||||
- You'll decide: refine, expand, or pivot
|
||||
|
||||
**Month 2-3** (If retrospective is positive):
|
||||
- Share learnings with broader team (tech talk with pilot team as speakers)
|
||||
- Encourage other teams to try ADRs
|
||||
- Build simple tooling (e.g., grep queries, dashboard)
|
||||
|
||||
**Year 2+**:
|
||||
- Automated ADR discovery and queries
|
||||
- Dashboards showing principle adoption
|
||||
- MCP tools that suggest decisions based on code changes
|
||||
|
||||
---
|
||||
|
||||
## Questions or Issues?
|
||||
|
||||
Refer to the relevant document:
|
||||
- **How do I run the meeting?** → `FACILITATOR_GUIDE.md`
|
||||
- **What should I tell the team?** → `SLACK_ANNOUNCEMENT_TEMPLATE.md`
|
||||
- **What's the ADR format?** → `000-template.md` or `README.md`
|
||||
- **How do I integrate with PRs?** → `PR_TEMPLATE_UPDATE.md`
|
||||
- **Why are we doing this?** → `001-use-markdown-adrs-for-dss-architecture-decisions.md`
|
||||
|
||||
---
|
||||
|
||||
**Document Status**: Ready for execution
|
||||
**Created**: 2025-12-08
|
||||
**Pilot Team**: dss_sync_figma (identified by you)
|
||||
**Target Launch**: This week
|
||||
**Next Milestone**: Kickoff meeting (30 min)
|
||||
@@ -1,262 +0,0 @@
|
||||
# Facilitator's Guide: ADR Kickoff Meeting
|
||||
|
||||
**For**: [YOUR NAME]
|
||||
**Meeting**: DSS Principles Pilot Kickoff
|
||||
**Pilot Team**: [TEAM MEMBERS]
|
||||
**Date & Time**: [DATE & TIME]
|
||||
**Duration**: 30 minutes (strictly; this is important)
|
||||
|
||||
---
|
||||
|
||||
## Pre-Meeting Checklist (Do This Before the Meeting)
|
||||
|
||||
- [ ] Review KICKOFF_AGENDA.md (this is your script)
|
||||
- [ ] Have `.knowledge/adrs/` open and ready to screen share
|
||||
- [ ] Open the three key files in tabs:
|
||||
- `000-template.md` (the template)
|
||||
- `001-use-markdown-adrs-for-dss-architecture-decisions.md` (the meta-ADR)
|
||||
- [Your project's current PR template, if you have one—or show the example below]
|
||||
- [ ] Have a decision from `dss_sync_figma` in mind that you can use as the "First Pancake" example if the team struggles to identify one
|
||||
- Example 1: "How will you handle Figma API token storage locally vs. securely?"
|
||||
- Example 2: "What's your strategy for caching Figma data between syncs?"
|
||||
- Example 3: "Which async library will you use in Python?"
|
||||
- [ ] Test your screen share setup (Zoom, Teams, or in-person projector)
|
||||
- [ ] Print or open the agenda for reference
|
||||
- [ ] Set a 30-minute timer (hard stop; don't let this run over)
|
||||
|
||||
---
|
||||
|
||||
## During the Meeting
|
||||
|
||||
### Arrival & Opening (1 minute)
|
||||
|
||||
**What You Say**:
|
||||
> "Thanks everyone for taking the time. We've got 30 minutes, and I want to make sure we use it well. Quick housekeeping: [mention if there will be recording, etc.]. Let's dig in."
|
||||
|
||||
**What You're Doing**: Set a professional but relaxed tone. This is not a lecture.
|
||||
|
||||
---
|
||||
|
||||
### Section 1: The "Why" (5 minutes)
|
||||
|
||||
**Talking Points** (choose what feels natural; don't read verbatim):
|
||||
|
||||
1. **Acknowledge them**: "Thanks for being our partners in this pilot. We chose you because you're building something complex with real decisions to make. Your feedback is what makes this work."
|
||||
|
||||
2. **Share a relatable pain point**: Pick one from below (or use your own):
|
||||
- "Remember when we debated [specific past decision]? The reasoning lived in Slack, and now nobody remembers why we chose that way."
|
||||
- "We've all stared at six-month-old code and thought, 'Why did we do it this way?' Git shows you what changed, but not why."
|
||||
- "New team members join and ask, 'Why are we using this library instead of that one?' and the answer is just... lost."
|
||||
|
||||
3. **State the hypothesis clearly**:
|
||||
> "Our hypothesis is that capturing these decisions in a lightweight, in-repo format will help us move faster, reduce ambiguity, and actually live our principles instead of just talking about them."
|
||||
|
||||
4. **Set the tone**:
|
||||
> "Success here isn't that you love everything about it. Success is getting your honest feedback: Is this helpful, or is it just noise?"
|
||||
|
||||
**Timing**: Aim for exactly 5 minutes. Don't dwell here; move to the demo.
|
||||
|
||||
**If They Ask** during this section:
|
||||
- *"Does this mean we have to do this for every decision?"* → "No, we'll clarify scope in a second. Just the big ones."
|
||||
- *"Is this mandatory?"* → "Right now it's a pilot. We're testing it. Your feedback will tell us if it becomes mandatory."
|
||||
|
||||
---
|
||||
|
||||
### Section 2: The "How" (10 minutes)
|
||||
|
||||
**IMPORTANT**: This is a live demo. Showing is infinitely more powerful than telling. Do the screen share.
|
||||
|
||||
**Timing Breakdown**:
|
||||
- Show the directory: 1 min
|
||||
- Show the template: 2 min
|
||||
- Show the meta-ADR: 3 min
|
||||
- Show PR integration: 2 min
|
||||
- Clarify scope: 2 min
|
||||
|
||||
**What to do**:
|
||||
|
||||
**1. Show the directory (1 min)**
|
||||
```bash
|
||||
Navigate to .knowledge/adrs/ and show the file listing
|
||||
```
|
||||
**What you say**:
|
||||
> "All ADRs live right here, in the same repo as the code. They're version-controlled, reviewed in PRs, and easy to search."
|
||||
|
||||
**2. Show the template (2 min)**
|
||||
|
||||
Open `.knowledge/adrs/000-template.md`
|
||||
|
||||
**What you say**:
|
||||
> "Here's the entire template. Just Markdown with a little metadata at the top. The goal is conciseness, not a novel. You'll spend maybe 15 minutes writing one of these."
|
||||
|
||||
Point out:
|
||||
- **ID & Title**: "Sequential number so we can reference it. 'ADR-003' in a comment means everyone knows what we're talking about."
|
||||
- **Status**: "This field keeps our decisions current. Starts as 'Proposed,' becomes 'Accepted' when there's consensus, and can be marked 'Deprecated' if we change direction. This matters because old decisions stay in the repo but don't confuse people."
|
||||
- **Principles**: "We link back to PRINCIPLES.md. Makes sure we're actually living our principles, not just talking about them."
|
||||
- **Related**: "Links to docs, other ADRs, PRs. This is how we start building a knowledge graph over time."
|
||||
|
||||
**Don't dwell**: You're not explaining every field. The template speaks for itself. Move on.
|
||||
|
||||
**3. Show the meta-ADR (3 min)**
|
||||
|
||||
Open `.knowledge/adrs/001-use-markdown-adrs-for-dss-architecture-decisions.md`
|
||||
|
||||
**What you say**:
|
||||
> "This is the ADR we wrote about the decision to use ADRs. See? It's the same format. We're dogfooding this to make sure it actually works."
|
||||
|
||||
Scroll through it. Point out:
|
||||
- **Context**: "We needed a way to capture decision rationale that didn't require external tools or setup."
|
||||
- **Decision**: "Use Markdown files with YAML frontmatter. No database, no special tooling. Just text files."
|
||||
- **Consequences**: "Look—even our own decision has trade-offs. Positive: it's lightweight and git-friendly. Negative: someone has to remember to create them. We're aware of that."
|
||||
- **Status**: "This one is 'Accepted.' It's in effect now."
|
||||
|
||||
**Why show this?** It proves you believe in the process. You're using it too.
|
||||
|
||||
**4. Show PR integration (2 min)**
|
||||
|
||||
Show the updated PR template (see below). Specifically, highlight the "DSS Principles Check" section:
|
||||
|
||||
```markdown
|
||||
### DSS Principles Check
|
||||
|
||||
- **ADR Link**: If this PR implements a decision, link it here. (e.g., `Implements ADR-003`)
|
||||
- **Principle Alignment**: Which principles does this support? Explain briefly.
|
||||
```
|
||||
|
||||
**What you say**:
|
||||
> "When you open a PR that implements an ADR, you'll add a couple of lines here. That's the connection between the decision and the code. It's not overhead; it's part of how you already work."
|
||||
|
||||
**5. Clarify scope (2 min)**
|
||||
|
||||
**What you say**:
|
||||
> "Now, let's be clear: not every technical decision needs an ADR. Use this for decisions that:
|
||||
> - Impact multiple parts of the system
|
||||
> - Have interesting trade-offs or alternatives
|
||||
> - Will be referenced in future decisions
|
||||
> - Need their rationale captured for people who come after you
|
||||
>
|
||||
> Bug fixes, naming choices, small refactors—use code comments instead. ADRs are for the big stuff."
|
||||
|
||||
**If they ask**:
|
||||
- *"How do I know if something is 'big stuff'?"* → "Good question. In the retro, we can clarify this together. For now, ask yourself: Will someone in 6 months ask, 'Why did we do it that way?' If yes, it's worth an ADR."
|
||||
|
||||
---
|
||||
|
||||
### Section 3: The "First Pancake" (10 minutes)
|
||||
|
||||
**This is the core of the meeting. It turns theory into practice and builds confidence.**
|
||||
|
||||
**Setup**:
|
||||
> "Let's do this right now. We'll write an ADR for `dss_sync_figma` together. What's a significant decision you've just made or are in the middle of deciding? Examples might be: How will you handle Figma tokens locally? What's your caching strategy? Which async library will you use?"
|
||||
|
||||
**Listen**. Let them pick a decision. If they hesitate, offer your pre-prepared example(s).
|
||||
|
||||
**Once they've chosen**:
|
||||
|
||||
1. **You share your screen** (tech lead can do this if they prefer, but you control the typing)
|
||||
2. **Copy the template**:
|
||||
- Open the template file
|
||||
- Duplicate it with a name: `002-[short-title].md`
|
||||
- Show that you're doing this in real-time in the editor or file manager
|
||||
|
||||
3. **Fill it out together**:
|
||||
- You type. They talk. They're the expert; you're the scribe.
|
||||
- **YAML frontmatter**: Fill in ID, title, date, author(s), status ("Proposed" or "Accepted"), principles
|
||||
- **Context**: "What's the problem we're solving? What constraints are we working under?"
|
||||
- **Decision**: "What did we decide to do and why?"
|
||||
- **Consequences**: "What are the positive and negative implications?"
|
||||
- **Don't aim for perfection**: The goal is speed and proof of concept. 10 minutes is fine.
|
||||
|
||||
4. **Save the file**:
|
||||
- Commit to git (or just show it saved in the editor if you're not in a git client)
|
||||
- "That's it. One file, one PR link in a few weeks, and we've captured the rationale."
|
||||
|
||||
**Why this works**: It's real. It's fast. It's not scary. It proves the process doesn't require specialists or heavy tooling.
|
||||
|
||||
**If they get stuck**: Help them along. "What was the main constraint?" "What would you have done differently if you didn't have that constraint?" → These questions unlock the thinking.
|
||||
|
||||
**Timing**: Aim for 8-9 minutes, leaving 1-2 min buffer. If you're running long, skip perfection; just show "you get the idea."
|
||||
|
||||
---
|
||||
|
||||
### Section 4: The "Ask" & Next Steps (5 minutes)
|
||||
|
||||
**What you say**:
|
||||
> "That's the core loop. When you face a big decision: Spend 15 minutes capturing the 'why' and you're done. Over the next 3-4 weeks, we're asking you to create 1-3 more ADRs like that for `dss_sync_figma`."
|
||||
|
||||
**The Ask**:
|
||||
- Create 1-3 ADRs over the next month for significant decisions
|
||||
- Link them in PRs using the PR template
|
||||
- Give honest feedback in the retrospective
|
||||
|
||||
**The Support**:
|
||||
- "I'll check in informally. If you feel friction, tell me. We want to learn from that."
|
||||
- "Questions right now? Ask them. You're not alone in this."
|
||||
|
||||
**The Follow-up**:
|
||||
- "In about 4 weeks, we'll do a 30-minute retrospective to get all your feedback."
|
||||
- "At that point, we decide: Is this valuable? Do we refine it? Do we expand it to other teams?"
|
||||
|
||||
**Open the floor**:
|
||||
> "Any immediate questions or concerns?"
|
||||
|
||||
**Listen. Don't interrupt. Address concerns directly.**
|
||||
|
||||
If there are no questions, that's fine too. Say:
|
||||
> "Great. Let's start, and I'll reach out in a week to see how it's going. Thanks for being our test pilots on this."
|
||||
|
||||
---
|
||||
|
||||
## Post-Meeting (5 minutes after meeting ends)
|
||||
|
||||
- [ ] Send the follow-up Slack message (template provided)
|
||||
- [ ] Create a calendar invite for the retrospective (Week 4)
|
||||
- [ ] Add the pilot team to an (optional) Slack thread or thread for async updates
|
||||
|
||||
---
|
||||
|
||||
## Common Concerns & How to Respond
|
||||
|
||||
| Concern | Your Response |
|
||||
|---------|--|
|
||||
| "This feels like extra bureaucracy." | "I get that. That's why we're testing it. If it feels like overhead with no benefit, we'll adjust. This isn't a mandate; it's an experiment." |
|
||||
| "Do we have to do this for everything?" | "No. Just the significant decisions. We'll refine the criteria together based on your feedback." |
|
||||
| "What if we don't want to do this?" | "Then we learn that this process doesn't work for your team. Honest feedback is valuable. The goal isn't to force a process; it's to find what helps." |
|
||||
| "Can't we just use Confluence / Notion / etc.?" | "Maybe! But those require setup, are outside the repo, and are harder to keep in sync with code. We wanted something version-controlled and friction-free to start. If Markdown ADRs don't work, we can revisit." |
|
||||
| "This sounds good, but will it actually get used?" | "That's what we're testing. You're going to tell us. That's why we picked you." |
|
||||
|
||||
---
|
||||
|
||||
## Success Looks Like
|
||||
|
||||
✅ Team feels confident they can create an ADR
|
||||
✅ Team leaves with a concrete example (the one you wrote together)
|
||||
✅ At least one person says, "Oh, I see why this matters"
|
||||
✅ No one is dreading the next 4 weeks
|
||||
✅ You got honest feedback or concerns (even better—now you know what to address)
|
||||
|
||||
---
|
||||
|
||||
## If the Meeting Runs Long
|
||||
|
||||
Priorities (in order):
|
||||
1. Never skip the "First Pancake" (Section 3)
|
||||
2. Cut "Show the meta-ADR" if needed (just say "look at 001 in the repo")
|
||||
3. Keep "Why" concise; move to the demo
|
||||
4. End on time; respect their calendar
|
||||
|
||||
---
|
||||
|
||||
## Notes for You
|
||||
|
||||
- **Be confident but humble**: You're not mandating. You're inviting feedback.
|
||||
- **Listen more than talk**: Their skepticism is a gift. Lean into it.
|
||||
- **Use real examples**: Abstract explanations don't stick. Concrete examples do.
|
||||
- **Show, don't tell**: The demo and the live write are the proof points.
|
||||
- **Acknowledge uncertainty**: "I don't know" is better than "trust me." Say "We'll figure it out together."
|
||||
|
||||
---
|
||||
|
||||
**You've got this. You're not asking them to change their world; you're asking them to spend 15 minutes capturing decisions they're already making. That's a small ask with real upside.**
|
||||
|
||||
Good luck! 🚀
|
||||
@@ -1,180 +0,0 @@
|
||||
# DSS Principles Pilot - Kickoff Meeting Agenda
|
||||
|
||||
**Date**: [DATE - THIS WEEK, e.g., Thursday Dec 12]
|
||||
**Time**: [TIME - 30 minutes, e.g., 2:00 PM - 2:30 PM]
|
||||
**Location**: [LOCATION - Zoom link or conference room]
|
||||
**Attendees**: [PILOT TEAM NAMES], [FACILITATOR NAME]
|
||||
|
||||
---
|
||||
|
||||
## Meeting Objective
|
||||
|
||||
Align the pilot team on the lightweight ADR (Architecture Decision Record) process, demonstrate its simplicity, and collaboratively write your first ADR to build confidence and momentum.
|
||||
|
||||
**This is NOT**: A mandate. A heavy process. Bureaucracy.
|
||||
**This IS**: An experiment to help us capture "why" decisions are made. Your honest feedback on whether it's valuable is the goal.
|
||||
|
||||
---
|
||||
|
||||
## Agenda (30 minutes)
|
||||
|
||||
### 1. The "Why" (5 minutes)
|
||||
|
||||
**Goal**: Frame the experiment and acknowledge their role as partners.
|
||||
|
||||
**Key Points**:
|
||||
- "Thanks for being our partners in this pilot. Your feedback is what makes this work."
|
||||
- **The Problem**: We've all asked, "Why did we do it this way?" Git history tells you *what* changed, but not *why*.
|
||||
- **The Hypothesis**: A lightweight, in-repo method for capturing decision rationale will help us move faster, reduce ambiguity, and make our principles real (not just a document).
|
||||
- **Success Criteria**: Not that you love everything about it—success is getting your honest, critical feedback. Is this helpful or just noise?
|
||||
|
||||
**Talking Points**:
|
||||
- Reference a recent past decision from the team: "Remember when we debated [example decision]? That rationale lived in Slack and now it's lost. We want to capture that."
|
||||
- Emphasize the lightness: "This is not a heavyweight process. It's 15 minutes to document a decision. That's it."
|
||||
|
||||
---
|
||||
|
||||
### 2. The "How" (10 minutes)
|
||||
|
||||
**Goal**: Demonstrate the tools are simple and unintimidating.
|
||||
|
||||
**Activity**: Live screen share. Show, don't just tell.
|
||||
|
||||
1. **Show the directory** (1 min)
|
||||
- Navigate to `.knowledge/adrs/`
|
||||
- "Everything lives right here, next to the code it relates to."
|
||||
|
||||
2. **Show the template** (2 min)
|
||||
- Open `000-template.md`
|
||||
- "This is the entire template. It's just Markdown with metadata at the top."
|
||||
- Briefly explain:
|
||||
- `status`: Keeps decisions current (Proposed → Accepted → Deprecated or Superseded)
|
||||
- `principles`: Connects the decision back to our core principles (strengthens adoption)
|
||||
- `related`: Links to docs, other ADRs, and PRs (builds the knowledge graph)
|
||||
|
||||
3. **Show the meta-ADR** (3 min)
|
||||
- Open `001-use-markdown-adrs-for-dss-architecture-decisions.md`
|
||||
- "We're dogfooding this. Here's the ADR we wrote for the decision to use ADRs. As you can see, it's short and to the point."
|
||||
- Highlight the sections: Context, Decision, Consequences
|
||||
|
||||
4. **Show the PR integration** (2 min)
|
||||
- "When you implement a decision, your PR will have a new section asking you to link the ADR. One line. That's it."
|
||||
- Show the updated PR template (section below)
|
||||
- "This connects the decision to the code."
|
||||
- Emphasize: "The process is not in the way; it's integrated into how you already work."
|
||||
|
||||
5. **Clarify scope** (2 min)
|
||||
- "Not every technical decision needs an ADR. Use this for significant decisions:"
|
||||
- Impact multiple components
|
||||
- Have trade-offs or alternatives
|
||||
- Will be referenced in future decisions
|
||||
- Need rationale captured for future developers
|
||||
- "Bug fixes, naming decisions, small refactors—those don't need ADRs. Use code comments instead."
|
||||
|
||||
---
|
||||
|
||||
### 3. The "First Pancake" (10 minutes)
|
||||
|
||||
**Goal**: Write an ADR together to prove the process is lightweight and approachable.
|
||||
|
||||
This is the most critical part of the meeting. It transforms understanding into confidence.
|
||||
|
||||
**Setup**:
|
||||
- "Let's do this right now. What's a foundational decision you're making on `dss_sync_figma` right now or have just settled on?"
|
||||
- Prompt examples if needed:
|
||||
- "How will you handle Figma API authentication? Store tokens locally or remotely?"
|
||||
- "What's your caching strategy for Figma data between runs?"
|
||||
- "What's the architecture for syncing Figma changes back to the project?"
|
||||
- "Which Python library will you use for async operations?"
|
||||
|
||||
**Execution**:
|
||||
1. Someone shares their screen (you or the tech lead)
|
||||
2. Copy `000-template.md` to `002-[decision-title].md` (show this in real-time)
|
||||
3. Fill it out collaboratively:
|
||||
- You type, pilot team provides the content
|
||||
- Aim for ~10 minutes total
|
||||
- **Don't aim for perfection**—the goal is to prove it's not intimidating
|
||||
- Get to "Accepted" status if there's consensus; otherwise "Proposed" is fine
|
||||
4. Save and show: "That's it. One file, 10 minutes, decision captured."
|
||||
|
||||
**During this exercise, demonstrate**:
|
||||
- YAML is easy (just copy the block, change the values)
|
||||
- Markdown is familiar (everyone writes it)
|
||||
- "Consequences" are often the most valuable part (forces you to think through trade-offs)
|
||||
|
||||
---
|
||||
|
||||
### 4. The "Ask" & Next Steps (5 minutes)
|
||||
|
||||
**Goal**: Set clear expectations for the pilot period and establish check-in cadence.
|
||||
|
||||
**Key Points**:
|
||||
|
||||
1. **The Ask**:
|
||||
- "Over the next 3-4 weeks, create 1-3 more ADRs for the most significant decisions on `dss_sync_figma`."
|
||||
- "A good rule of thumb: If a decision has long-term consequences, isn't easily reversible, or had interesting trade-offs, it's a good candidate."
|
||||
- "Link them from your PRs using the PR template: 'Implements ADR-NNN'"
|
||||
|
||||
2. **The Support**:
|
||||
- "I'll check in informally to see how it's going. If you feel any friction, let me know immediately. We want to learn from that."
|
||||
- "Ask questions. You're not alone in this—we're figuring it out together."
|
||||
|
||||
3. **The Follow-up**:
|
||||
- "We'll schedule a 30-minute retrospective in about 4 weeks to get all your feedback."
|
||||
- "At that point, we decide: Is this valuable? Do we refine it? Do we expand it to other teams?"
|
||||
|
||||
4. **Open the floor**:
|
||||
- "Any immediate questions, concerns, or thoughts?"
|
||||
- Listen. Address concerns directly. Be honest if you don't know something.
|
||||
|
||||
---
|
||||
|
||||
## Success Signals (What You're Looking For)
|
||||
|
||||
- ✅ Team creates 1-3 ADRs during the pilot
|
||||
- ✅ No major complaints about the process being burdensome
|
||||
- ✅ At least one person says, "Oh, I see why this matters"
|
||||
- ✅ Team links ADRs in PRs without being asked twice
|
||||
- ✅ Honest feedback in the retrospective (positive or negative)
|
||||
|
||||
## Red Flags (If You See These, Adjust)
|
||||
|
||||
- ❌ "This feels like extra bureaucracy" → Emphasize lightness; show template is only 15 min
|
||||
- ❌ "I don't know what counts as a significant decision" → Provide 1-2 concrete examples from their project
|
||||
- ❌ "Do we have to do this?" → No, it's a pilot. But we're counting on your feedback to make it better
|
||||
|
||||
---
|
||||
|
||||
## Notes for Facilitator
|
||||
|
||||
- **Be confident but humble**: You're not selling a policy; you're piloting an experiment together.
|
||||
- **Listen more than you talk**: Their skepticism and honest feedback are golden. Encourage it.
|
||||
- **Don't over-explain**: The template and example speak for themselves.
|
||||
- **Use time wisely**: The "First Pancake" exercise is worth the time; if you run short elsewhere, cut context. The live writing is the proof point.
|
||||
- **End on invitation, not mandate**: "We're excited to see what you learn. Let's reconvene in 4 weeks."
|
||||
|
||||
---
|
||||
|
||||
## Post-Meeting
|
||||
|
||||
Send a follow-up message to the pilot team:
|
||||
```
|
||||
Great kickoff! Here's what we covered:
|
||||
|
||||
• ADR template: .knowledge/adrs/000-template.md
|
||||
• The "why" behind ADRs: .knowledge/adrs/001-use-markdown-adrs-for-dss-architecture-decisions.md
|
||||
• Questions? Check: .knowledge/adrs/README.md
|
||||
|
||||
Next steps:
|
||||
1. Create 1-3 ADRs over the next month for significant dss_sync_figma decisions
|
||||
2. Link them in PRs (see PR template update)
|
||||
3. Give us feedback in the retro (Week 4)
|
||||
|
||||
Thanks for being our pilot team. Your honest feedback is what makes this work. 🚀
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Prepared for**: DSS Principles Pilot Program
|
||||
**Pilot Project**: dss_sync_figma
|
||||
**Week 1 of 4**
|
||||
@@ -1,252 +0,0 @@
|
||||
# PR Template Update: DSS Principles Check
|
||||
|
||||
This document shows how to integrate the Architecture Decision Records (ADRs) into your existing pull request workflow.
|
||||
|
||||
**Effort**: 2 minutes to add to existing PR template
|
||||
**Impact**: Connects code changes to architectural decisions and principles
|
||||
|
||||
---
|
||||
|
||||
## Current PR Template (Example)
|
||||
|
||||
If your project doesn't have a PR template, start with this structure:
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
Brief summary of what this PR does.
|
||||
|
||||
## Type of Change
|
||||
- [ ] Bug fix
|
||||
- [ ] New feature
|
||||
- [ ] Breaking change
|
||||
- [ ] Documentation update
|
||||
|
||||
## Related Issues
|
||||
Closes #[issue number]
|
||||
|
||||
## Testing
|
||||
How to verify this works.
|
||||
|
||||
## Screenshots (if applicable)
|
||||
Helpful for UI changes.
|
||||
|
||||
## Checklist
|
||||
- [ ] Code follows style guidelines
|
||||
- [ ] Self-reviewed my own code
|
||||
- [ ] Tests pass locally
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Where to Add the DSS Principles Check
|
||||
|
||||
**Add this section just before the Checklist** (at the end, right before closing the template):
|
||||
|
||||
```markdown
|
||||
## DSS Principles Check
|
||||
|
||||
- **ADR Link**: If this PR implements a decision from `.knowledge/adrs/`, link it here.
|
||||
Example: `Implements ADR-003: Use SQLite for Local Caching`
|
||||
|
||||
- **Principle Alignment**: Which DSS principles does this work advance? Explain briefly.
|
||||
Example: `Supports Single Source of Truth by centralizing token storage; supports Knowledge Persistence by documenting the caching strategy in ADR-003`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Updated Template (Full Example)
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
Brief summary of what this PR does.
|
||||
|
||||
## Type of Change
|
||||
- [ ] Bug fix
|
||||
- [ ] New feature
|
||||
- [ ] Breaking change
|
||||
- [ ] Documentation update
|
||||
|
||||
## Related Issues
|
||||
Closes #[issue number]
|
||||
|
||||
## Testing
|
||||
How to verify this works.
|
||||
|
||||
## Screenshots (if applicable)
|
||||
Helpful for UI changes.
|
||||
|
||||
## DSS Principles Check
|
||||
|
||||
- **ADR Link**: If this PR implements a decision from `.knowledge/adrs/`, link it here.
|
||||
Example: `Implements ADR-003: Use SQLite for Local Caching`
|
||||
|
||||
- **Principle Alignment**: Which DSS principles does this work advance? Explain briefly.
|
||||
Example: `Supports Single Source of Truth by centralizing token storage; supports Knowledge Persistence by documenting the caching strategy in ADR-003`
|
||||
|
||||
## Checklist
|
||||
- [ ] Code follows style guidelines
|
||||
- [ ] Self-reviewed my own code
|
||||
- [ ] Tests pass locally
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How to Update Your PR Template
|
||||
|
||||
### Option 1: GitHub PR Template File
|
||||
|
||||
If you're using GitHub, your PR template is usually at one of these locations:
|
||||
|
||||
```
|
||||
.github/pull_request_template.md
|
||||
docs/pull_request_template.md
|
||||
pull_request_template.md
|
||||
```
|
||||
|
||||
**To update**:
|
||||
1. Open the file
|
||||
2. Add the "DSS Principles Check" section before the "Checklist"
|
||||
3. Commit the change
|
||||
4. All future PRs will automatically include the new section
|
||||
|
||||
### Option 2: GitLab, Gitea, or Other Platforms
|
||||
|
||||
Check your platform's documentation for PR template location, but the process is the same: add the section to your template file.
|
||||
|
||||
### Option 3: If You Don't Have a Template Yet
|
||||
|
||||
Create a new file at `.github/pull_request_template.md` (for GitHub) with the complete template above.
|
||||
|
||||
---
|
||||
|
||||
## Good Examples vs. Anti-Patterns
|
||||
|
||||
### ✅ Good: Clear ADR Reference + Principle Alignment
|
||||
|
||||
```markdown
|
||||
## DSS Principles Check
|
||||
|
||||
- **ADR Link**: Implements ADR-005: Use async/await for Figma API calls
|
||||
- **Principle Alignment**: Supports MCP First by using async-native patterns;
|
||||
supports Foundational Contracts by documenting API call assumptions in the ADR
|
||||
```
|
||||
|
||||
**Why this works**: Clear reference to a specific ADR; explicit connection to principles with reasoning.
|
||||
|
||||
---
|
||||
|
||||
### ✅ Good: No ADR (Because This PR Doesn't Implement a Significant Decision)
|
||||
|
||||
```markdown
|
||||
## DSS Principles Check
|
||||
|
||||
- **ADR Link**: N/A (refactor of existing pattern)
|
||||
- **Principle Alignment**: No principle alignment—this is a straightforward refactor.
|
||||
See code comments for details.
|
||||
```
|
||||
|
||||
**Why this works**: Honest acknowledgment that not every PR needs an ADR. That's fine.
|
||||
|
||||
---
|
||||
|
||||
### ⚠️ Anti-Pattern: Vague Principle Claims
|
||||
|
||||
```markdown
|
||||
## DSS Principles Check
|
||||
|
||||
- **ADR Link**: ADR-001
|
||||
- **Principle Alignment**: Supports all principles
|
||||
```
|
||||
|
||||
**Problem**: Generic claim without explanation. Forces reviewer to guess what you mean.
|
||||
**Better**: Be specific. Name 1-2 principles and explain the connection.
|
||||
|
||||
---
|
||||
|
||||
### ⚠️ Anti-Pattern: ADR Reference That Doesn't Exist
|
||||
|
||||
```markdown
|
||||
## DSS Principles Check
|
||||
|
||||
- **ADR Link**: Implements ADR-042 (which doesn't actually exist)
|
||||
- **Principle Alignment**: Aligns with Principle X
|
||||
```
|
||||
|
||||
**Problem**: Creates confusion and breaks traceability.
|
||||
**Better**: Only reference ADRs that actually exist. If you're creating a new ADR, reference it after it's created and merged.
|
||||
|
||||
---
|
||||
|
||||
## For Code Reviewers
|
||||
|
||||
When reviewing a PR with the DSS Principles Check section:
|
||||
|
||||
1. **Verify the ADR exists**: If an ADR is referenced, confirm it's in `.knowledge/adrs/` and is relevant to the PR
|
||||
2. **Check principle alignment**: Does the PR actually support the principles claimed? If vague, ask for clarification
|
||||
3. **Allow flexibility**: Not every PR needs an ADR. Small bug fixes and refactors don't require principle alignment statements
|
||||
4. **Encourage good ADRs**: If a PR involves a significant decision but no ADR exists, ask: "Should we create an ADR for this decision?"
|
||||
|
||||
---
|
||||
|
||||
## Implementation Timeline
|
||||
|
||||
**Week 1 (Kickoff Week)**:
|
||||
- [ ] Update your PR template file with the "DSS Principles Check" section
|
||||
- [ ] Commit the change to git
|
||||
- [ ] Mention the update in the kickoff meeting
|
||||
|
||||
**Weeks 2-3 (Pilot Phase)**:
|
||||
- [ ] Pilot team creates 1-3 ADRs
|
||||
- [ ] PRs implementing those decisions link the ADR in this section
|
||||
- [ ] Reviewers validate the connections
|
||||
|
||||
**Week 4 (Retrospective)**:
|
||||
- [ ] Gather feedback: Was the PR template addition helpful or burdensome?
|
||||
- [ ] Adjust if needed (e.g., move section, simplify language, add more examples)
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Do I have to fill in the DSS Principles Check for every PR?**
|
||||
A: No. Only PRs that implement a significant decision (with an ADR) need the ADR Link. The Principle Alignment field is optional for small PRs.
|
||||
|
||||
**Q: What if I'm not sure if my PR needs an ADR?**
|
||||
A: Ask yourself: "Will someone in 6 months ask, 'Why did we make this choice?'" If yes, it probably warrants an ADR. When in doubt, ask during code review.
|
||||
|
||||
**Q: Can I reference an ADR that's still in "Proposed" status?**
|
||||
A: Yes. "Proposed" means it's being considered but not yet finalized. Once there's consensus, it moves to "Accepted." Referencing a "Proposed" ADR is fine; it just means the decision isn't final yet.
|
||||
|
||||
**Q: What if someone disagrees with the ADR I'm implementing?**
|
||||
A: That's what code review is for. If there's a concern about the decision itself (not just the implementation), the ADR should be revisited. This is healthy.
|
||||
|
||||
**Q: Should the ADR be created before the PR, or as part of it?**
|
||||
A: Ideally, before the PR. The ADR documents the *decision*, and the PR implements it. But if you're still finalizing the decision during the PR, you can create the ADR in the PR and reference it. Flexibility is fine during the pilot.
|
||||
|
||||
---
|
||||
|
||||
## Template Customization Checklist
|
||||
|
||||
Before finalizing your PR template:
|
||||
|
||||
- [ ] Check your current PR template location (`.github/pull_request_template.md` or equivalent)
|
||||
- [ ] Copy the "DSS Principles Check" section from above
|
||||
- [ ] Insert it before the "Checklist" section (or at the end if no checklist)
|
||||
- [ ] Test it by opening a draft PR and confirming the section appears
|
||||
- [ ] Mention the change during the kickoff meeting so the team knows what to expect
|
||||
|
||||
---
|
||||
|
||||
## Connection to Other Documents
|
||||
|
||||
- **ADR Template**: `.knowledge/adrs/000-template.md`
|
||||
- **ADR README**: `.knowledge/adrs/README.md`
|
||||
- **PRINCIPLES.md**: `/docs/01_core/PRINCIPLES.md` (reference for principle names)
|
||||
- **Kickoff Agenda**: `.knowledge/adrs/KICKOFF_AGENDA.md` (mentions PR integration during demo)
|
||||
|
||||
---
|
||||
|
||||
**Status**: Ready to customize and commit
|
||||
**Pilot Project**: dss_sync_figma
|
||||
**Created**: 2025-12-08
|
||||
**Next Action**: Add to your platform's PR template and commit
|
||||
@@ -1,81 +0,0 @@
|
||||
# Archived Operational Documents
|
||||
|
||||
This directory contains detailed operational documents from the ADR pilot program kickoff.
|
||||
|
||||
**These files are reference-only and have been archived to keep the main working directory lean.**
|
||||
|
||||
---
|
||||
|
||||
## What's Here
|
||||
|
||||
| File | Purpose | Used When |
|
||||
|------|---------|-----------|
|
||||
| `SLACK_ANNOUNCEMENT_TEMPLATE.md` | Message to announce pilot to team | Before kickoff meeting (post 24-48 hours before) |
|
||||
| `KICKOFF_AGENDA.md` | 30-minute meeting agenda with talking points | During kickoff meeting (facilitator reference) |
|
||||
| `FACILITATOR_GUIDE.md` | Comprehensive guide for running the kickoff | Before/during kickoff (facilitator reads fully) |
|
||||
| `PR_TEMPLATE_UPDATE.md` | How to integrate ADRs into PR template | Before/during pilot (update your PR template) |
|
||||
| `EXECUTION_CHECKLIST.md` | Phase-by-phase checklist for launch | During pilot prep/execution |
|
||||
|
||||
---
|
||||
|
||||
## Quick Access
|
||||
|
||||
**If you're running a kickoff meeting** → Start with `FACILITATOR_GUIDE.md`
|
||||
|
||||
**If you're announcing the pilot** → Use `SLACK_ANNOUNCEMENT_TEMPLATE.md`
|
||||
|
||||
**If you're setting up the process** → Use `EXECUTION_CHECKLIST.md` and `PR_TEMPLATE_UPDATE.md`
|
||||
|
||||
**If you need a detailed agenda** → See `KICKOFF_AGENDA.md`
|
||||
|
||||
---
|
||||
|
||||
## Why These Are Archived
|
||||
|
||||
These documents are:
|
||||
- ✅ Comprehensive and detailed
|
||||
- ✅ Important for initial setup
|
||||
- ❌ Not needed day-to-day after pilot launch
|
||||
- ❌ Would clutter the main working directory
|
||||
|
||||
By archiving them, we keep `.knowledge/adrs/` lean (5 core files) while preserving all detail for reference.
|
||||
|
||||
---
|
||||
|
||||
## How to Use
|
||||
|
||||
All files are still fully accessible:
|
||||
|
||||
```bash
|
||||
# View a specific file
|
||||
cat archived/operational/FACILITATOR_GUIDE.md
|
||||
|
||||
# Search within archived docs
|
||||
grep -r "First Pancake" archived/operational/
|
||||
|
||||
# Copy to working directory if needed
|
||||
cp archived/operational/KICKOFF_AGENDA.md ../
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
These documents were created as part of the DSS Core Principles pilot program (December 2025).
|
||||
|
||||
- **Pilot Project**: dss_sync_figma
|
||||
- **Pilot Team**: [Your team members]
|
||||
- **Duration**: 4 weeks (Weeks 1-4 of December)
|
||||
- **Goal**: Test Architecture Decision Records (ADRs) as a lightweight process for capturing architectural decisions
|
||||
|
||||
For ongoing ADR work, use:
|
||||
- `.knowledge/adrs/000-template.md` — Create new ADRs
|
||||
- `.knowledge/adrs/README.md` — Guide for creating ADRs
|
||||
- `.knowledge/adrs/PRINCIPLES_CORE_REFERENCE.md` — Quick principle lookup
|
||||
- `.knowledge/adrs/ADR_KNOWLEDGE_MAP.md` — How decisions trace back to principles
|
||||
|
||||
---
|
||||
|
||||
**Status**: Archived (reference-only)
|
||||
**Created**: 2025-12-08
|
||||
**Owner**: DSS Core Principles Initiative
|
||||
@@ -1,118 +0,0 @@
|
||||
# Slack Announcement Template
|
||||
|
||||
Copy this message and post to [YOUR_TEAM_SLACK_CHANNEL] when ready to launch the pilot.
|
||||
|
||||
Replace [PLACEHOLDERS] with your team-specific details.
|
||||
|
||||
---
|
||||
|
||||
## Message
|
||||
|
||||
> 🎯 **DSS Principles Pilot: Architecture Decision Records**
|
||||
>
|
||||
> Hey team! We're running a 4-week pilot to strengthen our DSS principles adoption—and we want [PILOT_TEAM_MEMBER_1], [PILOT_TEAM_MEMBER_2], and [PILOT_TEAM_MEMBER_3] to be our partners in testing it.
|
||||
>
|
||||
> **The Experiment**
|
||||
> We're using lightweight "Architecture Decision Records" (ADRs) to capture the rationale behind significant decisions we make. This helps us:
|
||||
> - 📝 Capture "why" while it's fresh (not reconstruct from git history months later)
|
||||
> - 🧅 Onboard new people with context, not just code
|
||||
> - 💡 Make our core principles real, not just a document
|
||||
>
|
||||
> **The Pilot Team**
|
||||
> This starts with the `dss_sync_figma` project. [PILOT_TEAM_NAMES], we're kicking off a 30-min sync on **[DAY], [DATE], [TIME]** to show how this works and get your feedback.
|
||||
>
|
||||
> **Why You?**
|
||||
> You're building something complex right now with interesting trade-offs. Perfect for piloting this process. We want your **honest feedback**—if this feels valuable, great. If it feels like noise, tell us that too.
|
||||
>
|
||||
> **Learn More**
|
||||
> Check out `.knowledge/adrs/README.md` for the full context and how this works.
|
||||
>
|
||||
> Questions? Drop them below or in the kickoff meeting.
|
||||
>
|
||||
> Let's go! 🚀
|
||||
|
||||
---
|
||||
|
||||
## Customization Checklist
|
||||
|
||||
- [ ] Replace `[YOUR_TEAM_SLACK_CHANNEL]` with actual channel name
|
||||
- [ ] Replace `[PILOT_TEAM_MEMBER_1], [PILOT_TEAM_MEMBER_2], [PILOT_TEAM_MEMBER_3]` with actual names
|
||||
- [ ] Replace `[DAY]` with day of week (Thursday, Friday, etc.)
|
||||
- [ ] Replace `[DATE]` with date (Dec 12, etc.)
|
||||
- [ ] Replace `[TIME]` with meeting time (2:00 PM, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Timing
|
||||
|
||||
Post this message **24-48 hours before the kickoff meeting** to give team time to:
|
||||
- Read the README
|
||||
- Ask questions
|
||||
- Mentally prepare
|
||||
|
||||
## Alternative (Longer Version)
|
||||
|
||||
If your team prefers more context, use this expanded version:
|
||||
|
||||
> 🎯 **DSS Principles Pilot: Let's Try Something New**
|
||||
>
|
||||
> We've spent the last month defining DSS's core principles—the "why" behind every decision we make. Now the real work begins: **bringing those principles to life in how we actually work.**
|
||||
>
|
||||
> **The Challenge**
|
||||
> Principles are only as good as their adoption. And one of our biggest challenges is that decision rationale gets lost. You write code today, and six months later, a new team member asks, "Why did we do it this way?" Git history says *what* changed, but not *why*. That context is in Slack, in commit messages, or just in your head. It's lost.
|
||||
>
|
||||
> **The Experiment**
|
||||
> We're testing a lightweight process: **Architecture Decision Records (ADRs)**. When we make a significant decision, we spend 15 minutes capturing:
|
||||
> - What is the decision?
|
||||
> - Why did we choose it?
|
||||
> - What alternatives did we consider and reject?
|
||||
> - What are the consequences?
|
||||
>
|
||||
> That's it. One file. Done.
|
||||
>
|
||||
> **The Pilot Team**
|
||||
> [PILOT_TEAM_NAMES], you're building `dss_sync_figma` right now, and that project has *exactly* the kind of architectural decisions this is designed for. We're asking you to be our test pilots.
|
||||
>
|
||||
> **What We're NOT Asking**
|
||||
> - Don't create ADRs for every decision (just the big, consequential ones)
|
||||
> - Don't spend hours on documentation (15 mins, max)
|
||||
> - Don't adopt new tools or learn new syntax (it's just Markdown)
|
||||
>
|
||||
> **What We ARE Asking**
|
||||
> - Create 1-3 ADRs over the next month for the biggest decisions
|
||||
> - Give us honest feedback: Does this help? Or is it just bureaucracy?
|
||||
> - Help us understand what works and what doesn't
|
||||
>
|
||||
> **Kickoff Meeting**
|
||||
> [DAY], [DATE], [TIME] – 30 minutes
|
||||
> We'll show you the template (it's tiny), write your first ADR together, and answer questions.
|
||||
>
|
||||
> **Learn More**
|
||||
> - `.knowledge/adrs/README.md` – Full overview
|
||||
> - `.knowledge/adrs/001-...md` – The meta-ADR explaining why we chose this approach
|
||||
>
|
||||
> Thanks for being our partners in this. Your feedback is what makes it work. 🚀
|
||||
|
||||
---
|
||||
|
||||
## Post-Kickoff Follow-up (Optional)
|
||||
|
||||
After the kickoff meeting, consider sending this short note:
|
||||
|
||||
> **ADR Kickoff Recap**
|
||||
>
|
||||
> Thanks everyone for the great kickoff! Here's what to do next:
|
||||
>
|
||||
> 📍 **Create ADRs** for your top 2-3 `dss_sync_figma` decisions over the next month
|
||||
> 📝 **Template**: Copy `.knowledge/adrs/000-template.md`
|
||||
> 🔗 **Link in PRs**: Add to the "DSS Principles Check" section
|
||||
> 💬 **Questions**: Post in thread or grab me directly
|
||||
>
|
||||
> Check-ins: I'll reach out around week 2-3 to see how it's going.
|
||||
> Retro: We'll do a 30-minute retrospective in Week 4 to gather your feedback.
|
||||
>
|
||||
> Let's see if this helps us move faster. 🎯
|
||||
|
||||
---
|
||||
|
||||
**Ready to send?** Replace the placeholders, copy, and paste to Slack!
|
||||
@@ -1,113 +0,0 @@
|
||||
{
|
||||
"$schema": "dss-knowledge-v1",
|
||||
"type": "architecture",
|
||||
"version": "0.8.0",
|
||||
"last_updated": null,
|
||||
"modules": [
|
||||
{
|
||||
"name": "messaging",
|
||||
"path": "admin-ui/js/core/messaging.js",
|
||||
"purpose": "Centralized notification system with structured error taxonomy and correlation IDs",
|
||||
"features": [
|
||||
"Event bus using CustomEvent API",
|
||||
"Structured message format with correlation IDs",
|
||||
"Error taxonomy (E1xxx-E5xxx for errors, S1xxx for success)",
|
||||
"Message persistence via localStorage",
|
||||
"Helper functions: notifySuccess, notifyError, notifyWarning, notifyInfo",
|
||||
"Message history and debugging capabilities"
|
||||
],
|
||||
"error_codes": {
|
||||
"E1xxx": "User errors (invalid input, forbidden actions)",
|
||||
"E2xxx": "Validation errors (missing fields, invalid formats)",
|
||||
"E3xxx": "API errors (request failed, timeout, unauthorized)",
|
||||
"E4xxx": "System errors (unexpected, network, storage)",
|
||||
"E5xxx": "Integration errors (Figma connection, API errors)",
|
||||
"S1xxx": "Success codes (operation complete, created, updated, deleted)"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "router",
|
||||
"path": "admin-ui/js/core/router.js",
|
||||
"purpose": "Centralized hash-based routing with guards and lifecycle hooks",
|
||||
"features": [
|
||||
"Centralized route registry",
|
||||
"Route guards (beforeEnter, afterEnter, onLeave)",
|
||||
"History management",
|
||||
"Programmatic navigation",
|
||||
"Route metadata support",
|
||||
"Common guards (requireAuth, requireProject)"
|
||||
],
|
||||
"routes": [
|
||||
"dashboard",
|
||||
"projects",
|
||||
"tokens",
|
||||
"components",
|
||||
"figma",
|
||||
"docs",
|
||||
"teams",
|
||||
"audit",
|
||||
"settings",
|
||||
"services",
|
||||
"quick-wins",
|
||||
"chat"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "workflows",
|
||||
"path": "admin-ui/js/core/workflows.js",
|
||||
"purpose": "Orchestrate multi-step user workflows with state machines",
|
||||
"features": [
|
||||
"Base StateMachine class",
|
||||
"CreateProjectWorkflow (Create \u2192 Configure \u2192 Extract \u2192 Success)",
|
||||
"TokenExtractionWorkflow (Connect \u2192 Select \u2192 Extract \u2192 Sync)",
|
||||
"Progress tracking",
|
||||
"State transition guards",
|
||||
"Side effects via actions",
|
||||
"Event emission for UI updates"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "rest_api",
|
||||
"path": "/home/overbits/dss/tools/api/server.py",
|
||||
"purpose": "FastAPI server providing REST API and static file serving",
|
||||
"port": 3456,
|
||||
"endpoints": [],
|
||||
"mounts": [
|
||||
{
|
||||
"path": "/admin-ui",
|
||||
"type": "StaticFiles",
|
||||
"line_number": 258
|
||||
},
|
||||
{
|
||||
"path": "/",
|
||||
"type": "StaticFiles",
|
||||
"line_number": 3073
|
||||
}
|
||||
],
|
||||
"total_endpoints": 0
|
||||
}
|
||||
],
|
||||
"design_patterns": [
|
||||
"Separation of Concerns",
|
||||
"Single Responsibility Principle",
|
||||
"Dependency Injection",
|
||||
"Observer Pattern",
|
||||
"State Machine Pattern",
|
||||
"Command Pattern",
|
||||
"Strategy Pattern"
|
||||
],
|
||||
"performance": {
|
||||
"bundle_size_increase": "+15KB (minified)",
|
||||
"initialization_time_increase": "+50ms",
|
||||
"memory_usage": "+~1MB (50 messages in localStorage)",
|
||||
"network_impact": "No additional requests"
|
||||
},
|
||||
"_metadata": {
|
||||
"generator": "APIExtractor",
|
||||
"generated_at": "2025-12-07T18:27:49.697019",
|
||||
"source_files": [
|
||||
"/home/overbits/dss/tools/api/server.py"
|
||||
],
|
||||
"version": "1.0.0"
|
||||
}
|
||||
}
|
||||
@@ -1,735 +0,0 @@
|
||||
{
|
||||
"$schema": "dss-knowledge-v1",
|
||||
"type": "coding_standards",
|
||||
"version": "1.0.0",
|
||||
"last_updated": "2025-12-08",
|
||||
"description": "Immutable coding best practices for all DSS code. These standards are enforced via pre-commit hooks and guide all code contributions.",
|
||||
|
||||
"web_components": {
|
||||
"principle": "All UI components MUST be Web Components using Custom Elements API",
|
||||
"rules": [
|
||||
{
|
||||
"id": "WC-001",
|
||||
"rule": "Shadow DOM Required",
|
||||
"requirement": "MUST use attachShadow({ mode: 'open' }) for all components",
|
||||
"exceptions": "None - this is non-negotiable for style encapsulation",
|
||||
"rationale": "Prevents global CSS pollution and ensures component isolation",
|
||||
"enforcement": "Pre-commit hook fails if component extends HTMLElement without Shadow DOM"
|
||||
},
|
||||
{
|
||||
"id": "WC-002",
|
||||
"rule": "Lifecycle Management",
|
||||
"requirement": "MUST implement connectedCallback, disconnectedCallback, and attributeChangedCallback where appropriate",
|
||||
"pattern": "Always clean up event listeners and subscriptions in disconnectedCallback",
|
||||
"example": "disconnectedCallback() { if (this.unsubscribe) this.unsubscribe(); if (this.abortController) this.abortController.abort(); }"
|
||||
},
|
||||
{
|
||||
"id": "WC-003",
|
||||
"rule": "Observable Attributes",
|
||||
"requirement": "Define observedAttributes static getter for reactive attributes",
|
||||
"pattern": "static get observedAttributes() { return ['title', 'value', 'color']; }",
|
||||
"rationale": "Enables reactive attribute changes without manual DOM manipulation"
|
||||
},
|
||||
{
|
||||
"id": "WC-004",
|
||||
"rule": "Component Registration",
|
||||
"requirement": "Define custom element in component file using customElements.define()",
|
||||
"pattern": "customElements.define('ds-component-name', ComponentClass);",
|
||||
"naming": "All DSS components prefixed with 'ds-' to avoid conflicts"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"style_management": {
|
||||
"principle": "Zero inline styles policy - all styles in Shadow DOM or external stylesheets",
|
||||
"rules": [
|
||||
{
|
||||
"id": "STYLE-001",
|
||||
"rule": "NO Inline Styles",
|
||||
"requirement": "FORBIDDEN: style=\"...\" attributes in templates",
|
||||
"exceptions": "ONLY dynamic computed values (e.g., transform: translateX(${x}px), width: ${percent}%)",
|
||||
"enforcement": "Pre-commit hook fails if >10 inline styles detected",
|
||||
"rationale": "Maintainability, separation of concerns, style encapsulation"
|
||||
},
|
||||
{
|
||||
"id": "STYLE-002",
|
||||
"rule": "Shadow DOM Styles",
|
||||
"requirement": "All component styles in <style> block within shadowRoot.innerHTML",
|
||||
"pattern": "this.shadowRoot.innerHTML = `<style>:host { display: block; } .card { padding: 16px; }</style><div class=\"card\">...</div>`;",
|
||||
"best_practice": "Define styles at top of template for clarity"
|
||||
},
|
||||
{
|
||||
"id": "STYLE-003",
|
||||
"rule": "VSCode Theme Tokens",
|
||||
"requirement": "MUST use CSS custom properties from VSCode theme",
|
||||
"required_variables": [
|
||||
"--vscode-foreground",
|
||||
"--vscode-background",
|
||||
"--vscode-sidebar-background",
|
||||
"--vscode-button-background",
|
||||
"--vscode-button-foreground",
|
||||
"--vscode-button-secondaryBackground",
|
||||
"--vscode-button-secondaryForeground",
|
||||
"--vscode-focusBorder",
|
||||
"--vscode-list-hoverBackground",
|
||||
"--vscode-list-activeSelectionBackground",
|
||||
"--vscode-list-activeSelectionForeground",
|
||||
"--vscode-descriptionForeground",
|
||||
"--vscode-widget-border",
|
||||
"--vscode-errorForeground"
|
||||
],
|
||||
"rationale": "Ensures consistent theming with VSCode dark/light mode"
|
||||
},
|
||||
{
|
||||
"id": "STYLE-004",
|
||||
"rule": "Constructable Stylesheets",
|
||||
"requirement": "Use for shared styles across multiple components",
|
||||
"pattern": "const sheet = new CSSStyleSheet(); sheet.replaceSync(css); shadowRoot.adoptedStyleSheets = [sheet];",
|
||||
"use_cases": ["Common button styles", "Typography system", "Layout utilities"]
|
||||
},
|
||||
{
|
||||
"id": "STYLE-005",
|
||||
"rule": "CSS Hover Effects",
|
||||
"requirement": "Use :hover pseudo-class, NOT onmouseover/onmouseout",
|
||||
"correct": ".card:hover { background: var(--vscode-list-hoverBackground); }",
|
||||
"forbidden": "onmouseover=\"this.style.background='...'\" onmouseout=\"this.style.background=''\"",
|
||||
"rationale": "Performance, maintainability, separation of concerns"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"event_handling": {
|
||||
"principle": "Event delegation pattern - NO inline event handlers",
|
||||
"rules": [
|
||||
{
|
||||
"id": "EVENT-001",
|
||||
"rule": "NO Inline Events",
|
||||
"requirement": "FORBIDDEN: onclick, onmouseover, onmouseout, onkeydown, onkeyup, etc. in HTML",
|
||||
"enforcement": "Pre-commit hook fails if ANY inline event handlers detected",
|
||||
"rationale": "Security (CSP compliance), maintainability, testability, separation of concerns"
|
||||
},
|
||||
{
|
||||
"id": "EVENT-002",
|
||||
"rule": "Event Delegation Pattern",
|
||||
"requirement": "Single delegated listener per component using data-action attributes",
|
||||
"pattern": "this.shadowRoot.addEventListener('click', (e) => { const action = e.target.closest('[data-action]')?.dataset.action; if (action && this[`handle${action}`]) { this[`handle${action}`](e); } });",
|
||||
"html_example": "<button data-action=\"save\" type=\"button\">Save</button>",
|
||||
"js_example": "handleSave(e) { /* implementation */ }"
|
||||
},
|
||||
{
|
||||
"id": "EVENT-003",
|
||||
"rule": "Custom Events for Communication",
|
||||
"requirement": "Component communication via CustomEvent with composed: true",
|
||||
"pattern": "this.dispatchEvent(new CustomEvent('ds-action', { detail: { action, data }, bubbles: true, composed: true }));",
|
||||
"rationale": "composed: true allows events to bubble out of Shadow DOM boundaries"
|
||||
},
|
||||
{
|
||||
"id": "EVENT-004",
|
||||
"rule": "Event Listener Cleanup",
|
||||
"requirement": "Always remove event listeners in disconnectedCallback",
|
||||
"pattern": "this.abortController = new AbortController(); addEventListener('click', handler, { signal: this.abortController.signal }); // disconnectedCallback: this.abortController.abort();",
|
||||
"alternative": "Store handlers as methods and call removeEventListener explicitly"
|
||||
},
|
||||
{
|
||||
"id": "EVENT-005",
|
||||
"rule": "Keyboard Navigation",
|
||||
"requirement": "Support Tab, Enter, Escape, Arrow keys for interactive components",
|
||||
"pattern": "this.shadowRoot.addEventListener('keydown', (e) => { if (e.key === 'Escape') this.close(); if (e.key === 'Enter') this.submit(); });",
|
||||
"rationale": "Accessibility requirement for keyboard-only users"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"accessibility": {
|
||||
"principle": "WCAG 2.1 Level AA compliance minimum",
|
||||
"rules": [
|
||||
{
|
||||
"id": "A11Y-001",
|
||||
"rule": "Semantic HTML",
|
||||
"requirement": "MUST use semantic elements: <button>, <nav>, <main>, <aside>, <header>, <footer>, <article>, <section>",
|
||||
"forbidden": "<div onclick=\"...\"> for interactive elements, <div class=\"button\">",
|
||||
"correct": "<button type=\"button\">Click me</button>",
|
||||
"rationale": "Screen readers rely on semantic HTML for navigation and interaction"
|
||||
},
|
||||
{
|
||||
"id": "A11Y-002",
|
||||
"rule": "Button Type Attribute",
|
||||
"requirement": "ALL <button> elements MUST have type=\"button\" (or type=\"submit\" in forms)",
|
||||
"pattern": "<button type=\"button\">Action</button>",
|
||||
"rationale": "Prevents accidental form submission in HTML forms",
|
||||
"enforcement": "Pre-commit hook warns about buttons without type attribute"
|
||||
},
|
||||
{
|
||||
"id": "A11Y-003",
|
||||
"rule": "ARIA Attributes",
|
||||
"requirement": "Use when semantic HTML insufficient",
|
||||
"required_patterns": [
|
||||
"aria-label for icon-only buttons",
|
||||
"aria-labelledby for complex widgets",
|
||||
"aria-describedby for additional context",
|
||||
"role for custom interactive elements"
|
||||
],
|
||||
"examples": [
|
||||
"<button aria-label=\"Close dialog\" type=\"button\">×</button>",
|
||||
"<div role=\"group\" aria-labelledby=\"tools-heading\">...</div>"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "A11Y-004",
|
||||
"rule": "Focus Management",
|
||||
"requirement": "Keyboard navigation support for all interactive elements",
|
||||
"css_pattern": ".btn:focus-visible { outline: 2px solid var(--vscode-focusBorder); outline-offset: 2px; }",
|
||||
"js_requirements": [
|
||||
"trapFocus() for modals",
|
||||
"restoreFocus() on close",
|
||||
"Skip links for main content",
|
||||
"Focus first invalid field on validation error"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "A11Y-005",
|
||||
"rule": "Color Contrast",
|
||||
"requirement": "Minimum 4.5:1 for normal text, 3:1 for large text",
|
||||
"tool": "Use VSCode theme tokens which meet contrast requirements",
|
||||
"testing": "Chrome DevTools Lighthouse audit"
|
||||
},
|
||||
{
|
||||
"id": "A11Y-006",
|
||||
"rule": "Screen Reader Testing",
|
||||
"requirement": "Test all components with NVDA/JAWS (Windows) or VoiceOver (Mac)",
|
||||
"checklist": [
|
||||
"Navigation order makes sense",
|
||||
"All buttons have clear labels",
|
||||
"Error messages announced",
|
||||
"Status updates announced with aria-live"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"state_management": {
|
||||
"principle": "Centralized state with reactive updates",
|
||||
"rules": [
|
||||
{
|
||||
"id": "STATE-001",
|
||||
"rule": "Context Store for Global State",
|
||||
"requirement": "Use contextStore for application-wide state (projectId, teamId, userId)",
|
||||
"pattern": "this.unsubscribe = contextStore.subscribeToKey('projectId', (newValue) => { this.projectId = newValue; this.render(); });",
|
||||
"path": "admin-ui/js/stores/context-store.js"
|
||||
},
|
||||
{
|
||||
"id": "STATE-002",
|
||||
"rule": "Component Local State",
|
||||
"requirement": "Component-specific state in this.state object",
|
||||
"pattern": "this.state = { isLoading: false, data: null, error: null }; setState(updates) { Object.assign(this.state, updates); this.render(); }",
|
||||
"best_practice": "Initialize state in constructor"
|
||||
},
|
||||
{
|
||||
"id": "STATE-003",
|
||||
"rule": "NO Direct DOM Manipulation",
|
||||
"requirement": "State changes trigger re-renders, not direct DOM updates",
|
||||
"forbidden": "document.getElementById('foo').textContent = 'bar'; element.style.display = 'none';",
|
||||
"correct": "this.setState({ foo: 'bar', visible: false }); // render() handles DOM updates",
|
||||
"rationale": "Maintains single source of truth, prevents state/view desync"
|
||||
},
|
||||
{
|
||||
"id": "STATE-004",
|
||||
"rule": "Subscription Cleanup",
|
||||
"requirement": "Always unsubscribe in disconnectedCallback",
|
||||
"pattern": "connectedCallback() { this.unsubscribe = store.subscribe(...); } disconnectedCallback() { if (this.unsubscribe) this.unsubscribe(); }",
|
||||
"rationale": "Prevents memory leaks from orphaned subscriptions"
|
||||
},
|
||||
{
|
||||
"id": "STATE-005",
|
||||
"rule": "Immutable State Updates",
|
||||
"requirement": "Create new state objects, don't mutate existing",
|
||||
"correct": "this.state = { ...this.state, count: this.state.count + 1 };",
|
||||
"forbidden": "this.state.count++; // direct mutation",
|
||||
"rationale": "Enables change detection and debugging"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"code_organization": {
|
||||
"principle": "Single Responsibility, clear structure, modular design",
|
||||
"rules": [
|
||||
{
|
||||
"id": "ORG-001",
|
||||
"rule": "File Size Limit",
|
||||
"requirement": "Maximum 500 lines per file",
|
||||
"action": "If larger, split into multiple modules",
|
||||
"enforcement": "Quality check warns on files >500 lines",
|
||||
"current_violation": "app.js at 4,347 lines must be decomposed"
|
||||
},
|
||||
{
|
||||
"id": "ORG-002",
|
||||
"rule": "Directory Structure",
|
||||
"requirement": "Strict organization by type and purpose",
|
||||
"structure": {
|
||||
"admin-ui/js/components/": "Web components (*.js)",
|
||||
"admin-ui/js/components/layout/": "Layout components (shell, header, sidebar)",
|
||||
"admin-ui/js/components/metrics/": "Dashboard and metric components",
|
||||
"admin-ui/js/components/tools/": "Tool-specific components",
|
||||
"admin-ui/js/components/listings/": "List/table components",
|
||||
"admin-ui/js/stores/": "State management",
|
||||
"admin-ui/js/utils/": "Helper functions and utilities",
|
||||
"admin-ui/js/core/": "Core modules (router, messaging, workflows)",
|
||||
"admin-ui/js/workdesks/": "Team workdesk controllers",
|
||||
"admin-ui/js/config/": "Configuration files"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "ORG-003",
|
||||
"rule": "Import Style",
|
||||
"requirement": "Explicit named imports, no wildcards",
|
||||
"correct": "import { hydrateComponent } from '../config/component-registry.js';",
|
||||
"forbidden": "import * as registry from '../config/component-registry.js';",
|
||||
"rationale": "Tree-shaking, explicit dependencies, better IDE support"
|
||||
},
|
||||
{
|
||||
"id": "ORG-004",
|
||||
"rule": "Export Style",
|
||||
"requirement": "Named exports for utilities, default export for components",
|
||||
"utility_pattern": "export function debounce(fn, ms) { ... } export function throttle(fn, ms) { ... }",
|
||||
"component_pattern": "export default class MyComponent extends HTMLElement { ... }",
|
||||
"rationale": "Convention clarity, supports tree-shaking"
|
||||
},
|
||||
{
|
||||
"id": "ORG-005",
|
||||
"rule": "Single Responsibility Principle",
|
||||
"requirement": "One component = one concern, one file = one primary export",
|
||||
"examples": [
|
||||
"ds-metric-card.js: Displays a single metric card",
|
||||
"ds-frontpage.js: Orchestrates dashboard layout",
|
||||
"context-store.js: Manages global application state"
|
||||
],
|
||||
"anti_pattern": "utility-functions.js with 50 unrelated functions"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"error_handling": {
|
||||
"principle": "Structured logging, user-friendly errors, graceful degradation",
|
||||
"rules": [
|
||||
{
|
||||
"id": "ERROR-001",
|
||||
"rule": "Centralized Logger",
|
||||
"requirement": "Use logger utility for all logging",
|
||||
"path": "admin-ui/js/utils/logger.js",
|
||||
"methods": [
|
||||
"logger.debug(msg, ...args): Development-only logging",
|
||||
"logger.info(msg, ...args): Informational messages",
|
||||
"logger.warn(msg, ...args): Warning conditions",
|
||||
"logger.error(msg, ...args): Error conditions"
|
||||
],
|
||||
"pattern": "import { logger } from '../utils/logger.js'; logger.info('[ComponentName] Action completed', { data });"
|
||||
},
|
||||
{
|
||||
"id": "ERROR-002",
|
||||
"rule": "NO console.log in Production",
|
||||
"requirement": "Replace all console.log/warn/error with logger methods",
|
||||
"enforcement": "Pre-commit hook warns if >10 console statements",
|
||||
"exceptions": "Core initialization logging in app.js only",
|
||||
"migration": "console.log('foo') → logger.debug('foo')"
|
||||
},
|
||||
{
|
||||
"id": "ERROR-003",
|
||||
"rule": "User-Friendly Error Messages",
|
||||
"requirement": "Error messages must be actionable and clear",
|
||||
"good": "Failed to load projects. Please check your internet connection and try again.",
|
||||
"bad": "Error: HTTP 500", "TypeError: Cannot read property 'id' of undefined",
|
||||
"pattern": "Show what failed + why it might have failed + what user can do"
|
||||
},
|
||||
{
|
||||
"id": "ERROR-004",
|
||||
"rule": "Error Taxonomy",
|
||||
"requirement": "Use structured error codes from messaging.js",
|
||||
"codes": {
|
||||
"E1xxx": "User errors (invalid input, forbidden actions)",
|
||||
"E2xxx": "Validation errors (missing fields, invalid formats)",
|
||||
"E3xxx": "API errors (request failed, timeout, unauthorized)",
|
||||
"E4xxx": "System errors (unexpected, network, storage)",
|
||||
"E5xxx": "Integration errors (Figma, external APIs)",
|
||||
"S1xxx": "Success codes"
|
||||
},
|
||||
"usage": "notifyError('E3001', 'Failed to fetch projects', error);"
|
||||
},
|
||||
{
|
||||
"id": "ERROR-005",
|
||||
"rule": "Graceful Degradation",
|
||||
"requirement": "Components must handle missing/invalid data gracefully",
|
||||
"patterns": [
|
||||
"if (!data) return this.renderEmptyState();",
|
||||
"if (error) return this.renderError(error);",
|
||||
"const items = data?.items ?? [];"
|
||||
],
|
||||
"anti_pattern": "Assuming data exists and causing cascading failures"
|
||||
},
|
||||
{
|
||||
"id": "ERROR-006",
|
||||
"rule": "Try-Catch for Async Operations",
|
||||
"requirement": "Wrap all async operations in try-catch",
|
||||
"pattern": "async loadData() { try { const data = await fetch(...); } catch (error) { logger.error('[Component] Failed to load', error); this.handleError(error); } }",
|
||||
"rationale": "Prevents unhandled promise rejections"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"performance": {
|
||||
"principle": "Optimize for user experience, measure and improve",
|
||||
"rules": [
|
||||
{
|
||||
"id": "PERF-001",
|
||||
"rule": "Lazy Loading",
|
||||
"requirement": "Non-critical components loaded on-demand via hydrateComponent()",
|
||||
"pattern": "await hydrateComponent('ds-screenshot-gallery', container);",
|
||||
"benefits": "Faster initial load, reduced bundle size",
|
||||
"applies_to": ["Tool components", "Heavy visualizations", "Rarely-used features"]
|
||||
},
|
||||
{
|
||||
"id": "PERF-002",
|
||||
"rule": "Virtual Scrolling",
|
||||
"requirement": "Use for lists >100 items",
|
||||
"libraries": ["lit-virtualizer", "virtual-scroller"],
|
||||
"pattern": "import { VirtualScroller } from 'virtual-scroller'; new VirtualScroller(container, { items, renderItem });",
|
||||
"applies_to": ["Token lists", "Component catalogs", "Log viewers"]
|
||||
},
|
||||
{
|
||||
"id": "PERF-003",
|
||||
"rule": "Debouncing and Throttling",
|
||||
"requirement": "Debounce search inputs, throttle scroll/resize handlers",
|
||||
"debounce_pattern": "this.searchDebounced = debounce(() => this.performSearch(), 300);",
|
||||
"throttle_pattern": "this.onScrollThrottled = throttle(() => this.handleScroll(), 100);",
|
||||
"use_cases": {
|
||||
"debounce": "Search inputs, form validation, autosave",
|
||||
"throttle": "Scroll handlers, resize handlers, mousemove tracking"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "PERF-004",
|
||||
"rule": "Avoid Unnecessary Re-renders",
|
||||
"requirement": "Only re-render when state actually changes",
|
||||
"pattern": "attributeChangedCallback(name, oldValue, newValue) { if (oldValue === newValue) return; this.render(); }",
|
||||
"best_practice": "Compare old vs new state before rendering"
|
||||
},
|
||||
{
|
||||
"id": "PERF-005",
|
||||
"rule": "Bundle Size Monitoring",
|
||||
"requirement": "Monitor and optimize JavaScript bundle sizes",
|
||||
"targets": {
|
||||
"individual_component": "<50KB",
|
||||
"total_bundle": "<500KB",
|
||||
"critical_path": "<200KB"
|
||||
},
|
||||
"tools": ["webpack-bundle-analyzer", "source-map-explorer"]
|
||||
},
|
||||
{
|
||||
"id": "PERF-006",
|
||||
"rule": "Minimize DOM Operations",
|
||||
"requirement": "Batch DOM updates, use DocumentFragment for multiple inserts",
|
||||
"pattern": "const fragment = document.createDocumentFragment(); items.forEach(item => fragment.appendChild(createNode(item))); container.appendChild(fragment);",
|
||||
"anti_pattern": "items.forEach(item => container.appendChild(createNode(item))); // causes multiple reflows"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"security": {
|
||||
"principle": "Secure by default, defense in depth",
|
||||
"rules": [
|
||||
{
|
||||
"id": "SEC-001",
|
||||
"rule": "NO Hardcoded Secrets",
|
||||
"requirement": "FORBIDDEN: API keys, passwords, tokens, credentials in code",
|
||||
"enforcement": "Pre-commit hook fails if secret patterns detected (apiKey, api_key, password, secret, token)",
|
||||
"correct": "Use environment variables or secure configuration service",
|
||||
"rationale": "Prevents credential leaks in version control"
|
||||
},
|
||||
{
|
||||
"id": "SEC-002",
|
||||
"rule": "Input Sanitization",
|
||||
"requirement": "ALWAYS escape user input before rendering to DOM",
|
||||
"utility": "ComponentHelpers.escapeHtml(userInput)",
|
||||
"pattern": "<div>${ComponentHelpers.escapeHtml(project.name)}</div>",
|
||||
"forbidden": "<div>${project.name}</div> // XSS vulnerability",
|
||||
"rationale": "Prevents XSS attacks"
|
||||
},
|
||||
{
|
||||
"id": "SEC-003",
|
||||
"rule": "CSP Compliance",
|
||||
"requirement": "NO eval(), NO new Function(), NO inline scripts",
|
||||
"forbidden": [
|
||||
"eval(code)",
|
||||
"new Function('x', 'return x * 2')",
|
||||
"<script>alert(1)</script> in templates"
|
||||
],
|
||||
"rationale": "Content Security Policy compatibility, prevents code injection"
|
||||
},
|
||||
{
|
||||
"id": "SEC-004",
|
||||
"rule": "HTTPS Only",
|
||||
"requirement": "All external requests use HTTPS",
|
||||
"enforcement": "No http:// URLs in fetch() calls",
|
||||
"correct": "fetch('https://api.example.com/data')",
|
||||
"forbidden": "fetch('http://api.example.com/data')",
|
||||
"exceptions": "localhost development only"
|
||||
},
|
||||
{
|
||||
"id": "SEC-005",
|
||||
"rule": "Validate API Responses",
|
||||
"requirement": "Always validate structure and content of API responses",
|
||||
"pattern": "const data = await response.json(); if (!data || !Array.isArray(data.items)) throw new Error('Invalid response');",
|
||||
"rationale": "Prevents errors from malformed/malicious responses"
|
||||
},
|
||||
{
|
||||
"id": "SEC-006",
|
||||
"rule": "Authentication Token Handling",
|
||||
"requirement": "Store auth tokens securely, never in localStorage",
|
||||
"correct": "sessionStorage (better: httpOnly cookies)",
|
||||
"forbidden": "localStorage for sensitive tokens",
|
||||
"rationale": "localStorage accessible to XSS attacks"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"testing_and_quality": {
|
||||
"principle": "Automated quality gates, comprehensive testing",
|
||||
"rules": [
|
||||
{
|
||||
"id": "TEST-001",
|
||||
"rule": "Pre-commit Hooks",
|
||||
"requirement": "MUST pass all quality checks before commit",
|
||||
"script": "scripts/verify-quality.sh",
|
||||
"thresholds": {
|
||||
"inline_styles": "≤10 (exceptions for dynamic values only)",
|
||||
"inline_events": "0 (zero tolerance)",
|
||||
"console_statements": "≤10 (production code only)",
|
||||
"file_size": "≤100KB per file",
|
||||
"syntax_errors": "0 (zero tolerance)"
|
||||
},
|
||||
"bypass": "git commit --no-verify (not recommended, requires justification)"
|
||||
},
|
||||
{
|
||||
"id": "TEST-002",
|
||||
"rule": "Component Unit Tests",
|
||||
"requirement": "Unit tests for all components",
|
||||
"coverage": "Minimum 80% for critical paths",
|
||||
"framework": "Web Test Runner or Vitest",
|
||||
"test_cases": [
|
||||
"Component renders correctly",
|
||||
"Props/attributes update component",
|
||||
"Event handlers work",
|
||||
"Cleanup happens on disconnect"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "TEST-003",
|
||||
"rule": "Integration Tests",
|
||||
"requirement": "Test critical user flows end-to-end",
|
||||
"examples": [
|
||||
"Project creation workflow",
|
||||
"Token extraction from Figma",
|
||||
"Component audit process",
|
||||
"User authentication flow"
|
||||
],
|
||||
"tools": ["Playwright", "Cypress"]
|
||||
},
|
||||
{
|
||||
"id": "TEST-004",
|
||||
"rule": "Visual Regression Testing",
|
||||
"requirement": "Screenshot comparison for UI changes",
|
||||
"tools": ["Playwright screenshots", "Percy", "Chromatic"],
|
||||
"process": "Capture baseline → Make changes → Compare → Approve/reject",
|
||||
"applies_to": "All visible UI components"
|
||||
},
|
||||
{
|
||||
"id": "TEST-005",
|
||||
"rule": "Documentation",
|
||||
"requirement": "JSDoc comments for public APIs and complex logic",
|
||||
"pattern": "/**\n * Load project data from API\n * @param {string} projectId - The project identifier\n * @returns {Promise<Project>} The loaded project\n * @throws {Error} If project not found or network error\n */\nasync loadProject(projectId) { ... }",
|
||||
"applies_to": ["Public component methods", "Utility functions", "Store APIs"]
|
||||
},
|
||||
{
|
||||
"id": "TEST-006",
|
||||
"rule": "Code Review Checklist",
|
||||
"requirement": "All PRs reviewed against these standards",
|
||||
"checklist": [
|
||||
"✓ Shadow DOM used for all components",
|
||||
"✓ No inline styles or event handlers",
|
||||
"✓ Proper accessibility attributes",
|
||||
"✓ Event listeners cleaned up",
|
||||
"✓ User input sanitized",
|
||||
"✓ Error handling implemented",
|
||||
"✓ Tests added/updated"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"enforcement": {
|
||||
"description": "How these standards are enforced in the development workflow",
|
||||
"mechanisms": [
|
||||
{
|
||||
"type": "Pre-commit Hooks",
|
||||
"file": ".git/hooks/pre-commit",
|
||||
"action": "Runs scripts/verify-quality.sh automatically",
|
||||
"can_bypass": "git commit --no-verify (requires justification)"
|
||||
},
|
||||
{
|
||||
"type": "Quality Verification Script",
|
||||
"file": "scripts/verify-quality.sh",
|
||||
"checks": [
|
||||
"Inline event handlers detection",
|
||||
"Inline styles counting",
|
||||
"Missing ARIA attributes",
|
||||
"Console.log statements",
|
||||
"JavaScript syntax validation",
|
||||
"Hardcoded secrets detection",
|
||||
"Shadow DOM usage statistics",
|
||||
"File size warnings"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "Immutability Protection",
|
||||
"file": ".clauderc",
|
||||
"protection": "This file listed in protected_core_files",
|
||||
"requirement": "ALLOW_CORE_CHANGES=true to modify"
|
||||
},
|
||||
{
|
||||
"type": "AI Agent Instructions",
|
||||
"description": "AI assistants programmed to follow these standards",
|
||||
"behavior": [
|
||||
"Always use Shadow DOM for components",
|
||||
"Never generate inline event handlers",
|
||||
"Extract inline styles to style blocks",
|
||||
"Add proper accessibility attributes",
|
||||
"Use logger instead of console.log"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"migration_strategy": {
|
||||
"description": "How to migrate existing code to these standards",
|
||||
"phases": [
|
||||
{
|
||||
"phase": 1,
|
||||
"name": "Foundation Fixes",
|
||||
"duration": "Week 1",
|
||||
"priority": "Critical",
|
||||
"tasks": [
|
||||
"Refactor tool-templates.js to generate compliant HTML",
|
||||
"Create logger utility (admin-ui/js/utils/logger.js)",
|
||||
"Update verify-quality.sh thresholds",
|
||||
"Create migration guide with examples"
|
||||
]
|
||||
},
|
||||
{
|
||||
"phase": 2,
|
||||
"name": "Component Migration - Batch A",
|
||||
"duration": "Week 2",
|
||||
"priority": "High",
|
||||
"targets": [
|
||||
"Layout components (ds-project-selector, ds-shell, ds-header)",
|
||||
"Most violated: ds-screenshot-gallery, ds-network-monitor"
|
||||
],
|
||||
"pattern": "Add Shadow DOM → Extract styles → Replace inline events → Add ARIA"
|
||||
},
|
||||
{
|
||||
"phase": 3,
|
||||
"name": "Component Migration - Batch B",
|
||||
"duration": "Week 3",
|
||||
"priority": "High",
|
||||
"targets": [
|
||||
"Tool components (ds-activity-log, ds-test-results)",
|
||||
"Admin/listings (ds-project-list, ds-token-list)"
|
||||
]
|
||||
},
|
||||
{
|
||||
"phase": 4,
|
||||
"name": "Monolith Decomposition",
|
||||
"duration": "Week 4",
|
||||
"priority": "Critical",
|
||||
"target": "app.js (4,347 lines → 7 modules)",
|
||||
"modules": [
|
||||
"app.js: Main orchestrator (<500 lines)",
|
||||
"router.js: Hash routing",
|
||||
"auth-manager.js: Authentication",
|
||||
"api-client.js: Fetch wrapper",
|
||||
"error-handler.js: Global errors",
|
||||
"state-manager.js: State coordination",
|
||||
"init.js: Initialization"
|
||||
]
|
||||
},
|
||||
{
|
||||
"phase": 5,
|
||||
"name": "Quality Enforcement",
|
||||
"duration": "Week 5",
|
||||
"priority": "Medium",
|
||||
"tasks": [
|
||||
"Update thresholds (inline styles ≤10, events = 0)",
|
||||
"Add ESLint/Stylelint rules",
|
||||
"CI/CD integration",
|
||||
"Developer training"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"reference_implementations": {
|
||||
"description": "Examples of components that follow these standards",
|
||||
"files": [
|
||||
{
|
||||
"file": "admin-ui/js/workdesks/base-workdesk.js",
|
||||
"demonstrates": [
|
||||
"Semantic HTML (buttons not divs)",
|
||||
"Event delegation pattern",
|
||||
"Extracted styles in style block",
|
||||
"ARIA attributes",
|
||||
"Focus management"
|
||||
]
|
||||
},
|
||||
{
|
||||
"file": "admin-ui/js/components/metrics/ds-frontpage.js",
|
||||
"demonstrates": [
|
||||
"Shadow DOM implementation",
|
||||
"Zero inline styles",
|
||||
"Lifecycle management",
|
||||
"State subscription pattern",
|
||||
"Event cleanup"
|
||||
]
|
||||
},
|
||||
{
|
||||
"file": "admin-ui/js/components/metrics/ds-metric-card.js",
|
||||
"demonstrates": [
|
||||
"Observable attributes",
|
||||
"Shadow DOM encapsulation",
|
||||
"Reactive rendering",
|
||||
"Component composition"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"success_metrics": {
|
||||
"description": "Measurable goals for DSS code quality",
|
||||
"current_state": {
|
||||
"shadow_dom_adoption": "23% (12/53 components)",
|
||||
"inline_event_handlers": "20+",
|
||||
"inline_styles": "1,288",
|
||||
"console_statements": "100+",
|
||||
"largest_file": "app.js at 4,347 lines / 156KB"
|
||||
},
|
||||
"target_state": {
|
||||
"shadow_dom_adoption": "100% (53/53 components)",
|
||||
"inline_event_handlers": "0 (zero tolerance)",
|
||||
"inline_styles": "<10 (dynamic values only)",
|
||||
"console_statements": "<10 (core only)",
|
||||
"largest_file": "<500 lines per file"
|
||||
},
|
||||
"tracking": {
|
||||
"method": "Pre-commit hook statistics",
|
||||
"frequency": "Every commit",
|
||||
"reporting": "Monthly code quality dashboard"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,106 +0,0 @@
|
||||
{
|
||||
"$schema": "dss-knowledge-v1",
|
||||
"type": "principles",
|
||||
"version": "1.0.0",
|
||||
"last_updated": "2025-12-07",
|
||||
"core_principles": [
|
||||
{
|
||||
"name": "Monolithic Design System Structure",
|
||||
"description": "DSS defines THE canonical design system structure. It does not change.",
|
||||
"structure": {
|
||||
"tokens": ["colors", "spacing", "typography", "borders", "shadows", "motion"],
|
||||
"components": ["Button", "Input", "Card", "..."],
|
||||
"patterns": ["forms", "navigation", "layouts"]
|
||||
},
|
||||
"rule": "This structure is sacred. External systems adapt to us, not the reverse."
|
||||
},
|
||||
{
|
||||
"name": "Translation Dictionaries (Per-Project)",
|
||||
"description": "Each client project maintains a Translation Dictionary that maps their legacy tokens/styles to DSS canonical tokens",
|
||||
"schema": "dss-translation-v1",
|
||||
"mapping_types": ["tokens", "components", "patterns"],
|
||||
"custom_props_namespace": "Isolated namespace for client-specific properties"
|
||||
},
|
||||
{
|
||||
"name": "Custom Props Strategy",
|
||||
"description": "When a client needs something outside DSS core",
|
||||
"rules": [
|
||||
"Never modify DSS core - The canonical structure stays intact",
|
||||
"Add to project's custom namespace - color.brand.{client}.*",
|
||||
"Create Storybook template for custom case",
|
||||
"Document in translation dictionary"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "Multi-System Ingestion Flow",
|
||||
"description": "All external systems translate TO DSS canonical format",
|
||||
"sources": ["Figma", "Legacy CSS", "shadcn", "HeroUI", "Tailwind"],
|
||||
"flow": [
|
||||
"Source tokens extracted",
|
||||
"Translation layer maps to DSS canonical",
|
||||
"Custom props identified and isolated",
|
||||
"Mappings stored in translation dictionary",
|
||||
"DSS core (immutable) + Project custom props",
|
||||
"Output: Storybook, token files, component library"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "Storybook Strategy",
|
||||
"description": "Separate core stories from client-specific stories",
|
||||
"structure": {
|
||||
"core": "DSS canonical components (never modified)",
|
||||
"clients": "Custom variations in /stories/clients/{client}/",
|
||||
"templates": "Edge cases, specific customizations"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "Component Extension Model",
|
||||
"description": "Clients extend/wrap DSS components, never modify core",
|
||||
"pattern": "Client wraps DSS component with additional props",
|
||||
"example": "AcmeButton extends Button with acmeIcon, acmeTracking props"
|
||||
},
|
||||
{
|
||||
"name": "Token Merge System",
|
||||
"description": "Intelligent token merging from multiple sources with conflict resolution",
|
||||
"strategies": [
|
||||
"FIRST: Keep first occurrence",
|
||||
"LAST: Override with latest",
|
||||
"PREFER_FIGMA: Prioritize Figma source",
|
||||
"PREFER_CODE: Prioritize CSS/SCSS",
|
||||
"PREFER_SPECIFIC: Prefer concrete values over references",
|
||||
"MERGE_METADATA: Combine metadata, use latest value"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "UI Library Atomic Structure Comparison",
|
||||
"description": "Different UI libraries use fundamentally different atomic structures. DSS normalizes them all",
|
||||
"comparisons": {
|
||||
"HeroUI": {
|
||||
"color_system": "Numeric scales (50-900)",
|
||||
"granularity": "HIGH (10 shades)",
|
||||
"translation": "Direct 1:1 mapping, strip prefix"
|
||||
},
|
||||
"shadcn": {
|
||||
"color_system": "Semantic pairs",
|
||||
"granularity": "LOW (2 values)",
|
||||
"translation": "Expand semantic to scale"
|
||||
},
|
||||
"Legacy_CSS": {
|
||||
"color_system": "Inconsistent",
|
||||
"granularity": "VARIES",
|
||||
"translation": "Normalize chaos to canonical format"
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"translation_dictionary_schema": {
|
||||
"$schema": "dss-translation-v1",
|
||||
"required_fields": ["project", "source", "mappings"],
|
||||
"optional_fields": ["version", "custom_props", "unmapped", "notes"],
|
||||
"mapping_structure": {
|
||||
"tokens": "source-token -> dss-canonical-token",
|
||||
"components": "source-component -> dss-component[variant]",
|
||||
"patterns": "source-pattern -> dss-pattern"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,500 +0,0 @@
|
||||
{
|
||||
"$schema": "dss-knowledge-v1",
|
||||
"type": "mcp_tools",
|
||||
"version": "1.0.0",
|
||||
"last_updated": null,
|
||||
"architecture": "MCP-first - All work via MCP tools, no REST endpoints",
|
||||
"tools": [
|
||||
{
|
||||
"name": "dss_analyze_project",
|
||||
"description": "Analyze a project for design system patterns, component usage, and tokenization opportunities. Returns comprehensive analysis including style patterns, React components, and dependency graph.",
|
||||
"category": "project_management",
|
||||
"parameters": [
|
||||
"path",
|
||||
"type",
|
||||
"description"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "dss_extract_tokens",
|
||||
"description": "Extract design tokens from CSS, SCSS, Tailwind, or JSON sources. Returns a unified TokenCollection with all discovered tokens.",
|
||||
"category": "token_ingestion",
|
||||
"parameters": [
|
||||
"path",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 714
|
||||
},
|
||||
{
|
||||
"name": "dss_generate_theme",
|
||||
"description": "Generate theme files from design tokens using style-dictionary. Supports CSS, SCSS, JSON, and JS output formats.",
|
||||
"category": "utilities",
|
||||
"parameters": [
|
||||
"tokens",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 719
|
||||
},
|
||||
{
|
||||
"name": "dss_list_themes",
|
||||
"description": "List all available themes in the DSS system",
|
||||
"category": "utilities",
|
||||
"parameters": [
|
||||
"format",
|
||||
"type",
|
||||
"enum",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 725
|
||||
},
|
||||
{
|
||||
"name": "dss_get_status",
|
||||
"description": "Get DSS system status including health checks, dependencies, configuration, metrics, and recommendations.",
|
||||
"category": "utilities",
|
||||
"parameters": [
|
||||
"format",
|
||||
"type",
|
||||
"enum",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 727
|
||||
},
|
||||
{
|
||||
"name": "dss_audit_components",
|
||||
"description": "Audit React components for design system adoption. Identifies hardcoded values, missing tokens, and refactoring opportunities.",
|
||||
"category": "analysis",
|
||||
"parameters": [
|
||||
"path",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 729
|
||||
},
|
||||
{
|
||||
"name": "dss_setup_storybook",
|
||||
"description": "Set up or configure Storybook for the project. Generates stories and theme configuration.",
|
||||
"category": "storybook",
|
||||
"parameters": [
|
||||
"path",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 731
|
||||
},
|
||||
{
|
||||
"name": "dss_sync_figma",
|
||||
"description": "Sync design tokens from a Figma file. Requires FIGMA_TOKEN environment variable.",
|
||||
"category": "figma_integration",
|
||||
"parameters": [
|
||||
"file_key",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 736
|
||||
},
|
||||
{
|
||||
"name": "dss_find_quick_wins",
|
||||
"description": "Find quick win opportunities for design system adoption. Identifies low-effort, high-impact improvements.",
|
||||
"category": "utilities",
|
||||
"parameters": [
|
||||
"path",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 738
|
||||
},
|
||||
{
|
||||
"name": "dss_transform_tokens",
|
||||
"description": "Transform tokens between formats using style-dictionary",
|
||||
"category": "token_ingestion",
|
||||
"parameters": [
|
||||
"tokens",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 740
|
||||
},
|
||||
{
|
||||
"name": "devtools_launch",
|
||||
"description": "Launch a new headless Chromium browser. Use this on remote/headless servers where no Chrome is running.",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"url",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 747
|
||||
},
|
||||
{
|
||||
"name": "devtools_connect",
|
||||
"description": "Connect to a running Chrome browser with remote debugging enabled. Start Chrome with: --remote-debugging-port=9222",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"port",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 752
|
||||
},
|
||||
{
|
||||
"name": "devtools_disconnect",
|
||||
"description": "Disconnect from Chrome DevTools and clean up resources.",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"page_id",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 757
|
||||
},
|
||||
{
|
||||
"name": "devtools_list_pages",
|
||||
"description": "List all available pages (tabs) in the connected browser with their URLs and titles.",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"page_id",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 759
|
||||
},
|
||||
{
|
||||
"name": "devtools_select_page",
|
||||
"description": "Set the active page for subsequent DevTools operations. Console and network logging will be enabled for the selected page.",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"page_id",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 761
|
||||
},
|
||||
{
|
||||
"name": "devtools_console_logs",
|
||||
"description": "Retrieve captured console log messages (log, warn, error, info, debug) from the active page.",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"level",
|
||||
"type",
|
||||
"enum",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 763
|
||||
},
|
||||
{
|
||||
"name": "devtools_network_requests",
|
||||
"description": "Retrieve captured network requests from the active page. Includes URL, method, headers, and resource type.",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"filter_url",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 769
|
||||
},
|
||||
{
|
||||
"name": "devtools_evaluate",
|
||||
"description": "Execute a JavaScript expression in the context of the active page and return the result.",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"expression",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 774
|
||||
},
|
||||
{
|
||||
"name": "devtools_query_dom",
|
||||
"description": "Query DOM elements on the active page using a CSS selector. Returns tag, text content, and outer HTML for each match.",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"selector",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 776
|
||||
},
|
||||
{
|
||||
"name": "devtools_goto",
|
||||
"description": "Navigate the active page to a URL.",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"url",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 778
|
||||
},
|
||||
{
|
||||
"name": "devtools_screenshot",
|
||||
"description": "Capture a screenshot of the active page or a specific element. Returns base64 encoded PNG.",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"selector",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 783
|
||||
},
|
||||
{
|
||||
"name": "devtools_performance",
|
||||
"description": "Get performance metrics for the active page including page load time, DNS lookup, TCP connect, and response times.",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"mode",
|
||||
"type",
|
||||
"enum",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 788
|
||||
},
|
||||
{
|
||||
"name": "browser_init",
|
||||
"description": "Initialize browser automation. Mode ",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"mode",
|
||||
"type",
|
||||
"enum",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 791
|
||||
},
|
||||
{
|
||||
"name": "browser_get_logs",
|
||||
"description": "Get console logs from the browser. Works in both LOCAL and REMOTE modes.",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"level",
|
||||
"type",
|
||||
"enum",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 798
|
||||
},
|
||||
{
|
||||
"name": "browser_screenshot",
|
||||
"description": "Capture a screenshot from the browser. Requires LOCAL mode.",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"selector",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 803
|
||||
},
|
||||
{
|
||||
"name": "browser_dom_snapshot",
|
||||
"description": "Get current DOM state as HTML. Works in both LOCAL and REMOTE modes.",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"limit",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 808
|
||||
},
|
||||
{
|
||||
"name": "browser_get_errors",
|
||||
"description": "Get captured errors (uncaught exceptions, unhandled rejections). Works in both modes.",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"limit",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 810
|
||||
},
|
||||
{
|
||||
"name": "browser_accessibility_audit",
|
||||
"description": "Run accessibility audit using axe-core. Returns WCAG violations and passes.",
|
||||
"category": "analysis",
|
||||
"parameters": [
|
||||
"selector",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 814
|
||||
},
|
||||
{
|
||||
"name": "browser_performance",
|
||||
"description": "Get Core Web Vitals and performance metrics (TTFB, FCP, LCP, CLS).",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"manifest_path",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 818
|
||||
},
|
||||
{
|
||||
"name": "browser_close",
|
||||
"description": "Close the browser automation session and clean up resources.",
|
||||
"category": "browser_tools",
|
||||
"parameters": [
|
||||
"manifest_path",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 820
|
||||
},
|
||||
{
|
||||
"name": "dss_get_resolved_context",
|
||||
"description": "Get fully resolved design system context for a project. Returns compiled tokens from 3-layer cascade (base \u2192 skin \u2192 project).",
|
||||
"category": "context_compiler",
|
||||
"parameters": [
|
||||
"manifest_path",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 823
|
||||
},
|
||||
{
|
||||
"name": "dss_resolve_token",
|
||||
"description": "Resolve a specific design token through the cascade. Use dot-notation (e.g. ",
|
||||
"category": "token_ingestion",
|
||||
"parameters": [
|
||||
"manifest_path",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 840
|
||||
},
|
||||
{
|
||||
"name": "dss_validate_manifest",
|
||||
"description": "Validate project manifest (ds.config.json) against schema.",
|
||||
"category": "utilities",
|
||||
"parameters": [
|
||||
"manifest_path",
|
||||
"type",
|
||||
"description"
|
||||
],
|
||||
"handler_line": 857
|
||||
},
|
||||
{
|
||||
"name": "dss_list_skins",
|
||||
"description": "List all available design system skins in the registry.",
|
||||
"category": "utilities",
|
||||
"parameters": [],
|
||||
"handler_line": 870
|
||||
},
|
||||
{
|
||||
"name": "dss_get_compiler_status",
|
||||
"description": "Get Context Compiler health and configuration status.",
|
||||
"category": "context_compiler",
|
||||
"parameters": [],
|
||||
"handler_line": 883
|
||||
}
|
||||
],
|
||||
"architecture_benefits": [
|
||||
"No REST endpoints - All work via MCP tools",
|
||||
"User-level credentials - Figma tokens stored per-user in database",
|
||||
"Manifest-driven - figma.json declares project dependencies",
|
||||
"Versionable - Manifests can be checked into git",
|
||||
"Discoverable - Claude can list available Figma files",
|
||||
"Audit trail - All operations logged in mcp_tool_usage",
|
||||
"Circuit breaker - Protected against cascading API failures",
|
||||
"Encrypted storage - Credentials encrypted with Fernet"
|
||||
],
|
||||
"context_compiler_tools": [
|
||||
{
|
||||
"name": "dss_get_resolved_context",
|
||||
"description": "Get fully resolved design system context for a project. Returns compiled tokens from 3-layer cascade (base \u2192 skin \u2192 project)",
|
||||
"parameters": [
|
||||
"manifest_path",
|
||||
"debug",
|
||||
"force_refresh"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "dss_resolve_token",
|
||||
"description": "Resolve a specific design token through the cascade. Use dot-notation (e.g. 'colors.primary')",
|
||||
"parameters": [
|
||||
"manifest_path",
|
||||
"token_path",
|
||||
"force_refresh"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "dss_validate_manifest",
|
||||
"description": "Validate project manifest (ds.config.json) against schema",
|
||||
"parameters": [
|
||||
"manifest_path"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "dss_list_skins",
|
||||
"description": "List all available design system skins in the registry",
|
||||
"parameters": []
|
||||
},
|
||||
{
|
||||
"name": "dss_get_compiler_status",
|
||||
"description": "Get Context Compiler health and configuration status",
|
||||
"parameters": []
|
||||
}
|
||||
],
|
||||
"total_tools": 35,
|
||||
"categories": {
|
||||
"project_management": [
|
||||
"dss_analyze_project"
|
||||
],
|
||||
"token_ingestion": [
|
||||
"dss_extract_tokens",
|
||||
"dss_transform_tokens",
|
||||
"dss_resolve_token"
|
||||
],
|
||||
"utilities": [
|
||||
"dss_generate_theme",
|
||||
"dss_list_themes",
|
||||
"dss_get_status",
|
||||
"dss_find_quick_wins",
|
||||
"dss_validate_manifest",
|
||||
"dss_list_skins"
|
||||
],
|
||||
"analysis": [
|
||||
"dss_audit_components",
|
||||
"browser_accessibility_audit"
|
||||
],
|
||||
"storybook": [
|
||||
"dss_setup_storybook"
|
||||
],
|
||||
"figma_integration": [
|
||||
"dss_sync_figma"
|
||||
],
|
||||
"browser_tools": [
|
||||
"devtools_launch",
|
||||
"devtools_connect",
|
||||
"devtools_disconnect",
|
||||
"devtools_list_pages",
|
||||
"devtools_select_page",
|
||||
"devtools_console_logs",
|
||||
"devtools_network_requests",
|
||||
"devtools_evaluate",
|
||||
"devtools_query_dom",
|
||||
"devtools_goto",
|
||||
"devtools_screenshot",
|
||||
"devtools_performance",
|
||||
"browser_init",
|
||||
"browser_get_logs",
|
||||
"browser_screenshot",
|
||||
"browser_dom_snapshot",
|
||||
"browser_get_errors",
|
||||
"browser_performance",
|
||||
"browser_close"
|
||||
],
|
||||
"context_compiler": [
|
||||
"dss_get_resolved_context",
|
||||
"dss_get_compiler_status"
|
||||
]
|
||||
},
|
||||
"_metadata": {
|
||||
"generator": "MCPExtractor",
|
||||
"generated_at": "2025-12-07T18:27:49.701717",
|
||||
"source_files": [
|
||||
"/home/overbits/dss/dss-claude-plugin/servers/dss-mcp-server.py"
|
||||
],
|
||||
"version": "1.0.0"
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user