From fba16f0c132c4b720d1731b00c1e2b8a8a0e550e Mon Sep 17 00:00:00 2001 From: Leo Miranda Date: Mon, 26 Jan 2026 16:23:09 +0000 Subject: [PATCH] Add "Sprint-1-viz-platform-Implementation-Plan" --- ...nt-1-viz-platform-Implementation-Plan.-.md | 267 ++++++++++++++++++ 1 file changed, 267 insertions(+) create mode 100644 Sprint-1-viz-platform-Implementation-Plan.-.md diff --git a/Sprint-1-viz-platform-Implementation-Plan.-.md b/Sprint-1-viz-platform-Implementation-Plan.-.md new file mode 100644 index 0000000..9568b1b --- /dev/null +++ b/Sprint-1-viz-platform-Implementation-Plan.-.md @@ -0,0 +1,267 @@ +# Sprint 1: viz-platform Plugin Implementation Plan + +**Milestone:** Sprint 1 - viz-platform Plugin +**Created:** 2026-01-26 +**Status:** Planning Complete +**Reference:** `docs/changes/CHANGE_V04_0_0_PROPOSAL_ORIGINAL.md` (Phases 4-5) + +--- + +## Sprint Overview + +Implement the viz-platform plugin with DMC component validation and visualization capabilities. + +### Scope + +| Component | Count | Description | +|-----------|-------|-------------| +| MCP Server | 1 | `mcp-servers/viz-platform/` | +| Tools | 15 | DMC (3), Chart (2), Layout (3), Theme (4), Page (3) | +| Commands | 7 | `/chart`, `/dashboard`, `/theme`, `/component`, etc. | +| Agents | 3 | theme-setup, layout-builder, component-check | + +### Key Decisions + +| Decision | Choice | Rationale | +|----------|--------|-----------| +| Component Registry | Static JSON | Fast, deterministic, offline-capable | +| Data Sharing | Claude passes inline | Simplest for v1, no shared state | +| Theme Storage | User + Project level | Project takes precedence | + +--- + +## Issues Created + +| # | Title | Type | Priority | Effort | Dependencies | +|---|-------|------|----------|--------|--------------| +| #170 | Create viz-platform MCP server foundation | feat | High | M | None | +| #171 | Implement DMC component registry with static JSON | feat | High | L | #170 | +| #172 | Implement DMC validation tools (3 tools) | feat | High | M | #170, #171 | +| #173 | Implement chart tools (2 tools) | feat | High | M | #170 | +| #174 | Implement layout tools (3 tools) | feat | Medium | M | #170 | +| #175 | Implement theme tools (4 tools) | feat | High | L | #170 | +| #176 | Implement page tools (3 tools) | feat | Medium | M | #170, #174 | +| #177 | Create viz-platform plugin structure | feat | High | S | #170 | +| #178 | Create viz-platform commands (7 commands) | feat | Medium | S | #177 | +| #179 | Create viz-platform agents (3 agents) | feat | Medium | M | #177, #172, #175 | +| #180 | Create viz-platform documentation | docs | Medium | M | #177 | +| #181 | Add viz-platform to marketplace | feat | High | S | ALL | +| #182 | Create viz-platform MCP server tests | test | Medium | L | #170-#175 | + +**Total Issues:** 13 + +--- + +## Dependency Graph + +``` +#170 (Foundation) + ├── #171 (Registry) ──► #172 (DMC Tools) + ├── #173 (Chart Tools) + ├── #174 (Layout Tools) ──► #176 (Page Tools) + ├── #175 (Theme Tools) + └── #177 (Plugin Structure) + ├── #178 (Commands) + ├── #179 (Agents) ◄── #172, #175 + └── #180 (Documentation) + +#182 (Marketplace Integration) ◄── ALL ISSUES + +#182 (Tests) ◄── #170, #171, #172, #173, #175 +``` + +--- + +## Execution Order (Parallel Batches) + +### Batch 1 (Foundation) +- #170: MCP server foundation + +### Batch 2 (Core Tools - can run in parallel) +- #171: Component registry +- #173: Chart tools +- #174: Layout tools +- #175: Theme tools + +### Batch 3 (Dependent Tools) +- #172: DMC validation tools (needs #171) +- #176: Page tools (needs #174) +- #177: Plugin structure (needs #170) + +### Batch 4 (Plugin Integration) +- #178: Commands (needs #177) +- #179: Agents (needs #177, #172, #175) +- #180: Documentation (needs #177) + +### Batch 5 (Testing) +- #182: Tests (needs core tools) + +### Batch 6 (Final) +- #181: Marketplace integration (needs ALL) + +--- + +## Technical Architecture + +### MCP Server Structure + +``` +mcp-servers/viz-platform/ +├── mcp_server/ +│ ├── __init__.py +│ ├── server.py # Entry point +│ ├── config.py # DMC version detection +│ ├── component_registry.py # Static JSON loader +│ ├── dmc_tools.py # list_components, get_component_props, validate_component +│ ├── chart_tools.py # chart_create, chart_configure_interaction +│ ├── layout_tools.py # layout_create, layout_add_filter, layout_set_grid +│ ├── theme_tools.py # theme_create, theme_extend, theme_validate, theme_export_css +│ ├── theme_store.py # Theme persistence +│ └── page_tools.py # page_create, page_add_navbar, page_set_auth +├── registry/ +│ └── dmc_0.14.json # Version-locked component definitions +├── scripts/ +│ └── generate-dmc-registry.py +├── tests/ +├── requirements.txt +└── pyproject.toml +``` + +### Plugin Structure + +``` +plugins/viz-platform/ +├── .claude-plugin/ +│ └── plugin.json +├── .mcp.json +├── mcp-servers/ +│ └── viz-platform -> ../../../mcp-servers/viz-platform +├── commands/ +│ ├── initial-setup.md +│ ├── chart.md +│ ├── dashboard.md +│ ├── theme.md +│ ├── theme-new.md +│ ├── theme-css.md +│ └── component.md +├── agents/ +│ ├── theme-setup.md +│ ├── layout-builder.md +│ └── component-check.md +├── hooks/ +│ └── hooks.json +├── README.md +└── claude-md-integration.md +``` + +--- + +## Tool Specifications + +### DMC Tools (Constraint Layer) + +| Tool | Input | Output | +|------|-------|--------| +| `list_components` | `category?: string` | Component names by category | +| `get_component_props` | `component: string` | Props schema with types/defaults | +| `validate_component` | `component: string, props: object` | `{valid, errors[], warnings[]}` | + +### Chart Tools + +| Tool | Input | Output | +|------|-------|--------| +| `chart_create` | `chart_type, data, options?` | Plotly figure JSON | +| `chart_configure_interaction` | `figure_ref, interactions` | Updated figure JSON | + +### Layout Tools + +| Tool | Input | Output | +|------|-------|--------| +| `layout_create` | `name, template?` | Layout reference | +| `layout_add_filter` | `layout_ref, filter_type, options` | Updated layout | +| `layout_set_grid` | `layout_ref, grid` | Updated layout | + +### Theme Tools + +| Tool | Input | Output | +|------|-------|--------| +| `theme_create` | `name, tokens` | Theme reference | +| `theme_extend` | `base_theme, overrides` | New theme reference | +| `theme_validate` | `theme_name` | Validation report | +| `theme_export_css` | `theme_name` | CSS custom properties | + +### Page Tools + +| Tool | Input | Output | +|------|-------|--------| +| `page_create` | `name, path, layout_ref?` | Page reference | +| `page_add_navbar` | `pages[], options` | Navbar component | +| `page_set_auth` | `page_ref, auth_config` | Updated page | + +--- + +## Design Token Structure + +```yaml +tokens: + colors: + primary: "#228be6" + secondary: "#868e96" + background: + base: "#ffffff" + subtle: "#f8f9fa" + text: + primary: "#212529" + muted: "#868e96" + spacing: + xs: "4px" + sm: "8px" + md: "16px" + lg: "24px" + typography: + fontFamily: "Inter, sans-serif" + fontSize: + sm: "14px" + md: "16px" + radii: + sm: "4px" + md: "8px" +``` + +--- + +## Success Criteria + +- [ ] MCP server starts without errors +- [ ] All 15 tools registered and functional +- [ ] Component registry loads for DMC 0.14.x +- [ ] `validate_component` catches invalid props +- [ ] Theme tokens apply to charts +- [ ] All 7 commands work via slash commands +- [ ] All 3 agents trigger correctly +- [ ] Plugin passes `./scripts/validate-marketplace.sh` +- [ ] Tests pass with >70% coverage +- [ ] Documentation complete + +--- + +## Cross-Plugin Integration + +After Sprint 1, projects can define cross-plugin agents in their CLAUDE.md: + +```markdown +| Agent | Sequence | +|-------|----------| +| dashboard_builder | pg_query → pandas.pivot → dmc.validate → chart_create → layout_create | +| visualization_prep | pg_query → pandas.reshape → chart_create | +``` + +--- + +## Next Sprint Preview + +**Sprint 2: contract-validator Plugin** +- Validates cross-plugin compatibility +- Parses plugin READMEs for interfaces +- Validates Claude.md agent definitions +- 3 commands, 2 agents, no MCP server