Files

tegwick b6f95066a3 chore: establish schema-of-schemas workplan and reorganize roadmap

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>

2026-01-04 23:47:02 +01:00

2.6 KiB

Raw Blame History

Schema-of-Schemas Implementation

Project: Markdown-First Schema System Status: Planning → Implementation Timeline: 8-10 days

Quick Links

WORKPLAN.md - Detailed implementation plan with phases
SCHEMA_MANAGEMENT_PROPOSAL.md - Full analysis and options
SCHEMA_MANAGEMENT_SUMMARY.md - Executive summary

What We're Building

Goals

✅ Filename convention: {domain}-schema-v{version}.md
✅ Markdown-first schema format (documentation + embedded JSON)
✅ Schema-for-schemas to validate all schemas
✅ Migrate existing schemas to new format
✅ 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

Phase 0: Planning & Setup (0.5 days) ← Current
Phase 1: Filename Convention (1 day)
Phase 2: Markdown Loader (2-3 days)
Phase 3: Schema-for-Schemas (2 days)
Phase 4: Schema Migration (1-2 days)
Phase 5: CLI & Docs (1 day)
Phase 6: Testing (1 day)

Current Status

Completed

Directory structure created
Planning documents moved to roadmap
Comprehensive workplan written
Example markdown schema created

Next Steps

Complete Phase 0 planning artifacts
Begin Phase 1 implementation
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:

---
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.

2.6 KiB Raw Blame History