Repository navigation
docs: evaluate @objectstack/spec metadata types and add Phase 10.5 Deep Metadata Adoption roadmap - #163
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…ata Adoption roadmap Evaluated all @objectstack/spec application-level schemas (28 used of ~80 available, 35% adoption). Identified 27 high-value unused schemas across UI, Automation, AI, Security, and System subpaths. Added Phase 10.5 with 4 sub-phases: Reports/Views/Charts, Flows/MCP/AI, Security/Notifications, Tests/Docs. Updated roadmap.mdx with condensed Phase 10.5 summary and evaluation highlights. Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR adds a comprehensive metadata evaluation and introduces Phase 10.5 (Deep Metadata Adoption) to the HotCRM roadmap. The evaluation reveals that HotCRM currently uses only 28 of ~80 application-level schemas (35%) from @objectstack/spec v3.0.0. The PR identifies 27 high-value unused schemas across three priority tiers and creates a detailed 12-week implementation plan to raise adoption to 69% before the planned Phase 11 ecosystem expansion.
Changes:
- Added comprehensive metadata type evaluation documenting all 28 currently-used schemas and gap analysis of 39 unused schemas across 3 priority tiers (P0/P1/P2)
- Introduced Phase 10.5 roadmap with 4 sub-phases focusing on reports, advanced views, flows, MCP tools, RLS policies, email templates, and scheduled jobs
- Updated Phase 11 timeline and metrics to account for Phase 10.5 preceding it, including baseline adjustments for "before" metrics
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| ROADMAP.md | Added 320+ lines of metadata evaluation (currently used schemas, 3-tier gap analysis), Phase 10.5 detailed task breakdown across 4 sub-phases (10.5A-D), updated Phase 11 baseline metrics, and version history entry |
| content/docs/roadmap.mdx | Added condensed Phase 10.5 section with schema adoption table, tier summary, and expected outcomes; updated Phase 11 metrics to reflect post-10.5 baseline |
| - [ ] Add `packages/crm/src/crm_actions.action_ui.ts` — Quick actions: "Log a Call", "Convert Lead", "Create Follow-up Task", "Send Quote" | ||
| - [ ] Add `packages/finance/src/finance_actions.action_ui.ts` — Quick actions: "Create Invoice", "Record Payment", "Send Reminder" | ||
| - [ ] Add `packages/support/src/support_actions.action_ui.ts` — Quick actions: "Escalate Case", "Merge Cases", "Create Knowledge Article" |
There was a problem hiding this comment.
The file naming convention .action_ui.ts uses an underscore, which deviates from the existing pattern where all file suffixes use dots as separators (e.g., .object.ts, .page.ts). This creates inconsistency with the established naming convention.
Consider using .action.ui.ts or a different suffix that follows the dot-separated pattern. Additionally, the existing .action.ts suffix already exists for "API Endpoints & AI Tools" according to the coding guidelines, so clarify how .action_ui.ts differs and update the guidelines accordingly.
| - [ ] Add `packages/crm/src/crm_actions.action_ui.ts` — Quick actions: "Log a Call", "Convert Lead", "Create Follow-up Task", "Send Quote" | |
| - [ ] Add `packages/finance/src/finance_actions.action_ui.ts` — Quick actions: "Create Invoice", "Record Payment", "Send Reminder" | |
| - [ ] Add `packages/support/src/support_actions.action_ui.ts` — Quick actions: "Escalate Case", "Merge Cases", "Create Knowledge Article" | |
| - [ ] Add `packages/crm/src/crm_actions.action.ui.ts` — Quick actions: "Log a Call", "Convert Lead", "Create Follow-up Task", "Send Quote" | |
| - [ ] Add `packages/finance/src/finance_actions.action.ui.ts` — Quick actions: "Create Invoice", "Record Payment", "Send Reminder" | |
| - [ ] Add `packages/support/src/support_actions.action.ui.ts` — Quick actions: "Escalate Case", "Merge Cases", "Create Knowledge Article" |
| ``` | ||
| 2025 ████████████████████████████████ Phases 1-9: Foundation → AI → Quality → Test → Integration → Schema → v3.0 → UI → DX | ||
| 2026 Q1-Q2 ████████████████████████████████ Phase 10: Salesforce Feature Parity ✅ COMPLETE | ||
| 2026 Q3-Q4 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Phase 11: Ecosystem & Connectivity ← NEXT | ||
| 2026 Q1-Q2 ████████████████████████████████ Phase 10: Salesforce Feature Parity ✅ COMPLETE | ||
| 2026 Q2-Q3 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Phase 10.5: Deep Metadata Adoption ← NEXT | ||
| 2026 Q3-Q4 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Phase 11: Ecosystem & Connectivity | ||
| 2027 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Phase 12: Vertical Solutions & Advanced AI |
There was a problem hiding this comment.
There is a timeline overlap between Phase 10.5 and Phase 11. Phase 10.5 is scheduled for Q2-Q3 2026 (ending in Q3), while Phase 11 is scheduled for Q3-Q4 2026 (starting in Q3). This creates ambiguity about when Phase 10.5 ends and Phase 11 begins.
Consider adjusting the timeline to eliminate overlap. For example:
- Phase 10.5: Q2 2026 (April-June)
- Phase 11: Q3-Q4 2026 (July-December)
Or clarify that Phase 11 begins in late Q3 2026 after Phase 10.5 completes.
| 2026 ████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Deep Metadata Adoption → Ecosystem & Connectivity ← YOU ARE HERE | ||
| 2027 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Vertical Solutions & Advanced AI | ||
| ``` |
There was a problem hiding this comment.
The timeline shows overlap between Phase 10.5 (Q2-Q3 2026) and Phase 11 (Q3-Q4 2026). This creates ambiguity about the schedule and when each phase begins/ends.
Consider clarifying the timeline to show when Phase 10.5 completes and Phase 11 begins, ensuring phases don't overlap unless parallel execution is intended and explicitly documented.
| - [ ] Add `packages/crm/src/pipeline_report.report.ts` — Sales pipeline report (stage breakdown, win rate, average deal size) | ||
| - [ ] Add `packages/crm/src/forecast_report.report.ts` — Revenue forecast report (by period, rep, territory) | ||
| - [ ] Add `packages/finance/src/revenue_report.report.ts` — Revenue recognition report (ASC 606 compliance, deferred/recognized) | ||
| - [ ] Add `packages/finance/src/ar_aging_report.report.ts` — Accounts receivable aging report | ||
| - [ ] Add `packages/hr/src/headcount_report.report.ts` — Headcount analytics (by department, location, tenure) | ||
| - [ ] Add `packages/marketing/src/campaign_roi_report.report.ts` — Campaign ROI report (spend vs revenue, attribution) | ||
| - [ ] Add `packages/products/src/product_mix_report.report.ts` — Product mix analysis (revenue by product, discount analysis) | ||
| - [ ] Add `packages/support/src/case_volume_report.report.ts` — Case volume report (by priority, category, SLA compliance) | ||
| - [ ] Validate all reports with `ReportSchema.parse()` — 100% spec compliance |
There was a problem hiding this comment.
The proposed file naming convention .report.ts is not documented in the project's coding guidelines. The coding guidelines specify established file suffixes (*.object.ts, *.page.ts, *.view.ts, *.dashboard.ts, *.workflow.ts, etc.), but .report.ts is a new extension that hasn't been added to the official file suffix protocol.
Before implementing Phase 10.5, the coding guidelines should be updated to document all new file naming conventions being introduced. This ensures consistency and helps developers understand the file organization protocol.
| - [ ] Add `packages/crm/src/pipeline_funnel.chart.ts` — Sales funnel chart (Lead → Qualified → Proposal → Closed) | ||
| - [ ] Add `packages/crm/src/revenue_trend.chart.ts` — Monthly revenue trend line chart | ||
| - [ ] Add `packages/finance/src/cash_flow.chart.ts` — Cash flow waterfall chart | ||
| - [ ] Add `packages/support/src/case_resolution.chart.ts` — Case resolution time distribution chart | ||
| - [ ] Add `packages/marketing/src/channel_performance.chart.ts` — Marketing channel performance bar chart | ||
| - [ ] Add `packages/hr/src/attrition_trend.chart.ts` — Employee attrition trend chart | ||
| - [ ] Validate all charts with `ChartConfigSchema.parse()` — 100% spec compliance |
There was a problem hiding this comment.
The proposed file naming convention .chart.ts is not documented in the project's coding guidelines. The coding guidelines specify established file suffixes, but .chart.ts is a new extension that hasn't been added to the official file suffix protocol.
All new file naming conventions introduced in Phase 10.5 (.report.ts, .chart.ts, .action_ui.ts, .widget.ts, .flow.ts, .mcp.ts, .orchestration.ts, .predictive.ts, .connector.ts, .security.ts, .notification.ts, .schedule.ts) should be documented in the coding guidelines before implementation to maintain consistency across the codebase.
Description
Audited all @objectstack/spec v3.0.0 application-level metadata schemas. HotCRM currently uses 28 of ~80 relevant schemas (35%). Identified 27 high-value unused schemas and created Phase 10.5 to raise adoption to 69% before the Phase 11 ecosystem expansion.
Type of Change
Related Issues
Changes Made
ROADMAP.md:
Metadata Type Evaluationsection: full inventory of 28 used schemas, 3-tier gap analysis (P0/P1/P2) with business justification per unused schemaPhase 10.5: Deep Metadata Adoption(Q2-Q3 2026) with 4 sub-phases:ReportSchema), advanced views (Kanban/Calendar/Gantt viaListViewSchema), charts (ChartConfigSchema), UI actions, widgetsFlowSchema), full MCP stack (MCPToolSchema/MCPResourceSchema/MCPPromptSchema), AI orchestration, predictive models, connectorsRowLevelSecurityPolicySchema), password/session policies, email templates (EmailTemplateSchema), notification channels, scheduled jobsSpec Schema Adoptionrow), Phase 11 outcomes, version historycontent/docs/roadmap.mdx:
Key gap findings:
ReportSchema,ListViewSchema(Kanban/Calendar/Gantt),ChartConfigSchemaFlowSchema,ConnectorSchema,ETLPipelineSchemaMCPToolSchema,MCPResourceSchema,MCPPromptSchema,AIOrchestrationSchemaRowLevelSecurityPolicySchema,PolicySchemaEmailTemplateSchema,NotificationChannelSchema,ScheduleSchema,JobSchemaTesting
npm test)npm run lint)npm run build)TypeScript compilation verified clean (
tsc --noEmit— zero errors). Documentation-only changes, no runtime impact.Screenshots
Checklist
Additional Notes
The spec exposes ~1,269 total schemas across 12 subpaths, but most are internal/transport types (API request/response envelopes). The ~80 figure represents application-level metadata schemas that define business configurations, UI layouts, automations, security policies, and AI capabilities — the ones HotCRM should care about.
Original prompt
💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.