cleveragents-core/implementation_plan.md

CleverAgents Implementation Plan

CRITICAL: Execute These Rules Without Exception

• Strictly adhere to guidelines in ./CONTRIBUTING.md: All rules and guidelines outlined in this file must be strictly followed at all times.
• Python implementation scope only: Every action described here pertains to building an idiomatic Python codebase that implements the CleverAgents architecture.
• NO BACKWARDS COMPATIBILITY: CleverAgents is a NEW standalone project. Do NOT maintain any backwards compatibility. No migration guides, no compatibility shims, no support for old configurations or data.
• Living document protocol: After finishing each checklist item (and its testing sub-items), immediately append every decision, discovery, open question, or deviation to this document under the matching Notes section. This plan remains the authoritative record.
• Single documentation surface: Do not create auxiliary notes elsewhere unless explicitly required. All architectural updates, troubleshooting outcomes, and contextual knowledge must flow back into this markdown file.
• Sequential discipline: Always begin with the first unchecked item in the checklist. Do not progress until that item, its documentation update, and its testing sub-items (including any spawned remediation tasks) are fully resolved.
• USE MODERN PYTHON TOOLING: This is a cutting-edge Python project that must use modern build tools and workflows. NO Makefiles, NO legacy approaches, NO helper scripts. Use Hatch exclusively for project management, nox for task automation, pyproject.toml for all configuration. Commands should be Python-native (e.g., hatch env create, nox -s test) not shell scripts or make targets. All tooling must be from the current Python ecosystem (2024+). When current tooling (such as "Behave" and "Robot Framework") can be used to solve a problem, use them rather than adding new tooling, keep it simple. NO wrapper scripts - use tools directly as designed.
• Unit + integration testing mandate: For every coding task, author or update both unit and integration tests, run them, and achieve passing results before marking the task complete. Testing subtasks are non-optional.
• Behavior-driven testing stack: Use Behave feature suites under features/ for unit-level and scenario tests and Robot Framework suites under robot/ for integration and end-to-end coverage. Keep both synchronized with the code under test and document all updates in this plan.
• Do not use pytest style unit tests: Under no circumstances should you write pytest styled unit tests, all unit tests should be Behave based (as noted in the last bullet point), which follows the Cucumber/Gherkin style of tests as seen under features/, this is why there is intentionally no tests/ folder.
• Test execution via nox: Run every unit, integration, Behave, Robot, and benchmark suite exclusively through the designated nox sessions (e.g., nox -s unit_tests, nox -s integration_tests). Do not invoke behave, robot, or similar runners directly; if a nox session is missing required tooling, add the dependency to the session before rerunning.
• Failure capture: Any Behave or Robot failure instantly spawns a new unchecked sub-item under the same step titled Fix – <short failure summary>. Document the failure context in the Notes section and resolve it before moving forward.
• Traceability requirement: When a decision impacts future work, reference the relevant functions or modules in the Notes section using the file_path:line_number pattern for fast navigation.
• unit tests coverage above 97% at all times: unit test coverage must remain above 97% at all times. Unit tests can be run with nox -e unit_tests and is run as part of the default test suite run with nox.
• must be statically typed: All code at all times must use statically typed typing and must pass the static check run with nox -e typecheck which is run as part of the default test suite with nox. Under no circumstances at no point should you ignore type checking, this means never turn it off in the config files, and never use inline comments to force an type checking error to be suppressed.
• Use existing tooling: Always prefer nox sessions over raw commands, Behave for unit tests over new frameworks, Robot for integration tests, Hatch for dependency management.
• Mock placement rule: ALL mocks, test doubles, and mock implementations MUST exist only in features/ directory. Production code in src/ and utility scripts in scripts/ must NEVER contain mock implementations, test data, or conditional testing behavior. Use dependency injection to swap implementations during tests.
• CRITICAL - Implementation Checklist Separation: The "Implementation Checklist" section MUST always remain separate and be the LAST section of this document. All development notes, design decisions, progress updates, technical details, and discoveries belong in their respective phase Notes sections (e.g., Phase 0 Notes, Phase 1 Notes, Phase 2 Notes) which appear BEFORE the Implementation Checklist. Never add content after the checklist section. The checklist is for tracking what needs to be done; the Notes sections are for documenting what was done and how.

CONTINUOUS CHECKLIST AND KNOWLEDGE STEWARDSHIP (MANDATORY)

• Immediate documentation loop: After completing any amount of work toward a checklist item, append the newly discovered information, assumptions, implementation notes, and open questions to this document before proceeding. No discovery, decision, or workaround may remain undocumented.
• Dynamic checklist maintenance: Before marking an item complete—or returning from work in progress—review all remaining checklist entries. Update their descriptions, add clarifying subtasks, and insert new entries capturing follow-on tasks, bug fixes, or future enhancements uncovered during implementation. Place new items in the phase where the work logically belongs (current or future) and note cross-phase dependencies.
• Implementation traceability: Record substantive code decisions (design pattern choices, module ownership, testing strategy, risk mitigations) back into the corresponding Notes section and checklist subtasks immediately after each coding/testing session.
• Checklist integrity: Never remove checklist items unless they are explicitly retired with documented reasoning. Mark completed work by checking the item(s) and append new tasks or restructuring bullets only when required—preserve original wording for historical traceability.
• Enforcement: Treat omissions as blocking bugs—if the plan falls out of sync with reality, halt work, reconcile the discrepancy here, and only then continue.

---

CleverAgents Vision

CleverAgents is your command center for AI agents—a unified platform for orchestrating any task you want agents to accomplish, from developing large software projects to writing comprehensive technical papers, administering databases, managing cloud infrastructure, or any complex multi-step workflow. The core value proposition is enabling long-running, complex, large-scale tasks to execute autonomously with minimal human intervention, making it ideal for building entire software systems, producing extensive documentation, or managing sophisticated operations largely hands-off.

When connected to a CleverAgents server (developed independently), the client becomes a gateway to a collaborative hub where teams can share resources—prompts, actors, actions, and projects—while executing plans on the server. This enables a consistent experience across all your devices: start a complex task on your laptop, check progress from your phone, and review results from any machine. Note: The server is a separate project; this implementation plan covers the client only.

While CleverAgents leverages LangGraph and LangChain for the underlying LLM runtime primitives (tool calling, graphs, routing), its value lies in what it builds on top:

• CleverAgents provides:

  • A first-class plan lifecycle (Action/Strategize/Execute/Apply) for breaking down and tracking complex work,
  • A project + resource model for grounding tasks in real codebases, databases, documents, and infrastructure,
  • A consistent actor abstraction for defining and composing intelligent agents,
  • A consistent skill abstraction for anything an agent can execute,
  • A sandbox + checkpoint safety model for safe, reversible execution,
  • A CLI/TUI/Web UX for controlling and monitoring large multi-step autonomous work.

Key Concepts

Concept	Definition
Plan	A tracked lifecycle for a single unit-of-work (which may spawn subplans). Phases: Action -> Strategize -> Execute -> Apply
Action	A reusable plan template. Created via CLI commands (NOT YAML files).
Actor	Anything conversational; may be a single agent/LLM or an entire graph. Defined via YAML configuration files. Always named <namespace>/<name>.
Project	A collection of resources + configuration. Created via CLI commands (NOT YAML files).
Resource	Anything that can be read/written/queried. Each resource defines its own sandbox strategy.
Skill	A callable capability defined inline in actor YAML as tool nodes.
Namespace	Scoping mechanism: local/, <username>/, <orgname>/, or provider namespaces (openai/, anthropic/).
Decision	A recorded choice point made during Strategize that affects downstream work. Forms a tree enabling correction and replay.

---

Objectives and Guiding Principles

• Ship a Python-based, feature-complete application named CleverAgents implementing the four-phase plan lifecycle with actors, projects, resources, and sandbox-based execution.
• Implement functionality using Pythonic architecture: dependency inversion, strategy, adapter, observer, state, builder, factory, template method, event sourcing, and decorator patterns where appropriate.
• Build a unified Python executable (agents) that operates as a client-only application, supporting stand-alone local-only mode or connecting to an independently developed server for multi-user deployments.
• Enforce fail-fast error handling, rich logging, and comprehensive type coverage with docstrings and runtime validation aligned to Python best practices.
• Provide a pluggable ORM abstraction supporting heavy (PostgreSQL/MySQL) and lightweight (SQLite/DuckDB/in-memory) backends, with zero-code configuration switches.
• Generate fresh documentation via MkDocs (Material for MkDocs) integrated within the docs/ directory of the CleverAgents project.

Core Architectural Requirements

Scalability: The system must handle massive codebases (50,000+ files) through:

• Three-tier memory architecture (hot/warm/cold)
• Hierarchical task decomposition
• Bounded dependency closures
• Lazy resource sandboxing

Reliability: Prevent cascading failures through:

• Complete execution isolation via sandboxes
• Multi-layer semantic error prevention
• Checkpoint-based rollback capabilities
• Invariant enforcement throughout execution

Autonomy with Control: Progressive automation through:

• Three-level automation system (manual, review-before-apply, full)
• Decision correction without full re-execution
• Confidence-based escalation
• Semantic understanding of when human input is needed

---

Continuous Testing and Documentation Policy

• Do not mark any parent checklist item complete until all subordinate Code, Document, Tests tasks and any generated Fix – … tasks are resolved and the associated Notes section has the latest context.
• Every time new information appears, extend the corresponding Notes section immediately with explicit references to code locations and decisions.
• Maintain a running catalog of Behave commands, Robot suites, fixtures, and environments in the Notes sections to assist subsequent contributors.
• Expand the nested Code/Document/Tests sub-bullets with newly discovered tasks as implementation advances so the plan always mirrors ground truth.

---

Completion Criteria

The implementation concludes only when every checklist item and spawned remediation task is checked, all Notes sections contain final decisions and references, and the full Behave and Robot test suites (unit, integration, end-to-end, benchmarking, packaging, documentation) pass without outstanding failures.

---

Architecture Overview

Plan Lifecycle Phases

Action -> Strategize -> Execute -> Apply -> Applied (terminal)

Current Phase	Command Verb	Next Phase
(none)	create	Action
Action	use	Strategize
Strategize	execute	Execute
Execute	apply	Applied

Plan States (Per Phase)

Action phase states: available, draft, archived

Strategize / Execute / Apply phase states: queued, processing, errored, complete, cancelled

Key Architectural Components

Multi-tier Memory System:

• Hot tier: Immediate working context in LLM context window
• Warm tier: Recent decisions and contexts from current plan tree
• Cold tier: Historical decisions from past plans, queryable but not in active memory
• Context snapshots with cryptographic hashes preserve complete decision context

Dependency Closure Computation:

• Resource-aware analysis during Strategize
• Hierarchical scoping with explicit resource lists
• Lazy expansion prevents closure explosion
• Interface-based boundaries for modular changes

Execution Coordination:

• Complete isolation via per-plan sandboxes
• Resource-specific sandbox strategies (git worktrees, transactions, etc.)
• Hierarchical merge resolution
• Checkpoint-based coordination for rollback

Semantic Error Prevention:

• Decision-time validation during Strategize
• Execution-time semantic guards in actors
• Invariant enforcement throughout
• Pattern-based predictive error prevention

Namespace Rules

Namespace	Scope	Storage
local/	Current machine only	Local database
<username>/	Personal server namespace	Server database
<orgname>/	Organization namespace	Server database
openai/, anthropic/, etc.	Built-in LLM actors	N/A (built-in)

Configuration Philosophy

• Actions: Created via CLI commands (agents [--data-dir PATH] [--config-path PATH] action create --config <file> ...)
• Projects: Created via CLI commands (agents [--data-dir PATH] [--config-path PATH] project create ...)
• Actors: Defined via YAML configuration files (the ONLY YAML configuration)
• Resources: Registered via agents resource add, then linked via agents project link-resource

---

Environment Variables for Testing

All environment variables needed during testing are stored in the .env file in the project root. This file contains API keys and tokens for various LLM providers and services. When implementing provider integrations or any features that require external services, use the environment variable names from this file or add new ones following the same pattern.

Current Environment Variables

Variable Name	Service	Usage
OPENROUTER_API_KEY	OpenRouter	Access to multiple LLM models through OpenRouter API
OPENAI_API_KEY	OpenAI	Direct access to OpenAI models (GPT-3.5, GPT-4, etc.)
ANTHROPIC_API_KEY	Anthropic	Access to Claude models
GOOGLE_API_KEY	Google AI	Access to Google's API for web searches
GEMINI_API_KEY	Google Gemini	Access to Google's Gemini models
HF_TOKEN	Hugging Face	Access to Hugging Face models and datasets

---

Development Log

This section will be updated with notes about each phase/task as they are implemented as well as forward looking remarks or insights.

Phase 0: Discovery and Requirements Elaboration (Python Tooling)

Status: [X] COMPLETE

All core Phase 0 discovery tasks have been successfully completed. See the Phase 0 section in the Implementation Checklist for detailed completion records.

Phase 0 Notes

• 2025-11-01: Implemented CLI inventory extraction tools, server endpoint extraction, data contract extraction, shell asset extraction
• 2025-11-02: Implemented environment variable extraction and implicit behavior extraction tools
• 2025-11-04: Completed workflow parity matrix generator and cloud features identification
• All discovery artifacts stored in docs/reference/

---

Phase 1: Target Architecture Definition

Status: [X] COMPLETE

All 10 ADRs have been created and package structure established. See the Phase 1 section in the Implementation Checklist for detailed completion records.

Phase 1 Notes

• 2025-11-04: Completed all 10 Architecture Decision Records
• 2025-11-05: Package structure created based on ADR-001
• All ADRs documented in docs/architecture/decisions/
• 2026-02-11: CLI syntax updated to spec-aligned forms (action create via --config, plan use positional args, project create positional). Legacy --name/--project examples retained in historical notes only.
• 2026-02-11: Action config YAML baseline (spec-aligned):

  name: local/example-action
  description: Example action for CLI flows
  strategy_actor: openai/gpt-4
  execution_actor: openai/gpt-4
  definition_of_done: "All steps complete"
  

---

Phase 2: Runtime Foundation (Completed Work)

Status: Substantially Complete - Transitioning to new Architecture

The following work from the previous implementation has been completed and will be preserved/adapted:

Completed Infrastructure

• LangChain/LangGraph dependencies and integration (ADR-011)
• PlanGenerationGraph, ContextAnalysisAgent, AutoDebugGraph workflows
• Memory service with EntityMemory
• SQLite persistence with Alembic migrations
• CLI streaming integration
• Provider adapters (OpenAI, Anthropic, Google, OpenRouter)
• Actor configuration system (Stage 7.5)
• Test coverage at 95%

Phase 2 Notes (Preserved from Previous Work)

2025-11-22: Week 12 Complete, Phase 2 Core Functionality DONE

• CLI Streaming Integration fully implemented
• AutoDebugGraph Implementation complete
• Mock provider enhancements with configurable failure modes
• Infrastructure improvements (DebugAttempt model, repositories)
• 2026-02-11: CLI syntax refreshed to spec-aligned forms in current execution sections; legacy --name/--project examples retained only in historical notes.

2025-12-05: LangSmith observability integration complete 2025-12-08: Actor-first provider wiring complete 2025-12-17: Stage 7 performance optimization complete 2026-02-02: Stage 7.5 Actor Configuration System complete 2026-02-05: Stage A1 & A2 Complete - Plan and Action Domain Models

• Created src/cleveragents/domain/models/core/plan.py with:
  • PlanPhase enum (ACTION, STRATEGIZE, EXECUTE, APPLY, APPLIED)
  • ActionState enum (AVAILABLE, DRAFT, ARCHIVED)
  • ProcessingState enum (QUEUED, PROCESSING, ERRORED, COMPLETE, CANCELLED)
  • NamespacedName model with parse() and str() methods
  • PlanIdentity model with ULID validation
  • Plan model with full lifecycle support
  • can_transition() function for phase transition validation
• Created src/cleveragents/domain/models/core/action.py with:
  • ActionArgument model with parse() method for CLI argument parsing
  • Action model with strategy/execution actor references
  • Argument validation including type checking
• Added 52 Behave test scenarios across 2 feature files:
  • features/plan_model.feature (30 scenarios)
  • features/action_model.feature (22 scenarios)
• All new tests pass, existing tests unaffected

2026-02-05: Stage A3 Complete - PlanLifecycleService

• Created src/cleveragents/application/services/plan_lifecycle_service.py with:
  • Full plan lifecycle management (Action -> Strategize -> Execute -> Apply -> Applied)
  • Action CRUD operations (create, get, list, make_available, archive)
  • Plan creation via use_action() which transitions Action to Strategize
  • Phase transition methods: execute_plan(), apply_plan()
  • State management: start_*(), complete_*(), fail_*() for each phase
  • cancel_plan() for non-terminal plans
  • Custom exceptions: InvalidPhaseTransitionError, ActionNotAvailableError, PlanNotReadyError
  • In-memory storage (to be replaced with persistence in Stage A5)
• Added python-ulid dependency for ULID generation
• Added 29 Behave test scenarios in features/plan_lifecycle_service.feature
• Total new test scenarios: 81 (30 + 22 + 29)

2026-02-05: Stage A4 In Progress - Plan CLI Commands

• Created src/cleveragents/cli/commands/action.py with:
  • agents [--data-dir PATH] [--config-path PATH] action create - Create new action with strategy/execution actors, definition of done, arguments
  • agents [--data-dir PATH] [--config-path PATH] action list - List actions with filtering by namespace, state
  • agents [--data-dir PATH] [--config-path PATH] action show - Show action details by ID or name
  • agents [--data-dir PATH] [--config-path PATH] action available - Make draft action available for use
  • agents [--data-dir PATH] [--config-path PATH] action archive - Archive an action (soft delete)
• Extended src/cleveragents/cli/commands/plan.py with v3 lifecycle commands:
  • agents [--data-dir PATH] [--config-path PATH] plan use <action> <project> - Use action to create plan in Strategize phase (legacy --project retained in old notes)
  • agents [--data-dir PATH] [--config-path PATH] plan execute [plan_id] - Transition plan from Strategize to Execute
  • agents [--data-dir PATH] [--config-path PATH] plan apply [plan_id] - Transition plan from Execute to Apply
  • agents [--data-dir PATH] [--config-path PATH] plan status [plan_id] - Show v3 plan status and details
  • agents [--data-dir PATH] [--config-path PATH] plan list [--phase <phase>] [--state <state>] [--project <project>] [--action <action>] - List v3 lifecycle plans with filtering
  • agents [--data-dir PATH] [--config-path PATH] plan cancel <plan_id> - Cancel a non-terminal plan
• Registered action commands in CLI main.py
• Added 15 Behave test scenarios in features/action_cli.feature
• Total test scenarios: 96 (81 + 15)

2026-02-06: CRITICAL ARCHITECTURAL DECISION - Tool-Based Resource Modification

• REPLACED: OutputParser/code fence parsing approach
• WITH: Tool-based change tracking (modern approach used by Claude Code, Cursor, Aider)
• Key changes:
  • LLMs call skills/tools directly (edit_file, write_file, delete_file, etc.)
  • Skills operate on sandbox state directly
  • ChangeSet is built from skill invocation history, NOT by parsing LLM text output
• Added built-in resource skills (now C4.file/C4.search/C4.git): file ops, dir ops, search, git ops
• Added MCP skill adapter (now C7.mcp): connect to external MCP servers
  • Replaced C4 "Multi-File ChangeSet Generation" with "Tool-Based Change Tracking"
  • Added SkillInvocationTracker and ToolCallRouter components
