cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity
Files
b7c3152855df8f36bd6a91abcda942c91e419dcd
cleveragents-core/implementation_plan.md
T

41 KiB
Raw Blame History

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.
  • Respect the reference: Never modify any file inside ./plandex/. Treat it purely as a read-only source of truth while building Python counterparts. This directory is TEMPORARY and will be deleted once migration is complete.
  • NO BACKWARDS COMPATIBILITY: CleverAgents is a NEW standalone project. Do NOT maintain any backwards compatibility with Plandex. No migration guides, no compatibility shims, no support for Plandex 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 85% at all times: unit test coverage must remain above 85% 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.
  • NO PLANDEX REFERENCES: All environment variables must use CLEVERAGENTS_ prefix, not PLANDEX_. No references to Plandex should exist in the final code. CleverAgents is a standalone project, not a fork or migration.
  • 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 a configuration-driven framework for building and running LangGraph/LangChain systems. The core value is orchestration, lifecycle, repeatability, UX, and safety (sandbox/checkpoints)—not replacing what LangGraph and LangChain already do well.

Core Value Proposition

  • LangGraph / LangChain provide the runtime primitives for LLMs, tool calling, graphs, and routing.
  • CleverAgents provides:
    • A first-class plan lifecycle (Action → Strategize → Execute → Apply)
    • A project + resource model for grounding tasks
    • A consistent actor abstraction for "anything conversational"
    • A consistent skill abstraction for "anything executable"
    • A sandbox + checkpoint safety model
    • A CLI/TUI/Web UX for controlling large multi-step 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 supports both in-process single-user mode and agents serve --port <port> multi-user deployments without cloud dependencies.
  • Use only CleverAgents/CleverThis branding throughout the entire codebase - no Plandex references should exist in the final product.
  • 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 Docusaurus integrated within the docs/ directory of the CleverAgents project.
  • Delete the plandex/ reference directory once migration is complete - it serves only as temporary reference material.

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

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 action create ...)
  • Projects: Created via CLI commands (agents project create ...)
  • Actors: Defined via YAML configuration files (the ONLY YAML configuration)
  • Resources: Added to projects via CLI commands

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/

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)

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

Implementation Roadmap

Milestone Overview

Milestone Target Date Description
M0: Foundation Day 0 (Current) Existing LangGraph infrastructure preserved
M1: Minimal Plan Lifecycle +3 days Basic Action → Strategize → Execute → Apply working
M2: Projects & Resources +5 days Project/Resource CLI commands, local filesystem sandbox
M3: Actors & Skills +8 days YAML actor loading, skill execution
M4: Decision Tree +12 days Decision recording during Strategize, basic correction
M5: Multi-Project & Subplans +18 days Subplan spawning, parallel execution
M6: Server Mode +25 days agents serve with remote project support
M7: Full Feature Set +35 days All spec features complete

Parallel Workstreams

The following workstreams can be worked on independently:

WORKSTREAM A: Plan Lifecycle (1 developer)
├── Plan model & state machine
├── Phase transitions
├── CLI commands (plan create, use, execute, apply)
└── Plan persistence

WORKSTREAM B: Projects & Resources (1 developer)  
├── Project model & CLI
├── Resource model & sandbox strategies
├── Git worktree sandbox
├── Filesystem sandbox
└── Project persistence

WORKSTREAM C: Actors & Skills (1 developer)
├── Actor YAML parsing (v2 format compatibility)
├── Actor registry (existing work)
├── Skill execution framework
├── Built-in provider actors
└── Actor-to-LangGraph graph compilation

MERGE POINT: After M3, workstreams must coordinate on:
- Plan→Actor binding (which actor handles strategize/execute)
- Resource→Context flow (how resources feed into actors)
- Skill→Tool mapping (how skills become LangGraph tools)

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 >85%)

# 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.

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 - 1 Developer]

