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

@@ -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/

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

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 `keepaChangelog` for CHANGELOG.md updates
-- Use `changelog-keeper` 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
 

TODO.md

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

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-<name>.md`, installed or packaged).
 - Project memory (`.kaizen/agents/<name>/memory.md`) when present.
 - Metrics summary (`.kaizen/metrics/<name>/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

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 |
 

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")):
+    scope_path = project_root / "SCOPE.md"
-        candidate = project_root / filename
+    if scope_path.exists():
-        if candidate.exists():
+        pointers["scope"] = str(scope_path)
-            pointers[label] = str(candidate)
+    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")