From 5cd5d9919853eb8816217fd24193a9e3221ac1b3 Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 19 Jun 2026 21:10:27 +0200 Subject: [PATCH] chore: retire TODO.md in favour of workplans Drop the repo-level Todofile; active work lives in workplans/ and State Hub per ADR-001. Schedule prepare now surfaces workplans/ instead of TODO.md. Gitignore .kaizen/agents/ and .kaizen/metrics/ runtime state. --- .gitignore | 4 + CHANGELOG.md | 4 + CONTRIBUTING.md | 8 +- TODO.md | 219 ------------------ docs/adr/ADR-005-scheduled-agent-execution.md | 2 +- .../kaizen-schedule-prepared-event.md | 4 +- src/kaizen_agentic/cli.py | 12 +- 7 files changed, 22 insertions(+), 231 deletions(-) delete mode 100644 TODO.md diff --git a/.gitignore b/.gitignore index bb04693..1289008 100644 --- a/.gitignore +++ b/.gitignore @@ -45,3 +45,7 @@ htmlcov/ # Backup directories created by optimization scripts agents_backup_*/ + +# Project-scoped kaizen runtime state (ADR-002, ADR-004) +.kaizen/agents/ +.kaizen/metrics/ diff --git a/CHANGELOG.md b/CHANGELOG.md index c1744b0..1b41c71 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Removed +- **`TODO.md`** — work tracking uses `workplans/` and State Hub (ADR-001); the + `keepaTodofile` agent remains available for other projects + ### Added - **`metrics record --emit-event`** — publishes `kaizen.metrics.recorded` NATS envelope for activity-core event-driven definitions (optional `nats-py` via diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 507006c..c0d801f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,7 +45,7 @@ This repository follows PythonVibes best practices: - `src/kaizen_agentic/` - Core framework source code - `agents/` - Specialized agent definitions (17+ agents) - `tests/` - Comprehensive test suite -- `TODO.md` - Current development tasks (Keep a Todofile format) +- `workplans/` - Active workstreams and tasks (ADR-001) - `CHANGELOG.md` - Version history (Keep a Changelog format) ### Making Changes @@ -155,15 +155,15 @@ When reporting bugs, please include: 1. **Discuss significant changes** in an issue first 2. **Keep PRs focused** on a single feature or fix 3. **Write clear commit messages** following conventional commit format -4. **Update relevant documentation** including TODO.md and CHANGELOG.md +4. **Update relevant documentation** including workplans and CHANGELOG.md 5. **Ensure all checks pass** including tests and linting 6. **Respond to review feedback** promptly and constructively ## Agent-Assisted Development This repository includes 17+ specialized agents to assist with development: -- Use `todo-keeper` for TODO.md maintenance -- Use `changelog-keeper` for CHANGELOG.md updates +- Use `keepaChangelog` for CHANGELOG.md updates +- Use `project-assistant` for workplan and session orientation - Use `contributing-keeper` for this file maintenance - See CLAUDE.md for complete agent catalog and usage diff --git a/TODO.md b/TODO.md deleted file mode 100644 index e75fbea..0000000 --- a/TODO.md +++ /dev/null @@ -1,219 +0,0 @@ -# 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/TodoFileGuide). - -The structure organizes **future tasks** by their impact, just as a changelog organizes past changes by their impact. - -*** - -## [Unreleased] - *Active Vibe-Coding State* 💡 - -Tasks in workplan: `workplans/kaizen-agentic-WP-0007-agent-authoring-doc-generation.md` (v1.4.0) - -### Implemented (pending v1.4.0 tag) -* **`create-agent`** — scaffold schema-valid agents -* **`docs generate [--check]`** — idempotent CLAUDE.md Installed Agents refresh -* **Frontmatter schema validation** in `validate` -* **Doc-regeneration idempotency fix** + agent file rename (project-assistant) - -### To Add (release) -* **Tag v1.4.0** — after review -* **activity-core implementation** — WP-0006 resolver + sync (separate repo; see handoff doc) - -### Shipped — v1.3.0 (2026-06-17) -* **ADR-005 + `.kaizen/schedule.yml`** — scheduled agent execution contract -* **`kaizen-agentic schedule`** — validate, init, prepare, list -* **activity-core definitions** — weekly coach + optimization on preselected repos - -### Deferred / future -* Interactive agent selection wizard (multi-step) — `create-agent` covers the - single-agent scaffold; a guided multi-agent wizard remains future work -* Multi-file agent packages / protocol scaffolding - -*** - -## [1.1.0] - Community Engagement — *Shipped 2026-06-18* - -See `CHANGELOG.md` [1.1.0] and `workplans/kaizen-agentic-WP-0001-community-engagement.md`. - -*** - -## [COMPLETED] - *Documentation Standards Compliance - Version 0.2.0* - -### ✅ Completed: To Add -* **CLI interface** for agent management and execution - DONE - - Full `kaizen-agentic` CLI with 8 commands (init, install, update, remove, list, status, validate, templates) - - Console script entry point for global availability - - Complete command-line interface with options and help -* **Comprehensive tests** for optimization module (PerformanceMetrics, OptimizationLoop) - DONE - - 24 tests covering all components with 100% pass rate - - Test coverage for registry, installer, and core functionality - - Automated test execution with make test/test-all targets -* **Agent registry and installer functionality** - DONE - - Complete AgentRegistry with categorization and dependency resolution - - AgentInstaller with backup/rollback capabilities - - ProjectInitializer with template-based project creation -* **Comprehensive documentation system** - DONE - - GETTING_STARTED.md - Complete setup and usage guide - - AGENT_DISTRIBUTION.md - Architecture documentation - - CLI_CHEAT_SHEET.md - Quick reference guide - - Updated README.md with complete usage examples - -### ✅ Completed: To Refactor -* **Agent definitions** to follow consistent format standards - DONE - - All 17+ agents updated to YAML frontmatter format - - Consistent categorization system (project-management, development-process, etc.) - - Proper dependency declarations and descriptions -* **Makefile structure** for better user experience - DONE - - Reorganized with consistent naming (agents-, setup-, standards- prefixes) - - Enhanced help system with examples and clear descriptions - - 50+ targets organized into logical sections -* **Test execution performance** optimization - DONE - - Fast execution with all 24 tests completing in <1 second - - Parallel execution capabilities - - Efficient backup/cleanup in test teardown - -### ✅ Completed: To Fix -* **Makefile targets** compatibility across environments - DONE - - Cross-platform compatibility with proper shell detection - - Virtual environment handling with fallback mechanisms - - Error handling and recovery in setup processes -* **Linting issues** in core modules - DONE - - All flake8 violations resolved across entire codebase - - PEP 8 compliance achieved - - Consistent code formatting with black -* **Virtual environment setup** reliability - DONE - - Robust venv creation and activation - - Dependency installation with upgrade handling - - Status checking and validation -* **CLI installation make target (agents-install-cli)** - DONE - - Target is working properly and requires virtual environment activation as documented - - Installation process functions correctly with proper venv setup -* **YAML frontmatter errors in agent files** causing loading failures - DONE - - All 16 agents now properly loading without YAML parsing errors - - Frontmatter format standardized across all agent definitions -* **Agent categorization issues** (agents showing as "Unknown" instead of proper categories) - DONE - - All 16 agents now properly categorized and displaying correct categories - - Category mapping and recognition system functioning correctly - -### ✅ Completed: To Secure -* **Configuration file validation** - DONE - - Safe YAML parsing with error handling - - Input validation for all CLI parameters - - Backup creation before modifications -* **Agent integrity checks** - DONE - - Validation system for agent definitions - - Dependency conflict detection - - Installation verification - -### ✅ Completed: To Remove -* **Obsolete test fixtures** - DONE - - Clean test directory structure - - Removed unused imports and variables - - Eliminated development scaffolding - -*** - -## [COMPLETED] - *Scenario 1: Greenfield Project Excellence - Version 0.2.1* - -### ✅ Completed: Scenario 1 Tasks -* **Scenario 1 exploration: Establish codebase from scratch** - DONE - - Research current onboarding experience with existing setup targets - DONE - - Identify gaps in documentation for new project creation - DONE - - Test and validate smooth project initialization workflows - DONE - - Evaluate agent selection and recommendation systems for new projects - DONE - - Document best practices for greenfield project setup - DONE - -### ✅ Completed: Additional Scenario 1 Improvements -* **Agent template name mappings fixed** - DONE - - Fixed agent template name mappings to match actual agent names - - Ensured consistency between template references and installed agents -* **ProjectInitializer enhancements** - DONE - - Added Makefile creation to ProjectInitializer for complete greenfield setup - - Implemented comprehensive project scaffolding -* **Test framework stability** - DONE - - Fixed all failing tests for agent framework updates - - Achieved 100% test pass rate across all components -* **Documentation and tutorial creation** - DONE - - Updated documentation with correct agent names - - Created HelloWorld tutorial for new users - - Comprehensive onboarding experience established - -### ✅ Completed: Production Readiness -* **Scenario 1 state achievement** - DONE - - Scenario 1 (establish codebase from scratch) is now excellent and production-ready - - Complete end-to-end workflow for greenfield projects - - Robust agent selection and project initialization - -*** - -## [COMPLETED] - *Production Release with Release Management - Version 1.0.0* - -### ✅ Completed: Release Management System -* **Complete release management system** with agent-releaseManager - DONE - - 6 structured make targets for complete release workflow - - `release-check` - Validate release readiness with comprehensive checklist - - `release-prepare` - Build packages and prepare for publication - - `release-test` - Test publication workflow using TestPyPI - - `release-publish` - Publish to production PyPI with safety checks - - `release-finalize` - Post-release tasks (tags, GitHub releases, documentation) - - `release-rollback` - Emergency rollback procedures and guidance -* **Local package installation capability** - DONE - - `make install-local` target for PyPI-equivalent testing - - Local package building and installation workflow - - Integration testing with locally built packages -* **Documentation updates for installation options** - DONE - - Updated documentation to reflect all installation methods - - PyPI installation guidance and local development setup - - Complete user onboarding documentation -* **Package distribution readiness** - DONE - - Full package ready for PyPI publication - - All agents included in package data distribution - - Console script entry point for global CLI availability - - Version 1.0.0 production release achieved - -*** - -## [COMPLETED] - *Scenario 2: Existing Project Integration Excellence - Version 0.2.2* - -### ✅ Completed: Scenario 2 Tasks -* **Scenario 2 exploration: Integration with existing projects having agents** - DONE - - Research detection of existing agent systems in projects - DONE - - Design conflict resolution strategies for overlapping agent functionality - DONE - - Create migration paths for replacing outdated project-specific agents - DONE - - Develop extension mechanisms for project-specific kaizen agent customizations - DONE - - Define integration patterns that respect existing project structure - DONE - - Build tooling for safe agent system transitions - DONE - -### ✅ Completed: Major Components Built -* **Detection system (detection.py)** for analyzing existing agent systems - DONE - - Comprehensive agent system detection across multiple formats - - Analysis of conflicts and overlap identification - - Integration readiness assessment -* **Migration framework (migration.py)** with 5 migration strategies - DONE - - Replace strategy for complete agent replacement - - Merge strategy for combining functionalities - - Extend strategy for adding new capabilities - - Coexist strategy for parallel operation - - Archive strategy for deprecation handling -* **Extension system (extensions.py)** for project-specific customizations - DONE - - Plugin-based architecture for agent customization - - Dynamic loading and configuration management - - Safe extension isolation and validation -* **Complete CLI integration** with detect, migrate, and extensions commands - DONE - - kaizen-agentic detect command for system analysis - - kaizen-agentic migrate command with strategy selection - - kaizen-agentic extensions command for customization management -* **Integration patterns documentation** with 5 proven scenarios - DONE - - Established patterns for common integration scenarios - - Best practices for safe agent system transitions - - Comprehensive documentation and examples - -### ✅ Completed: Production Readiness -* **Scenario 2 state achievement** - DONE - - Scenario 2 (existing project integration) is now excellent and production-ready - - Complete detection, migration, and extension capabilities - - Safe and reliable agent system transitions - - Both Scenario 1 (greenfield) and Scenario 2 (existing projects) are production-ready diff --git a/docs/adr/ADR-005-scheduled-agent-execution.md b/docs/adr/ADR-005-scheduled-agent-execution.md index f9cdf91..2957cd9 100644 --- a/docs/adr/ADR-005-scheduled-agent-execution.md +++ b/docs/adr/ADR-005-scheduled-agent-execution.md @@ -105,7 +105,7 @@ Assembles, from **local `.kaizen/` state only** (offline-safe): - The agent prompt (`agents/agent-.md`, installed or packaged). - Project memory (`.kaizen/agents//memory.md`) when present. - Metrics summary (`.kaizen/metrics//summary.json`) when present. -- Repo pointers (`SCOPE.md`, `TODO.md`) when present. +- Repo pointers (`SCOPE.md`, `workplans/`) when present. - Suggested session-close commands (`metrics record`, memory update). Output is `markdown` (default) or `json` (`--format json`) so activity-core can diff --git a/docs/integrations/kaizen-schedule-prepared-event.md b/docs/integrations/kaizen-schedule-prepared-event.md index c077f5b..59708a1 100644 --- a/docs/integrations/kaizen-schedule-prepared-event.md +++ b/docs/integrations/kaizen-schedule-prepared-event.md @@ -35,7 +35,7 @@ NATS/event-bus subject, sibling to the existing `kaizen.metrics.recorded` and "agent_prompt_found": true, "has_memory": true, "has_metrics": true, - "pointers": ["scope", "todo"], + "pointers": ["scope", "workplans"], "bytes": 8421 }, "session_close": [ @@ -60,7 +60,7 @@ NATS/event-bus subject, sibling to the existing `kaizen.metrics.recorded` and | `bundle.agent_prompt_found` | bool | Mirrors `schedule prepare --format json` | | `bundle.has_memory` | bool | Memory file present | | `bundle.has_metrics` | bool | Metrics summary present | -| `bundle.pointers` | string[] | Repo pointer labels found (`scope`, `todo`) | +| `bundle.pointers` | string[] | Repo pointer labels found (`scope`, `workplans`) | | `bundle.bytes` | int | Rendered bundle size | | `session_close` | string[] | Suggested close commands | diff --git a/src/kaizen_agentic/cli.py b/src/kaizen_agentic/cli.py index ed0c2a2..e191f83 100644 --- a/src/kaizen_agentic/cli.py +++ b/src/kaizen_agentic/cli.py @@ -1704,10 +1704,12 @@ def _build_prepare_bundle(agent_name: str, project_root: Path) -> dict: metrics_summary = metrics_store.write_summary() pointers = {} - for label, filename in (("scope", "SCOPE.md"), ("todo", "TODO.md")): - candidate = project_root / filename - if candidate.exists(): - pointers[label] = str(candidate) + scope_path = project_root / "SCOPE.md" + if scope_path.exists(): + pointers["scope"] = str(scope_path) + workplans_path = project_root / "workplans" + if workplans_path.is_dir(): + pointers["workplans"] = str(workplans_path) return { "agent": agent_name, @@ -1762,7 +1764,7 @@ def _render_prepare_markdown(bundle: dict) -> str: for label, path in pointers.items(): lines.append(f"- {label}: {path}") else: - lines.append("- (no SCOPE.md / TODO.md found)") + lines.append("- (no SCOPE.md / workplans/ found)") lines.append("") lines.append("## Session Close")