Target: Milestone M1 (+3 days)

  • Stage A1: Plan Data Model (Day 1)

    • 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

  • Stage A2: Action Model (Day 1)

    • 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

  • Stage A3: Plan State Machine (Day 1-2)

    • 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

  • Stage A4: Plan CLI Commands (Day 2-3)

    • Code: Implement plan lifecycle CLI
      • agents action create --name <name> --strategy-actor <actor> --execution-actor <actor> --definition-of-done "<text>" [--arg ...]
      • agents action list - list available actions
      • agents action show <name> - show action details
      • agents plan use <action> --project <project> [--arg name=value ...] - create plan from action
      • agents plan execute [plan_id] - execute current or specified plan
      • agents plan apply [plan_id] - apply executed plan
      • agents plan status [plan_id] - show plan phase/state
      • agents plan list - list plans with phases/states
      • Location: src/cleveragents/cli/commands/action.py, src/cleveragents/cli/commands/plan.py
    • Tests: Behave + Robot for all CLI commands

  • Stage A5: Plan Persistence (Day 3)

    • Code: Plan database schema and repository
      • Alembic migration for plans table
      • Alembic migration for actions table
      • PlanRepository with methods
      • ActionRepository
      • Location: alembic/versions/, src/cleveragents/infrastructure/database/
    • Tests: Integration tests for plan/action persistence

M1 SUCCESS CRITERIA:

  • Can create an action via CLI
  • Can use an action on a project to create a plan
  • Plan transitions through phases (even if execution is stubbed)
  • Plan state persists to database

Section 4: Projects & Resources [WORKSTREAM B - 1 Developer]

Target: Milestone M2 (+5 days)

  • Stage B1: Project Data Model (Day 1)

    • Code: Create Project domain model
      • Define Project Pydantic model (project_id ULID, name, namespace, tags, is_remote)
      • Define Resource Pydantic model (resource_id, name, type, location, is_remote, sandbox_strategy, read_only, metadata)
      • Define ResourceType enum (git_repository, database, filesystem, api_endpoint, etc.)
      • Define SandboxStrategy enum (git_worktree, copy_on_write, overlay, transaction_rollback, none)
      • Location: src/cleveragents/domain/models/core/project.py, src/cleveragents/domain/models/core/resource.py
    • Tests: Behave scenarios for model validation

  • Stage B2: Project CLI Commands (Day 2)

    • Code: Implement project CLI
      • agents project create --name <name> [--tag <tag> ...]
      • agents project add-resource --project <name> --name <resource-name> --type <type> --location <path/url> --sandbox-strategy <strategy> [--read-only]
      • agents project remove-resource --project <name> --name <resource-name>
      • agents project list
      • agents project show <name>
      • agents project set-validation --project <name> --resource <name> --test-command <cmd> [--lint-command <cmd>] [--type-check-command <cmd>]
      • Location: src/cleveragents/cli/commands/project.py
    • Tests: Behave + Robot for all project CLI commands

  • Stage B3: Sandbox Framework (Day 3-4)

    • Code: Implement sandbox abstraction
      • Define Sandbox protocol/interface
      • Implement GitWorktreeSandbox for git repositories
      • Implement FilesystemSandbox (copy-on-write) for local files
      • Implement NoSandbox for non-sandboxable resources
      • Add sandbox lifecycle (create, commit, rollback, cleanup)
      • Location: src/cleveragents/infrastructure/sandbox/
    • Tests: Integration tests for each sandbox type

  • Stage B4: Resource Integration (Day 4-5)

    • Code: Connect resources to plan execution
      • Create ResourceService for resource access during execution
      • Implement lazy sandboxing (sandbox on access, not upfront)
      • Add sandbox cleanup on plan completion/failure
      • Location: src/cleveragents/application/services/resource_service.py
    • Tests: End-to-end tests for plan execution with sandboxed resources

  • Stage B5: Project Persistence (Day 5)

    • Code: Project/Resource database schema
      • Alembic migration for projects table
      • Alembic migration for resources table
      • Alembic migration for project_resources junction table
      • ProjectRepository, ResourceRepository
      • Location: alembic/versions/, src/cleveragents/infrastructure/database/
    • Tests: Integration tests for persistence