• Rationale:
  • No parsing ambiguity (is this code or explanation?)
  • Each operation is explicit, typed, and trackable
  • Supports rollback (replay inverse of recorded changes)
  • Resource-agnostic (works for files, databases, APIs, any resource type)
  • Compatible with MCP standard for external tools
• See docs/specification.md sections:
  • "Tool-Based Resource Modification (Modern Architecture)"
  • "Unified Resource Abstraction Layer"
  • "MCP Integration Architecture"

---

Implementation Roadmap

Milestone Overview

Milestone	Target Date	Description
M0: Foundation	Day 0 (Current)	Existing LangGraph infrastructure preserved
M1: Minimal Plan Lifecycle	+7 days	Basic Action -> Strategize -> Execute -> Apply working for source code
M2: Projects & Resources	+10 days	Project/Resource CLI commands, local filesystem sandbox
M3: Actors & Skills	+14 days	YAML actor loading, skill execution, multi-file generation
M4: Decision Tree	+21 days	Decision recording during Strategize, basic correction
M5: Multi-Project & Subplans	+25 days	Subplan spawning, parallel execution
M6: Large Project Autonomy	+30 days	Handle 10K+ file projects, decision correction, deep subplan hierarchies (LOCAL MODE ONLY)
M7: Server Connectivity	+35+ days	Client-server communication for remote project support (server developed independently)
M8: Full Feature Set	+40 days	All spec features complete

Critical Path to 7-Day MVP (Source Code Only)

WEEK 1 GOAL: A minimally usable application that can:

1. Create an action from CLI
2. Use the action on a source code project
3. Execute with sandbox isolation
4. Generate multi-file changes
5. Apply changes after review

CRITICAL PATH (Sequential):
Day 1: A5 Plan/Action Persistence (Luis)
Day 2: B1.core + B2.service/B3.cli Project/Resource models + CLI (Hamza)
Day 3: B4.sandbox Git worktree sandbox (Luis + Hamza)
Day 4: C1.schema/C1.examples + C2.loader/C2.compiler Actor schema + compilation (Aditya + Jeff)
Day 5: C3.protocol/C3.context/C3.inline + C4.file Skill framework + file skills (Jeff)
Day 6: C4.search/C4.git + C5.model/C5.router/C5.diff Change tracking + tool routing (Luis + Jeff)
Day 7: C6.pipeline/C6.gating + C7.mcp + C8.providers + C9.execute/C9.apply Plan-actor integration + validation (Aditya + Jeff + Luis)
Day 8: End-to-end Integration & Testing (All)

Parallel Workstreams

WORKSTREAM A: Plan Lifecycle & Persistence [Luis - Lead Architect]
├── Plan/Action database persistence
├── Phase transitions with database
├── Plan state machine completion
└── CLI integration with persistence

WORKSTREAM B: Projects & Resources [Hamza - RDF Expert]
├── B1.core domain models (resource types, resources, projects)
├── B2.persistence tables + repositories + services
├── B3.cli resource type/resource/project commands
└── B4.sandbox strategies (git_worktree + copy_on_write stub)

WORKSTREAM C: Actors & Skills [Aditya - Domain Expert]
├── Actor YAML schema formalization
├── Hierarchical actor configurations
├── Skill execution framework
├── Built-in resource skills (file ops, dir ops, search, git)
├── MCP skill adapter for external servers
├── Actor-to-LangGraph compilation
└── Built-in provider actors

WORKSTREAM D: Tool-Based Change Tracking [Luis + Rui]
├── ChangeSet model enhancement
├── Skill invocation tracking
├── Tool call routing (OpenAI/Anthropic/LangChain)
├── Validation pipeline
└── Diff review artifacts

WORKSTREAM Q: Quality Automation & Infrastructure [Brent - Detail Oriented]
├── Automated quality gate setup (Days 1-3)
├── Continuous quality monitoring (Days 4-30)
├── Documentation automation (Continuous)
└── Transition to high-impact work after Day 8

MERGE POINT 1: After Day 7 (M1)
- Plan->Actor binding verified
- Resource->Context flow working
- Skill->Tool mapping complete

MERGE POINT 2: After Day 14 (M3)
- Full plan lifecycle tested
- Actor compilation working
- Multi-file generation proven

MERGE POINT 3: After Day 30 (M6 - Large Project Autonomy)
- Decision tree correction working
- Large project handling verified (10K+ files)
- Deep subplan hierarchies operational (5+ levels)
- Server connectivity deferred (client-only stubs; no server implementation)

---

Quick Reference for Development

Tool Commands

# Development setup
pip install -e .[dev,tests,docs]    # Install with all extras
hatch env create                     # Create virtual environment
hatch shell                          # Activate environment

# Testing
nox                                  # Run all tests
nox -s unit_tests                    # Run Behave tests only
nox -s integration_tests             # Run Robot tests only
nox -s coverage_report               # Check coverage (must be >=97%)

# Code quality
nox -s format                        # Format with Ruff
nox -s lint                          # Lint with Ruff
nox -s typecheck                     # Type check with pyright

# Documentation
nox -s docs                          # Build documentation

Key Files and Their Purpose

• pyproject.toml - All project configuration (no setup.py, no requirements.txt)
• noxfile.py - All task automation (no Makefile, no scripts/)
• features/ - Behave unit tests (no tests/ directory)
• robot/ - Robot integration tests
• docs/reference/ - Discovery artifacts from Phase 0
• docs/architecture/decisions/ - ADRs from Phase 1

Environment Variables (CLEVERAGENTS_* only)

# Core configuration
CLEVERAGENTS_HOME=~/.cleveragents
CLEVERAGENTS_LOG_LEVEL=INFO
CLEVERAGENTS_API_KEY=<your-key>

# Development
CLEVERAGENTS_DEBUG=true
CLEVERAGENTS_TEST_MODE=true

---

Implementation Checklist

This comprehensive checklist tracks all implementation tasks for the CleverAgents project. Each phase item includes mandatory Code, Document, and Tests bullets. Only mark the parent complete when every sub-bullet (including any spawned Fix – … remediation tasks) is checked.

Organization: This checklist is organized to enable parallel development and achieve a minimally working version as quickly as possible. Workstreams are clearly marked. Dependencies between workstreams are noted at merge points.

Execute all required tests through the appropriate nox sessions—never call behave, robot, or other runners directly. After touching any subtask, immediately add discoveries to the Notes section and update task descriptions.

Updated Team Assignments (by Expertise)

Developer	Strengths	Assignment Focus	Availability
Jeff	CTO, fastest developer, expert in everything	Critical path blockers, architecture, complex integrations, decision correction, unblocking others	PRIMARY - Available for all critical work
Aditya	Domain expert (agents/LLMs), understands hierarchical configs	Actor YAML configurations, hierarchical actor graphs, strategy/execution actors, MCP integration	HIGH - Primary on actor/skill work
Rui	Fastest developer, new to Python	Testing (Behave/Robot), simple implementations, CLI scaffolding, test fixtures	HIGH - Parallel testing track
Brent	Slow but detail-oriented	Days 1-3: Automated quality gates setup; Days 4-8: Selective review; After Day 8: Validation testing	CONTINUOUS - Independent QA track
Hamza	RDF expert, Python proficient, no LLM experience	Projects, resources, sandbox, database infrastructure, decision models, context indexing	HIGH - Infrastructure lead
Luis	Best Python architect, pedantic	Algorithms, state machines, service layer architecture, change tracking, validation pipelines	HIGH - Architecture/service layer
Mike/Brian	Sysadmins	Deployment only (minimal coding tasks)	LOW - Only deployment tasks

Work Assignment Philosophy

Jeff should be assigned to:

• Any task that is blocking other developers
• Complex integrations requiring deep architectural understanding
• Decision correction mechanism (critical for 30-day goal)
• Skill execution framework (core to MVP)
• Performance-critical code paths
• Final review of all architectural decisions

Jeff's Critical Path Task Summary (Day-by-Day)

Day	Task IDs	Description	Blocks
Day 1	A5.alpha, A5.gamma	Plan/Action DB schema + Plan Repository	Luis (A5.beta), All downstream
Day 2	A5.gamma	Service integration + DI wiring	CLI integration (A4 tests)
Day 3	C3.protocol	Skill protocol + metadata	All skill implementations
Day 4	C3.context, C3.inline	SkillContext + inline executor	Luis (C5.model)
Day 5	C4.file	File operation skills	Change tracking tests
Day 6	C4.search, C4.git	Search + git skills	Actor compilation (C2.compiler)
Day 7	C6.gating, C9.execute, C9.apply	Plan-actor integration + validation	MVP verification
Day 8	M1.1-M1.10	MVP merge point coordination	Release v0.1.0-rc1
Day 15-16	D4.revert	Correction Service core algorithm	Decision correction
Day 17	D4.append	Append correction mode	Re-execution
Day 18	D5.di	Decision wiring + re-exec	M4 milestone
Day 19	D5.di	Unblock E3 parallelism	Luis (E3)
Day 20-21	E3	Parallel execution fine-tuning	Subplan merging
Day 22-25	Deep subplan hierarchies	5+ level subplan testing	M6
Day 26-28	Performance optimization	10K+ file codebase support	Large project autonomy
Day 30	M6.1-M6.10	Large project merge point	Release v0.3.0

BLOCKING CHAIN: If Jeff is unavailable, the following chains stall:

• A5.alpha → A5.beta → A5.gamma → Plan persistence (Day 1-2)
• C3.protocol → C3.context → C4.file → Skill execution (Day 3-6)
• D4.revert → D4.append → Decision correction (Day 15-18)

Aditya should be assigned to:

• ALL actor configuration YAML files and examples
• Hierarchical actor graph compositions
• Strategy and execution actor templates
• MCP skill adapter implementation
• Skill metadata definitions
• Anything requiring understanding of LLM tool calling patterns

Luis should be assigned to:

• State machine implementations (plan lifecycle, phase transitions)
• Repository pattern implementations
• Service layer architecture
• Algorithm design (merge strategies, dependency closure)
• Validation pipeline orchestration
• Should NOT be assigned to simple CRUD or UI work

Hamza should be assigned to:

• Database schema design and Alembic migrations
• Resource model and sandbox infrastructure
• Context indexing and RDF graph store integration
• Decision tree persistence layer
• Session management
• Should NOT be assigned to LLM/agent-specific logic

Rui should be assigned to:

• ALL Behave test scenarios (write BEFORE implementation)
• Robot integration tests
• Simple CLI scaffolding
• Test fixtures and mocks in features/
• Should ALWAYS work in parallel with feature developers

Brent should be assigned to:

• Days 1-3: Setting up comprehensive automated quality gates
• Days 4-8: Selective manual review of high-priority items only
• After Day 8: High-impact validation and edge case testing with Luis
• Continuous: Monitoring automated quality metrics
• Should work INDEPENDENTLY with no blocking dependencies

Updated Timeline Targets

Milestone	Day	Goal	Success Criteria
M1: MVP	Day 7	Create action → Use on project → Execute with sandbox → Apply changes (source code only)	agents [--data-dir PATH] [--config-path PATH] action create --config + agents [--data-dir PATH] [--config-path PATH] plan use <action> <project> + agents [--data-dir PATH] [--config-path PATH] plan execute + agents [--data-dir PATH] [--config-path PATH] plan apply working end-to-end on a git repository with sandboxed execution
M2: Projects	Day 10	Project/Resource CLI working with git worktree sandbox	agents [--data-dir PATH] [--config-path PATH] project create + agents [--data-dir PATH] [--config-path PATH] resource add git-checkout + agents [--data-dir PATH] [--config-path PATH] project link-resource (B3.cli) + git worktree isolation verified
M3: Actors	Day 14	Full plan lifecycle with actors, skills, multi-file generation	Actor YAML parsed → LangGraph compiled → Skills executed → Multi-file ChangeSet produced → Validation passing → Applied
M4: Decisions	Day 21	Decision recording, tree viewing, correction mechanism	agents [--data-dir PATH] [--config-path PATH] plan tree shows decisions → agents [--data-dir PATH] [--config-path PATH] plan explain works → agents [--data-dir PATH] [--config-path PATH] plan correct --mode=revert re-executes from correction point
M4: Decisions	Day 21	Invariant CLI usage	agents [--data-dir PATH] [--config-path PATH] invariant add --project <project> "<text>" + agents [--data-dir PATH] [--config-path PATH] invariant list --project <project>
M5: Subplans	Day 25	Hierarchical subplans with parallel execution and merging	Parent plan spawns 5+ subplans → Parallel execution → Three-way merge → Validation passes
M6: Large Projects	Day 30	Handle 10,000+ file projects, autonomous language porting	Can port a 500-file Python module to TypeScript using hierarchical decomposition with decision correction
Server Connectivity	Beyond Day 30	Client interfaces for server communication; server developed independently	Client-to-server API abstractions defined, but local execution only; no server implementation in this project

CRITICAL: Server Connectivity Policy

The CleverAgents client does NOT include server functionality. The server is a separate project that will be developed independently. This implementation plan covers the client only. During Days 1-30, developers should:

1. Design with Server Connectivity in Mind: Ensure abstractions support future connection to an external server
2. Create Client Interface Stubs Only: Define ServerClientAPI, RemoteExecutionClient, AuthenticationClient interfaces but implement as stubs that raise NotImplementedError("Server connectivity not yet implemented")
3. No Server Implementation Work: The server is NOT part of this project—do NOT spend time on server implementation, only on client-side connection interfaces
4. Focus on Core Functionality: All effort goes to plan lifecycle, actors, skills, sandboxing, decisions, and subplans

The following Section 8 (Server Connectivity) items are explicitly OUT OF SCOPE for the 30-day deadline:

• Client-to-server API integration
• WebSocket streaming to server
• Remote project execution via server
• Server authentication flow (client-side)
• Server API client implementation (beyond stubs)

Rationale: Getting a minimally usable application working for single-user local operation in 7 days, and large project autonomy in 30 days, is more valuable than incomplete server connectivity. The server will be developed as a separate project.

Critical Path Analysis

The following chains represent sequential dependencies where each item MUST complete before the next can start:

CHAIN 1: Data Layer (Days 1-3)

A5.alpha (DB migrations) → A5.beta (ORM models) → A5.gamma (repos/service/DI)

CHAIN 2: Resource Layer (Days 2-4)

B1.core (Domain Models) → B2.persistence (DB tables) → B2.service (Services) → B3.cli (CLI)

CHAIN 3: Sandbox Layer (Days 3-5)

B4.sandbox (Strategy + Manager) → B4.sandbox git_worktree → B4.sandbox copy_on_write

CHAIN 4: Actor Layer (Days 4-7)

C1.schema (Actor Schema) → C2.loader (Actor Loader) → C2.compiler (Actor Compiler) → C2.refs (Reference Resolution)

CHAIN 5: Skill Layer (Days 5-8)

C3.protocol (Skill Protocol) → C3.context (Skill Context) → C3.inline (Inline Executor) → C4.file/C4.search/C4.git (Built-in Skills)

CHAIN 6: Change Tracking (Days 6-9)

C5.model (Change Models) → C5.router (Tool Router) → C5.diff (Diff Generator)

CHAIN 7: Plan-Actor Integration (Days 8-14)

C9.execute (Strategize/Execute) → C6.pipeline/C6.gating (Validation) → C9.apply (Apply + Review)

Parallel Workstream Allocation

WEEK 1 FOCUS: MVP (Local Source Code Only)

WEEK 1 PARALLEL TRACKS:

TRACK A [Jeff - CRITICAL PATH LEAD + Luis - ARCHITECTURE]:
├── Day 1 AM: Jeff - A5.alpha DB migrations (2-3 hours)
│   └── Luis can start A5.beta ORM models after schema doc review
├── Day 1 PM: Jeff - A5.gamma repositories (2-3 hours)
│   └── Luis - A5.beta ORM models (parallel)
├── Day 2: Jeff - A5.gamma service integration (main blocker)
│   └── Luis - A5.gamma DI wiring
├── Day 3-4: Jeff - C3.protocol/C3.context/C3.inline Skill framework (CRITICAL)
│   └── Luis - C5.model Change models + tracker (parallel after C3.protocol)
├── Day 5-6: Jeff - C4.file/C4.search Built-in skills (file/dir/search)
│   └── Luis - C5.router/C5.diff Tool router + diff review artifacts
├── Day 7: Jeff - C9.execute/C9.apply Plan-Actor integration (brings it all together)
│   └── Luis - C6.pipeline/C6.gating Validation pipeline + apply gating
└── Day 8: Jeff - MVP Integration Testing + Bug Fixes

TRACK B [Hamza - INFRASTRUCTURE (No LLM Knowledge Needed)]:
├── Day 1: B1.core Domain models (resource types, resources, projects)
├── Day 2: B2.persistence tables + B2.service service layer
│   └── B3.cli resource type/resource/project commands
├── Day 3: B4.sandbox strategy + manager + git_worktree
├── Day 4: B4.sandbox copy_on_write stub + git-checkout handler
├── Day 5: B2.service integration + resource registry service
├── Day 6: B2.persistence repositories + migration tests
└── Day 7: CLI integration tests + M2 merge gate verification

TRACK C [Aditya - ACTORS (Domain Expert - Hierarchical Configs)]:
├── Day 4: C1.schema Actor YAML schema models
│   └── Aditya writes ALL actor YAML examples (C1.examples)
├── Day 5: C2.loader + C2.compiler Actor loading + compilation
├── Day 6: C2.refs Reference resolution + C7.mcp MCP Skill Adapter
├── Day 7: C8.providers Built-in provider actors (openai/, anthropic/, openrouter/)
└── Day 8: Actor compilation integration tests

TRACK Q [Brent - AUTOMATED QUALITY GATES (Days 1-3) then SELECTIVE REVIEW]:
├── Day 1: Pre-commit hooks setup (see Section 0 Q0-Minimum)
│   └── pyright, ruff, bandit, vulture, semgrep
├── Day 2: CI/CD pipeline with GitHub Actions (see Section 0 Q0-Minimum)
│   └── Automated PR validation, coverage enforcement
├── Day 3: Advanced automation & monitoring (see Section 0 Q0-Advanced)
│   └── Complexity checks, performance regression, metrics
├── Days 4-8: Selective manual review only for:
│   └── Architecture, complex algorithms, API contracts
├── Day 8: Sign off on MVP quality metrics
└── After Day 8: Transition to validation pipeline work with Luis

TRACK T [Rui - TESTING (CONTINUOUS - WRITE TESTS FIRST)]:
├── Day 1: A5.tests Plan/Action persistence tests (BEFORE implementation)
├── Day 1-2: B1.core model tests
├── Day 2-3: B3.cli CLI tests + Robot integration
├── Day 3-4: B4.sandbox tests (git worktree, copy_on_write stub, isolation)
├── Day 5: C3.protocol/C3.context/C3.inline skill framework tests
├── Day 6: C5.model/C5.router/C5.diff change tracking + tool routing tests
├── Day 7: C6.pipeline/C6.gating + C9.execute/C9.apply plan-actor integration tests
└── Day 8: Full MVP integration test suite

MERGE POINT: Day 8 - All tracks converge for MVP verification
  - All tests must pass
  - Coverage must be >=97%
  - Brent signs off on quality
  - Jeff leads integration testing
  
  MERGE POINT DAY 8 - EXPLICIT COORDINATION TASKS:
  ├── [Jeff - 9:00 AM] M1.1: Run full `nox` test suite, collect failures
  ├── [Jeff - 10:00 AM] M1.2: Verify Plan persistence (A5) connects to CLI (A4)
  │   └── Test: `agents [--data-dir PATH] [--config-path PATH] action create --config ... && agents [--data-dir PATH] [--config-path PATH] plan use <action> <project> && agents [--data-dir PATH] [--config-path PATH] plan status`
