From c5f49b2dd09cbe872339447dfd2246101a12264c Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 25 Oct 2025 02:48:45 +0200 Subject: [PATCH] feat: implement todofile system and retire NEXT.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace NEXT.md approach with standardized Keep a Todofile V0.0.1 format for better task management and human-AI collaboration during coding sessions. ## Todofile System Setup: - **TODO.md**: Main todofile following Keep a Todofile V0.0.1 format - **TODOFILE_GUIDE.md**: Comprehensive system documentation and workflow - **Integration**: Fully integrated with existing kaizen-agentic framework - **Agent Support**: Uses agent-keepaTodofile for maintenance ## Content Migration: - Migrated strategic priorities from NEXT.md to TODO.md [Unreleased] section - Preserved session success criteria and development milestones - Organized tasks by impact type (To Add, To Fix, To Refactor) - Archived NEXT.md to history/NEXT_archived_20251025.md ## Documentation Updates: - README.md: Updated "Next Actions" → "Current Tasks" link - agent-project-management.md: Updated workflow to use TODO.md - docs/README.md: Updated project management references - Added comprehensive TODOFILE_GUIDE.md ## Benefits: - **Standardized Format**: Industry-standard Keep a Todofile format - **Better Organization**: Impact-based task categorization - **AI-Ready**: Designed for human-AI collaboration workflows - **Context Preservation**: Maintains coding flow across session interruptions - **Integration Ready**: Works with existing agent and capability systems Active tasks now in TODO.md [Unreleased] section focusing on strategic issue resolution and capability management validation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CHANGELOG.md | 18 ++++ README.md | 2 +- TODO.md | 101 +++++++++++++++++++ TODOFILE_GUIDE.md | 81 +++++++++++++++ agents/agent-project-management.md | 4 +- docs/README.md | 2 +- NEXT.md => history/NEXT_archived_20251025.md | 0 7 files changed, 204 insertions(+), 4 deletions(-) create mode 100644 TODO.md create mode 100644 TODOFILE_GUIDE.md rename NEXT.md => history/NEXT_archived_20251025.md (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 68cb8c1b..e26fdf83 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added +- **Kaizen-Agentic Framework Integration** as external capability submodule +- **Test Reorganization by Capability** with separated test targets for better modularity +- **Comprehensive Capability Inclusion Management System** with automated discovery tools + +### Changed +- **Capability Directory Reorganization** - moved all external dependencies to `capabilities/` directory +- **Issue Management Migration** - replaced local issue system with external `issue-facade` submodule +- **Project Structure Optimization** - established clear separation between capabilities and core documentation +- **Test Architecture Enhancement** - separated capability-specific tests from core system tests +- **Makefile Test Targets** - added granular test execution with `make test-capabilities` and capability-specific targets + +### Improved +- **Logical Organization** - capabilities/ for external dependencies, wiki/ for project documentation at root +- **Test Performance** - core tests now exclude capability tests for faster execution +- **Development Workflow** - clear separation between internal and external capabilities +- **Documentation Ecosystem** - complete capability documentation with CAPABILITIES.md and CAPABILITY_REGISTRY.md + ## [0.2.0] - 2025-10-20 ### Added diff --git a/README.md b/README.md index 80124b3f..632acd1a 100644 --- a/README.md +++ b/README.md @@ -18,4 +18,4 @@ MarkiTect transforms markdown from plain text into intelligent, structured data **Development:** [TDD Workflow](docs/development/tdd-workflow.md) · [Contributing](#contributing) · [Capabilities Overview](CAPABILITIES.md) -**Project Status:** [Current Status](history/ProjectStatusDigest.md) · [Roadmap](history/ROADMAP.md) · [Next Actions](NEXT.md) +**Project Status:** [Current Status](history/ProjectStatusDigest.md) · [Roadmap](history/ROADMAP.md) · [Current Tasks](TODO.md) diff --git a/TODO.md b/TODO.md new file mode 100644 index 00000000..35e0322d --- /dev/null +++ b/TODO.md @@ -0,0 +1,101 @@ +# 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](https://coulomb.social/open/KeepaTodofile). + +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. + +* **To Add:** + * Complete AST Query and Analysis CLI implementation (Issue #15) + * Performance Validation CLI implementation (Issue #16) + * Enhanced discovery tools validation and refinement +* **To Refactor:** + * Update any missing links in existing documentation to new capability system + * Refine capability discovery workflow based on practical usage + * Enhance AI assistant integration with capability system +* **To Fix:** + * Validate that CAPABILITY_DOCUMENTATION_INDEX.md provides effective navigation + * Ensure all agents are aware of capability inclusion workflow + * Test automated detection prevention of code duplication +* **To Remove:** + * Retire NEXT.md file after successful todofile migration + * Clean up any outdated task management references + +*** + +## [0.3.0] - Strategic Development Execution - *Next Planned Increment* + +This version represents the next set of concrete, planned features focusing on strategic issue resolution and capability validation. + +### To Add +* **AST Query and Analysis CLI** - Complete implementation of Issue #15 with full AST parsing and analysis capabilities +* **Performance Validation CLI** - Complete implementation of Issue #16 with comprehensive performance testing and metrics +* **Enhanced Discovery Tools** - Improve `make capability-search TERM=xyz` based on real-world usage patterns +* **Capability Integration Validation** - Test framework for ensuring capability inclusion workflow effectiveness + +### To Refactor +* **Documentation Ecosystem** - Update any missing links to new capability system components +* **AI Assistant Integration** - Enhance capability reference utilization for informed decision-making +* **Workflow Optimization** - Refine capability-first development process based on practical experience + +### To Fix +* **Documentation Navigation** - Ensure CAPABILITY_DOCUMENTATION_INDEX.md provides effective project navigation +* **Agent Workflow Integration** - Validate all agents properly utilize capability inclusion workflow +* **Duplication Prevention** - Test and improve automated detection systems + +### To Secure +* **Capability Validation** - Ensure capability inclusion system maintains security best practices +* **Dependency Management** - Validate external capability references and security implications + +### To Remove +* **Legacy Task Management** - Retire NEXT.md approach in favor of standardized todofile system +* **Outdated Documentation References** - Clean up any references to deprecated task management approaches + +*** + +## [COMPLETED] - *Capability Inclusion Management System - Version 0.2.0* + +### ✅ Completed: To Add +* **Complete capability documentation ecosystem** - DONE + - CAPABILITIES.md for internal capabilities with detailed descriptions + - CAPABILITY_REGISTRY.md for external capabilities and dependencies + - CAPABILITY_DOCUMENTATION_INDEX.md for navigation and discovery + - CLAUDE_CAPABILITY_REFERENCE.md for AI assistant quick reference + - CAPABILITY_INCLUSION_GUIDE.md for workflow and best practices +* **Automated discovery tools** - DONE + - `make capability-search TERM=xyz` for capability discovery + - Prevention of code duplication through automated detection + - Enhanced agent definitions with capability inclusion workflow +* **Architectural clarity** - DONE + - Clear separation of internal vs external capabilities + - Comprehensive categorization system + - Detailed capability documentation with examples + +### ✅ Completed: To Refactor +* **Agent definitions** - DONE + - Enhanced all agents with capability inclusion workflow awareness + - Updated agent instructions to utilize capability references + - Improved AI assistant integration patterns + +### ✅ Completed: To Fix +* **Documentation ecosystem integration** - DONE + - All capability files properly interconnected + - Navigation system functional and comprehensive + - Discovery tools working effectively + +### ✅ Completed: To Secure +* **Capability validation system** - DONE + - Proper validation of capability inclusion workflow + - Security considerations for external capability references + +### ✅ Completed: To Remove +* **Code duplication risks** - DONE + - Implemented prevention mechanisms + - Automated detection and discovery systems \ No newline at end of file diff --git a/TODOFILE_GUIDE.md b/TODOFILE_GUIDE.md new file mode 100644 index 00000000..b358f537 --- /dev/null +++ b/TODOFILE_GUIDE.md @@ -0,0 +1,81 @@ +# MarkiTect Todofile System + +## Overview + +MarkiTect uses the **Keep a Todofile V0.0.1** format for task management and development coordination. This replaces the previous NEXT.md approach with a standardized todofile system that provides better structure for maintaining coding flow and AI assistant coordination. + +## Location and Format + +- **Main Todofile**: `TODO.md` in the project root +- **Format**: [Keep a Todofile V0.0.1](https://coulomb.social/open/KeepaTodofile) +- **Agent Support**: Managed by the `agent-keepaTodofile` agent in the kaizen-agentic framework + +## Structure + +The todofile is organized by **impact type** rather than arbitrary priority: + +### [Unreleased] - Active Vibe-Coding State 💡 +- **To Add**: New features, capabilities, or functionality +- **To Refactor**: Code improvements and restructuring +- **To Fix**: Bug fixes and error corrections +- **To Remove**: Features or code to eliminate + +### [Version] - Planned Increments +Organized by planned version/milestone with the same impact categories: +- **To Add**: Planned new functionality +- **To Fix**: Scheduled bug fixes +- **To Refactor**: Planned code improvements +- **To Deprecate**: Features marked for future removal +- **To Secure**: Security improvements +- **To Remove**: Planned removals + +## Integration with Project Workflow + +### Task Management +- Use `TODO.md` for active development tasks and immediate next steps +- Link to Gitea issues for longer-term planning: `Related to issue #123` +- Update during development sessions to maintain context + +### AI Assistant Coordination +- The todofile serves as a **shared source of truth** between human developers and AI assistants +- Helps maintain context during interruptions and session transfers +- Enables consistent progress tracking and decision-making + +### Development Best Practices +1. **Update Regularly**: Maintain current state during active development +2. **Focus on Immediate**: Keep [Unreleased] section for current work +3. **Plan Versions**: Use version sections for commit boundaries +4. **Archive Completed**: Move completed items to archive sections +5. **Link Issues**: Connect todofile items to Gitea issues for full context + +## Agent Integration + +The `agent-keepaTodofile` agent provides specialized support for: +- Creating and maintaining TODO.md files following the official format +- Organizing tasks by impact type (Add, Fix, Refactor, etc.) +- Integrating with issue tracking and TDD workflows +- Maintaining coding flow and context preservation +- Converting between task management formats + +## Migration from NEXT.md + +The previous NEXT.md file has been archived to `history/NEXT_archived_YYYYMMDD.md`. All relevant content has been migrated to the new TODO.md format while preserving: +- Strategic development priorities +- Capability management workflows +- Session success criteria +- Development milestones + +## Related Documentation + +- **Agent Definition**: `agents/agent-keepaTodofile.md` - Specialized todofile management agent +- **Context Documentation**: `capabilities/kaizen-agentic/context/KeepaTodofile.md` - Detailed format specification +- **Capability Integration**: `CAPABILITY_INCLUSION_GUIDE.md` - How todofile fits with capability discovery +- **Project Management**: `agents/agent-project-management.md` - Overall project coordination + +## Benefits + +1. **Standardized Format**: Follows established Keep a Todofile conventions +2. **Better Organization**: Impact-based categorization aligns with changelog structure +3. **AI Assistant Ready**: Designed for human-AI collaboration in coding sessions +4. **Context Preservation**: Maintains coding flow across interruptions +5. **Integration Ready**: Works with existing issue management and TDD workflows \ No newline at end of file diff --git a/agents/agent-project-management.md b/agents/agent-project-management.md index 616e7cad..9230af38 100644 --- a/agents/agent-project-management.md +++ b/agents/agent-project-management.md @@ -17,7 +17,7 @@ You are the MarkiTect project assistant, specialized in providing project status - **ProjectStatusDigest.md**: The canonical source of truth for project architecture, features, and current state - **ProjectDiary.md**: Chronological record of major work packages, milestones, and development sessions -- **NEXT.md**: Next steps and priorities to ease transfer between coding sessions +- **TODO.md**: Task management and priorities following Keep a Todofile format for maintaining coding flow - **Makefile**: Provides helpers to use and improve the capabilities provided by the project **Gitea Issues**: Backlog of issues and backlog of tasks stored as issues in gitea @@ -125,7 +125,7 @@ When asked to help wrap up a development session, follow this standardized routi ### End-of-Session Checklist: 1. **Update ProjectDiary.md**: Add entry documenting progress, challenges, and achievements -2. **Update NEXT.md**: Set clear priorities and strategy for next session +2. **Update TODO.md**: Set clear priorities and strategy for next session using todofile format 3. **Update ProjectStatusDigest.md**: Refresh current status, metrics, and completed features 4. **Issue Management**: Review and create any issues for sidequests and discoveries made during session 5. **Anchor patterns**: Update this project-assistant definition with any new workflow patterns diff --git a/docs/README.md b/docs/README.md index d8f966e3..7f6b36ce 100644 --- a/docs/README.md +++ b/docs/README.md @@ -35,7 +35,7 @@ Documentation for contributors and developers extending MarkiTect. ### Project Management - [Project Status](../history/ProjectStatusDigest.md) - Current development status - [Roadmap](../history/ROADMAP.md) - Strategic development plan -- [Next Actions](../NEXT.md) - Immediate development priorities +- [Current Tasks](../TODO.md) - Task management using Keep a Todofile format ## Key Concepts diff --git a/NEXT.md b/history/NEXT_archived_20251025.md similarity index 100% rename from NEXT.md rename to history/NEXT_archived_20251025.md