M2 SUCCESS CRITERIA:

  • Can create a project with resources via CLI
  • Git repository resources can be sandboxed with worktrees
  • Filesystem resources can be sandboxed with copy-on-write
  • Plan execution uses sandboxed resources
  • Sandbox cleanup works on success and failure

Section 5: Actors & Skills [WORKSTREAM C - 1 Developer]

Target: Milestone M3 (+8 days)

  • Stage C1: Actor YAML Schema (Day 1)

    • Code: Formalize actor YAML schema
      • Document canonical actor YAML format (compatible with existing v2 format)
      • Add skill definition in actor YAML (tool nodes with inline code)
      • Add route definitions for graph-based actors
      • Add context/memory configuration options
      • Location: src/cleveragents/actor/schema.py
    • Document: Create docs/reference/actor_configuration.md with full schema

  • Stage C2: Actor Loading Enhancement (Day 2-3)

    • Code: Enhance actor loading
      • Parse skill definitions from actor YAML
      • Generate LangGraph tool nodes from skill code
      • Compile actor config into executable LangGraph StateGraph
      • Support actor references (actor can reference other actors)
      • Location: src/cleveragents/actor/compiler.py
    • Tests: Behave scenarios for actor compilation

  • Stage C3: Skill Execution (Day 3-4)

    • Code: Implement skill execution framework
      • Define Skill protocol for executable skills
      • Create skill executor that runs inline Python code
      • Add context injection for skills (project resources, plan state)
      • Implement subplan spawning skill (context.spawn_subplan())
      • Location: src/cleveragents/actor/skills.py
    • Tests: Integration tests for skill execution

  • Stage C4: Built-in Provider Actors (Day 5)

    • Code: Create built-in actors for each provider
      • Generate openai/gpt-4, openai/gpt-3.5-turbo, etc.
      • Generate anthropic/claude-3-opus, anthropic/claude-3-sonnet, etc.
      • Generate google/gemini-pro, etc.
      • Ensure built-in actors work as strategy/execution actors
      • Location: src/cleveragents/actor/builtins.py
    • Tests: Verify built-in actors work in plan lifecycle

  • Stage C5: Plan-Actor Integration (Day 6-8)

    • Code: Connect actors to plan lifecycle
      • Strategize phase invokes strategy_actor with project context
      • Execute phase invokes execution_actor with strategy output
      • Actors receive plan description, project resources, and arguments
      • Actor output flows to next phase
      • Location: src/cleveragents/application/services/plan_lifecycle_service.py
    • Tests: End-to-end tests for full plan lifecycle with actors

M3 SUCCESS CRITERIA:

  • Can define actors in YAML with skills
  • Actors compile to LangGraph graphs
  • Skills can execute inline Python code
  • Built-in provider actors work
  • Full plan lifecycle works: Action → Strategize (with actor) → Execute (with actor) → Apply

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

Section 6: Decision Tree [After M3 Merge - All Developers]

Target: Milestone M4 (+12 days)

  • Stage D1: Decision Data Model (Day 9)

    • Code: Create Decision domain model
      • Define Decision Pydantic model per spec (decision_id ULID, plan_id, parent_decision_id, decision_type, question, chosen_option, alternatives_considered, rationale, etc.)
      • Define DecisionType enum (prompt_definition, strategy_choice, implementation_choice, resource_selection, subplan_spawn, tool_invocation, error_recovery, validation_response, user_intervention)
      • Location: src/cleveragents/domain/models/core/decision.py
    • Tests: Behave scenarios for decision model

  • Stage D2: Decision Recording (Day 10)

    • Code: Record decisions during Strategize
      • Strategy actor outputs decisions as structured data
      • Each decision gets a ULID and is persisted
      • Build decision tree from parent_decision_id relationships
      • Root decision is the plan's prompt_definition
      • Location: src/cleveragents/application/services/decision_service.py
    • Tests: Verify decision tree is built during Strategize

  • Stage D3: Decision CLI (Day 11)

    • Code: Decision viewing and correction commands
      • agents plan tree [plan_id] - display decision tree (ASCII)
      • agents plan correct <decision_id> --mode=<revert|append> --guidance "<text>"
      • agents plan correct <decision_id> --mode=<revert|append> --guidance-file <path>
      • Location: src/cleveragents/cli/commands/decision.py
    • Tests: CLI tests for decision commands

  • Stage D4: Decision Persistence (Day 12)

    • Code: Decision database schema
      • Alembic migration for decisions table
      • Alembic migration for decision_dependencies table
      • Alembic migration for correction_attempts table
      • DecisionRepository
      • Location: alembic/versions/, src/cleveragents/infrastructure/database/
    • Tests: Integration tests for decision persistence

