-
Notifications
You must be signed in to change notification settings - Fork 35
Closed as not planned
0 / 10 of 1 issue completedClosed as not planned
0 / 10 of 1 issue completed
Copy link
Labels
Description
Overview
This tracking issue covers improvements to schema metadata and documentation quality identified in the December 29, 2025 schema audit.
Source: Discussion #8130
The audit identified 8 issues (2 critical, 6 moderate) across our three schema files. While internal consistency is excellent (100% root descriptions, all $defs used, strong validation), we need to improve metadata and example coverage for better IDE integration and developer experience.
Planned Tasks
This work is broken down into 5 focused sub-issues:
- Add top-level metadata to all schemas - Critical for IDE integration and schema identification
- Add applyTo field description - Complete missing root-level documentation
- Add examples to major workflow fields - Improve discoverability of key features
- Add examples to MCP schema - Currently has zero examples despite complexity
- Improve schema validation constraints - Convert single-value enums and add format constraints
Context
All identified issues have persisted since the November 2025 audit (no regression, but no improvement either). These improvements will:
- Enhance IDE autocomplete and inline documentation
- Support schema versioning and evolution tracking
- Improve developer onboarding and discoverability
- Strengthen validation with better constraints
Priority
- Critical (sub-issues rejig docs #1-2): Core metadata and documentation gaps
- Medium (sub-issues Add workflow: githubnext/agentics/weekly-research #3-4): Developer experience improvements
- Low (sub-issue Add workflow: githubnext/agentics/weekly-research #5): Schema quality refinements
AI generated by Plan Command for discussion #8130
Copilot