├── [Jeff - 11:00 AM] M1.3: Verify resource/project CLI (B3.cli) creates resources in DB (B2.persistence)
  │   └── Test: `agents [--data-dir PATH] [--config-path PATH] project create ... && agents [--data-dir PATH] [--config-path PATH] resource add git-checkout ... && agents [--data-dir PATH] [--config-path PATH] project link-resource ...`
├── [Jeff - 12:00 PM] M1.4: Verify Sandbox (B4.sandbox) integrates with resource registry service (B2.service)
  │   └── Test: Create plan, write to resource, verify sandbox isolation
├── [Luis - 1:00 PM] M1.5: Verify Actor compilation (C2.compiler/C2.refs) produces valid LangGraph
  │   └── Test: Compile each example actor, invoke with mock input
├── [Aditya - 2:00 PM] M1.6: Verify Skill execution (C3) records Changes (C5)
  │   └── Test: Execute WriteFileSkill, verify ChangeSet contains Change
├── [Hamza - 3:00 PM] M1.7: Verify Plan-Actor binding (C9) with real actors
  │   └── Test: Full plan use → execute → apply with openai/gpt-4
  ├── [Rui - 4:00 PM] M1.8: Run Robot end-to-end suite
  │   └── All robot/*.robot files must pass
  ├── [Brent - 5:00 PM] M1.9: Final quality gate
  │   └── Sign off: coverage >=97%, lint clean, typecheck clean
  └── [Jeff - 6:00 PM] M1.10: Tag release candidate v0.1.0-rc1

WEEK 2-3 PARALLEL TRACKS:

TRACK A [Jeff - DECISION CORRECTION (CRITICAL FOR 30-DAY GOAL)]:
├── Day 15-16: D4.revert Correction Service (core algorithm)
├── Day 17: D4.append Append correction mode
├── Day 18: D5.di Decision wiring + re-exec
├── Day 19: D5.di integration + unblocking E3 parallelism
└── Day 20-21: E3.exec Parallel Execution fine-tuning

TRACK B [Hamza - DECISION PERSISTENCE]:
├── Day 15-16: D1.domain Decision domain model
├── Day 16-17: D2.service Decision Service + recording
├── Day 17-18: D3.cli Decision CLI (tree, explain)
├── Day 18-19: D5.db/D5.repo Decision DB schema + repos
└── Day 19-20: D5.di Decision services wired to CLI

TRACK C [Aditya - STRATEGY ACTOR ENHANCEMENTS]:
├── Day 15-16: Strategy actor emitting SUBPLAN_SPAWN decisions
├── Day 17-18: Hierarchical actor configurations for decomposition
├── Day 19-20: E2.actor plan_subplan tool + E2.service spawn workflow
└── Day 21: Integration with decision tree

TRACK D [Luis - SUBPLANS & MERGING]:
├── Day 12-13: E1.domain Subplan Model (before D stage)
├── Day 12-14: E2.service SubplanService + queries
├── Day 19: E3.exec Parallel Execution (after Jeff unblocks)
├── Day 20: E4.merge Result Merging (three-way, sequential)
└── Day 21: E4.merge Post-merge validation

TRACK Q [Brent - HIGH-IMPACT QUALITY WORK]:
├── Days 15-16: Help Luis with semantic validation framework
├── Day 17: Review decision model architecture (P0 priority)
├── Day 19: Review subplan merge algorithms (P0 priority)
├── Day 20: Create validation test scenarios with edge cases
└── Day 21: M4 quality gate - automated metrics check

TRACK T [Rui - TESTING]:
├── Day 15-16: D1.domain Decision model tests
├── Day 17-18: D2.service + D3.cli Decision service + CLI tests
├── Day 19: E2.service Subplan spawning tests
├── Day 20: E3.exec Parallel execution tests
└── Day 21: E4.merge Merge tests

MERGE POINT: Day 21 - M4 Decision Correction Working

WEEK 4 PARALLEL TRACKS (Days 22-30):

TRACK A [Jeff - LARGE PROJECT AUTONOMY]:
├── Day 22-23: G1.decompose Deep subplan hierarchies (5+ levels)
├── Day 24-25: E5.multi Multi-project support
├── Day 26-28: G3.semantic validation + perf tuning
├── Day 29: End-to-end language porting test (Python → TypeScript)
└── Day 30: Final M6 verification + bug fixes

TRACK B [Hamza - CONTEXT INDEXING]:
├── Day 22-23: G4.context hot/warm tiers (recent decisions from plan tree)
├── Day 24-25: G4.context cold tier queries (historical decisions)
├── Day 26-28: CTX1.index/CTX2.embedding indexing optimization
└── Day 29-30: Integration with decision correction

TRACK C [Aditya - ACTOR OPTIMIZATION]:
├── Day 22-23: Context views (strategist, executor, reviewer)
├── Day 24-25: Bounded dependency closure computation
├── Day 26-28: Actor caching + compilation optimization
└── Day 29-30: Large project actor testing

TRACK D [Luis - AUTOMATION LEVELS]:
├── Day 22-23: A6.core automation level implementation
├── Day 24-25: A6.service confidence-based escalation
├── Day 26-28: A6.service review-before-apply mode
└── Day 29-30: A6.cli automation mode testing

TRACK Q [Brent - VALIDATION & EDGE CASE TESTING]:
├── Days 22-25: Deep validation testing with Luis
│   └── Edge cases, error paths, semantic checks
├── Days 26-28: Performance optimization validation
│   └── Verify 10K+ file handling, memory usage
├── Day 29: Automated quality report generation
└── Day 30: M6 automated metrics verification + sign-off

TRACK T [Rui - INTEGRATION TESTS]:
├── Day 22-24: E5.multi Multi-project tests
├── Day 25-27: Large project tests (1K, 5K, 10K files)
├── Day 28-29: Autonomous porting end-to-end test
└── Day 30: Final test suite run

MERGE POINT: Day 30 - M6 Large Project Autonomy Target

  MERGE POINT DAY 30 - EXPLICIT COORDINATION TASKS:
  ├── [Jeff - 9:00 AM] M6.1: Run full `nox` test suite including large project tests
  ├── [Jeff - 10:00 AM] M6.2: Execute autonomous language porting test (Python → TypeScript)
  │   └── Test: Port a 500-file Python module with hierarchical decomposition
  ├── [Luis - 11:00 AM] M6.3: Verify decision correction re-execution works
  │   └── Test: Correct a strategy decision, verify downstream re-executes
  ├── [Hamza - 12:00 PM] M6.4: Verify deep subplan hierarchies (5+ levels)
  │   └── Test: Create plan that spawns subplans recursively
  ├── [Aditya - 1:00 PM] M6.5: Verify context views filter appropriately for large codebases
  │   └── Test: strategist view vs executor view on 10K file project
  ├── [Luis - 2:00 PM] M6.6: Verify parallel execution with merge works
  │   └── Test: 5 parallel subplans, three-way merge, no conflicts
  ├── [Hamza - 3:00 PM] M6.7: Verify context cold tier queries work
  │   └── Test: Query historical decisions from past plans
  ├── [Rui - 4:00 PM] M6.8: Run Robot large project test suite
  │   └── All robot/large_project_*.robot files must pass
  ├── [Brent - 5:00 PM] M6.9: Final documentation and quality gate
  │   └── Sign off: All ADRs current, coverage >=97%, docs complete
  └── [Jeff - 6:00 PM] M6.10: Tag release v0.3.0 (Large Project Autonomy)

Parallel Workstreams Structure

• Workstream A: Plan Lifecycle & Persistence [Jeff + Luis] - CRITICAL PATH
• Workstream B: Projects & Resources [Hamza] - PARALLEL with A
• Workstream B focus: B1.core domain models, B2.persistence/B2.service, B3.cli, B4.sandbox
• Workstream C: Actors, Skills & Change Tracking [Aditya + Jeff] - After Day 3
• Workstream Q: Quality Assurance [Brent] - CONTINUOUS
• Workstream T: Testing [Rui] - CONTINUOUS

Merge Points:

• Day 7 (M1): All workstreams coordinate for MVP verification
• Day 14 (M3): Full plan lifecycle integration
• Day 21 (M4): Decision tree and correction mechanism
• Day 30 (M6): Large project autonomy target

MERGE POINT DAY 14 (M3) - Full Plan Lifecycle Integration:

├── [Jeff - 9:00 AM] M3.1: Verify full plan lifecycle end-to-end
│   └── Test: action create → plan use → plan execute → plan apply
├── [Aditya - 10:00 AM] M3.2: Verify actor YAML loads and compiles to LangGraph
│   └── Test: All examples/actors/*.yaml compile without error
├── [Luis - 11:00 AM] M3.3: Verify tool-based change tracking produces valid ChangeSet
│   └── Test: Actor makes edits via skills, ChangeSet reflects all changes
├── [Hamza - 12:00 PM] M3.4: Verify sandbox commit applies changes to original
│   └── Test: Execute with sandbox, commit, verify git commits appear
├── [Aditya - 1:00 PM] M3.5: Verify MCP skill adapter works with external server
│   └── Test: Connect to filesystem MCP server, execute tool, verify result
├── [Luis - 2:00 PM] M3.6: Verify validation pipeline catches errors
│   └── Test: Generate invalid Python, verify syntax validation fails
├── [Rui - 3:00 PM] M3.7: Run Robot actor integration suite
├── [Brent - 4:00 PM] M3.8: Quality gate for M3
└── [Jeff - 5:00 PM] M3.9: Tag release v0.2.0-rc1 (Actors & Skills)

MERGE POINT DAY 21 (M4) - Decision Tree & Correction:

├── [Hamza - 9:00 AM] M4.1: Verify decision recording captures context
│   └── Test: Execute strategy phase, verify decisions recorded with snapshots
├── [Jeff - 10:00 AM] M4.2: Verify decision correction re-executes from point
│   └── Test: Correct a strategy decision, verify downstream work redone
├── [Hamza - 11:00 AM] M4.3: Verify decision tree visualization works
│   └── Test: `agents [--data-dir PATH] [--config-path PATH] plan tree <plan_id>` shows correct hierarchy
├── [Jeff - 12:00 PM] M4.4: Verify sandbox checkpointing supports correction
│   └── Test: Checkpoint, make changes, rollback to checkpoint
├── [Luis - 1:00 PM] M4.5: Verify subplan spawning creates valid child plans
│   └── Test: Strategy actor spawns 3 subplans, all have correct parent_plan_id
├── [Aditya - 2:00 PM] M4.6: Verify strategy actor emits SUBPLAN_SPAWN decisions
│   └── Test: Actor config enables subplan spawning, decision recorded
├── [Rui - 3:00 PM] M4.7: Run Robot decision correction suite
├── [Brent - 4:00 PM] M4.8: Quality gate for M4
└── [Jeff - 5:00 PM] M4.9: Tag release v0.2.0 (Decision Correction)

---

Section 0: Quality Automation Setup [WORKSTREAM Q - Brent Lead]

Target: Days 0-3 (Minimum gates before merges; advanced gates after M1)

Parallelization rules:

• Minimum gating (pre-commit + CI + coverage enforcement) is a merge blocker; it can run in parallel with Week 1 coding but must land before any feature branches merge.
• Advanced automation (complexity metrics, dashboards, extended security scanning) is deferred until after M1 to avoid blocking the MVP.

Parallel Group Q0-Minimum Gates [Brent - blocks merges]

• COMMIT (Owner: Brent | Group: Q0-Minimum) - Commit message: "feat(qa): add pre-commit baseline hooks" (Only check after all subitems + nox pass + coverage >=97%, then commit)

  • Code [Brent]: Add pre-commit>=3.6.0 to pyproject.toml dev dependencies.
  • Code [Brent]: Create .pre-commit-config.yaml with hooks for ruff format, ruff check, pyright, check-merge-conflict, end-of-file-fixer, trailing-whitespace.
  • Code [Brent]: Add/confirm nox -s lint session that runs Ruff + pyright using project settings.
  • Docs [Brent]: Update CONTRIBUTING.md with pre-commit install + run steps (no helper scripts).
  • Tests (Behave) [Rui]: Add scenarios in features/quality_automation.feature that parse .pre-commit-config.yaml and assert required hooks are configured.
  • Tests (Robot) [Rui]: Add robot/quality_automation.robot that runs nox -s lint and asserts zero failures.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Brent]: git commit -m "feat(qa): add pre-commit baseline hooks".

• COMMIT (Owner: Brent | Group: Q0-Minimum) - Commit message: "feat(ci): add nox-based PR validation workflow" (Only check after all subitems + nox pass + coverage >=97%, then commit)

  • Code [Brent]: Add .github/workflows/pr-validation.yml that installs dependencies via Hatch and runs nox (unit + integration + typecheck + lint).
  • Code [Brent]: Ensure CI uses Python 3.13 and caches pip/Hatch artifacts.
  • Code [Brent]: Fail pipeline if any nox session fails or coverage <97%.
  • Docs [Brent]: Add CI usage notes in docs/development/ci-cd.md.
  • Tests (Behave) [Rui]: Add a scenario that validates workflow file exists and references nox sessions.
  • Tests (Robot) [Rui]: Add a Robot smoke test that runs the same nox session matrix locally.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Brent]: git commit -m "feat(ci): add nox-based PR validation workflow".

• COMMIT (Owner: Brent | Group: Q0-Minimum) - Commit message: "feat(qa): enforce coverage >=97%" (Only check after all subitems + nox pass + coverage >=97%, then commit)

  • Code [Brent]: Update nox -s coverage_report (or equivalent session) to fail when coverage <97%.
  • Code [Brent]: Wire coverage threshold enforcement into CI summary output.
  • Docs [Brent]: Update docs/development/testing.md with new coverage requirement.
  • Tests (Behave) [Rui]: Add a scenario that parses coverage config and asserts threshold >=97%.
  • Tests (Robot) [Rui]: Add a Robot test that runs nox -s coverage_report and asserts pass/fail behavior.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Brent]: git commit -m "feat(qa): enforce coverage >=97%".

Parallel Group Q0-Advanced Gates [Brent - AFTER M1]

• COMMIT (Owner: Brent | Group: Q0-Advanced) - Commit message: "feat(qa): add security scanning hooks" (After M1)

  • Code [Brent]: Add bandit[toml]>=1.7.5 and semgrep dev dependencies; configure rules in pyproject.toml.
  • Code [Brent]: Add pre-commit hooks for Bandit + Semgrep with minimal safe ruleset.
  • Docs [Brent]: Document security scan expectations in docs/development/quality-automation.md.
  • Tests (Behave) [Rui]: Add scenario verifying Bandit/Semgrep hooks are declared in .pre-commit-config.yaml.
  • Tests (Robot) [Rui]: Add Robot test that runs nox -s security (create session if missing).
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Brent]: git commit -m "feat(qa): add security scanning hooks".

• COMMIT (Owner: Brent | Group: Q0-Advanced) - Commit message: "feat(qa): add complexity monitoring" (After M1)

  • Code [Brent]: Add radon>=6.0.1 and a nox -s complexity session with threshold <=10.
  • Code [Brent]: Add complexity check to CI matrix (non-blocking until M3).
  • Docs [Brent]: Document complexity thresholds and exceptions policy.
  • Tests (Behave) [Rui]: Add scenario that asserts radon configuration exists.
  • Tests (Robot) [Rui]: Add Robot test that runs nox -s complexity on a fixture module.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Brent]: git commit -m "feat(qa): add complexity monitoring".

• COMMIT (Owner: Brent | Group: Q0-Advanced) - Commit message: "docs(qa): add quality automation guide" (After M1)

  • Docs [Brent]: Create docs/development/quality-automation.md with hook lists, CI steps, and troubleshooting.
  • Docs [Brent]: Link the guide from README.md and CONTRIBUTING.md.
  • Tests (Behave) [Rui]: Add scenario verifying the guide exists and is linked.
  • Tests (Robot) [Rui]: Add Robot doc build smoke test via nox -s docs.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Brent]: git commit -m "docs(qa): add quality automation guide".

---

Section 1: Completed Foundation (Phases 0-1) [PRESERVED]

• Phase 0: Discovery and Requirements Elaboration

  • Code: Implement Python discovery tooling for CLI, server, data contracts, supporting assets, environment variables, implicit behaviors, and parity matrix generation.
  • Document: Append findings, scripts, and open questions to Phase 0 Notes with file_path:line_number references.
  • Tests: Run Behave discovery scenarios and Robot smoke suites covering the generated artifacts.

• Phase 1: Architecture Definition

  • Code: Produce ADR stubs, module scaffolding, coding standard configurations, and packaging setup.
    • ADR-001: Python Package Layering and Module Boundaries
    • ADR-002: Asyncio Concurrency Model
    • ADR-003: Dependency Injection Framework
    • ADR-004: Pydantic for Data Validation
    • ADR-005: Error Handling Hierarchy
    • ADR-006: CLEVERAGENTS Environment Variables
    • ADR-007: Repository Pattern for Persistence
    • ADR-008: Provider Plugin Architecture
    • ADR-009: CLI Framework Selection
    • ADR-010: Logging and Observability
  • Document: Update Phase 1 Notes with ADR locations, dependency policies, and style guides.
  • Tests: Execute Ruff, pyright, Behave architecture scenarios, and Robot lint pipelines.

---

Section 2: Preserved Work from Previous Implementation [PRESERVED]

• LangChain/LangGraph Foundation

  • Dependencies installed (langchain, langgraph, langsmith, etc.)
  • ADR-011: LangChain/LangGraph Integration Patterns
  • Base StateGraph classes (BaseAgent, BaseStateGraph)
  • LangChain mock provider (FakeListLLM)

• Core LangGraph Workflows

  • PlanGenerationGraph (load_context -> analyze_requirements -> generate_plan -> validate)
  • ContextAnalysisAgent (5-node workflow for context analysis)
  • AutoDebugGraph (analyze_error -> generate_fix -> validate_fix -> apply_fix)
  • Memory service with EntityMemory
  • CLI streaming integration

• Provider Integration

  • Provider registry
  • OpenAI, Anthropic, Google, OpenRouter adapters
  • LangSmith observability

• Actor System (Stage 7.5)

  • Actor domain model with config hashing
  • Actor persistence (database, repository)
  • Actor registry (built-ins from provider registry)
  • Actor CLI commands (add, update, remove, list, show)
  • Actor-first plan/chat commands (--actor flag)
  • v2 format compatibility for actor configs

---

Section 3: Plan Lifecycle [WORKSTREAM A - Luis Lead]

Target: Milestone M1 (+7 days)

WEEK 1 - CRITICAL PATH

• Stage A1: Plan Data Model (Day 1) - COMPLETED 2026-02-05

  • Code: Create Plan domain model
    • Define Plan Pydantic model with fields (plan_id ULID, parent_plan_id, root_plan_id, attempt counter, phase, state, timestamps)
    • Define PlanPhase enum (Action, Strategize, Execute, Apply, Applied)
    • Define PlanState enum per phase (available, draft, archived, queued, processing, errored, complete, cancelled)
    • Add namespace support to plan naming ([server:][namespace/]<name>)
    • Location: src/cleveragents/domain/models/core/plan.py
  • Tests: Behave scenarios for plan model validation, phase/state transitions (30 scenarios in features/plan_model.feature)

• Stage A2: Action Model (Day 1) - COMPLETED 2026-02-05

  • Code: Create Action domain model
    • Define Action Pydantic model (name, description, definition_of_done, strategy_actor, execution_actor, inputs_schema, reusable, read_only)
    • Add argument parsing for action parameters (--arg name:type:required|optional:description)
    • Location: src/cleveragents/domain/models/core/action.py
  • Tests: Behave scenarios for action model validation (22 scenarios in features/action_model.feature) Parallel Group A2b: Action/Plan Spec Alignment (M1-critical) PARALLEL SUBTRACK A2b.alpha [Jeff]: Action metadata alignment PARALLEL SUBTRACK A2b.beta [Luis]: Plan metadata alignment PARALLEL SUBTRACK A2b.gamma [Aditya]: Action YAML schema + examples (config-first)
    • COMMIT (Owner: Jeff | Group: A2b.alpha) - Commit message: "feat(domain): add action invariants and automation metadata" (Only check after all subitems + nox pass + coverage >=97%, then commit)
      • Code [Jeff]: Add automation_profile, invariant_actor, and invariants fields to Action with clear docstrings and defaults.
      • Code [Jeff]: Add validation that invariant strings are non-empty and automation profile names follow <namespace>/<name> rules.
      • Code [Jeff]: Add definition_of_done_template (string) to preserve templated DoD before argument substitution.
      • Docs [Jeff]: Update action model reference doc (create docs/reference/action_model.md if missing) to include new fields.
      • Tests (Behave) [Rui]: Add scenarios verifying action invariants and automation profile validation in features/action_model.feature.
      • Tests (Robot) [Rui]: Add a smoke test that creates an action with --automation-profile and --invariant once CLI is wired.
      • Quality [Brent]: Run nox and verify coverage >=97%.
      • Commit [Jeff]: git commit -m "feat(domain): add action invariants and automation metadata".
    • COMMIT (Owner: Luis | Group: A2b.beta) - Commit message: "feat(domain): add plan automation and invariant metadata" (Only check after all subitems + nox pass + coverage >=97%, then commit)
      • Code [Luis]: Add automation_profile, invariant_actor, and invariants fields to Plan (v3 lifecycle model).
      • Code [Luis]: Add action_id, changeset_id, and sandbox_refs fields for lifecycle tracking (keep optional for MVP).
      • Code [Luis]: Add validation to ensure automation_profile is locked after plan use and cannot be mutated in later phases.
      • Docs [Luis]: Update docs/reference/plan_model.md with new metadata fields and phase rules.
      • Tests (Behave) [Rui]: Add scenarios in features/plan_model.feature verifying automation profile lock and invariant persistence.
      • Tests (Robot) [Rui]: Add a Robot scenario that inspects plan status output once CLI is updated.
      • Quality [Brent]: Run nox and verify coverage >=97%.
      • Commit [Luis]: git commit -m "feat(domain): add plan automation and invariant metadata".
    • COMMIT (Owner: Aditya | Group: A2b.gamma) - Commit message: "docs(action): add action YAML schema and examples" (Only check after all subitems + nox pass + coverage >=97%, then commit)
      • Docs [Aditya]: Author docs/schema/action.schema.yaml covering description, DoD, actors, inputs, invariants, automation profile.
      • Docs [Aditya]: Add example action configs under examples/actions/ (simple + multi-project + invariant-heavy).
      • Code [Aditya]: Add minimal schema validation helper in src/cleveragents/action/schema.py to load/validate YAML without CLI.
      • Tests (Behave) [Rui]: Add scenarios that load each example and assert schema validation passes.
      • Tests (Robot) [Rui]: Add a Robot smoke test that reads example YAML files and reports parse success.
      • Quality [Brent]: Run nox and verify coverage >=97%.
      • Commit [Aditya]: git commit -m "docs(action): add action YAML schema and examples".

• Stage A3: Plan State Machine (Day 1-2) - COMPLETED 2026-02-05

  • Code: Implement plan lifecycle state machine
    • Create PlanLifecycleService with phase transition methods
    • Implement create_action() - creates plan in Action phase
    • Implement use_action(action, projects, args) - transitions to Strategize
    • Implement execute_plan() - transitions to Execute
    • Implement apply_plan() - transitions to Applied
    • Add validation for phase transitions (only valid transitions allowed)
    • Location: src/cleveragents/application/services/plan_lifecycle_service.py
  • Tests: Behave scenarios for all phase transitions, invalid transition errors (29 scenarios in features/plan_lifecycle_service.feature)

• Stage A4: Plan CLI Commands (Day 2-3) - IN PROGRESS 2026-02-05

  • Code: Implement plan lifecycle CLI
    • agents [--data-dir PATH] [--config-path PATH] action create --config <file> [<name>] [--strategy-actor <actor>] [--execution-actor <actor>] [--definition-of-done "<text>"] [--arg ...] (legacy --name syntax kept in historical notes)
    • agents [--data-dir PATH] [--config-path PATH] action list - list available actions
    • agents [--data-dir PATH] [--config-path PATH] action show <name> - show action details
    • agents [--data-dir PATH] [--config-path PATH] action available <id> - make action available
    • agents [--data-dir PATH] [--config-path PATH] action archive <id> - archive action
    • agents [--data-dir PATH] [--config-path PATH] plan use <action> <project> [--arg name=value ...] - create plan from action (legacy --project syntax kept in historical notes)
    • agents [--data-dir PATH] [--config-path PATH] plan execute [plan_id] - execute current or specified plan
    • agents [--data-dir PATH] [--config-path PATH] plan apply [plan_id] - apply executed plan (v3 lifecycle)
    • agents [--data-dir PATH] [--config-path PATH] plan status [plan_id] - show plan phase/state
    • agents [--data-dir PATH] [--config-path PATH] plan list [--phase <phase>] [--state <state>] [--project <project>] [--action <action>] - list plans with filters
    • agents [--data-dir PATH] [--config-path PATH] plan cancel <plan_id> - cancel non-terminal plan
    • Location: src/cleveragents/cli/commands/action.py, src/cleveragents/cli/commands/plan.py
  • Tests: Behave tests for action CLI (15 scenarios in features/action_cli.feature) Parallel Group A4b: Action/Plan CLI Spec Alignment + Tests (M1-critical) PARALLEL SUBTRACK A4b.alpha [Jeff]: CLI feature alignment PARALLEL SUBTRACK A4b.beta [Rui]: Behave + Robot coverage
    • COMMIT (Owner: Jeff | Group: A4b.alpha) - Commit message: "feat(cli): support action create from YAML config" (Only check after all subitems + nox pass + coverage >=97%, then commit)
      • Code [Jeff]: Add --config support to agents action create and wire to Action YAML loader.
      • Code [Jeff]: Implement override precedence (CLI flags override config file fields) per spec.
      • Docs [Jeff]: Update CLI docs to show YAML-based action creation and override examples.
      • Tests (Behave) [Rui]: Add scenarios in features/action_cli.feature covering config file creation, overrides, and invalid YAML.
      • Tests (Robot) [Rui]: Add Robot end-to-end test robot/action_cli_from_config.robot.
      • Quality [Brent]: Run nox and verify coverage >=97%.
      • Commit [Jeff]: git commit -m "feat(cli): support action create from YAML config".
    • COMMIT (Owner: Jeff | Group: A4b.alpha) - Commit message: "feat(cli): extend plan use with invariants and automation profile" (Only check after all subitems + nox pass + coverage >=97%, then commit)
      • Code [Jeff]: Add flags --automation-profile, --invariant, and --invariant-actor to agents plan use.
      • Code [Jeff]: Validate automation profile and invariant input before plan creation.
      • Docs [Jeff]: Update CLI help text and usage examples in docs/reference/plan_cli.md.
      • Tests (Behave) [Rui]: Add scenarios covering profile resolution and invariant attachment in features/plan_lifecycle_cli.feature.
      • Tests (Robot) [Rui]: Add Robot tests for plan use with invariants.
      • Quality [Brent]: Run nox and verify coverage >=97%.
      • Commit [Jeff]: git commit -m "feat(cli): extend plan use with invariants and automation profile".
    • COMMIT (Owner: Rui | Group: A4b.beta) - Commit message: "test(cli): add plan lifecycle Behave and Robot coverage" (Only check after all subitems + nox pass + coverage >=97%, then commit)
      • Tests (Behave) [Rui]: Add full coverage for plan execute, plan apply, plan status, plan list, plan cancel (success + error paths).
      • Tests (Robot) [Rui]: Add robot/plan_lifecycle_cli.robot covering end-to-end lifecycle transitions.
      • Docs [Rui]: Update docs/development/testing.md with new CLI suites.
      • Quality [Brent]: Run nox and verify coverage >=97%.
      • Commit [Rui]: git commit -m "test(cli): add plan lifecycle Behave and Robot coverage".

Parallel Group A5: Plan Persistence (M1-critical) PARALLEL SUBTRACK A5.alpha [Jeff]: Alembic migrations for action/plan tables PARALLEL SUBTRACK A5.beta [Luis]: SQLAlchemy models for new tables SEQUENTIAL AFTER alpha+beta [Jeff + Luis]: Repositories + service integration PARALLEL CONTINUOUS [Rui]: Persistence tests added inside each commit

• COMMIT (Owner: Jeff | Group: A5.alpha) - Commit message: "feat(db): add actions and action_invariants tables" (Only check after all subitems + nox pass + coverage >=97%, then commit)

  • Code [Jeff]: Add Alembic migration for actions with ULID PK, namespaced name, actor refs, DoD, automation_profile, invariant_actor.
  • Code [Jeff]: Add action_invariants table (action_id FK, invariant_text, created_at).
  • Docs [Jeff]: Update docs/reference/database_schema.md with new tables.
  • Tests (Behave) [Rui]: Add scenario that runs migrations and asserts tables exist.
  • Tests (Robot) [Rui]: Add Robot migration smoke test using nox -s db_migrate (create session if missing).
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(db): add actions and action_invariants tables".

• COMMIT (Owner: Jeff | Group: A5.alpha) - Commit message: "feat(db): add lifecycle_plans and plan_projects tables" (Only check after all subitems + nox pass + coverage >=97%, then commit)

  • Code [Jeff]: Add Alembic migration for lifecycle_plans (ULID PK, phase/state, automation_profile, action_id, timestamps).
  • Code [Jeff]: Add plan_projects table (plan_id, project_id, project_read_only flag, alias).
  • Docs [Jeff]: Update schema docs with plan/project link details.
  • Tests (Behave) [Rui]: Add migration scenario to verify plan/project link table.
  • Tests (Robot) [Rui]: Add Robot test that inserts a plan/project link and queries it.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(db): add lifecycle_plans and plan_projects tables".

• COMMIT (Owner: Jeff | Group: A5.alpha) - Commit message: "feat(db): add plan arguments and plan invariants tables" (Only check after all subitems + nox pass + coverage >=97%, then commit)

  • Code [Jeff]: Add plan_arguments table (plan_id, name, value_json) and plan_invariants table (plan_id, invariant_text, source_scope).
  • Docs [Jeff]: Document plan argument storage and invariant source scopes.
  • Tests (Behave) [Rui]: Add migration scenario verifying both tables.
  • Tests (Robot) [Rui]: Add Robot test for plan invariant persistence.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(db): add plan arguments and plan invariants tables".

• COMMIT (Owner: Luis | Group: A5.beta) - Commit message: "feat(models): add action and lifecycle plan ORM models" (Only check after all subitems + nox pass + coverage >=97%, then commit)

  • Code [Luis]: Add SQLAlchemy models for ActionModel, ActionInvariantModel, LifecyclePlanModel, PlanProjectLinkModel, PlanArgumentModel, PlanInvariantModel.
  • Code [Luis]: Implement to_domain() and from_domain() for action/plan models with ULID + timestamp conversion.
  • Docs [Luis]: Update ORM mapping notes in docs/reference/database_schema.md.
  • Tests (Behave) [Rui]: Add scenarios for ORM round-trip serialization.
  • Tests (Robot) [Rui]: Add Robot test that loads a plan and asserts fields map correctly.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(models): add action and lifecycle plan ORM models".

• COMMIT (Owner: Jeff | Group: A5.gamma) - Commit message: "feat(repo): add action and lifecycle plan repositories" (Only check after all subitems + nox pass + coverage >=97%, then commit)

  • Code [Jeff]: Implement ActionRepository CRUD + list filters by namespace/state.
  • Code [Jeff]: Implement PlanRepository CRUD + list filters by phase/state/project.
  • Code [Jeff]: Add retry decorator to repositories; retry only on OperationalError, never on IntegrityError.
  • Docs [Jeff]: Document repository interfaces and expected error types.
    • Tests (Behave) [Rui]: Add scenarios for repository create/get/list/update.
    • Tests (Robot) [Rui]: Add Robot test that exercises repository through service layer.
    • Quality [Brent]: Run nox and verify coverage >=97%.
    • Commit [Jeff]: git commit -m "feat(repo): add action and lifecycle plan repositories".

• COMMIT (Owner: Luis | Group: A5.gamma) - Commit message: "feat(service): persist plan lifecycle via repositories" (Only check after all subitems + nox pass + coverage >=97%, then commit)

  • Code [Luis]: Update PlanLifecycleService to use repositories instead of in-memory dicts.
  • Code [Luis]: Ensure plan creation stores arguments, invariants, and project links.
  • Code [Luis]: Use transaction boundaries for multi-step operations (create action + plan, correction updates).
  • Docs [Luis]: Update service docs to reflect persistence and remove in-memory notes.
    • Tests (Behave) [Rui]: Add scenarios for persisted lifecycle transitions.
    • Tests (Robot) [Rui]: Add end-to-end test that restarts the app and re-reads plan state.
    • Quality [Brent]: Run nox and verify coverage >=97%.
    • Commit [Luis]: git commit -m "feat(service): persist plan lifecycle via repositories".
  • COMMIT (Owner: Luis | Group: A5.gamma) - Commit message: "feat(di): wire lifecycle repos and services" (Only check after all subitems + nox pass + coverage >=97%, then commit)
    • Code [Luis]: Register ActionRepository + PlanRepository in application/container.py and UnitOfWork.
    • Code [Luis]: Inject repositories into PlanLifecycleService and CLI commands.
    • Docs [Luis]: Update DI wiring notes in docs/architecture/decisions/adr-003.md.
    • Tests (Behave) [Rui]: Add scenarios that use container wiring for lifecycle commands.
  • Tests (Robot) [Rui]: Add Robot smoke test verifying CLI uses persisted service.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(di): wire lifecycle repos and services".

• COMMIT (Owner: Rui | Group: A5.tests) - Commit message: "test(persistence): add plan/action persistence suites" (Only check after all subitems + nox pass + coverage >=97%, then commit)

  • Tests (Behave) [Rui]: Add plan persistence scenarios (create, update phase/state, list filters, plan tree, concurrency).
  • Tests (Behave) [Rui]: Add action persistence scenarios (create, list available, delete guard).
  • Tests (Robot) [Rui]: Add plan persistence E2E (full lifecycle, restart persistence, concurrent CLI access).
  • Docs [Rui]: Update docs/development/testing.md with persistence suites.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Rui]: git commit -m "test(persistence): add plan/action persistence suites".

Parallel Group A5.legacy: Remove legacy plan build/apply path (M1-critical)

• COMMIT (Owner: Jeff | Group: A5.legacy) - Commit message: "refactor(plan): remove legacy plan service and CLI" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Remove PlanService usage from CLI (plan tell/build/apply/new/current/list/cd/continue).
  • Code [Jeff]: Remove or archive legacy PlanModel/PlanStatus DB tables if unused by v3.
  • Docs [Jeff]: Update CLI docs to list only v3 lifecycle commands.
  • Tests (Behave) [Rui]: Remove/replace legacy scenarios with v3 equivalents.
  • Tests (Robot) [Rui]: Remove legacy robot suites and add v3 replacements where needed.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "refactor(plan): remove legacy plan service and CLI".

Parallel Group A6: Automation Levels Foundation [Luis + Jeff] (M1-critical; depends on A5 persistence)

• COMMIT (Owner: Luis | Group: A6.core) - Commit message: "feat(domain): add automation level settings" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Add AutomationLevel enum (manual/review/full) in plan domain model.
  • Code [Luis]: Add config setting + env var (CLEVERAGENTS_AUTOMATION_LEVEL) with precedence plan > session > global.
  • Docs [Luis]: Add docs/reference/automation_levels.md describing precedence and defaults.
  • Tests (Behave) [Rui]: Add scenarios for default and override precedence.
  • Tests (Robot) [Rui]: Add config smoke test for automation level resolution.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(domain): add automation level settings".
• COMMIT (Owner: Jeff | Group: A6.service) - Commit message: "feat(service): integrate automation levels in lifecycle" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Add automation_level handling to use_action() and auto transition logic for execute/apply.
  • Code [Jeff]: Add pause/resume behavior for review-before-apply mode.
  • Docs [Jeff]: Update plan lifecycle docs with automation behavior.
  • Tests (Behave) [Rui]: Add manual/review/full automation scenarios.
  • Tests (Robot) [Rui]: Add end-to-end automation flow test.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(service): integrate automation levels in lifecycle".
• COMMIT (Owner: Luis | Group: A6.cli) - Commit message: "feat(cli): add automation level commands" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Add --automation-level to plan use and add plan set-automation-level command.
  • Code [Luis]: Add config set automation-level and session set automation-level commands.
  • Docs [Luis]: Update CLI reference for automation level flags.
  • Tests (Behave) [Rui]: Add CLI scenarios for plan/session automation changes.
  • Tests (Robot) [Rui]: Add Robot CLI coverage for automation commands.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(cli): add automation level commands".

M1 SUCCESS CRITERIA (Day 7 MVP - source code only):

• Action created from YAML config and persisted (namespaced name, invariants, automation profile).
• Project created and linked to a local git-checkout resource.
• Plan use -> strategize -> execute -> apply completes with sandbox isolation and diff review.
• Tool-based change tracking produces a ChangeSet and applies to the repo after approval.
• nox passes with coverage >=97% on the MVP end-to-end path.

---

Section 4: Projects & Resources [WORKSTREAM B - Hamza Lead]

Target: Milestone M2 (+10 days) Week 1-2 focus: local source code only (git-checkout + fs-directory). Database, API, and remote resources are schema-only stubs for future work.

Parallel Group B1: Resource Registry Core [Hamza + Jeff] (can start after A5.alpha migrations are available)

• COMMIT (Owner: Hamza | Group: B1.core) - Commit message: "feat(domain): add resource type spec and resource model" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Create src/cleveragents/domain/models/core/resource_type.py with ResourceTypeSpec, ResourceTypeArgument, ResourceKind (physical/virtual), and SandboxStrategy enum.
  • Code [Hamza]: Add Resource and ResourceRef models with ULID, namespaced name, type name, location, sandbox strategy, read_only, and metadata.
  • Code [Hamza]: Add validators for namespaced naming, ULID format, and parent/child DAG sanity (no self loops, no duplicate edges).
  • Docs [Hamza]: Add docs/reference/resource_model.md with examples for git-checkout and fs-directory resources.
  • Tests (Behave) [Rui]: Add scenarios validating ULID, namespace, and sandbox strategy rules.
  • Tests (Robot) [Rui]: Add Robot test that loads a ResourceTypeSpec YAML fixture and validates it.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(domain): add resource type spec and resource model".
• COMMIT (Owner: Hamza | Group: B1.core) - Commit message: "feat(domain): add project model v3 with linked resources" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Add Project, ProjectResourceLink, ProjectValidation, and ProjectContextPolicy models with ULID and namespaced name.
  • Code [Hamza]: Include invariants, invariant_actor, and automation_profile fields with validation.
  • Docs [Hamza]: Add docs/reference/project_model.md describing resource linking and validation config.
  • Tests (Behave) [Rui]: Add scenarios for project model validation and link overrides.
  • Tests (Robot) [Rui]: Add Robot test that creates a Project object and prints serialized output.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(domain): add project model v3 with linked resources".
• COMMIT (Owner: Jeff | Group: B1.core) - Commit message: "feat(db): add resource registry tables" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Add Alembic migration for resource_types, resources, and resource_edges tables with indexes on type/name.
  • Code [Jeff]: Store resource_kind (physical/virtual) and sandbox_strategy in resources.
  • Docs [Jeff]: Update docs/reference/database_schema.md with resource registry tables.
  • Tests (Behave) [Rui]: Add migration scenarios verifying tables and indices.
  • Tests (Robot) [Rui]: Add Robot migration smoke test using nox -s db_migrate.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(db): add resource registry tables".

Parallel Group B2: Project Persistence + Services [Hamza + Luis] (depends on B1 domain models)

• COMMIT (Owner: Jeff | Group: B2.persistence) - Commit message: "feat(db): add projects and project links tables" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Add Alembic migration for projects, project_resource_links, and project_validations tables.
  • Code [Jeff]: Ensure project names are unique within a namespace.
  • Docs [Jeff]: Document project table schema and link semantics.
  • Tests (Behave) [Rui]: Add migration scenarios verifying project tables.
  • Tests (Robot) [Rui]: Add Robot test that inserts a project and link row.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(db): add projects and project links tables".
• COMMIT (Owner: Hamza | Group: B2.persistence) - Commit message: "feat(repo): add resource repositories" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Implement ResourceTypeRepository CRUD and ResourceRepository CRUD with DAG edge helpers.
  • Code [Hamza]: Add methods for tree traversal and child discovery queries.
  • Docs [Hamza]: Document repository interfaces in docs/reference/repositories.md.
  • Tests (Behave) [Rui]: Add repository scenarios for create/get/list/tree.
  • Tests (Robot) [Rui]: Add Robot test exercising tree output ordering.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(repo): add resource repositories".
• COMMIT (Owner: Hamza | Group: B2.persistence) - Commit message: "feat(repo): add project repositories" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Implement ProjectRepository and ProjectResourceLinkRepository with namespace filtering.
  • Docs [Hamza]: Update repository docs with project link examples.
  • Tests (Behave) [Rui]: Add scenarios for project create/link/unlink.
  • Tests (Robot) [Rui]: Add Robot test that links two resources to one project.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(repo): add project repositories".
• COMMIT (Owner: Hamza | Group: B2.service) - Commit message: "feat(service): add resource registry service" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Implement ResourceRegistryService for register/remove/show/tree operations.
  • Code [Hamza]: Add auto-discovery hook that delegates to resource handlers (git-checkout for MVP).
  • Docs [Hamza]: Add docs/reference/resource_registry.md describing API behavior.
  • Tests (Behave) [Rui]: Add scenarios for register/remove/show/tree behavior.
  • Tests (Robot) [Rui]: Add Robot test that registers a git-checkout and inspects child count.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(service): add resource registry service".
• COMMIT (Owner: Luis | Group: B2.service) - Commit message: "feat(service): add project service v3" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Implement ProjectService create/list/show/delete/link/unlink methods using repositories.
  • Code [Luis]: Add validation commands and context policy setters for project.
  • Docs [Luis]: Update docs/reference/project_service.md with usage examples.
  • Tests (Behave) [Rui]: Add scenarios for project create/link/unlink/validation.
  • Tests (Robot) [Rui]: Add Robot test that creates project and links a resource.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(service): add project service v3".

Parallel Group B3: CLI Commands [Rui] (depends on B2 services)

• COMMIT (Owner: Rui | Group: B3.cli) - Commit message: "feat(cli): add resource type commands" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Rui]: Add agents resource type add/remove/list/show commands with YAML config input.
  • Docs [Rui]: Update CLI reference with resource type examples.
  • Tests (Behave) [Rui]: Add scenarios for resource type lifecycle.
  • Tests (Robot) [Rui]: Add Robot suite robot/resource_type_cli.robot.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Rui]: git commit -m "feat(cli): add resource type commands".
• COMMIT (Owner: Rui | Group: B3.cli) - Commit message: "feat(cli): add resource commands" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Rui]: Add agents resource add/remove/list/show/tree commands with type-specific flags.
  • Docs [Rui]: Update CLI reference with resource examples (git-checkout, fs-directory).
  • Tests (Behave) [Rui]: Add scenarios for resource registration and tree rendering.
  • Tests (Robot) [Rui]: Add Robot suite robot/resource_cli.robot.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Rui]: git commit -m "feat(cli): add resource commands".
• COMMIT (Owner: Rui | Group: B3.cli) - Commit message: "feat(cli): add project commands" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Rui]: Add agents project create/show/list/delete/link-resource/unlink-resource commands.
  • Code [Rui]: Add agents project validation add/remove/list and project context set/show commands.
  • Docs [Rui]: Update CLI reference with project examples and validation output.
  • Tests (Behave) [Rui]: Add scenarios for project create/link/validation.
  • Tests (Robot) [Rui]: Add Robot suite robot/project_cli.robot.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Rui]: git commit -m "feat(cli): add project commands".

Parallel Group B4: Sandboxing [Luis + Jeff] (depends on resource registry + project links)

• COMMIT (Owner: Luis | Group: B4.sandbox) - Commit message: "feat(sandbox): add sandbox strategy interface and manager" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Add SandboxStrategy protocol, SandboxRef, and SandboxManager with per-resource sandboxes.
  • Code [Luis]: Implement lazy sandbox creation and cleanup hooks (retention policy stub).
  • Docs [Luis]: Add docs/reference/sandbox.md describing lifecycle and APIs.
  • Tests (Behave) [Rui]: Add scenarios for sandbox manager creation and cleanup.
  • Tests (Robot) [Rui]: Add Robot test that creates a sandbox and verifies filesystem isolation.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(sandbox): add sandbox strategy interface and manager".
• COMMIT (Owner: Luis | Group: B4.sandbox) - Commit message: "feat(sandbox): implement git_worktree strategy" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Implement git worktree creation, checkout, and cleanup for git-checkout resources.
  • Code [Luis]: Add safe fallback for repositories without clean worktrees.
  • Docs [Luis]: Update sandbox doc with git_worktree usage.
  • Tests (Behave) [Rui]: Add scenarios for git worktree sandbox creation and rollback.
  • Tests (Robot) [Rui]: Add Robot test that modifies sandbox and verifies original repo unchanged.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(sandbox): implement git_worktree strategy".
• COMMIT (Owner: Hamza | Group: B4.sandbox) - Commit message: "feat(resource): add git-checkout handler and discovery" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Add git-checkout handler that validates repo path, branch, and read_only flags.
  • Code [Hamza]: Implement child resource discovery for fs-directory children (schema-only for now).
  • Docs [Hamza]: Document git-checkout handler behavior in docs/reference/resources_git.md.
  • Tests (Behave) [Rui]: Add scenarios for handler validation and discovery counts.
  • Tests (Robot) [Rui]: Add Robot test registering a git repo and asserting discovered children.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(resource): add git-checkout handler and discovery".
• COMMIT (Owner: Luis | Group: B4.sandbox) - Commit message: "feat(sandbox): add copy_on_write strategy stub" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Add copy_on_write strategy skeleton with TODOs for large-project optimization.
  • Docs [Luis]: Document that copy_on_write is stubbed for post-M1 work.
  • Tests (Behave) [Rui]: Add scenario that selecting copy_on_write raises NotImplementedError with clear message.
  • Tests (Robot) [Rui]: Add Robot test verifying stub error output.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(sandbox): add copy_on_write strategy stub".

M2 MERGE GATE:

• Register a git-checkout resource and link it to a project via CLI.
• Create a sandbox for the linked resource and verify isolation via tests.
• Project context/validation commands work and persist.
• nox passes with coverage >=97%.

M2 SUCCESS CRITERIA:

• Resource registry supports resource types, resources, and DAG links with persistence (tables + repositories).
• Projects can link/unlink resources with CLI commands for resource types/resources/projects (list/show/tree included).
• Git-checkout sandbox isolates changes; copy_on_write strategy returns clear NotImplementedError for fs-directory (documented).
• Resource/project services are DI-wired and exercised by Behave + Robot suites.
• nox passes with coverage >=97% across resource/project suites.

---

Section 5: Actors, Skills & Tool Execution [WORKSTREAM C - Aditya Lead]

Target: Milestone M3 (+14 days)

Week 2 focus: Actor YAML, compilation, skills, and tool-based change tracking.

Parallel Group C1: Actor Schema & Examples [Aditya + Jeff] (start Day 5; C2 depends on this)

• COMMIT (Owner: Aditya | Group: C1.schema) - Commit message: "feat(actor): add actor yaml schema models" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Aditya]: Add schema models (ActorType, NodeType, ContextView, ToolDefinition, RouteDefinition, ActorConfigSchema) with strict validation.
  • Code [Aditya]: Add YAML load/serialize helpers and schema version guard.
  • Docs [Aditya]: Add docs/reference/actors_schema.md with field definitions and constraints.
  • Tests (Behave) [Rui]: Add features/actor_schema.feature scenarios for validation and topology errors.
  • Tests (Robot) [Rui]: Add robot/actor_schema.robot YAML load smoke test.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Aditya]: git commit -m "feat(actor): add actor yaml schema models".
• COMMIT (Owner: Aditya | Group: C1.examples) - Commit message: "docs(actor): add actor yaml examples" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Docs [Aditya]: Add docs/reference/actors_examples.md with strategist, executor, reviewer, tool-only, and graph YAML examples.
  • Tests (Behave) [Rui]: Add features/actor_examples.feature to ensure all examples validate.
  • Tests (Robot) [Rui]: Add robot/actor_examples.robot to load each example.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Aditya]: git commit -m "docs(actor): add actor yaml examples".

Parallel Group C2: Actor Loading & Compilation [Aditya + Jeff] (depends on C1)

• COMMIT (Owner: Aditya | Group: C2.loader) - Commit message: "feat(actor): add actor registry and loader" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Aditya]: Implement actor loader/registry with namespaced lookup and cache invalidation.
  • Docs [Aditya]: Add docs/reference/actors_loading.md with discovery rules and namespaces.
  • Tests (Behave) [Rui]: Add features/actor_loading.feature for discovery, duplicates, and namespace lookup.
  • Tests (Robot) [Rui]: Add robot/actor_loading.robot for loader smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Aditya]: git commit -m "feat(actor): add actor registry and loader".
• COMMIT (Owner: Jeff | Group: C2.compiler) - Commit message: "feat(actor): compile actor configs to LangGraph" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Implement ActorCompiler that builds LangGraph for LLM, TOOL, and GRAPH actors with tool node wiring.
  • Docs [Jeff]: Add docs/reference/actors_compilation.md covering compile outputs and error modes.
  • Tests (Behave) [Rui]: Add features/actor_compilation.feature for LLM/GRAPH compilation.
  • Tests (Robot) [Rui]: Add robot/actor_compilation.robot smoke test compiling all examples.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(actor): compile actor configs to LangGraph".
• COMMIT (Owner: Jeff | Group: C2.refs) - Commit message: "feat(actor): resolve actor references and subgraphs" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Implement reference resolution, cycle detection, and subgraph wiring for actor refs.
  • Docs [Jeff]: Update docs/reference/actors_compilation.md with reference semantics.
  • Tests (Behave) [Rui]: Add features/actor_reference_resolution.feature for missing/recursive refs.
  • Tests (Robot) [Rui]: Add robot/actor_reference_resolution.robot for subgraph wiring.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(actor): resolve actor references and subgraphs".

Parallel Group C3: Skill Protocol & Context [Jeff] (critical path; depends on C1)

• COMMIT (Owner: Jeff | Group: C3.protocol) - Commit message: "feat(skill): add skill protocol and metadata" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Define Skill protocol interface, SkillMetadata, SkillResult, and SkillError types.
  • Docs [Jeff]: Add docs/reference/skills_protocol.md describing metadata and JSON schema rules.
  • Tests (Behave) [Rui]: Add features/skill_protocol.feature for metadata validation and error capture.
  • Tests (Robot) [Rui]: Add robot/skill_protocol.robot smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(skill): add skill protocol and metadata".
• COMMIT (Owner: Jeff | Group: C3.context) - Commit message: "feat(skill): add skill context and registry" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Implement SkillContext (plan/resource access, sandbox path, change tracker) and SkillRegistry.
  • Docs [Jeff]: Add docs/reference/skills_context.md with context fields and helper methods.
  • Tests (Behave) [Rui]: Add features/skill_context.feature for sandboxed access and registry resolution.
  • Tests (Robot) [Rui]: Add robot/skill_context.robot for registry smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(skill): add skill context and registry".
• COMMIT (Owner: Jeff | Group: C3.inline) - Commit message: "feat(skill): add inline tool executor" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Implement inline tool execution with timeouts and restricted environment.
  • Docs [Jeff]: Add docs/reference/skills_inline.md with safety constraints.
  • Tests (Behave) [Rui]: Add features/skill_inline.feature for execution and timeout handling.
  • Tests (Robot) [Rui]: Add robot/skill_inline.robot for inline tool smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(skill): add inline tool executor".

Parallel Group C4: Built-in Skills [Jeff + Luis] (depends on C3)

• COMMIT (Owner: Jeff | Group: C4.file) - Commit message: "feat(skill): add file operation skills" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Implement ReadFile, WriteFile, EditFile, and DeleteFile skills with read_only enforcement.
  • Docs [Jeff]: Add docs/reference/skills_file.md with examples and error cases.
  • Tests (Behave) [Rui]: Add features/skill_file_ops.feature for read/write/edit/delete flows.
  • Tests (Robot) [Rui]: Add robot/skill_file_ops.robot for file ops integration.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(skill): add file operation skills".
• COMMIT (Owner: Jeff | Group: C4.search) - Commit message: "feat(skill): add directory and search skills" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Implement ListDir, Glob, and Grep skills with ignore patterns and size limits.
  • Docs [Jeff]: Add docs/reference/skills_search.md with examples.
  • Tests (Behave) [Rui]: Add features/skill_search.feature for listing/globbing/searching.
  • Tests (Robot) [Rui]: Add robot/skill_search.robot for search integration.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(skill): add directory and search skills".
• COMMIT (Owner: Luis | Group: C4.git) - Commit message: "feat(skill): add git operation skills" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Implement read-only git skills (status, diff, log, show) for sandboxed repos.
  • Docs [Luis]: Add docs/reference/skills_git.md clarifying no destructive ops in MVP.
  • Tests (Behave) [Rui]: Add features/skill_git.feature for git skill outputs.
  • Tests (Robot) [Rui]: Add robot/skill_git.robot for git skill integration.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(skill): add git operation skills".

Parallel Group C5: Tool Routing & Change Tracking [Luis + Jeff] (depends on C3/C4)

• COMMIT (Owner: Luis | Group: C5.model) - Commit message: "feat(change): add ChangeSet models and invocation tracker" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Add Change/ChangeSet/ToolInvocation models and SkillInvocationTracker.
  • Docs [Luis]: Add docs/reference/change_tracking.md describing tool-to-change mapping.
  • Tests (Behave) [Rui]: Add features/change_tracking.feature for ChangeSet aggregation.
  • Tests (Robot) [Rui]: Add robot/change_tracking.robot for tracker smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(change): add ChangeSet models and invocation tracker".
• COMMIT (Owner: Jeff | Group: C5.router) - Commit message: "feat(change): add tool router for providers" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Implement ToolCallRouter for OpenAI/Anthropic/LangChain tool schemas with deterministic IDs.
  • Docs [Jeff]: Add docs/reference/tool_router.md with provider-specific mappings.
  • Tests (Behave) [Rui]: Add features/tool_router.feature for schema mapping.
  • Tests (Robot) [Rui]: Add robot/tool_router.robot for routing smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(change): add tool router for providers".
• COMMIT (Owner: Luis | Group: C5.diff) - Commit message: "feat(change): add diff review artifacts" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Implement DiffBuilder and ReviewArtifact models for CLI review.
  • Docs [Luis]: Add docs/reference/diff_review.md with output format.
  • Tests (Behave) [Rui]: Add features/diff_review.feature for diff generation.
  • Tests (Robot) [Rui]: Add robot/diff_review.robot for review artifacts.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(change): add diff review artifacts".

Parallel Group C6: Validation Pipeline [Luis + Jeff] (depends on C5 and project validation config)

• COMMIT (Owner: Luis | Group: C6.pipeline) - Commit message: "feat(validation): add validation pipeline and results model" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Implement ValidationCommand, ValidationResult, and ValidationPipeline using project validation config.
  • Docs [Luis]: Add docs/reference/validation_pipeline.md with command ordering and timeouts.
  • Tests (Behave) [Rui]: Add features/validation_pipeline.feature for pass/fail paths.
  • Tests (Robot) [Rui]: Add robot/validation_pipeline.robot for pipeline smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(validation): add validation pipeline and results model".
• COMMIT (Owner: Jeff | Group: C6.gating) - Commit message: "feat(validation): integrate validation with apply gating" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Block apply on validation failure; surface validation artifacts for review.
  • Docs [Jeff]: Update docs/reference/plan_actor_integration.md with validation gating behavior.
  • Tests (Behave) [Rui]: Add features/validation_gating.feature for apply blocking.
  • Tests (Robot) [Rui]: Add robot/validation_gating.robot for end-to-end gating.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(validation): integrate validation with apply gating".

Parallel Group C7: MCP Adapter [Aditya] (depends on C3)

• COMMIT (Owner: Aditya | Group: C7.mcp) - Commit message: "feat(skill): add MCP adapter for external tools" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Aditya]: Implement MCP client adapter conforming to Skill interface with connection config.
  • Docs [Aditya]: Add docs/reference/skills_mcp.md with server connection examples.
  • Tests (Behave) [Rui]: Add features/skill_mcp.feature for MCP tool calls.
  • Tests (Robot) [Rui]: Add robot/skill_mcp.robot for MCP adapter smoke test.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Aditya]: git commit -m "feat(skill): add MCP adapter for external tools".

Parallel Group C8: Built-in Provider Actors [Aditya] (depends on C1/C2)

• COMMIT (Owner: Aditya | Group: C8.providers) - Commit message: "feat(actor): add built-in provider actors" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Aditya]: Add built-in actor configs for openai/, anthropic/, and openrouter/ (plus google/ if configured).
  • Docs [Aditya]: Add docs/reference/provider_actors.md with provider defaults.
  • Tests (Behave) [Rui]: Add features/provider_actors.feature for built-in actor loading.
  • Tests (Robot) [Rui]: Add robot/provider_actors.robot for registry visibility.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Aditya]: git commit -m "feat(actor): add built-in provider actors".

Parallel Group C9: Plan-Actor Integration [Jeff + Luis] (depends on C2/C5/C6)

• COMMIT (Owner: Jeff | Group: C9.execute) - Commit message: "feat(plan): execute strategize and execute phases via actors" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Connect PlanLifecycleService to actor execution for Strategize and Execute phases.
  • Docs [Jeff]: Add docs/reference/plan_actor_integration.md with phase flow.
  • Tests (Behave) [Rui]: Add features/plan_actor_integration.feature for strategy/execute flows.
  • Tests (Robot) [Rui]: Add robot/plan_actor_integration.robot for end-to-end actor execution.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(plan): execute strategize and execute phases via actors".
• COMMIT (Owner: Jeff | Group: C9.apply) - Commit message: "feat(plan): integrate change review and apply flow" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Wire ChangeSet review artifacts into plan diff and review-before-apply flow.
  • Docs [Jeff]: Update CLI docs for plan diff and plan apply review output.
  • Tests (Behave) [Rui]: Add features/plan_review_apply.feature for review gate behavior.
  • Tests (Robot) [Rui]: Add robot/plan_review_apply.robot for review-before-apply path.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(plan): integrate change review and apply flow".

M3 SUCCESS CRITERIA:

• Actor YAML schema validated; examples load and compile to LangGraph.
• Skills execute via SkillContext; built-in file/dir/search/git skills available.
• Tool-based change tracking (no output parsing) produces ChangeSet and diff review artifacts.
• MCP adapter executes a tool against a test MCP server.
• Built-in provider actors available (openai/, anthropic/, openrouter/ as configured).
• Validation pipeline runs project validation commands and blocks apply on failure.
• Plan lifecycle uses actors for Strategize/Execute and applies ChangeSet after review.
• nox passes with coverage >=97% across actor/skill/change-tracking suites.

--- MERGE POINT 1: After M3, all workstreams coordinate ---

---

Section 6: Execution Pipeline, Decisions & Invariants [M3-M4]

Target: Milestone M4 (+21 days) Week 3 focus: decision capture, correction, invariants, and DoD gating.

Parallel Group D1: Decision Domain [Hamza + Rui] (foundation for D2-D5)

• COMMIT (Owner: Hamza | Group: D1.domain) - Commit message: "feat(domain): add decision model and context snapshots" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Add DecisionType, ContextSnapshot, and Decision models with correction fields and helpers.
  • Docs [Hamza]: Add docs/reference/decision_model.md with examples and schema notes.
  • Tests (Behave) [Rui]: Add features/decision_model.feature for validation and helpers.
  • Tests (Robot) [Rui]: Add robot/decision_model.robot smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(domain): add decision model and context snapshots".

Parallel Group D2: Decision Recording Service [Hamza + Luis] (depends on D1)

• COMMIT (Owner: Hamza | Group: D2.service) - Commit message: "feat(service): add decision recording and snapshot store" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Implement DecisionService with record_decision, sequence numbers, tree queries, and downstream linking.
  • Code [Hamza]: Add ContextSnapshotStore interface with a file-backed MVP implementation and hash dedupe.
  • Code [Luis]: Integrate decision recording into strategize/execute phases (prompt/strategy/subplan/tool decisions).
  • Docs [Hamza]: Add docs/reference/decision_service.md covering recording and snapshots.
  • Tests (Behave) [Rui]: Add features/decision_recording.feature scenarios.
  • Tests (Robot) [Rui]: Add robot/decision_recording.robot integration smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(service): add decision recording and snapshot store".

Parallel Group D3: Decision CLI & Viewing [Hamza + Rui] (depends on D1/D2)

• COMMIT (Owner: Hamza | Group: D3.cli) - Commit message: "feat(cli): add plan tree and explain commands" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Implement plan tree and plan explain with rich/json/flat formats and --show-superseded/--show-context.
  • Docs [Hamza]: Update CLI reference for decision viewing commands.
  • Tests (Behave) [Rui]: Add tree/explain scenarios including superseded handling.
  • Tests (Robot) [Rui]: Add robot/decision_cli.robot smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(cli): add plan tree and explain commands".

Parallel Group D4: Decision Correction [Jeff + Luis] (depends on D2/D3)

• COMMIT (Owner: Jeff | Group: D4.revert) - Commit message: "feat(service): add decision correction revert flow" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Implement correction impact analysis and dry-run reporting.
  • Code [Jeff]: Revert flow with checkpoint rollback, supersede downstream decisions, and subtree re-exec.
  • Docs [Jeff]: Add docs/reference/decision_correction.md for revert behavior.
  • Tests (Behave) [Rui]: Add revert + dry-run scenarios.
  • Tests (Robot) [Rui]: Add revert integration tests with checkpoint rollback.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(service): add decision correction revert flow".
• COMMIT (Owner: Jeff | Group: D4.append) - Commit message: "feat(service): add decision correction append flow" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Append flow creating fix subplan without rewriting history; link correction attempt + decision tree updates.
  • Docs [Jeff]: Extend correction docs for append mode and guidance-file usage.
  • Tests (Behave) [Rui]: Add append correction scenarios.
  • Tests (Robot) [Rui]: Add append correction smoke test.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(service): add decision correction append flow".

Parallel Group D5: Decision Persistence [Hamza + Luis] (depends on D1)

• COMMIT (Owner: Hamza | Group: D5.db) - Commit message: "feat(db): add decision tables" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Add Alembic migrations for decisions and context_snapshots with indexes.
  • Docs [Hamza]: Update docs/reference/database_schema.md with decision tables.
  • Tests (Behave) [Rui]: Add migration verification scenarios.
  • Tests (Robot) [Rui]: Add DB migration smoke test.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(db): add decision tables".
• COMMIT (Owner: Hamza | Group: D5.repo) - Commit message: "feat(repo): add decision repositories" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Implement DecisionRepository + ContextSnapshotRepository with tree queries and max-sequence helpers.
  • Docs [Hamza]: Document repository interfaces in docs/reference/repositories.md.
  • Tests (Behave) [Rui]: Add decision persistence scenarios (create/query/superseded).
  • Tests (Robot) [Rui]: Add repository integration smoke test.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(repo): add decision repositories".
• COMMIT (Owner: Luis | Group: D5.di) - Commit message: "feat(di): wire decision services" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Wire decision repositories + services into DI and CLI.
  • Docs [Luis]: Update DI docs for decision wiring.
  • Tests (Behave) [Rui]: Add DI wiring scenarios for decision commands.
  • Tests (Robot) [Rui]: Add CLI smoke test using persisted decisions.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(di): wire decision services".
• COMMIT (Owner: Rui | Group: D5.tests) - Commit message: "test(persistence): add decision persistence suites" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Tests (Behave) [Rui]: Add features/decision_persistence.feature scenarios.
  • Tests (Robot) [Rui]: Add robot/decision_persistence.robot E2E coverage.
  • Docs [Rui]: Update docs/development/testing.md with decision suites.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Rui]: git commit -m "test(persistence): add decision persistence suites".

Parallel Group DOD: Definition of Done + Invariants [Luis + Jeff] (depends on D2/D4)

• COMMIT (Owner: Luis | Group: DOD.dod) - Commit message: "feat(dod): enforce definition-of-done gating" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Evaluate definition_of_done before apply; block apply with clear error if unmet.
  • Docs [Luis]: Add docs/reference/definition_of_done.md with examples.
  • Tests (Behave) [Rui]: Add DoD pass/fail scenarios.
  • Tests (Robot) [Rui]: Add DoD integration smoke test.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(dod): enforce definition-of-done gating".
• COMMIT (Owner: Jeff | Group: DOD.invariants) - Commit message: "feat(invariant): add invariant models and enforcement" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Add invariant models, merge order (action/project/plan/global), and enforcement before apply.
  • Code [Jeff]: Add agents invariant add/list/remove CLI with scope flags.
  • Docs [Jeff]: Add docs/reference/invariants.md and update CLI reference.
  • Tests (Behave) [Rui]: Add invariant merge + violation scenarios.
  • Tests (Robot) [Rui]: Add invariant CLI integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(invariant): add invariant models and enforcement".

Section 7: Subplans & Parallelism [M5]

Target: Milestone M5 (+25 days) Week 3-4 focus: subplan spawning, parallel execution, and result merging.

Parallel Group E1: Subplan Domain [Luis + Rui]

• COMMIT (Owner: Luis | Group: E1.domain) - Commit message: "feat(domain): add subplan config and status models" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Add ExecutionMode, MergeStrategy, SubplanConfig, SubplanStatus, and SubplanAttempt models.
  • Code [Luis]: Extend Plan with parent/root IDs, subplan statuses, and helpers (is_subplan, has_subplans).
  • Docs [Luis]: Add docs/reference/subplan_model.md.
  • Tests (Behave) [Rui]: Add features/subplan_model.feature scenarios.
  • Tests (Robot) [Rui]: Add robot/subplan_model.robot smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(domain): add subplan config and status models".

Parallel Group E2: Subplan Spawning [Jeff + Aditya] (depends on D2 + E1)

• COMMIT (Owner: Jeff | Group: E2.service) - Commit message: "feat(service): add subplan service and spawn workflow" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Implement SubplanService with spawn_subplan, spawn_batch, tree queries, bounded context builder.
  • Code [Jeff]: Link SUBPLAN_SPAWN decisions to created subplans and status tracking.
  • Docs [Jeff]: Add docs/reference/subplan_service.md.
  • Tests (Behave) [Rui]: Add subplan spawn scenarios.
  • Tests (Robot) [Rui]: Add subplan spawn integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(service): add subplan service and spawn workflow".
• COMMIT (Owner: Aditya | Group: E2.actor) - Commit message: "feat(actor): add plan_subplan tool and decision emission" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Aditya]: Add plan_subplan tool to strategy actors and emit SUBPLAN_SPAWN decisions.
  • Docs [Aditya]: Update actor YAML examples for subplan emission.
  • Tests (Behave) [Rui]: Add scenarios for subplan decision emission.
  • Tests (Robot) [Rui]: Add actor tool integration smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Aditya]: git commit -m "feat(actor): add plan_subplan tool and decision emission".

Parallel Group E3: Parallel Execution [Luis + Jeff] (depends on E1/E2)

• COMMIT (Owner: Luis | Group: E3.exec) - Commit message: "feat(service): add subplan scheduler and execution" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Add subplan scheduler with max_parallel, dependency ordering, and fail-fast handling.
  • Code [Luis]: Track status updates for subplans and propagate to parent plan.
  • Docs [Luis]: Add docs/reference/subplan_execution.md.
  • Tests (Behave) [Rui]: Add parallel + dependency execution scenarios.
  • Tests (Robot) [Rui]: Add parallel execution integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(service): add subplan scheduler and execution".

Parallel Group E4: Result Merging [Jeff + Luis] (depends on E3)

• COMMIT (Owner: Jeff | Group: E4.merge) - Commit message: "feat(merge): add subplan merge strategies" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Add three-way merge strategy for file changes and conflict markers.
  • Code [Luis]: Add sequential merge and JSON merge strategies; expose merge result artifacts.
  • Docs [Jeff]: Add docs/reference/subplan_merge.md.
  • Tests (Behave) [Rui]: Add merge + conflict scenarios.
  • Tests (Robot) [Rui]: Add merge integration tests for multi-subplan plans.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(merge): add subplan merge strategies".

Parallel Group E5: Multi-Project Plans [Hamza + Luis] (depends on E2/E4)

• COMMIT (Owner: Hamza | Group: E5.multi) - Commit message: "feat(plan): add multi-project subplan support" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Allow plans to target multiple projects with separate resource link contexts.
  • Code [Luis]: Ensure sandbox isolation and cross-project dependency resolution.
  • Docs [Hamza]: Add docs/reference/multi_project_plans.md.
  • Tests (Behave) [Rui]: Add multi-project subplan scenarios.
  • Tests (Robot) [Rui]: Add multi-project integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(plan): add multi-project subplan support".

Section 8: Large Project Autonomy & Context [M6]

Target: Milestone M6 (+30 days) Local-mode only: large-project autonomy is required; server connectivity remains stubbed.

Parallel Group G1: Large-Project Decomposition [Jeff + Luis]

• COMMIT (Owner: Jeff | Group: G1.decompose) - Commit message: "feat(plan): add large-project decomposition and dependency closure" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Jeff]: Add hierarchical decomposition with 4+ levels and bounded context per subplan.
  • Code [Luis]: Add dependency closure computation for large graphs and DAG execution ordering.
  • Docs [Jeff]: Add docs/reference/large_project_decomposition.md.
  • Tests (Behave) [Rui]: Add deep hierarchy + dependency closure scenarios.
  • Tests (Robot) [Rui]: Add large-project decomposition integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "feat(plan): add large-project decomposition and dependency closure".

Parallel Group G2: Checkpointing & Rollback [Luis]

• COMMIT (Owner: Luis | Group: G2.checkpoint) - Commit message: "feat(checkpoint): add checkpointing and rollback" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Add checkpoint declarations for skills and plan-level rollback policy.
  • Code [Luis]: Implement plan rollback <plan_id> <checkpoint_id> command.
  • Docs [Luis]: Add docs/reference/checkpointing.md.
  • Tests (Behave) [Rui]: Add checkpoint/rollback scenarios.
  • Tests (Robot) [Rui]: Add rollback integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(checkpoint): add checkpointing and rollback".

Parallel Group G3: Semantic Validation [Luis]

• COMMIT (Owner: Luis | Group: G3.semantic) - Commit message: "feat(validation): add semantic validation service" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Add semantic validation hooks during strategize/execute and error-pattern checks.
  • Docs [Luis]: Add docs/reference/semantic_validation.md.
  • Tests (Behave) [Rui]: Add semantic validation scenarios.
  • Tests (Robot) [Rui]: Add semantic validation integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(validation): add semantic validation service".

Parallel Group G4: Context Tiers & Views [Hamza + Rui]

• COMMIT (Owner: Hamza | Group: G4.context) - Commit message: "feat(context): add hot/warm/cold tiers and actor views" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Implement hot/warm/cold tiers with indexing, LRU eviction, and promotion/demotion.
  • Code [Hamza]: Add per-actor context views (strategist/executor/reviewer) and filtered presentation.
  • Docs [Hamza]: Add docs/reference/context_tiers.md.
  • Tests (Behave) [Rui]: Add context tier scenarios.
  • Tests (Robot) [Rui]: Add context tier integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(context): add hot/warm/cold tiers and actor views".

Parallel Group G5: Cost & Risk Estimation [Hamza]

• COMMIT (Owner: Hamza | Group: G5.estimate) - Commit message: "feat(estimation): add cost and risk estimation actor" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Add optional estimation_actor role and cost/risk estimation outputs.
  • Docs [Hamza]: Add docs/reference/estimation.md with output format.
  • Tests (Behave) [Rui]: Add estimation scenarios.
  • Tests (Robot) [Rui]: Add estimation integration smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(estimation): add cost and risk estimation actor".

Parallel Group G6: CLI Polish [All]

• COMMIT (Owner: Jeff | Group: G6.cli) - Commit message: "chore(cli): polish help and output" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [All]: Standardize help text, progress indicators, and error messages with recovery hints.
  • Docs [All]: Update CLI output examples where needed.
  • Tests (Robot) [Rui]: Add CLI UX smoke tests for critical commands.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Jeff]: git commit -m "chore(cli): polish help and output".

--- MERGE POINT 2: Day 30 - Large Project Autonomy Target (LOCAL MODE ONLY) ---

By Day 30, the system must be able to (all in LOCAL MODE, server connectivity is deferred):

• Handle projects with 10,000+ files using hierarchical decomposition.
• Port source code from one language to another autonomously.
• Use hierarchical subplans (5+ levels deep) for large tasks.
• Correct decisions at any point without full re-execution.
• Operate entirely in local mode (server client stubs in place but not implemented).

Section 9: Server Connectivity (Stubs Only) [Beyond Day 30]

Target: Milestone M7 (+35 days)

Parallel Group F0: Server Client Stubs [Luis + Rui] (required for M6; no server implementation)

• COMMIT (Owner: Luis | Group: F0.stubs) - Commit message: "feat(interfaces): add server client stubs" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Add protocol stubs for ServerClient, RemoteExecutionClient, and AuthClient with NotImplementedError.
  • Code [Luis]: Add agents connect <server_url> CLI stub in cli/commands/server_client.py.
  • Docs [Luis]: Add docs/reference/server_client_stubs.md noting client-only behavior.
  • Tests (Behave) [Rui]: Add stub behavior scenarios.
  • Tests (Robot) [Rui]: Add CLI stub smoke test.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(interfaces): add server client stubs".

Deferred Groups (Post-Day 30, client-only)

• COMMIT (Owner: Luis | Group: F1.client) - Commit message: "feat(client): add server http client" [DEFERRED]
  • Code [Luis]: HTTP client, health check, version negotiation, OpenAPI codegen.
  • Tests (Robot) [Rui]: Mock-server connection tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
• COMMIT (Owner: Luis | Group: F2.sync) - Commit message: "feat(client): add plan sync and remote execution" [DEFERRED]
  • Code [Luis]: Sync actions, request remote plan execution/apply/status.
  • Tests (Robot) [Rui]: Mock-server sync tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
• COMMIT (Owner: Luis | Group: F3.ws) - Commit message: "feat(client): add websocket updates" [DEFERRED]
  • Code [Luis]: WebSocket client for plan updates.
  • Tests (Robot) [Rui]: WebSocket mock tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
• COMMIT (Owner: Hamza | Group: F4.remote) - Commit message: "feat(client): add remote project support" [DEFERRED]
  • Code [Hamza]: Remote resource selection and server execution requests.
  • Tests (Robot) [Rui]: Remote execution mock tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.

M7 SUCCESS CRITERIA (Post-Day 30):

• agents [--data-dir PATH] [--config-path PATH] connect <server_url> establishes connection to an external server.
• Plans can be synced and executed on a remote server.
• Real-time updates received via WebSocket from server.
• Remote projects can be specified and executed on server.

Section 10: Async Infrastructure & Later-Stage Quality Work [Various Leads]

Note: Quality automation setup is in Section 0; Section 10 focuses on async infrastructure and later-stage validation support.

Parallel Group 10A: Async Infrastructure [Luis]

• COMMIT (Owner: Luis | Group: 10A.async) - Commit message: "feat(async): add async command execution and workers" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Implement async command execution per ADR-002 with cancellation and timeout handling.
  • Code [Luis]: Add background worker orchestration for plan lifecycle events.
  • Docs [Luis]: Update docs/reference/async_architecture.md with execution flow and shutdown rules.
  • Tests (Behave) [Rui]: Add features/async_execution.feature for async command handling.
  • Tests (Robot) [Rui]: Add robot/async_execution.robot smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(async): add async command execution and workers".
• COMMIT (Owner: Luis | Group: 10A.retry) - Commit message: "feat(async): wire retry policies into services" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Integrate retry/circuit breaker policies into service layer operations.
  • Docs [Luis]: Document retry policy defaults and override points.
  • Tests (Behave) [Rui]: Add retry/circuit breaker behavior scenarios.
  • Tests (Robot) [Rui]: Add resilience smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(async): wire retry policies into services".

Parallel Group 10B: Selective Quality Review [Brent]

• COMMIT (Owner: Brent | Group: 10B.review) - Commit message: "docs(qa): add review playbook and priority matrix" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Docs [Brent]: Create docs/development/review_playbook.md with focus areas and skip rules.
  • Docs [Brent]: Add priority matrix and review SLA guidance.
  • Tests (Behave) [Rui]: Add scenarios validating review playbook references exist.
  • Tests (Robot) [Rui]: Add docs build smoke test covering the new guide.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Brent]: git commit -m "docs(qa): add review playbook and priority matrix".

Parallel Group 10C: Validation Testing Support [Brent + Luis]

• COMMIT (Owner: Brent | Group: 10C.edge) - Commit message: "test(validation): add edge case suites" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Brent]: Add shared edge-case fixtures under features/fixtures/validation/.
  • Docs [Brent]: Update docs/development/testing.md with validation test catalog.
  • Tests (Behave) [Rui]: Add edge-case scenarios for concurrency, conflicts, and rollbacks.
  • Tests (Robot) [Rui]: Add integration coverage for edge-case suites.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Brent]: git commit -m "test(validation): add edge case suites".
• COMMIT (Owner: Luis | Group: 10C.semantic) - Commit message: "test(validation): add semantic validation suites" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Add semantic validation fixtures and error-pattern samples.
  • Docs [Luis]: Document semantic validation coverage expectations.
  • Tests (Behave) [Rui]: Add semantic validation scenarios.
  • Tests (Robot) [Rui]: Add semantic validation integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "test(validation): add semantic validation suites".
• COMMIT (Owner: Brent | Group: 10C.performance) - Commit message: "test(perf): add scale test fixtures" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Brent]: Add scale fixtures for 1K/5K/10K file repos in features/fixtures/scale/.
  • Docs [Brent]: Add scale test runbook and environment notes.
  • Tests (Behave) [Rui]: Add scale test scenarios validating thresholds.
  • Tests (Robot) [Rui]: Add large-project Robot tests for performance runs.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Brent]: git commit -m "test(perf): add scale test fixtures".

---

Section 11: Security & Safety [WORKSTREAM F - Luis + Brent]

Target: Throughout project, critical items by Day 14

Note: Security tasks focus on runtime protections; quality gates are handled in Section 0.

Parallel Group SEC1: Remove eval() usage [Luis]

• COMMIT (Owner: Luis | Group: SEC1.eval) - Commit message: "fix(security): remove eval-based config parsing" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Audit and remove all eval/exec/compile usage from production config paths.
  • Docs [Luis]: Add docs/reference/security_eval.md with replacement patterns.
  • Tests (Behave) [Rui]: Add features/security_eval.feature scenarios.
  • Tests (Robot) [Rui]: Add robot/security_eval.robot smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "fix(security): remove eval-based config parsing".

Parallel Group SEC2: Template Injection Prevention [Luis]

• COMMIT (Owner: Luis | Group: SEC2.template) - Commit message: "fix(security): harden template rendering" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Replace unsafe template usage with a sandboxed renderer and strict token set.
  • Docs [Luis]: Add docs/reference/template_security.md with safe patterns.
  • Tests (Behave) [Rui]: Add features/security_templates.feature scenarios.
  • Tests (Robot) [Rui]: Add robot/security_templates.robot smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "fix(security): harden template rendering".

Parallel Group SEC3: Exception Handling Audit [Luis]

• COMMIT (Owner: Luis | Group: SEC3.exceptions) - Commit message: "fix(security): enforce explicit exception handling" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Replace silent exception handling with explicit errors and context propagation.
  • Docs [Luis]: Document error propagation standards and logging rules.
  • Tests (Behave) [Rui]: Add features/security_exceptions.feature scenarios.
  • Tests (Robot) [Rui]: Add exception handling integration smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "fix(security): enforce explicit exception handling".

Parallel Group SEC4: Async Lifecycle Correctness [Luis]

• COMMIT (Owner: Luis | Group: SEC4.async) - Commit message: "fix(security): close async resources and leaks" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Close async resources, checkpoint files, and subscription leaks with retention policies.
  • Docs [Luis]: Add docs/reference/async_safety.md on cleanup rules.
  • Tests (Behave) [Rui]: Add features/security_async.feature scenarios.
  • Tests (Robot) [Rui]: Add async cleanup integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "fix(security): close async resources and leaks".

Parallel Group SEC5: Secrets Management [Hamza]

• COMMIT (Owner: Hamza | Group: SEC5.secrets) - Commit message: "feat(security): add secrets masking and validation" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Mask credentials in logs, validate required keys, and block secret leakage in outputs.
  • Docs [Hamza]: Add docs/reference/secrets_handling.md.
  • Tests (Behave) [Rui]: Add features/security_secrets.feature scenarios.
  • Tests (Robot) [Rui]: Add secrets handling integration smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(security): add secrets masking and validation".

Parallel Group SEC6: Read-Only Enforcement [Luis]

• COMMIT (Owner: Luis | Group: SEC6.readonly) - Commit message: "feat(security): enforce read-only actions" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Validate read-only actions only use read-only skills at execution time.
  • Docs [Luis]: Add docs/reference/read_only_actions.md.
  • Tests (Behave) [Rui]: Add features/security_readonly.feature scenarios.
  • Tests (Robot) [Rui]: Add read-only enforcement integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(security): enforce read-only actions".
  • Note: Safety profile enforcement is deferred; see Section 18 POST1.

Parallel Group SEC7: Audit Logging [Hamza]

• COMMIT (Owner: Hamza | Group: SEC7.audit) - Commit message: "feat(security): add audit logging for apply" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Add audit log model, migration, and agents audit list CLI command.
  • Docs [Hamza]: Add docs/reference/audit_logging.md.
  • Tests (Behave) [Rui]: Add features/security_audit.feature scenarios.
  • Tests (Robot) [Rui]: Add audit logging integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(security): add audit logging for apply".

Section 12: Session & Provider Fixes [WORKSTREAM G - Hamza]

Target: Days 8-12

Parallel Group SESS1: Session Management [Hamza]

• COMMIT (Owner: Hamza | Group: SESS1.session) - Commit message: "feat(session): add session model and CLI" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Implement Session model, service, persistence, and CLI commands.
  • Docs [Hamza]: Add docs/reference/session_management.md.
  • Tests (Behave) [Rui]: Add features/session_management.feature scenarios.
  • Tests (Robot) [Rui]: Add session CLI smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(session): add session model and CLI".

Parallel Group SESS2: Memory Persistence [Hamza]

• COMMIT (Owner: Hamza | Group: SESS2.memory) - Commit message: "feat(memory): persist session history" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Persist MemoryService history keyed by session_id with backend config.
  • Docs [Hamza]: Document memory backend options and warnings.
  • Tests (Behave) [Rui]: Add features/memory_persistence.feature scenarios.
  • Tests (Robot) [Rui]: Add memory persistence integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(memory): persist session history".

Parallel Group PROV1: Provider Fixes [Luis]

• COMMIT (Owner: Luis | Group: PROV1.fixes) - Commit message: "fix(provider): remove FakeListLLM defaults" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Remove FakeListLLM fallback, fix auto-debug provider usage, and implement provider auto-detection.
  • Docs [Luis]: Update provider configuration docs and error messages.
  • Tests (Behave) [Rui]: Add features/provider_fixes.feature scenarios.
  • Tests (Robot) [Rui]: Add provider detection smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "fix(provider): remove FakeListLLM defaults".

Parallel Group PROV2: Cost Controls & Fallback [Luis]

• COMMIT (Owner: Luis | Group: PROV2.costs) - Commit message: "feat(provider): add cost controls and fallback" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Track tokens/costs, enforce budgets, rate limits, and provider fallback order.
  • Docs [Luis]: Add docs/reference/cost_controls.md.
  • Tests (Behave) [Rui]: Add features/cost_controls.feature scenarios.
  • Tests (Robot) [Rui]: Add cost control integration smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(provider): add cost controls and fallback".

---

Section 13: Additional CLI Commands & UX [Days 10-14]

Parallel Group CLI0: Core System Commands [Hamza]

• COMMIT (Owner: Hamza | Group: CLI0.core) - Commit message: "feat(cli): add version/info/diagnostics" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Implement version, info, and diagnostics commands.
  • Docs [Hamza]: Update CLI reference with core system commands.
  • Tests (Behave) [Rui]: Add features/cli_core.feature scenarios.
  • Tests (Robot) [Rui]: Add core command smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(cli): add version/info/diagnostics".

Parallel Group CLI1: Plan Interaction Commands [Hamza]

• COMMIT (Owner: Hamza | Group: CLI1.plan) - Commit message: "feat(cli): add plan prompt/diff/artifacts" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Implement plan prompt, plan diff, and plan artifacts commands.
  • Docs [Hamza]: Update CLI reference with plan interaction commands.
  • Tests (Behave) [Rui]: Add features/plan_interaction_cli.feature scenarios.
  • Tests (Robot) [Rui]: Add plan interaction CLI smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(cli): add plan prompt/diff/artifacts".

Parallel Group CLI2: Configuration Commands [Hamza]

• COMMIT (Owner: Hamza | Group: CLI2.config) - Commit message: "feat(cli): add config and provider commands" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Implement config set/get/list and providers list commands.
  • Docs [Hamza]: Update CLI reference with configuration commands.
  • Tests (Behave) [Rui]: Add features/config_cli.feature scenarios.
  • Tests (Robot) [Rui]: Add config CLI smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(cli): add config and provider commands".

Parallel Group CLI3: Context Commands [Hamza]

• COMMIT (Owner: Hamza | Group: CLI3.context) - Commit message: "feat(cli): add context policy commands" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Implement project context set/show and actor context set/show commands.
  • Docs [Hamza]: Update CLI reference with context policy usage.
  • Tests (Behave) [Rui]: Add features/context_cli.feature scenarios.
  • Tests (Robot) [Rui]: Add context CLI smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(cli): add context policy commands".

---

Section 14: Concurrency & Cleanup [Days 12-14]

Parallel Group CONC1: Plan Locking [Luis]

• COMMIT (Owner: Luis | Group: CONC1.lock) - Commit message: "feat(concurrency): add plan and project locks" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Implement plan-level and project-level locks with timeouts.
  • Docs [Luis]: Add docs/reference/concurrency.md with lock behavior.
  • Tests (Behave) [Rui]: Add features/concurrency.feature scenarios.
  • Tests (Robot) [Rui]: Add lock integration smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(concurrency): add plan and project locks".

Parallel Group CONC2: Resumable Execution [Luis]

• COMMIT (Owner: Luis | Group: CONC2.resume) - Commit message: "feat(concurrency): add plan resume" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Luis]: Persist step-level progress and implement plan resume with graceful shutdown handling.
  • Docs [Luis]: Update plan lifecycle docs for resume behavior.
  • Tests (Behave) [Rui]: Add features/plan_resume.feature scenarios.
  • Tests (Robot) [Rui]: Add resume integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Luis]: git commit -m "feat(concurrency): add plan resume".

Parallel Group CONC3: Garbage Collection [Hamza]

• COMMIT (Owner: Hamza | Group: CONC3.gc) - Commit message: "feat(ops): add cleanup commands" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Add cleanup for sandboxes, checkpoints, and stale sessions with CLI commands.
  • Docs [Hamza]: Document cleanup commands and retention defaults.
  • Tests (Behave) [Rui]: Add features/garbage_collection.feature scenarios.
  • Tests (Robot) [Rui]: Add cleanup integration smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(ops): add cleanup commands".

---

Section 16: Context Indexing [Days 15-17]

Parallel Group CTX1: Repository Indexing [Hamza]

• COMMIT (Owner: Hamza | Group: CTX1.index) - Commit message: "feat(context): add repo indexing service" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Implement indexing service with file tree, language detection, and incremental refresh.
  • Docs [Hamza]: Add docs/reference/context_indexing.md.
  • Tests (Behave) [Rui]: Add features/context_indexing.feature scenarios.
  • Tests (Robot) [Rui]: Add indexing integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(context): add repo indexing service".

Parallel Group CTX2: Embedding Index [Hamza]

• COMMIT (Owner: Hamza | Group: CTX2.embedding) - Commit message: "feat(context): add optional embedding search" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Hamza]: Add embedding-based search with opt-in flag and fallback to full-text search.
  • Docs [Hamza]: Add docs/reference/embedding_search.md.
  • Tests (Behave) [Rui]: Add features/embedding_search.feature scenarios.
  • Tests (Robot) [Rui]: Add embedding search integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Hamza]: git commit -m "feat(context): add optional embedding search".

---

Section 17: Skill Registry [Days 17-18]

Parallel Group SKILL1: Skill Catalog [Aditya]

• COMMIT (Owner: Aditya | Group: SKILL1.registry) - Commit message: "feat(skill): add skill registry and CLI" (Only check after all subitems + nox pass + coverage >=97%, then commit)
  • Code [Aditya]: Implement SkillRegistry, auto-registration from actor configs, and skills list CLI.
  • Docs [Aditya]: Add docs/reference/skill_registry.md.
  • Tests (Behave) [Rui]: Add features/skill_registry.feature scenarios.
  • Tests (Robot) [Rui]: Add skill registry integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [Aditya]: git commit -m "feat(skill): add skill registry and CLI".

---

Section 18: Deferred Work

Deferred items remain planned but are not part of the 30-day MVP scope.

• COMMIT (Owner: TBD | Group: POST.repl) - Commit message: "feat(cli): add interactive repl" [DEFERRED]

  • Code [TBD]: Implement REPL command loop with history and completion.
  • Docs [TBD]: Add REPL usage guide.
  • Tests (Behave) [Rui]: Add REPL behavior scenarios.
  • Tests (Robot) [Rui]: Add REPL smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [TBD]: git commit -m "feat(cli): add interactive repl".

• COMMIT (Owner: TBD | Group: POST.auth) - Commit message: "feat(cli): add auth and team commands" [DEFERRED]

  • Code [TBD]: Add auth/team CLI commands (requires server connectivity).
  • Docs [TBD]: Document auth/team workflows.
  • Tests (Behave) [Rui]: Add auth/team CLI scenarios.
  • Tests (Robot) [Rui]: Add auth/team integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [TBD]: git commit -m "feat(cli): add auth and team commands".

• COMMIT (Owner: TBD | Group: POST.tui) - Commit message: "feat(ui): add TUI/Web interface" [DEFERRED]

  • Code [TBD]: Implement TUI/Web interfaces (client-only).
  • Docs [TBD]: Add UI usage guide.
  • Tests (Behave) [Rui]: Add UI behavior scenarios.
  • Tests (Robot) [Rui]: Add UI smoke tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [TBD]: git commit -m "feat(ui): add TUI/Web interface".

• COMMIT (Owner: TBD | Group: POST.dbresources) - Commit message: "feat(resource): add database resources" [DEFERRED]

  • Code [TBD]: Add database resource types and sandbox strategy.
  • Docs [TBD]: Document database resource configuration.
  • Tests (Behave) [Rui]: Add database resource scenarios.
  • Tests (Robot) [Rui]: Add database resource integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [TBD]: git commit -m "feat(resource): add database resources".

• COMMIT (Owner: TBD | Group: POST.cloud) - Commit message: "feat(resource): add cloud infrastructure resources" [DEFERRED]

  • Code [TBD]: Add cloud resource types and sandbox strategies.
  • Docs [TBD]: Document cloud resource configuration.
  • Tests (Behave) [Rui]: Add cloud resource scenarios.
  • Tests (Robot) [Rui]: Add cloud resource integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [TBD]: git commit -m "feat(resource): add cloud infrastructure resources".

• COMMIT (Owner: TBD | Group: POST.permissions) - Commit message: "feat(security): add permission system" [DEFERRED]

  • Code [TBD]: Implement namespace/project/plan/skill permission enforcement (requires server).
  • Docs [TBD]: Document permission model and roles.
  • Tests (Behave) [Rui]: Add permission scenarios.
  • Tests (Robot) [Rui]: Add permission integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [TBD]: git commit -m "feat(security): add permission system".

• COMMIT (Owner: TBD | Group: POST.safety) - Commit message: "feat(security): add safety profile enforcement" [DEFERRED]

  • Code [TBD]: Add SafetyProfile model, CLI flags, and execution enforcement.
  • Docs [TBD]: Document safety profile options and defaults.
  • Tests (Behave) [Rui]: Add safety profile enforcement scenarios.
  • Tests (Robot) [Rui]: Add safety profile integration tests.
  • Quality [Brent]: Run nox and verify coverage >=97%.
  • Commit [TBD]: git commit -m "feat(security): add safety profile enforcement".

---

Timeline Summary

TEAM ROLES AND ASSIGNMENTS

Developer	Role	Primary Focus Areas	Notes
Jeff	CTO/Lead Architect	Critical path items, architectural decisions, complex integrations	Fastest, most expert developer - handles blocking issues
Luis	Senior Python Architect	Domain models, persistence, algorithms, state machines	Good architecture but can be pedantic - needs clear requirements
Aditya	Domain Expert (Agents/LLMs)	Actor YAML configs, hierarchical actors, skill execution	Understands topic best but code may need cleanup
Hamza	Python/RDF Expert	Resources, sandbox, database, general Python	Well-rounded, no agent experience - assign infrastructure
Rui	Fast Developer	Testing (Behave/Robot), simpler implementations	New to Python - assign testing and straightforward tasks
Brent	Quality Specialist	Code review, linting, type checking, documentation	Slow but detail-oriented - low contention independent work
Mike/Brian	Sysadmins	Deployment, infrastructure setup	Minimal coding tasks

Week 1 (Days 1-7) - MVP Target (Source Code Only)

Day	Morning Focus	Owner	Afternoon Focus	Owner
1	A5.alpha/A5.beta DB migrations + ORM models	Jeff + Luis	B1.core Project/Resource models	Hamza
2	A5.gamma repos/services + A5.tests	Jeff	B2.persistence/B2.service + B3.cli Resource CLI	Hamza + Rui (tests)
3	B4.sandbox git_worktree	Jeff + Hamza	B4.sandbox manager + tests	Luis + Rui
4	C1.schema/C1.examples Actor YAML	Aditya	C2.loader/C2.compiler Actor compilation	Aditya + Jeff
5	C3.protocol/C3.context/C3.inline Skill framework	Jeff	C4.file/C4.search Built-in skills	Luis + Jeff
6	C7.mcp MCP Adapter	Aditya + Jeff	C4.git + C5.model/C5.router Change tracking	Luis + Jeff
7	C5.diff Diff review artifacts	Luis	C6.pipeline/C6.gating Validation pipeline	Luis + Rui

Week 2 (Days 8-14) - M3 Complete + Plan-Actor Integration

Day	Focus	Owner	Deliverable
8	C8.providers + C9.execute Plan-Actor integration	Jeff + Aditya	Full execute phase working
9	C9.apply Apply Phase + Review	Jeff + Luis	Apply with review gates
10	D1.domain Decision Model	Hamza + Jeff	Decision recording foundation
11	D2.service Decision Recording	Jeff + Hamza	Decisions captured in Strategize
12	E1.domain Subplan Model	Luis	Subplan spawning design
13	E2.service/E2.actor Subplan spawning	Jeff + Luis	Subplan workflow wiring
14	End-to-end integration testing	All + Rui	M3 milestone verified

Week 3 (Days 15-21) - M4 Target (Decision Tree + Correction)

Day	Focus	Owner	Deliverable
15	D5.db/D5.repo Decision persistence	Hamza	Decision storage wired
16	D3.cli Decision viewing	Hamza + Rui	agents [--data-dir PATH] [--config-path PATH] plan tree, agents [--data-dir PATH] [--config-path PATH] plan explain
17	D4.revert Decision correction (revert)	Jeff	agents [--data-dir PATH] [--config-path PATH] plan correct revert flow
18	D4.append + D5.di Decision wiring	Jeff + Luis	Append correction + service wiring
19	E3.exec Parallel Subplan Execution	Luis	Concurrent subplans
20	E4.merge Result Merging	Jeff + Luis	Git-style merge for subplans
21	M4 integration testing	All	Decision correction working

Week 4 (Days 22-30) - M6 Target (Large Project Autonomy - LOCAL MODE ONLY)

Day	Focus	Owner	Deliverable
22-23	CTX1.index Context indexing	Hamza	Large codebase indexing
24-25	G4.context Hot/Warm/Cold tiers	Hamza	Three-tier memory
26-27	Deep Subplan Hierarchies (5+ levels)	Jeff + Luis	Autonomous decomposition
28-29	F0.stubs + G1/G3 large project tests	Luis + Rui	Client stubs (NOT server impl), 10K file tests
30	M6 integration testing	All	Large project autonomy verified (Server connectivity DEFERRED)

Note

: Server connectivity (F1-F4) is DEFERRED beyond Day 30. Days 26-29 focus on client stubs only and large project testing. The server is a separate project.

Week 5 (Days 31-35) - M7 Target (Server Connectivity - Client Side Only)

Day	Focus	Owner	Deliverable
31-32	F1.client Server client infrastructure	Luis	HTTP client for server communication
33	F2.sync Plan sync client	Luis	Client can sync plans to server
34	F3.ws WebSocket client	Luis	Client receives real-time updates
35	F4.remote Remote project support	Hamza	Client can request server execution

Week 6 (Days 36-40) - M8 Target (Full Feature Set + Polish)

Day	Focus	Owner	Deliverable
36	A6.* automation level refinements	Jeff + Luis	Automation modes stabilized
37	G5.estimate cost/risk estimation	Aditya	Estimation working
38	G2.checkpoint rollback	Jeff	Checkpointing + rollback
39	G1.decompose + G3.semantic performance tuning	Luis + Jeff	Benchmarks passing
40	Final integration + documentation	All	Release candidate ready

Continuous Tasks (Throughout)

Brent (Quality - Independent, Low Contention):

• Review all PRs within 4 hours of submission
• Run nox -s typecheck on all branches before merge
• Run nox -s lint and ensure 0 warnings
• Monitor test coverage (must stay >=97%)
• Update documentation for API changes
• Security audit: no eval(), no template injection, no secrets in code

Rui (Testing - Parallel with Feature Work):

• Write Behave scenarios for each feature (before implementation starts)
• Write Robot integration tests for each milestone
• Run full test suite daily
• Report test failures immediately
• Maintain test fixtures and mocks in features/

Critical Path Dependencies

Day 1: A5 (Persistence) ────────────────────────────────────────────┐
Day 2: B1.core/B2.persistence/B2.service/B3.cli (Project/Resource) ─┐│
Day 3: B4.sandbox (Sandbox) ────────────────────────────────────────┼┤
Day 4: C1.schema/C2.compiler (Actor) ───────────────────────────────┘│
Day 5: C3.protocol/C4.file (Skills) ─────────────────────────────────┤
Day 6: C4.search/C5.model (Change Tracking) ─────────────────────────┤
Day 7: C6.pipeline/C7.mcp/C8.providers (Validation + Providers) ─────┘
                                                        │
Day 8-9: C9.execute/C9.apply (Integration + Apply) ────────────────┤
Day 10-14: D1-E2 (Decisions + Subplans) ────────────────┤
                                                        │
                          MERGE POINT M3 ◄──────────────┘
                                                        │
Day 15-21: D3-E4 (Correction + Parallel) ───────────────┤
                                                        │
                          MERGE POINT M4 ◄──────────────┘
                                                        │
Day 22-30: CTX/G + F0 (Context + Large Project + Stubs) ─┘

Risk Mitigation

Risk	Mitigation	Owner
Git worktree complexity	Use B4.sandbox git_worktree with pre-commit verification and isolation tests	Jeff
Multi-file generation reliability	Validate C9.execute/C9.apply flows with diff review artifacts and Robot E2E	Luis + Rui
Decision tree correction bugs	Jeff reviews D4 correction + checkpointing; add revert/append Behave coverage	Jeff
Large codebase performance	Profile CTX1/CTX2 indexing + hot/warm/cold tiers; enforce bounded memory tests	Luis + Hamza
Server connectivity stubs stability	Keep client-only stubs isolated; gate with feature flags and contract tests	Jeff + Luis

Definition of Done (Each Task)

1. ✅ Code implemented with full type annotations
2. ✅ Behave scenarios written and passing
3. ✅ Robot integration tests (for CLI/E2E tasks) passing
4. ✅ nox -s typecheck passes with 0 errors
5. ✅ nox -s lint passes with 0 warnings
6. ✅ Test coverage >=97%
7. ✅ PR reviewed by Brent (or Jeff for critical items)
8. ✅ Implementation notes added to this document

---

MILESTONE SUCCESS CRITERIA (DETAILED)

M1: MVP (Day 7) - Minimally Usable for Source Code

End-to-end verification command sequence:

# 1. Create an action
cat > /tmp/test_action.yaml <<EOF
name: local/test-action
description: MVP test action
strategy_actor: openai/gpt-4
execution_actor: openai/gpt-4
definition_of_done: "All files created successfully"
EOF
agents [--data-dir PATH] [--config-path PATH] action create --config /tmp/test_action.yaml
agents [--data-dir PATH] [--config-path PATH] action available local/test-action

# 2. Register a git resource (built-in git-checkout type)
agents [--data-dir PATH] [--config-path PATH] resource add git-checkout local/main-repo \
  --path /path/to/repo \
  --branch main  # Optional; default is main per spec

# 3. Create project and link resource
agents [--data-dir PATH] [--config-path PATH] project create local/test-project
agents [--data-dir PATH] [--config-path PATH] project link-resource local/test-project local/main-repo

# Note: project link-resource is defined in Section 4 (B3.cli)

# 4. Use action to create plan
agents [--data-dir PATH] [--config-path PATH] plan use local/test-action local/test-project

# 5. Execute plan (sandbox created, changes made)
agents [--data-dir PATH] [--config-path PATH] plan execute <plan_id>

# 6. Review diff
agents [--data-dir PATH] [--config-path PATH] plan diff <plan_id>

# 7. Apply changes
agents [--data-dir PATH] [--config-path PATH] plan apply <plan_id>

# 8. Verify changes in repo
cd /path/to/repo && git log -1  # Shows CleverAgents commit

Technical Criteria:

• Plan and Action records persist to SQLite database.
• Phase transitions (ACTION → STRATEGIZE → EXECUTE → APPLY → APPLIED) work correctly.
• Git worktree sandbox creates isolated working directory.
• Changes in sandbox do not affect original until Apply.
• At least 3 automation levels work (manual mode minimum).
• Error handling produces actionable messages.
• Test coverage remains >=97%.

M3: Full Plan Lifecycle with Actors (Day 14)

End-to-end verification:

# Create actor YAML file
cat > my_actor.yaml <<EOF
version: "3"
name: my_coder
namespace: local
type: llm
model: openai/gpt-4
temperature: 0.7
system_prompt: "You are a helpful coding assistant."
EOF

# Load actor
agents [--data-dir PATH] [--config-path PATH] actor add --file ./my_actor.yaml

# Create action using custom actor
cat > /tmp/custom_action.yaml <<EOF
name: local/custom-action
strategy_actor: local/my_coder
execution_actor: local/my_coder
definition_of_done: "Code written and tests pass"
EOF
agents [--data-dir PATH] [--config-path PATH] action create --config /tmp/custom_action.yaml --available

# Use and execute (should use custom actor)
agents [--data-dir PATH] [--config-path PATH] plan use local/custom-action local/test-project
agents [--data-dir PATH] [--config-path PATH] plan execute <plan_id>

# Verify multi-file generation
agents [--data-dir PATH] [--config-path PATH] plan artifacts <plan_id>  # Should show multiple files

Technical Criteria:

• Actor YAML files parse and validate correctly.
• Actors compile to LangGraph StateGraphs.
• Inline skill code executes in sandboxed environment.
• Built-in file skills (read/write/edit/delete) work.
• ChangeSet built from skill invocations (not parsed from output).
• Validation pipeline runs (syntax check, lint, tests).
• Multi-file generation produces correct ChangeSet.
• MCP skill adapter can connect to external servers (basic).

M4: Decision Tree & Correction (Day 21)

End-to-end verification:

# Execute a plan to generate decisions
agents [--data-dir PATH] [--config-path PATH] plan use local/complex-action local/large-project
agents [--data-dir PATH] [--config-path PATH] plan execute <plan_id>

# View decision tree
agents [--data-dir PATH] [--config-path PATH] plan tree <plan_id>
# Output shows:
# ├── [prompt_definition] "Build user authentication"
# │   ├── [strategy_choice] "Use JWT tokens" (confidence: 0.85)
# │   │   └── [subplan_spawn] "Create token service" → subplan_01ABC
# │   └── [implementation_choice] "Store tokens in Redis"

# Explain a decision
agents [--data-dir PATH] [--config-path PATH] plan explain <decision_id>
# Shows: question, chosen_option, alternatives, rationale, context

# Add and list project invariants
agents [--data-dir PATH] [--config-path PATH] invariant add --project local/large-project "Use session cookies"
agents [--data-dir PATH] [--config-path PATH] invariant list --project local/large-project

# Correct a decision (dry run first)
agents [--data-dir PATH] [--config-path PATH] plan correct <decision_id> --mode=revert --guidance "Use session cookies instead of JWT" --dry-run
# Shows impact: 3 decisions, 1 subplan affected

# Execute correction
agents [--data-dir PATH] [--config-path PATH] plan correct <decision_id> --mode=revert --guidance "Use session cookies instead of JWT"
# Re-executes from that point

# Verify new outcome
agents [--data-dir PATH] [--config-path PATH] plan tree <plan_id>
# Shows corrected decision and regenerated downstream work

Technical Criteria:

• Decisions recorded during Strategize with full context snapshot.
• Decision tree persists to database.
• agents [--data-dir PATH] [--config-path PATH] plan tree displays ASCII tree correctly.
• agents [--data-dir PATH] [--config-path PATH] plan explain shows all decision details.
• Correction in revert mode:
  • Archives old decisions.
  • Rolls back sandbox to checkpoint.
  • Re-executes from decision point.
  • Generates new downstream decisions.
• Correction in append mode creates fix subplan.
• History preserved for comparison.

M5: Subplans & Parallel Execution (Day 25)

End-to-end verification:

# Execute plan that spawns multiple subplans
agents [--data-dir PATH] [--config-path PATH] plan use local/refactor-action local/monorepo
agents [--data-dir PATH] [--config-path PATH] plan execute <plan_id>

# View subplan tree
agents [--data-dir PATH] [--config-path PATH] plan tree <plan_id>
# Shows:
# ├── [root] Refactor codebase
# │   ├── [subplan] Refactor auth module (status: COMPLETE)
# │   ├── [subplan] Refactor api module (status: PROCESSING)
# │   └── [subplan] Refactor utils module (status: QUEUED)

# Check status until complete
agents [--data-dir PATH] [--config-path PATH] plan status <plan_id>

# Verify merged results
agents [--data-dir PATH] [--config-path PATH] plan diff <plan_id>  # Shows merged changes from all subplans

Technical Criteria:

• SUBPLAN_SPAWN decisions created during Strategize.
• Subplans actually spawned during Execute.
• Sequential subplan execution works (one at a time).
• Parallel subplan execution works (with max_parallel limit).
• Each subplan has isolated sandbox.
• Three-way merge combines non-conflicting changes.
• Merge conflicts detected and marked.
• Parent plan tracks all subplan statuses.
• A plan with 10+ subplans completes successfully.

M6: Large Project Handling (Day 30)

End-to-end verification:

# Index a large project (10,000+ files)
agents [--data-dir PATH] [--config-path PATH] project create local/large-project
agents [--data-dir PATH] [--config-path PATH] resource add git-checkout local/large-repo \
  --path /path/to/large/repo \
  --branch main  # Optional; default is main per spec
agents [--data-dir PATH] [--config-path PATH] project link-resource local/large-project local/large-repo

# Note: project link-resource is defined in Section 4 (B3.cli)

# Verify indexing handles scale
agents [--data-dir PATH] [--config-path PATH] project show local/large-project
# Shows: 15,247 files indexed, 2.3M tokens

# Execute complex hierarchical task
cat > /tmp/port_action.yaml <<EOF
name: local/port-to-typescript
strategy_actor: local/architect
execution_actor: local/coder
definition_of_done: "All Python files converted to TypeScript with tests"
EOF
agents [--data-dir PATH] [--config-path PATH] action create --config /tmp/port_action.yaml --available

agents [--data-dir PATH] [--config-path PATH] plan use local/port-to-typescript local/large-project
agents [--data-dir PATH] [--config-path PATH] plan execute <plan_id>

# Monitor hierarchical decomposition
agents [--data-dir PATH] [--config-path PATH] plan tree <plan_id>
# Shows multi-level hierarchy:
# ├── Root: Port codebase to TypeScript
# │   ├── Phase 1: Core modules (3 subplans)
# │   │   ├── Port auth module (5 subplans)
# │   │   │   ├── Convert auth types
# │   │   │   ├── Convert auth handlers
# │   │   │   └── ...
# │   ├── Phase 2: API layer (4 subplans)
# │   └── Phase 3: Integration tests (2 subplans)

# Correct mid-level decision if needed
agents [--data-dir PATH] [--config-path PATH] plan correct <module_decision_id> --mode=revert --guidance "Use Zod instead of io-ts for validation"
# Only affected module and its subplans recompute

# Complete and apply
agents [--data-dir PATH] [--config-path PATH] plan status <plan_id>
agents [--data-dir PATH] [--config-path PATH] plan apply <plan_id>

Technical Criteria:

• Projects with 10,000+ files index without timeout.
• Context window management works (hot/warm/cold tiers).
• Hierarchical decomposition creates 4+ levels of subplans.
• Decision correction at any level recomputes only affected subtree.
• Parallel execution scales to 10+ concurrent subplans.
• Memory usage stays bounded (lazy context loading).
• A realistic porting task (500 file Python → TypeScript) completes autonomously.

M6 SUCCESS CRITERIA (Day 30):

• 10,000+ file project indexes with bounded memory and hot/warm/cold tiering.
• Hierarchical decomposition reaches 4+ levels with correction limited to affected subtree.
• Parallel execution scales to 10+ subplans with merge and conflict handling.
• Autonomous porting task completes with validation and review gates.
• nox passes with coverage >=97% including large-project suites.

---

QUICK REFERENCE: TASK DEPENDENCIES

LEGEND:
  ───► = Sequential dependency (must complete before next)
  ═══► = Parallel tracks that can proceed simultaneously
  ⊕    = Merge point (all parallel tracks must complete)

WEEK 1 CRITICAL PATH:

DAY 1-2: DATA LAYER
┌─────────────────────────────────────────────────────────────────┐
│  [Jeff] A5.alpha DB migrations ═══► [Luis] A5.beta ORM models    │
│              │                           │                       │
│              └───────────⊕───────────────┘                       │
│                          │                                       │
│              [Jeff] A5.gamma Repos + Service + DI                │
│                          │                                       │
│              [Rui] A5.tests Persistence suites                   │
└─────────────────────────────────────────────────────────────────┘

DAY 1-3: RESOURCE LAYER (PARALLEL)
┌─────────────────────────────────────────────────────────────────┐
│  [Hamza] B1.core Domain Models                                  │
│              │                                                   │
│              ▼                                                   │
│  [Hamza] B2.persistence + B2.service + B3.cli                   │
└─────────────────────────────────────────────────────────────────┘

DAY 3-5: SANDBOX LAYER
┌─────────────────────────────────────────────────────────────────┐
│  [Luis] B4.sandbox strategy + manager ═══► [Hamza] git_worktree  │
│              │                           │                       │
│              └───────────⊕───────────────┘                       │
│                          │                                       │
│              [Luis] B4.sandbox copy_on_write stub                │
└─────────────────────────────────────────────────────────────────┘

DAY 4-7: ACTOR/SKILL LAYER
┌─────────────────────────────────────────────────────────────────┐
│  [Aditya] C1.schema/C1.examples Actor Schema                    │
│              │                                                   │
│              ▼                                                   │
│  [Aditya+Jeff] C2.loader/C2.compiler Actor Compiler             │
│              │                                                   │
│  [Jeff] C3.protocol/C3.context/C3.inline ═══► [Aditya] C7.mcp   │
└─────────────────────────────────────────────────────────────────┘

DAY 6-9: CHANGE TRACKING LAYER
┌─────────────────────────────────────────────────────────────────┐
│  [Luis] C5.model/C5.router Change Model + Router                │
│              │                                                   │
│              ▼                                                   │
│  [Luis] C5.diff + C6.pipeline Validation Pipeline               │
└─────────────────────────────────────────────────────────────────┘

DAY 8: M1 MERGE POINT ⊕
┌─────────────────────────────────────────────────────────────────┐
│  All tracks converge:                                           │
│  - Plan lifecycle (A) + Resources (B) + Actors (C) + Skills     │
│  - End-to-end verification of MVP criteria                      │
│  - All tests must pass                                          │
└─────────────────────────────────────────────────────────────────┘

WEEK 2: INTEGRATION + DECISIONS
┌─────────────────────────────────────────────────────────────────┐
│  [Jeff+Luis] C9 Plan-Actor Integration                          │
│              │                                                   │
│              ▼                                                   │
│  [Hamza] D1.domain/D2.service/D3.cli Decisions                  │
│              │                                                   │
│              ▼                                                   │
│  [Luis] E1 Subplan Model                                        │
└─────────────────────────────────────────────────────────────────┘

DAY 14: M3 MERGE POINT ⊕
┌─────────────────────────────────────────────────────────────────┐
│  Full plan lifecycle with actors verified                       │
│  Multi-file generation working                                  │
│  Validation pipeline operational                                │
└─────────────────────────────────────────────────────────────────┘

WEEK 3: DECISION CORRECTION + SUBPLANS
┌─────────────────────────────────────────────────────────────────┐
│  [Jeff] D4.revert/D4.append Decision Correction ─┐              │
│                                                  │              │
│  [Jeff+Luis] E2/E3/E4 Subplan Spawning + Merging ┤              │
│                                                  │              │
│  [Hamza] D5.db/D5.repo Decision Persistence ────┘              │
└─────────────────────────────────────────────────────────────────┘

DAY 21: M4 MERGE POINT ⊕
┌─────────────────────────────────────────────────────────────────┐
│  Decision tree viewing and correction working                   │
│  Can correct any decision and recompute affected work           │
└─────────────────────────────────────────────────────────────────┘

WEEK 4: SCALE + SERVER PREP
┌─────────────────────────────────────────────────────────────────┐
│  [Hamza] CTX1.index Context indexing                            │
│  [Luis] G3.semantic validation + perf tuning                    │
│  [Jeff] F0.stubs server connectivity (client-only)              │
└─────────────────────────────────────────────────────────────────┘

DAY 30: M6 TARGET ⊕
┌─────────────────────────────────────────────────────────────────┐
│  Handle 10,000+ file projects                                   │
│  Autonomous language porting with hierarchical subplans         │
│  Decision correction enables efficient iteration                │
└─────────────────────────────────────────────────────────────────┘

---

SERVER CONNECTIVITY DEFERRAL NOTICE

Server connectivity (WORKSTREAM F) is deferred beyond the 30-day timeline. The server is a separate project—this implementation covers the client only.

The CleverAgents executable (agents) is purely a client application that can:

1. Run in stand-alone local-only mode (no server required)
2. Connect to an independently developed CleverAgents server for multi-user/collaborative features

During Days 1-30, client stub infrastructure is delivered via Section 9 (F0.stubs), covering the connect command, client interfaces, local/remote detection, and NotImplementedError stubs.

What is NOT needed by Day 30:

• Server implementation (the server is a separate project)
• Full client-server API implementation
• WebSocket client implementation
• Remote plan execution requests
• Authentication flow with server
• Permission system integration

The client code should be structured so that adding server connectivity later is straightforward, but no functional server communication code is required for the 30-day milestone. The server will be developed as a separate project.