coulomb/markitect-main
2
0
Fork 0
Code Issues 60 Pull Requests Actions Projects 12 Releases 1 Wiki Activity
Files
b6f95066a357a2d91d123316ef829f854b5821fc
markitect-main/TODO.md
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

6.4 KiB
Raw Blame History

Todofile

This is a "to do next" file, particularly useful to keep the human and a coding assistant in sync.

The format is based on Keep a Todofile V0.0.1.

The structure organizes future tasks by their impact, just as a changelog organizes past changes by their impact.

[Unreleased] - Active Vibe-Coding State 💡

This section is for tasks currently being discussed with or worked on by the coding assistant. These are the ephemeral, flow-of-thought tasks.

Schema-of-Schemas Implementation (Active - Phase 1)

Status: Phase 1 - Filename Convention & Validation (In Progress) Workplan: See roadmap/schema-of-schemas/WORKPLAN.md

Current Goals:

  1. ✅ Establish naming convention: {domain}-schema-v{major}.{minor}.md
  2. 🔄 Implement filename validation logic
  3. 🔄 Update CLI with validation
  4. ⏳ Create markdown schema loader
  5. ⏳ Build schema-for-schemas metaschema
  6. ⏳ Migrate existing schemas to new format

Phase 1 Tasks (Current):

  • Write markitect/schema_naming.py with validation logic
  • Add unit tests for filename validation
  • Update schema-ingest command with validation
  • Create SCHEMA_NAMING_SPEC.md documentation

Next Phases:

  • Phase 2: Markdown Schema Loader (2-3 days)
  • Phase 3: Schema-for-Schemas Metaschema (2 days)
  • Phase 4: Schema Migration (1-2 days)
  • Phase 5: CLI & Documentation Updates (1 day)
  • Phase 6: Testing & Validation (1 day)

Expected Completion: 8-10 days total

Extract Capability-Capability from Issue-Facade (Paused)

Context: Issue-facade currently provides two capabilities:

  1. issue-tracking (explicit in CAPABILITY-issue-tracking.yaml) - Issue management across platforms
  2. capability-capability (implicit) - Patterns and tools for creating/managing capabilities

The capability-capability includes:

  • Feedback pattern (feedback/ directory, .capability/feedback CLI tool, documentation)
  • Detachment facility (.capability/detach script for clean capability removal)
  • Integration pattern (.capability/integrate.sh for project integration)
  • CAPABILITY-*.yaml specification format
  • ReusableCapabilitiesArchitecture.md (complete specification)
  • Directory conventions (_family/implementation, visible/hidden patterns)

Goal: Extract capability-capability to separate reusable-capability repository so it can be used by any capability in the markitect ecosystem.

Approach: Step-by-step extraction, starting with specification.

Phase 1: Specification & Planning (Current)

  • Create CAPABILITY-capability.yaml in issue-facade to explicitly declare the implicit capability
  • Define what belongs to capability-capability family vs issue-tracking family
  • Document the capability-capability API surface (what tools/patterns it provides)
  • Identify all files/directories to extract
  • Plan extraction strategy (copy vs move, how to maintain during transition)

Phase 2: Repository Creation

  • Create reusable-capability repository structure
  • Extract ReusableCapabilitiesArchitecture.md to new repo
  • Extract feedback pattern (directory structure, CLI tool, README)
  • Extract detachment facility (.capability/detach)
  • Extract integration scripts (.capability/integrate.sh, integration-checklist.md)
  • Create CAPABILITY-capability.yaml in new repo (canonical version)
  • Add README.md for reusable-capability repo

Phase 3: Integration & Testing

  • Update issue-facade to depend on reusable-capability (as integrated capability)
  • Integrate reusable-capability into issue-facade using _capability/reusable-capability pattern
  • Test that issue-facade still works with extracted capability
  • Update issue-facade documentation to reference both capabilities it provides/uses
  • Verify feedback system still works
  • Verify detachment still works

Phase 4: Dogfooding & Validation

  • Choose another markitect capability for dogfooding
  • Integrate reusable-capability into that capability
  • Add feedback system to new capability
  • Add detachment facility to new capability
  • Document learnings and refine reusable-capability based on real-world usage
  • Update ReusableCapabilitiesArchitecture.md with insights

Current Step: Phase 1, Task 1 - Create CAPABILITY-capability.yaml

Completed Tasks

Recent completed tasks have been documented in _issue-tracking/issue-facade/CHANGELOG.md following Keep a Changelog format.

2026-01-04 - Phase 2: Schema Refinement Tools & Terminology Example

  • ✅ Implemented schema-analyze command to detect rigidity issues
  • ✅ Implemented schema-refine command with automatic loosening logic
  • ✅ Added interactive mode to schema-refine for fine-grained control
  • ✅ Created comprehensive test suite (33 unit tests, 100% passing)
  • ✅ Wrote user guide documentation with examples and workflows
  • ✅ Successfully tested on example schemas (reduced rigidity from 60/100 to 24/100)
  • ✅ Integrated into CLI with proper exit codes and error handling
  • ✅ Moved SCHEMA_EVOLUTION_WORKPLAN.md to todo/ directory
  • ✅ Created terminology validation example (examples/terminology/)

Key Features Delivered:

  • Rigidity score calculation (0-100 scale)
  • Automatic detection of exact counts, const values, overly specific numbers
  • Path navigation for nested schema properties
  • Dry-run mode for previewing changes
  • Interactive approval workflow
  • Comprehensive reporting (normal and verbose modes)

Terminology Example:

  • Complete terminology document structure (terminology-example.md)
  • JSON schema with MarkiTect extensions (terminology-schema.json)
  • Demonstrates schema usage for non-manpage documents
  • Validates term definitions, synonyms, related terms, examples
  • Includes content control and validation rules
  • Full documentation and usage examples (README.md)

2025-12-17 - Architecture Refactoring

  • ✅ Implemented ReusableCapabilitiesArchitecture v0.1
  • ✅ Added feedback capability to issue-facade
  • ✅ Created detachment facility
  • ✅ Refactored to family-based directory structure (_issue-tracking/issue-facade)
  • ✅ Made feedback directory visible (feedback/ not .feedback/)
  • ✅ Renamed to explicit family declaration (CAPABILITY-issue-tracking.yaml)
  • ✅ Created CHANGELOG.md documenting v1.0.0
Reference in New Issue View Git Blame Copy Permalink