M4 SUCCESS CRITERIA:

  • Decisions are recorded during Strategize
  • Decision tree can be viewed via CLI
  • Basic correction mechanism works (re-runs affected subtree)

Section 7: Subplans & Parallelism [After M4]

Target: Milestone M5 (+18 days)

  • Stage E1: Subplan Model (Day 13)

    • Code: Extend Plan model for hierarchy
      • Add parent_plan_id, root_plan_id to plan model
      • Track subplan execution mode (sequential/parallel)
      • Add result merging strategy per resource type
      • Location: Update src/cleveragents/domain/models/core/plan.py
    • Tests: Behave scenarios for subplan model

  • Stage E2: Subplan Spawning (Day 14-15)

    • Code: Implement subplan spawning in Execute phase
      • Subplan decisions recorded during Strategize
      • Subplans actually spawned during Execute
      • Support sequential and parallel execution modes
      • Location: src/cleveragents/application/services/plan_lifecycle_service.py
    • Tests: Integration tests for subplan spawning

  • Stage E3: Result Merging (Day 16-17)

    • Code: Implement result merging
      • Git-style merge for code resources
      • Sequential application for databases
      • Pluggable merge strategies
      • Location: src/cleveragents/application/services/merge_service.py
    • Tests: Integration tests for result merging

  • Stage E4: Multi-Project Plans (Day 18)

    • Code: Support plans targeting multiple projects
      • Plan can reference multiple projects
      • Strategy clarifies which steps affect which projects
      • Apply commits to each project separately
      • Location: Update plan lifecycle service
    • Tests: End-to-end tests for multi-project plans

M5 SUCCESS CRITERIA:

  • Plans can spawn subplans
  • Subplans can run in parallel
  • Results from subplans are merged correctly
  • Plans can target multiple projects

Section 8: Server Mode [After M5]

Target: Milestone M6 (+25 days)

  • Stage F1: Server Infrastructure (Day 19-20)

    • Code: agents serve command
      • FastAPI server setup
      • Health/version endpoints
      • OpenAPI documentation
      • Location: src/cleveragents/runtime/server.py
    • Tests: Server startup/shutdown tests

  • Stage F2: Plan Execution API (Day 21-22)

    • Code: REST API for plan lifecycle
      • POST /actions - create action
      • POST /plans - use action to create plan
      • POST /plans/{id}/execute - execute plan
      • POST /plans/{id}/apply - apply plan
      • GET /plans/{id} - get plan status
      • Location: src/cleveragents/runtime/api/
    • Tests: API integration tests

  • Stage F3: WebSocket Streaming (Day 23-24)

    • Code: Real-time plan status streaming
      • WebSocket endpoint for plan updates
      • Stream phase transitions, node completions
      • Location: src/cleveragents/runtime/api/websocket.py
    • Tests: WebSocket integration tests

  • Stage F4: Remote Project Execution (Day 25)

    • Code: Execute plans on remote projects
      • Server can access remote resources
      • Client sends execution requests to server
      • Location: Update resource service
    • Tests: End-to-end tests for remote execution

M6 SUCCESS CRITERIA:

  • agents serve starts a working API server
  • Plans can be created and executed via API
  • Real-time updates via WebSocket
  • Remote projects can be used

