tegwick
b6f95066a3
This commit sets up the comprehensive workplan for implementing a
markdown-first schema management system with naming conventions,
versioning, and self-validation capabilities.
## Directory Reorganization
- Renamed `todo/` → `roadmap/` for better organization
- Created `roadmap/schema-of-schemas/` subdirectory
- Moved schema management planning artifacts to dedicated directory
## Planning Artifacts Created
### Workplan & Documentation
- **WORKPLAN.md** (19KB) - Comprehensive 6-phase implementation plan
- **SCHEMA_MANAGEMENT_PROPOSAL.md** - Full analysis with 4 options
- **SCHEMA_MANAGEMENT_SUMMARY.md** - Executive summary
- **README.md** - Quick reference guide
### Example Schema
- **examples/schemas/manpage-schema-v1.md** - Demonstrates markdown format
## Schema Management System Design
### Naming Convention
**Format:** `{domain}-schema-v{major}.{minor}.md`
**Examples:**
- `manpage-schema-v1.0.md`
- `terminology-schema-v1.0.md`
- `api-documentation-schema-v1.0.md`
### Markdown-First Format
Schemas will be markdown files with:
- YAML frontmatter for metadata
- Rich documentation sections
- Embedded JSON schema in code block
- Version history and examples
### Implementation Phases (8-10 days)
**Phase 0:** Planning & Setup ✅ (0.5 days) - COMPLETE
**Phase 1:** Filename Convention (1 day) - NEXT
**Phase 2:** Markdown Loader (2-3 days)
**Phase 3:** Schema-for-Schemas (2 days)
**Phase 4:** Schema Migration (1-2 days)
**Phase 5:** CLI & Documentation (1 day)
**Phase 6:** Testing & Validation (1 day)
### Goals
1. ✅ Establish naming convention
2. ⏳ Implement filename validation
3. ⏳ Create markdown schema loader
4. ⏳ Build schema-for-schemas metaschema
5. ⏳ Migrate 5 existing schemas (remove 2 duplicates)
6. ⏳ Update CLI and documentation
## Updated Tracking
### TODO.md
- Added Schema-of-Schemas as active work item
- Documented Phase 1 tasks and timeline
- Paused capability extraction work
### CHANGELOG.md
- Added schema management system to [Unreleased]
- Documented directory reorganization
- Added "In Progress" section for current work
## Next Steps
Begin Phase 1:
1. Implement schema_naming.py with validation
2. Add unit tests
3. Update CLI schema-ingest command
4. Create naming specification document
## Files Changed
- CHANGELOG.md - Added unreleased schema management features
- TODO.md - Updated active work tracking
- roadmap/ - Reorganized from todo/
- roadmap/schema-of-schemas/ - New planning directory
- examples/schemas/ - Example markdown schema
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
95 lines
2.6 KiB
Markdown
95 lines
2.6 KiB
Markdown
# Schema-of-Schemas Implementation
|
|
|
|
**Project:** Markdown-First Schema System
|
|
**Status:** Planning → Implementation
|
|
**Timeline:** 8-10 days
|
|
|
|
## Quick Links
|
|
|
|
- **[WORKPLAN.md](./WORKPLAN.md)** - Detailed implementation plan with phases
|
|
- **[SCHEMA_MANAGEMENT_PROPOSAL.md](./SCHEMA_MANAGEMENT_PROPOSAL.md)** - Full analysis and options
|
|
- **[SCHEMA_MANAGEMENT_SUMMARY.md](./SCHEMA_MANAGEMENT_SUMMARY.md)** - Executive summary
|
|
|
|
## What We're Building
|
|
|
|
### Goals
|
|
1. ✅ Filename convention: `{domain}-schema-v{version}.md`
|
|
2. ✅ Markdown-first schema format (documentation + embedded JSON)
|
|
3. ✅ Schema-for-schemas to validate all schemas
|
|
4. ✅ Migrate existing schemas to new format
|
|
5. ✅ Clean up duplicate/legacy schemas
|
|
|
|
### Why
|
|
- **Consistency:** Enforced naming and versioning
|
|
- **Alignment:** Markdown-first matches MarkiTect philosophy
|
|
- **Documentation:** Rich docs alongside schemas
|
|
- **Validation:** Schema-for-schemas ensures quality
|
|
- **Maintainability:** Clear versions and structure
|
|
|
|
## Implementation Phases
|
|
|
|
1. **Phase 0:** Planning & Setup (0.5 days) ← **Current**
|
|
2. **Phase 1:** Filename Convention (1 day)
|
|
3. **Phase 2:** Markdown Loader (2-3 days)
|
|
4. **Phase 3:** Schema-for-Schemas (2 days)
|
|
5. **Phase 4:** Schema Migration (1-2 days)
|
|
6. **Phase 5:** CLI & Docs (1 day)
|
|
7. **Phase 6:** Testing (1 day)
|
|
|
|
## Current Status
|
|
|
|
### Completed
|
|
- [x] Directory structure created
|
|
- [x] Planning documents moved to roadmap
|
|
- [x] Comprehensive workplan written
|
|
- [x] Example markdown schema created
|
|
|
|
### Next Steps
|
|
1. Complete Phase 0 planning artifacts
|
|
2. Begin Phase 1 implementation
|
|
3. Checkpoint review after Phase 1
|
|
|
|
## Key Decisions
|
|
|
|
### Naming Convention
|
|
**Format:** `{domain}-schema-v{major}.{minor}.md`
|
|
**Example:** `manpage-schema-v1.0.md`
|
|
|
|
### Schema Format
|
|
**Markdown with embedded JSON:**
|
|
```markdown
|
|
---
|
|
schema-id: "https://markitect.dev/schemas/manpage/v1"
|
|
version: "1.0.0"
|
|
---
|
|
|
|
# Manpage Schema v1.0
|
|
|
|
[Documentation...]
|
|
|
|
## Schema Definition
|
|
|
|
```json
|
|
{ ... JSON schema ... }
|
|
```
|
|
```
|
|
|
|
### Schema Migration Plan
|
|
```
|
|
Old → New
|
|
──────────────────────────────────────────────────
|
|
terminology-schema.json → terminology-schema-v1.0.md
|
|
api-documentation → api-documentation-schema-v1.0.md
|
|
enhanced-manpage → manpage-schema-v2.0.md
|
|
markdown-manpage → REMOVE (duplicate)
|
|
markdown-manpage-schema.json → REMOVE (duplicate)
|
|
```
|
|
|
|
## Progress Tracking
|
|
|
|
Track progress in: `roadmap/schema-of-schemas/IMPLEMENTATION_LOG.md` (to be created)
|
|
|
|
## Questions?
|
|
|
|
See the full workplan for detailed implementation steps, risks, and mitigation strategies.
|