tegwick
da34303057
Created detailed user guide for schema refinement tools: - Command reference for schema-analyze and schema-refine - Complete options and examples - Issue type explanations with before/after examples - Workflow guides (basic, interactive, CI/CD, migration) - Best practices and troubleshooting - Integration examples (Git hooks, Makefile, Python) - Rigidity score interpretation table Updated TODO.md to mark Phase 2 completion: - Documented all delivered features - Listed key capabilities (rigidity detection, auto-refine, interactive mode) - Noted test coverage (33 tests, 100% passing) - Added example results (60/100 → 24/100 rigidity reduction) Phase 2 is now complete and fully documented. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
4.9 KiB
4.9 KiB
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.
- the file TODO.html is legacy i think and can be removed
Extract Capability-Capability from Issue-Facade
Context: Issue-facade currently provides two capabilities:
- issue-tracking (explicit in CAPABILITY-issue-tracking.yaml) - Issue management across platforms
- 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
- ✅ 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
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)
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