Section 9: Full Feature Set [After M6]

Target: Milestone M7 (+35 days)

  • Stage G1: Automation Levels (Day 26-27)

    • Code: Implement automation level support
      • Manual: User prompted for each decision
      • Review-before-apply: Auto decisions, user reviews before Apply
      • Full automation: All decisions automatic
      • Configurable per plan/session/global
      • Location: Update plan lifecycle service
    • Tests: Tests for each automation level

  • Stage G2: Checkpointing & Rollback (Day 28-29)

    • Code: Enhanced checkpointing
      • Skill-level checkpointability declarations
      • Plan-level rollback policy
      • Rollback to checkpoint command
      • Location: src/cleveragents/infrastructure/checkpoint/
    • Tests: Checkpoint/rollback tests

  • Stage G3: Context Tiers (Day 30-31)

    • Code: Hot/warm/cold context management
      • Hot context: immediate LLM access
      • Warm context: quick retrieval
      • Cold context: archived/compressed
      • Per-actor context views
      • Location: src/cleveragents/application/services/context_tier_service.py
    • Tests: Context tier tests

  • Stage G4: Cost & Risk Estimation (Day 32-33)

    • Code: Optional estimation actor
      • Analyze strategy output
      • Estimate tokens/cost/time
      • Provide risk assessment
      • Location: src/cleveragents/agents/estimation.py
    • Tests: Estimation accuracy tests

  • Stage G5: Full CLI Polish (Day 34-35)

    • Code: Complete CLI refinement
      • Consistent help text across all commands
      • Rich terminal output throughout
      • Progress indicators for all long operations
      • Error messages with recovery suggestions
    • Tests: CLI UX tests
    • Document: Complete user documentation

M7 SUCCESS CRITERIA:

  • All spec features implemented
  • Full test coverage (>85%)
  • Documentation complete
  • Ready for release

Section 10: Async Infrastructure & Quality [Ongoing]

  • Stage 8: Async Infrastructure (Parallel with above)

    • Implement async command execution (asyncio per ADR-002)
    • Implement the 33 retry patterns with tenacity (COMPLETED 2025-11-17)
    • Add circuit breaker for failures (COMPLETED 2025-11-17)
    • Add background workers (convert 7 concurrency patterns to asyncio tasks)
    • Integrate retry patterns into services

  • Stage 11: ADR Alignment Verification

    • Verify all 11 ADRs are followed in implementation
    • ADR-001 through ADR-011 compliance check

  • Stage 12: Quality Metrics

    • 100% type coverage (no Any types)
    • 85%+ test coverage maintained
    • All 11 ADRs followed
    • Zero linting errors (Ruff)
    • Zero type errors (pyright)
    • Performance targets met

Section 11: Deferred Work

The following items from the previous implementation plan are deferred or no longer applicable:

  • Deferred: REPL Mode - Focus on CLI first, REPL is optional enhancement
  • Deferred: Auth/Team Commands - Requires server infrastructure
  • Removed: Old 67-command structure - Replaced by new command structure
  • Removed: Configuration migration utilities - CleverAgents is standalone

Timeline Summary

Week Milestone Focus
Week 1 (Days 1-3) M1 Plan Lifecycle basics
Week 1-2 (Days 4-5) M2 Projects & Resources
Week 2 (Days 6-8) M3 Actors & Skills, MERGE
Week 2-3 (Days 9-12) M4 Decision Tree
Week 3-4 (Days 13-18) M5 Subplans & Parallelism
Week 4-5 (Days 19-25) M6 Server Mode
Week 5-6 (Days 26-35) M7 Full Feature Set

Aggressive assumptions:

  • 2-3 developers working full-time
  • Existing LangGraph infrastructure is reusable
  • Actor system (Stage 7.5) provides foundation
  • No major architectural surprises

Risk factors:

  • Sandbox implementation complexity (esp. git worktrees)
  • Decision tree correction mechanism
  • Multi-project merge conflicts
  • Server mode stability
Reference in New Issue View Git Blame Copy Permalink