From 7be8d321bd4e6d585a88f052535477408739f6bb Mon Sep 17 00:00:00 2001 From: Jeffrey Phillips Freeman Date: Wed, 4 Feb 2026 19:55:44 -0500 Subject: [PATCH] Added a new v3 spec to describe new architecture direction --- v3_spec.md | 1932 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1932 insertions(+) create mode 100644 v3_spec.md diff --git a/v3_spec.md b/v3_spec.md new file mode 100644 index 00000000..71c5ad51 --- /dev/null +++ b/v3_spec.md @@ -0,0 +1,1932 @@ +# CleverAgents v3 Documentation (Detailed Spec) + +## Source Material + +This document is derived from the attached meeting notes / transcript (). It reflects the architectural direction described by Jeffrey Freeman, Drew Morris, and Aditya Chhabra, with discussion also involving Justin Morris. Key themes include: + +* A **four-phase plan lifecycle** (Action → Strategize → Execute → Apply). +* **Actors** as a unifying abstraction (an LLM/agent *or* a whole graph). +* A **sandbox + diff review** workflow and **CLI-first** interaction model. +* A scalable **context/memory architecture** (hot/warm/cold tiers, per-actor views). +* A future-facing correction model where the user can “edit the decision tree” and only recompute affected subtrees. + +# Big Picture: What CleverAgents v3 *is* + +CleverAgents v3 is intended to be a **configuration-driven framework for building and running LangGraph/LangChain systems**, rather than a “new agent framework that competes by adding exotic capabilities.” In other words: the core value is **orchestration, lifecycle, repeatability, UX, and safety (sandbox/checkpoints)**—not replacing what LangGraph and LangChain already do well. + +Said differently: + +* **LangGraph / LangChain** provide the runtime primitives for LLMs, tool calling, graphs, and routing. +* **CleverAgents v3** 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. + +# Glossary (Terms Used Precisely) + +* **Plan**: A tracked lifecycle for a single unit-of-work (which may spawn subplans). +* **Action**: A reusable plan template not tied to any project yet. +* **Strategize**: Read-only planning phase that produces a strategy and subplan blueprint. +* **Execute**: Phase that performs work in a sandbox; can spawn subplans; produces artifacts/diffs. +* **Apply**: Phase that commits sandbox results into the real project (and records an “applied” plan state). +* **Project**: A collection of resources + skills that define “where work happens” and “what can be touched.” +* **Resource**: Anything that can be read/written/queried (files, repo trees, DB endpoints, cloud clusters, documents). +* **Skill**: A callable capability (MCP server skill, built-in tool, CLI wrapper, custom python node) used by actors. +* **Actor**: Anything conversational; may be a single agent/LLM or an entire graph of actors/tools. +* **Session**: A user interaction context and conversation thread that can span multiple plans. +* **Server**: Optional shared service for multi-user storage, permissions, and orchestration. + +# Components + +## Plan + +A **plan** is the fundamental unit of orchestration and traceability in v3. + +### Plan Lifecycle Phases + +A plan always moves through the following phases, in order: + +**Action → Strategize → Execute → Apply → Applied (terminal)** + +Your draft uses “Strategy / Execution / Applied,” while the meeting notes use “Strategize / Execute / Apply.” In this spec: + +* **Strategize** is the phase name (the output is a **strategy**). +* **Execute** is the phase name (the output is an **execution result**). +* **Apply** is the phase name (the output is an **applied change**). +* **Applied** is the resulting terminal state after Apply succeeds. + +This four-stage model is explicitly called out as the new architecture replacing a prior linear pipeline. + +### Phase Transition Verbs (CLI / UX Contract) + +Your draft proposes verbs that trigger phase transitions. v3 should standardize these verbs as the **public API** (CLI, TUI, web): + +| Current Phase | Command Verb | Next Phase | +| ------------- | ------------ | ---------- | +| (none) | `create` | Action | +| Action | `use` | Strategize | +| Strategize | `execute` | Execute | +| Execute | `apply` | Applied | + +**Important behavioral rule:** +CleverAgents must support multiple “automation levels” that can automatically progress through these verbs without the user explicitly issuing them, but the verbs remain the conceptual contract. + +### Plan States (Per Phase) + +A plan’s phase indicates “what step of the lifecycle it is in.” Separately, the plan has a **processing state** indicating “what is happening right now.” + +Recommended state model: + +* **Action phase states** + + * `available` (action exists and can be used) + * `draft` (action is being authored/edited) + * `archived` (soft-deleted or hidden, optional) + +* **Strategize / Execute / Apply phase states** + + * `queued` (waiting for compute/worker) + * `processing` (currently running) + * `errored` (failed; includes error metadata) + * `complete` (finished successfully) + * `cancelled` (user/system cancelled; safe terminal for that phase) + +Your draft says “processing/errored/complete” for all non-action phases; I’m extending to `queued` and `cancelled` because they become essential in parallel execution and server mode. + +### Plan Identity and Traceability + +Every plan should have: + +* **plan_id**: Unique, immutable ID (UUID or ULID). +* **parent_plan_id**: Nullable; present for subplans. +* **root_plan_id**: The top-most plan in the tree. +* **attempt**: An integer attempt counter that increments when re-running a phase (e.g., re-executing after a fix). +* **created_at / updated_at / completed_at** timestamps. +* **created_by** (user identity / session identity). + +### Plan Hierarchy (Subplans) and Parallelism + +A single plan should usually represent the smallest “complete” unit of work (similar to what would fit in one git commit). However: + +* **Plans are hierarchical.** +* During **Execute**, a plan may **spawn subplans** to handle smaller incremental work units. +* Subplans can run **in parallel**. +* The parent plan is responsible for **merging results** (conceptually like merging commits), producing a coherent final result. + +This is core to the long-term objective: tackling large tasks while only recomputing parts of the decision tree when corrected. + +### The Plan “Decision Tree” and Visualization + +CleverAgents v3 intends to record enough information to render: + +* an **ASCII tree** in the TUI, and +* optionally a GUI tree via visualization tools (D3/Cytoscape) once the data exists. + +This implies each plan should persist: + +* decisions made, +* the rationale (or at least the prompt/context snapshot that produced it), +* dependencies (“this decision influenced these child plans”). + +This is required for “correcting plans” (see Behavior section). + +## Action + +Your Action section is already strong. Below is the completed/expanded spec that preserves your intent. + +### What an Action Is + +An **action** is a reusable plan template that is not associated with any projects yet. + +Examples: + +* “Increase test coverage to 80%” +* “Refactor module X to be async-safe” +* “Write an RFC for feature Y” +* “Provision an infra cluster and validate access” (non-code) + +Actions are **intentionally project-agnostic** so they can be reused across projects. + +### Action Data Model (Expanded) + +A plan in the Action phase has: + +#### 1) `name` (namespaced) + +Format: + +* `[server:][namespace/]` + +Rules: + +* If server is omitted, default server is assumed unless namespace is `local`. +* If namespace is omitted, default is `local`. +* Names should be stable identifiers (kebab-case recommended). + +Examples: + +* `local/code-coverage` +* `personal/code-coverage` +* `org/platform/code-coverage` +* `prod:org/platform/code-coverage` (server-qualified) + +#### 2) `short_description` + +Optional at creation; auto-filled if blank. + +#### 3) `long_description` + +Optional but recommended for reusable actions. + +#### 4) `definition_of_done` (DoD) + +Required. Must be explicit and testable. Prefer structured “must/should/may” language: + +* Must: requirements that must be met for completion +* Should: quality targets +* May: optional stretch goals + +#### 5) `actors` + +Two actors minimum: + +* **strategy_actor** (planner/architect) +* **execution_actor** (builder/implementer) + +You can optionally add: + +* **review_actor** (code review / QA) +* **apply_actor** (release/merge specialist) + …but these can also be handled as subplans. + +Actors can be: + +* an LLM agent, +* a graph, +* or another actor reference. + +Actor abstraction is central: an actor may be a single agent or an entire graph. + +#### 6) `reusable` (boolean) + +* Default: `true`. +* If `true`: using the action creates a *new* plan in Strategize while leaving the action available. +* If `false`: action self-deletes (or auto-archives) after first use. + +#### 7) `read_only` (boolean) + +* Default: `false`. +* If `true`: the plan must only use read-only skills and must never modify resources (even in sandbox). +* Read-only actions are still useful for “investigation reports,” architecture reviews, or dry-run planning. + +#### 8) `inputs_schema` (recommended addition) + +To make actions genuinely reusable, actions should declare their inputs: + +* required args (e.g., target coverage percent), +* optional args (e.g., test framework), +* validation rules (types, bounds). + +Example: + +* `target_coverage_percent`: integer 0–100 + +#### 9) `safety_profile` (recommended addition) + +A policy bundle that can be applied to enforce safe execution: + +* allowed skill categories, +* require checkpoints, +* require sandbox, +* require human approval at Apply. + +This relates to the “checkpointable skills + sandbox” approach for safe writing. + +## Strategy (Strategize Phase) + +### What Strategize Does + +When an action is **used** on projects, it becomes a **plan in Strategize**. + +Strategize is: + +* **read-only**, producing a plan of attack, +* responsible for gathering context from project resources, +* responsible for generating a strategy and subplan blueprint, +* not allowed to execute subplans or modify resources. + +This “architect vs coder” separation is explicitly described as a core motivation. + +### Strategize Data Model + +A plan in Strategize contains all Action fields plus: + +#### 1) `projects` + +A list of projects the plan is used on. + +Important: A strategy plan may target **multiple projects**. Multi-project work in one “window” is considered a major usability advantage over tools that require being run from a single directory. + +#### 2) `strategy_context` + +A structured object describing: + +* what resources were considered, +* how they were retrieved, +* what filtering/limits were applied, +* what the actor saw. + +This matters because a plan must be debuggable and correctable later. + +Recommended fields: + +* `resource_refs`: IDs of resources used +* `queries`: search queries performed +* `selected_chunks`: chunk IDs + sources + reasons +* `constraints`: context window limits, file ignore patterns +* `generated_summaries`: if summarization occurred + +#### 3) `strategy` + +The output plan: + +* steps (ordered and/or DAG), +* conditions/branches (“if tests fail, do X”), +* subplans to spawn (including which action templates to use), +* evaluation criteria (how to know success), +* risk assessment. + +#### 4) `execution_blueprint` (recommended addition) + +Strategize should output not only narrative text but also a machine-usable blueprint: + +* list of tasks, +* required skills, +* expected outputs, +* dependencies between tasks. + +This blueprint becomes the input to Execute. + +#### 5) `cost_estimate` and `risk_estimate` (recommended addition) + +Since full automation is a goal, Strategize should optionally estimate: + +* LLM tokens/cost range, +* number of steps, +* expected risk of rollbacks. + +This becomes critical in server/multi-user usage and cost controls (which are noted as a future need). + +## Execution (Execute Phase) + +### What Execute Does + +Execute is where the plan actually performs work, but **in a sandboxed environment** that can later be reviewed and applied. + +Key properties: + +1. **Work happens in a sandbox** + All file modifications, generated artifacts, and intermediate outputs live in an isolated “execution workspace” until Apply. + +2. **Execute may spawn subplans** + Subplans are a first-class behavior of Execute: a parent plan can distribute work to child plans and merge results. + +3. **Execute must support checkpointing / rollback (when enabled)** + Checkpointable skills allow rolling back to a checkpoint ID to recover from partial failure or wrong turns. + +4. **Execute produces a “reviewable diff”** + Diff review sandbox is described as a differentiating feature: users can inspect changes before applying. + +### Execution Workspace / Sandbox Model (Detailed) + +A sandbox must behave like a “shadow copy” of the project resources, with clear rules: + +#### Recommended sandbox implementation strategies + +CleverAgents should support multiple sandbox backends: + +1. **Filesystem copy sandbox** + +* Copy project directory to a sandbox directory. +* Execute modifies sandbox copy. +* Apply syncs diff back. + +Pros: simple. +Cons: expensive for huge repos. + +2. **Git worktree / branch sandbox (preferred for code projects)** + +* Create a worktree or temporary branch. +* All modifications are commits or staged changes. +* Apply merges/cherry-picks. + +Pros: natural rollback, diff support, efficient. +Cons: requires git. + +3. **Overlay filesystem sandbox** + +* Use overlayfs-style “copy-on-write” to avoid full copies. + +Pros: efficient. +Cons: more complex. + +A plan’s configuration can choose a sandbox backend based on project type. + +### Execution Data Model + +A plan in Execute contains: + +#### 1) `execution_context` + +The context used for execution (often smaller/more tactical than strategy context). + +#### 2) `execution_log` + +Structured timeline of: + +* skill calls, +* actor calls, +* outputs, +* errors and retries, +* checkpoints created. + +This log is essential for debugging. + +#### 3) `artifacts` + +Outputs produced: + +* changed files, +* generated files, +* reports, +* diagrams, +* test outputs, +* diffs. + +#### 4) `sandbox_ref` + +Pointer to the sandbox location/state: + +* path, branch name, workspace ID, container ID, etc. + +#### 5) `checkpoint_graph` (if enabled) + +A record of checkpoints: + +* checkpoint ID +* timestamp +* skill responsible +* resources affected +* rollback instructions / metadata + +### Checkpointing in Execute (Core Safety Mechanism) + +The meeting notes repeatedly emphasize the need for checkpoints tied to skills and rollbacks. The intended user-level behavior is: + +* “Give me a checkpoint ID.” +* Perform additional operations. +* “Roll back to checkpoint X.” + +Not all skills can support this; checkpointing must be declared per skill. + +#### Skill-level checkpointability + +Each skill declares: + +* `checkpointable: true|false` +* `rollback_mechanism`: how rollback occurs +* `scope`: what resources it can revert + +Examples: + +* File skill: snapshot file states pre-modification +* Git skill: create commit or stash; rollback is reset/checkout +* CLI skill inside a container: rollback by restoring filesystem snapshot or reloading base image state + +There’s explicit discussion that checkpointing is easier when skill scope is constrained (e.g., “only files within a docker image + git”). + +#### Plan-level rollback policy + +Plans should have an option: + +* `rollback_enabled: true|false` + +If disabled, the plan may use more generic/unsafe skills with fewer restrictions (useful for low-stakes tasks). + +### Execution as Transactions (Recommended) + +Execution should be treated like a transactional pipeline: + +* Each step either: + + * commits a checkpoint on success, or + * rolls back to the previous checkpoint on failure. + +This is explicitly motivated by “partial failure leaves codebase inconsistent” and the need for transaction rollback. + +### Parsing and File Generation Expectations + +The notes call out planned improvements: + +* Extract code blocks properly (avoid markdown explanation text in output files). +* Avoid generic file names like `generated.py`. +* Improve file structure generation. +* Handle invalid python responses better than wrapping in docstrings. + +Therefore, v3 should define a **standard output parsing pipeline**: + +1. Parse model output. +2. Identify code blocks and associated filenames (if present). +3. If filename missing, infer from context and existing project structure. +4. Validate syntax (when language known). +5. If invalid, either: + + * request correction from actor, or + * quarantine the output as a “draft artifact” rather than writing it as real source. + +## Applied (Apply Phase) + +### What Apply Does + +Apply takes the sandboxed work product and makes it “real” in the project. + +Core properties: + +1. **Apply is a controlled commit step** + Apply exists specifically to separate “generated work” from “committed work,” enabling review and safer automation. + +2. **Apply is often the highest-risk step** + It changes real systems. This is where permissions, approvals, and checks matter most. + +3. **Apply produces a terminal ‘applied’ plan** + After successful apply, the plan becomes Applied. + +### Apply Responsibilities (Recommended Checklist) + +Apply should perform (configurable) validations before committing: + +* **Diff review gate** + + * If automation level requires review, show: + + * changed files summary, + * full diff, + * risk warnings. +* **Pre-apply tests** + + * Run unit tests / lint / type checks (optional but recommended). +* **Conflict resolution** + + * If applying to a git repo, handle rebase/merge conflicts safely. +* **Audit log** + + * Record who applied, what changed, when, and why. + +### Apply Data Model + +A plan in Apply includes: + +* `apply_summary` +* `applied_artifacts` (final commit hash, merged PR link, file list) +* `final_validation_results` (test outputs, lint outputs) +* `approval_record` (if human approvals are required) +* `deployment_record` (optional, if apply triggers deploy) + +### “Applied” Terminal State + +When Apply succeeds: + +* plan.phase = `applied` +* plan.state = `complete` +* the sandbox may be cleaned up or archived depending on retention policy + +When Apply fails: + +* plan.phase remains Apply +* plan.state = `errored` +* sandbox remains intact for inspection/retry + +## Project + +A **project** is the boundary that answers: + +* “Where is the work happening?” +* “What can this plan read and write?” +* “What tools can this plan use?” +* “What context is available?” + +In the transcript, a project is described as a **collection of resources and skills**. + +### Project Data Model (Recommended) + +A project should include: + +#### 1) Identity + +* `project_id` +* `name` +* `namespace` (local/personal/org) +* `tags` (e.g., “python”, “infra”, “paper”, “prod”) + +#### 2) Resources + +Resources are the “things you can act on,” such as: + +* filesystem root(s), +* git repository, +* database endpoints, +* cloud accounts, +* document corpora (papers, PDFs), +* API schemas. + +Each resource should have: + +* `resource_id` +* `type` +* `location` (path/url/connection string) +* `read_policy` and `write_policy` +* `metadata` (language, repo size, etc.) + +#### 3) Skills + +Skills are the “ways you can operate on resources.” + +* Built-in skills (file ops, git ops, search/rag, etc.) +* MCP skills +* CLI skills (shell access, docker exec) +* Custom python nodes (config-defined) + +Skill definitions should include capability metadata (read/write/checkpointable) because MCP alone may not provide enough detail. + +#### 4) Context configuration + +Project-level defaults: + +* ignore patterns (like `.gitignore` semantics) +* max file size +* indexing strategy +* preferred chunking/summarization policy (even if evolving) +* context retention policy + +#### 5) Security / permissions defaults + +* who can run write plans +* which skills are restricted +* whether apply requires approvals + +### Multi-Project Operations + +A single plan may target multiple projects (e.g., updating shared schemas across services). This is considered a key UX advantage over “run in one directory” systems. + +In multi-project execution: + +* Strategize must clarify which steps affect which projects. +* Execution must isolate sandboxes per project OR define a composite sandbox. +* Apply must commit changes to each project separately, with separate approval records if necessary. + +## Namespaces + +Namespaces define **ownership, scoping, and discoverability** of actions, projects, and actors. + +Your draft lists: + +* Local +* Personal +* Organization + +That’s a good baseline. + +### Namespace Rules (Recommended) + +* **`local/`** + + * Exists only on the current machine. + * Fast iteration, no sharing. + * Default namespace for quick experiments. + +* **`personal/`** + + * Belongs to a user identity (even if only on local machine initially). + * Intended to sync to a server (optional). + * Used for reusable actions/actors a user wants across machines. + +* **`org//`** + + * Shared across a team/organization. + * Requires server support. + * Actions/actors/projects can be centrally managed. + * Permissions and approvals matter more. + +### Server-qualified Names + +To disambiguate between servers: + +* `dev:org/acme/code-coverage` +* `prod:org/acme/code-coverage` + +This enables a pattern where: + +* local machine runs a lightweight client, +* server stores canonical definitions. + +## Actor + +### What an Actor Is + +An **actor** is the v3 abstraction that generalizes “agent” into “anything conversational.” + +* It can be as small as a single LLM agent. +* It can also be an entire graph that itself calls other actors/tools. +* Actors can be nested/hierarchical, enabling “orchestrator of orchestrators.” + +### Actor vs Agent (Relationship) + +* **Agent**: an actor that is specifically an LLM with tools and reasoning behaviors. +* **Actor**: may be an agent, but may also be: + + * a composite workflow, + * a multi-step graph, + * a wrapper around a third-party system (as long as it’s “text in → text out” conversationally). + +### Actor Definition Fields (From Notes + Extended) + +The notes describe an actor as a configuration profile with fields like name, provider, model, configuration, blob, and graph description. + +A robust v3 actor schema should include: + +* `name` (namespaced) +* `provider` (LLM provider or runtime target) +* `model` +* `system_prompt` (or prompt template) +* `tool_access_policy` +* `graph_descriptor` (for composite actors) +* `memory_policy` (per-plan/per-actor—see memory section) +* `context_view_policy` (what context this actor sees) +* `limits` (token limits, tool call limits, retries) +* `cost_policy` (caps, budgets) +* `metadata` (tags, use cases, version) + +### Actor Composition and Graphs + +Actors can reference: + +* other actors +* skills (MCP/custom tools) +* subgraphs + +This is central to enabling both: + +* multi-agent orchestration, and +* modular reuse of workflows. + +### Nodes in the Graph: Actor, Skill, or Custom Tool + +The transcript explicitly frames the graph nodes as being any of: + +* an actor, +* an MCP skill, +* a custom tool node (arbitrary python code). + +This is a powerful simplification: “everything is a node.” + +## Agent + +### Agent Definition + +In CleverAgents v3, an **agent** is a specialized actor with: + +* a conversational interface, +* tool-calling capability, +* potentially memory, planning heuristics, and role identity. + +Examples of agent roles: + +* planner/architect (strategy actor) +* coder/implementer (execution actor) +* reviewer/qa agent +* release/apply agent + +The transcript explicitly discusses role separation like planner/coder/reviewer in context views/memory proposals. + +### Agent Behavior Configuration + +Agents should be configurable without code changes: + +* prompt templates +* tool sets +* safety constraints +* style constraints (verbosity, code style) +* reliability controls (self-checks, validations) + +A design goal is user empowerment: “users customize LLM behavior without modifying core code.” + +## Skills + +### What a Skill Is + +A **skill** is an executable capability exposed to the system. +Examples: + +* file read/write +* git operations +* shell command execution +* database query execution +* API calls +* vector search / RAG query +* cloud administration actions + +### Skill Sources + +Skills come from multiple places: + +1. **Built-in skills** (first-party) + + * files, git, search, indexing, context mgmt, sandbox ops +2. **MCP skills** (external servers) +3. **Imported skills** from other ecosystems + + * wrap tools from other agent frameworks as long as interface is compatible +4. **Custom tool nodes** + + * arbitrary python code embedded in configuration + * behaves as a graph node + +### Skill Capability Metadata (Critical for Safety) + +The transcript highlights that MCP’s metadata is not sufficient (read-only/idempotent isn’t enough; write scope is unclear). So v3 needs an extension or internal registry that stores richer metadata. + +Recommended skill metadata: + +* `read_only: bool` +* `writes: bool` +* `write_scope`: + + * file paths allowed, + * resource IDs allowed, + * environment boundaries (container only vs host) +* `idempotent: bool` +* `checkpointable: bool` +* `checkpoint_scope` (what can be rolled back) +* `side_effects` (install packages, mutate infra, etc.) +* `required_permissions` +* `rate_limits` / `cost_profile` +* `human_approval_required: bool` (optional) + +### Skill Registry / Catalog + +To scale, CleverAgents should maintain a catalog of skills with metadata, possibly: + +* auto-extracted from MCP descriptors (where possible), +* refined manually via annotations, +* enhanced by “our own extension” approach discussed in the transcript. + +This registry supports: + +* plan validation (“this plan requires checkpointable write skills; do we have them?”), +* safe automation (“don’t ask permission for every tiny command—use sandbox/checkpoints instead”). + +## Session + +### What a Session Is + +A **session** is a user’s interactive thread with CleverAgents across time. + +A session should: + +* maintain conversational continuity, +* store plan references, +* persist memory (if enabled), +* provide a UI anchor (CLI invocation, TUI workspace, web session). + +### Session and Memory Persistence + +The notes include a known issue: conversation history can be lost between CLI invocations depending on connection string configuration, implying the system needs a stable memory service backend. + +Therefore, v3 should specify: + +* sessions have stable IDs +* sessions can be resumed +* session storage backend is configured explicitly +* if session persistence is disabled, the UX should be explicit about it (no silent history loss) + +## Server + +### What a Server Is (in v3) + +A server is an optional mode that enables: + +* multi-user access, +* shared org namespaces, +* persistent plan records, +* distributed execution workers, +* permissioning and governance. + +Single-user local mode should be the default (so setup is easy), but the architecture should anticipate server mode, especially for shared skills and org-level actions. + +### Multi-user Risks and Prompt Injection + +The transcript notes prompt injection isn’t critical in single-user mode but becomes important for multi-user server environments. + +Therefore server mode must include: + +* permission boundaries +* prompt sanitization / safe templating +* resource access controls +* auditing + +## Permissions + +Permissions exist at multiple layers: + +### 1) Namespace-level permissions + +* Who can create/edit org actions/actors/projects? +* Who can run them? + +### 2) Project-level permissions + +* Who can modify project resources? +* Who can apply changes? + +### 3) Plan-level permissions + +* Can this plan write? +* Does it require approvals? +* Can it access restricted skills? + +### 4) Skill-level permissions + +* Some skills should require: + + * explicit user approval per call, or + * elevated role membership. + +### Approval Gates by Phase (Recommended) + +A simple and powerful governance model: + +* Strategize: generally safe, read-only → minimal restrictions +* Execute: writes occur but sandboxed → moderate restrictions +* Apply: writes are real → strict restrictions + optional mandatory review + +This aligns with the four-phase model’s safety rationale. + +## Resources + +Resources are any objects a plan can reason about or manipulate. + +### Resource Types (Examples) + +* **FilesystemResource**: directories, files +* **GitRepoResource**: git repos, branches +* **DatabaseResource**: SQL/NoSQL endpoints +* **CloudResource**: clusters, accounts, infra configs +* **DocumentCorpusResource**: PDFs, markdown docs, wikis +* **APISpecResource**: OpenAPI/Swagger, Postman collections +* **IssueTrackerResource**: tickets, bugs, tasks (optional) + +### Resource Access Tracking + +A major theme is that the system needs to know **which skills touch which resources** to reason about safety and checkpointing. + +So every skill call should log: + +* resource IDs accessed +* read/write actions +* file paths or object IDs touched + +This enables: + +* better context assembly, +* better rollback feasibility analysis, +* better auditing. + +## Context + +Context in v3 is not “dump all files into an LLM.” It is a system that: + +* finds relevant information from resources, +* injects appropriate subsets into each actor/node, +* and scales to large repositories. + +### Current Reality and Planned Improvements + +The transcript implies: + +* There is a global context concept, +* But nodes only see what is injected into their prompts, +* It’s functional but not yet elegant, +* A more advanced automated system is planned. + +### Tiered Context Architecture (Hot/Warm/Cold) + +A proposed architecture: + +* **Hot context (hot cache)** + The small set of immediately relevant chunks injected into the current actor prompt. + +* **Warm context** + Indexed embeddings / vector search / graph store representation of the codebase. + +* **Cold storage** + Long-term storage in SQLite or caching systems: history, prior summaries, older plan artifacts. + +Promotion/demotion behavior: + +* System analyzes current query, +* promotes relevant data upward (cold → warm → hot), +* demotes stale data out of hot to keep prompts tight. + +### Actor-Specific Context Views + +A key missing feature identified in the notes is per-actor context views, filtering, relevance, and actor-aware context limits. + +The intended direction: + +* global context exists at plan level, +* each actor gets a “view” of that context tuned to their role, +* memory may be shared or per-plan depending on design choices. + +#### Actor Context View Service (Proposed) + +A dedicated module/service that: + +* maintains actor-specific “context views,” +* tracks actor memory and relevance, +* enforces actor-specific limits (tokens, file types, etc.). + +### Initial Context vs Deep Context + +A practical approach mentioned: + +* Initial context is high-level (repo tree, language, overview), +* Then the system searches for relevant details iteratively via RAG. + +This strongly suggests v3 should define: + +* an “initial context recipe” per project type (codebase vs documents vs infra), +* iterative context refinement loops during strategize/execute. + +# Behavior + +## Automation Levels + +Automation levels determine which phase transitions happen automatically. + +At minimum, define three modes: + +1. **Manual** + +* User runs: create → use → execute → apply +* Every phase transition is explicit. + +2. **Review-before-apply** + +* Strategize + Execute happen automatically. +* System pauses before Apply to show diff and ask for approval. + This is directly described as a key usability pattern. + +3. **Full automation** + +* System runs all phases automatically end-to-end. + Also explicitly described. + +Recommended additional granularity: + +* `auto_strategize` +* `auto_execute` +* `auto_apply` +* `auto_retry_on_failure` + +This allows combinations like: + +* auto strategize, manual execute, manual apply (rare but useful for risky infra tasks) + +## Validation and Guardrails + +### Plan generation validation + +There is a note that validation logic is stubbed and must be implemented. The spec should require: + +* validate action schema +* validate actor availability +* validate required skills exist +* validate permission policy +* validate rollback feasibility (if enabled) +* validate project resource accessibility + +This prevents “plan runs with fake providers” and other surprises. + +### Cost / rate limits + +The notes mention future concerns: + +* API call limits +* cost caps + So v3 should define: +* per-plan budgets +* per-session budgets +* per-org budgets +* per-actor max tool calls / max retries + +## Correcting Plans (Core v3 Feature) + +Correcting plans is where v3 becomes more than “a fancy prompt runner.” + +### The Goal + +When a plan makes a wrong decision early, we want to: + +* correct the decision, +* recompute only the affected subtree, +* preserve unaffected work. + +This is explicitly described: “redo everything below that decision, not the entire code base.” + +### Decision Tree Representation + +Every plan should record: + +* decisions (choice points), +* dependencies (which later work depended on that decision), +* child plans spawned because of that decision, +* artifacts generated under that branch. + +This makes plan runs auditable and correctable. + +### Two Correction Modes (Explicitly Supported) + +The notes describe two distinct user intents: + +1. **Revert-from-history correction** + +* Find the decision point in the tree, +* change the decision, +* recompute everything downstream. +* Potentially expensive if high up in the tree. + +2. **Add-at-end correction** + +* Leave history intact, +* append a new plan at the end that fixes the outcome. +* Cheaper and safer sometimes. + +This dual-mode is explicitly discussed in the transcript. + +### UX for Correction + +A good v3 UX would allow: + +* `plan tree ` → show ASCII tree of decisions/plans +* `plan explain ` → show what decision was made and why +* `plan correct --mode=revert` → recompute subtree +* `plan correct --mode=append` → add corrective subplan + +### Correction Safety and Sandbox Interaction + +Corrections should: + +* create a new attempt revision, +* preserve old artifacts for diff/compare, +* run execute in sandbox again, +* require apply gating again. + +This keeps history reproducible and prevents accidental destructive edits. + +## Human-in-the-Loop Collaboration + +Even though the direction is “more autonomous,” the transcript explicitly recognizes that real workflows require engineers to collaborate with the system, editing code while it works, and using better UX integration (TUI/web/IDE). + +So v3 should aim for: + +* visibility: what is it doing now? +* interruptibility: pause/cancel/retry +* editability: allow user to modify strategy before execute +* reconciliation: detect if user changed sandbox files mid-run and handle it + +## UI / Interaction Model + +### CLI-first + TUI + Web App + IDE + +The system intends to be CLI-first, with: + +* a TUI built using Textual, +* which can generate a web app “for free,” +* and later an IDE plugin that embeds the TUI in the IDE. + +This implies a “single UI codebase” model: + +* same underlying view logic, +* multiple frontends. + +### Plan Tree Visualization + +The TUI should show: + +* plan list +* plan details +* plan tree (ASCII) +* diff view +* approvals + +And should later allow exporting the tree as image (PNG) or JSON for other visualization tools. + +# Additional Recommended Sections (Missing from Draft but Important) + +## Storage and Persistence + +v3 should define where each concept lives: + +* Actions: stored in a registry (local files or server DB) +* Actors: stored similarly (config files + DB indexing) +* Projects: stored locally or on server +* Plans: stored in plan DB with full logs +* Context indexes: vector store / graph store / SQLite +* Artifacts: filesystem or object storage + +## Observability + +To debug large plans: + +* every phase should emit events +* every actor call should log prompt/context references +* every skill call should log resource access +* every checkpoint should be recorded + +## Security Model + +* sandbox isolation +* resource-level ACLs +* prompt injection mitigations (server mode) +* secret management (API keys, DB credentials) +* audit logs for apply + +## Extensibility + +* plugin system for skills +* custom node types +* action templates +* actor templates (noted as missing currently) + +# Summary of Key Intended Behaviors (If You Only Read One Section) + +* Plans follow **Action → Strategize → Execute → Apply** with automation levels controlling transitions. +* **Strategize is read-only** and produces a strategy + blueprint. +* **Execute happens in a sandbox**, can spawn subplans, and should support checkpoints/rollback when enabled. +* **Apply commits changes** from sandbox to real project after review/validation. +* Actors are **hierarchical**: an actor can be a single agent or an entire graph. +* Graph nodes can be **actors, MCP skills, or custom tool nodes**. +* Context should evolve toward **hot/warm/cold tiers** and **actor-specific context views**. +* The system is designed for large tasks where the user can **correct a decision** and only recompute downstream work, visualizable as a plan decision tree. + +If you want, I can also produce: + +* a canonical **JSON/YAML schema** for Actions, Actors, Projects, Plans, Skills, and Context Views, +* a **CLI command reference** (every command, flags, examples), +* and a set of **end-to-end example workflows** (single project, multi-project, infra task, paper-writing task) consistent with this spec. + +# Work Remaining to Make CleverAgents Fully Functional + +This section describes—**exhaustively and in implementation terms**—what remains to be done to bring the current CleverAgents codebase up to the intended CleverAgents v3 behavior described in the transcript/meeting notes (Action → Strategize → Execute → Apply; actors as composable graphs; sandbox + diff review; context scaling; checkpointable skills; etc.). + +It is based primarily on the attached “what’s missing / code analysis” document (last updated **Jan 29, 2026**) which outlines the current master branch’s functional gaps, architectural limitations, and regressions introduced by new reactive/langgraph code. + +--- + +## Current State vs Intended v3: The Gap in One Sentence + +Right now, the codebase still behaves like a **linear, single-file “LLM dump to generated.py” pipeline** (with tiny context and stubbed validation), while intended v3 requires a **plan lifecycle engine that can reliably generate, validate, sandbox, diff-review, and apply multi-file/multi-project changes—backed by checkpointable skills, rich context, and composable actor graphs**. + +Everything below is the concrete work required to close that gap. + +--- + +## 1) Restore the Core Capability: Multi‑File Change Generation (Hard Blocker) + +### Problem (today) + +Per the code analysis, the current plan generation workflow is **hard-coded to emit exactly one `Change`** and write one file containing **raw LLM output** (often including markdown + explanations). This alone prevents “repo writing,” multi-service changes, scaffolding, and most realistic coding tasks. + +### What “done” looks like + +The system must be able to produce **N changes** across **N files**, where each change is one of: + +* `create` (new file) +* `modify` (update an existing file) +* `delete` +* `rename/move` (path change + optional content change) + +…and do so **reliably**, with predictable structure and minimal ambiguity. + +### High-level implementation plan + +#### A. Upgrade the internal “change set” model (do this first) + +Create a canonical internal representation for generated output, e.g.: + +* `ChangeSet` + + * `changes: list[Change]` + * `warnings: list[str]` + * `generated_by_actor: ActorRef` + * `validation: ValidationResult` + * `source_prompt_snapshot: PromptSnapshot` (for audit/debug) + +Where `Change` includes: + +* `operation` (enum) +* `path` (required except delete/move cases) +* `new_path` (for move) +* `content` (full content for create, optional for modify if using patches) +* `patch` (optional unified diff) +* `language` (optional but helpful for validation) + +**Key requirement:** the pipeline must stop treating a plan as “one output string”; it must treat the plan as “a structured set of file ops.” + +#### B. Force a structured LLM output contract (JSON-first) + +To get multi-file reliably, require the execution actor (or a dedicated “renderer” actor) to output **strict JSON** that conforms to a schema, for example: + +```json +{ + "changes": [ + {"operation": "create", "path": "src/main.py", "content": "..."}, + {"operation": "create", "path": "src/routes/users.py", "content": "..."}, + {"operation": "modify", "path": "README.md", "patch": "...unified diff..."} + ], + "notes": ["Run tests: pytest", "Add env var: DATABASE_URL"] +} +``` + +Implementation details: + +* Define a JSON schema (or Pydantic model) and validate strictly. +* If invalid JSON: + + * run an automatic “repair” step (LLM or deterministic fixer), + * if still invalid, fail the phase with a clear error and keep artifacts for review (don’t write junk into files). + +**Why JSON-first matters:** the current “strip only the outer fences” behavior is not enough and will always regress into “explanations in code.” + +#### C. Provide a fallback parser (markdown/code-fence tolerant) but never “raw dump” + +Even with JSON-first, a fallback parser is practical. But the fallback must produce the same `ChangeSet` structure. + +A robust fallback should: + +* Parse multiple fenced blocks +* Detect per-block file paths from: + + * headings like `### path/to/file.py` + * inline hints like `// file: ...` + * or an explicit preamble list +* Reject/strip explanatory prose **unless** it is explicitly routed to a non-code artifact (e.g., `notes.md` or `PLAN.md`) + +**Never again** write the entire model response into a source file. + +#### D. Implement directory creation and scaffolding rules + +Once you can create multiple files, you need deterministic rules for directories: + +* auto-create directories for new files (safe, idempotent) +* enforce project root boundaries (never escape the repo root) +* enforce ignore patterns / deny lists (e.g., don’t create inside `.git/`) + +This directly addresses the “create REST API” expectation (routes/, models/, etc.) that current code cannot meet. + +--- + +## 2) Connect the New Reactive/LangGraph Infrastructure to the Actual Plan Workflow (Hard Blocker) + +### Problem (today) + +The Jan 29 update introduced substantial new code under `src/cleveragents/langgraph/` and `src/cleveragents/reactive/` (graphs, nodes, state, RxPy routing), but the analysis states it is **not connected to the main plan generation workflow** and therefore does not fix the fundamental functional issues. + +### What “done” looks like + +* A plan’s Strategize and Execute phases run through a real graph engine (LangGraph-like execution). +* The graph actually drives: + + * context selection, + * strategy creation, + * code generation, + * validation, + * sandbox writes, + * diff production, + * apply actions. + +### High-level implementation plan + +#### A. Create a single “PlanLifecycleGraph” entrypoint + +Define a top-level orchestrator graph per plan instance: + +**Strategize subgraph** + +* gather context (read-only) +* produce strategy (machine-usable blueprint + narrative) +* produce an “execution plan” (tasks/subplans) + +**Execute subgraph** + +* allocate sandbox +* execute tasks (spawn subplans where needed) +* produce `ChangeSet` + artifacts + logs +* run validation gates +* produce diff view summary + +**Apply subgraph** + +* apply changes transactionally +* record audit log + final state + +#### B. Replace (or wrap) the current “tell/build/apply/file” pipeline + +Maintain backward compatibility at the CLI layer (for now), but internally: + +* `tell` creates/updates an Action (or a plan request) +* `build` maps to Strategize + Execute +* `apply` maps to Apply + +The key is to stop having “build” be “one LLM call that returns one file.” + +#### C. Make the new reactive routing optional—not mandatory + +The reactive router (RxPy streams) is powerful, but don’t make it the required execution substrate until it’s stable and secure (see security section below). Use it as: + +* an experimental routing layer, +* or a message bus, +* or a future optimization for streaming UX. + +But the “plan must work” path should be stable with deterministic orchestration. + +--- + +## 3) Implement Real Sandbox + Diff Review + Transactional Apply (Hard Blocker) + +### Problem (today) + +The analysis notes that apply currently writes files directly and can leave the codebase inconsistent on partial failures; diff preview is missing or insufficient; rollback is not robust. + +### What “done” looks like (v3 expectation) + +* Execute never mutates the real project directly. +* All changes happen in a sandbox. +* User (or automation policy) reviews diffs. +* Apply commits changes **atomically** (all-or-nothing) to real project resources. + +### High-level implementation plan + +#### A. Standardize sandbox backends (choose one as default per project type) + +For code repos, default should usually be **git-based**: + +* git worktree or temporary branch +* sandbox has its own working directory +* diff is native git diff + +For non-git projects: + +* filesystem copy or overlay sandbox + +Each project declares: + +* preferred sandbox backend +* whether sandbox is mandatory + +#### B. Apply must be transactional + +Transactional apply means: + +* if any step fails (permission error, merge conflict, write failure), the system: + + * aborts apply, + * reverts partial writes, + * preserves sandbox for inspection, + * provides a resumable/retry path. + +Implementation details: + +* In git mode: apply is a merge/cherry-pick of sandbox commits (atomic-ish). +* In filesystem mode: write to temp files, then rename swap, then finalize (atomic within filesystem constraints). + +#### C. Diff review must become a first-class artifact + +A plan should store: + +* file list changed +* per-file diff +* summary (what changed + why) +* “risk markers” (e.g., touched auth code, migrations, infra) + +This is a core differentiator and must be polished because it is the human safety boundary. + +--- + +## 4) Build the “Checkpointable Skills” Layer (Hard Blocker for Reliable Autonomy) + +### Problem (today) + +The system lacks robust rollback, and the analysis emphasizes the need for checkpoints to avoid partial failures and inconsistent states. The meeting notes also highlight the intent to build checkpointable skills because MCP metadata is insufficient for write scope and rollback guarantees. + +### What “done” looks like + +* Skills declare whether they are checkpointable. +* The execution engine can: + + * create a checkpoint ID, + * perform actions, + * roll back to checkpoint. + +### High-level implementation plan + +#### A. Define a checkpoint contract at the skill interface level + +Every skill should optionally support: + +* `checkpoint() -> CheckpointId` +* `rollback(checkpoint_id) -> None` +* `describe_effects(call) -> ResourceEffects` (what it read/wrote) + +Not every skill can implement rollback. But for “write” skills you rely on, you need either: + +* skill-level rollback, or +* containment (sandbox) + external rollback (git reset, snapshot restore). + +#### B. Implement checkpointable “core skills” first + +Start with: + +* file skill (write with pre-write snapshots) +* git skill (commit/stash checkpoints) +* shell skill inside sandbox container (filesystem snapshot or git-backed) + +This provides enough reliability to support multi-step Execute. + +#### C. Add a skill metadata registry (even if MCP is used) + +The system needs to know: + +* read-only vs write +* write scope (paths/resources) +* idempotency +* checkpointability +* side effects + +The meeting notes explicitly call out that MCP doesn’t provide enough writing-scope metadata for safe automation; v3 needs an internal extension/registry. + +--- + +## 5) Expand Context Beyond “300 chars × 5 files” and Make It Actor-Aware (Hard Blocker for Real Code Understanding) + +### Problem (today) + +The analysis states the context system is effectively a placeholder: + +* only a small preview of a few files, +* no robust repo understanding, +* inadequate for realistic tasks. + +### What “done” looks like + +* The system can ingest and reason over large repos via indexing and retrieval. +* Context is not a single global blob; it is **assembled per actor/node** based on role and task. +* Users can pin/force include critical resources. + +### High-level implementation plan + +#### A. Implement repo indexing + retrieval + +Minimum viable: + +* file tree + language detection +* full-text search +* embedding index (optional but recommended) +* ignore patterns applied consistently + +#### B. Adopt the tiered context architecture (hot/warm/cold) + +As described in the meeting notes: + +* hot cache = prompt-injected snippets +* warm = indexes/embeddings/graph storage +* cold = historical artifacts, summaries, prior plan outputs + +Then implement automatic promote/demote. + +#### C. Add “Actor Context Views” + +Actors require tailored views: + +* strategist sees architecture docs, READMEs, module boundaries, dependency graphs +* executor sees precise code sections relevant to edits +* reviewer sees diffs + tests + risk zones + +This actor-aware context view system is explicitly described as missing today and a planned improvement. + +--- + +## 6) Fix Provider/LLM Plumbing So It Cannot Fail Silently (Hard Blocker) + +### Problem (today) + +The analysis identifies multiple provider-level failures: + +* defaulting to a FakeListLLM that returns hardcoded strings, +* returning `None` provider silently, +* hardcoding auto-debug to OpenAI GPT-4 regardless of configuration, +* OpenRouter listed but not implemented. + +### What “done” looks like + +* If no provider is configured, the user gets a clear, actionable error. +* Auto-debug uses the configured actor/provider. +* Providers are discoverable, consistent, and testable. + +### High-level implementation plan + +#### A. Remove FakeListLLM as default behavior + +* Keep FakeListLLM **only** for tests. +* In production, enforce: “no provider configured → fail fast with clear message.” + +#### B. Make provider selection actor-driven end-to-end + +Actor config should determine: + +* provider +* model +* tool access +* safety settings + +Auto-debug should be: + +* a plan/action using an actor, not a hard-coded special-case. + +#### C. Implement “provider auto-support” strategy + +To avoid manual churn: + +* derive supported providers from LangChain/LangGraph provider availability +* or implement a provider adapter registry that can load provider plugins dynamically + +--- + +## 7) Replace Stubbed Validation With Real Validation Gates (Hard Blocker for Quality) + +### Problem (today) + +Validation is currently a stub (“PASS” or output length > 10). This guarantees that broken outputs will be considered valid. + +### What “done” looks like + +Validation in Execute must include: + +* syntax checks +* lint/format checks (optional) +* unit tests (when available) +* build checks (typecheck, compile) +* security sanity checks (optional) +* schema validation for structured outputs + +### High-level implementation plan + +Create a `ValidationPipeline` that can run per project type: + +**Python project** + +* `python -m py_compile` for changed files +* `ruff` / `black` (optional) +* `pytest` (optional) + +**Node project** + +* `npm test`, `tsc`, etc. + +**Infra** + +* `terraform validate`, etc. + +Then enforce: + +* Execute phase cannot complete if validation fails (unless user overrides explicitly). + +Also fix the “invalid python docstring wrap” behavior: + +* invalid output should trigger a repair loop or be quarantined as an artifact, +* not silently converted into useless code. + +--- + +## 8) Make Apply/Execute Safe Under Failure, Concurrency, and Resume (Stability Blockers) + +### Problems (today) + +The analysis calls out: + +* partial failure leaves repo inconsistent, +* no concurrency protection (two builds can race), +* no resume/progress persistence, +* missing cleanup for abandoned plans. + +### What “done” looks like + +* Plans can be resumed after interruption. +* Plan execution is locked per project/sandbox to avoid races. +* Abandoned sandboxes are cleaned up safely. +* The system can report progress reliably. + +### High-level implementation plan + +* Add a plan lock (DB row lock or filesystem lock). +* Persist step-level progress events. +* Implement resumable execution by checkpoint: + + * “resume from checkpoint X” or “resume from step Y” +* Add lifecycle cleanup jobs: + + * garbage collect old sandboxes + * expire old checkpoint files (see also new LangGraph checkpoint file leak) + +--- + +## 9) Address Critical Security Issues Introduced by New Reactive Code (Security Blocker) + +### Problems (today) + +The analysis reports a **critical `eval()` vulnerability** in stream routing configuration (remote code execution vector), plus additional concerns: + +* silent exception swallowing, +* event loop leaks, +* thread safety issues, +* template injection risks. + +### What “done” looks like + +* No configuration-driven arbitrary code execution (no eval). +* Errors are surfaced, not swallowed. +* Long-running systems do not leak tasks/subscriptions/checkpoint files. +* Template rendering is safe. + +### High-level implementation plan + +#### A. Remove `eval()` from any config parsing path + +Replace with one of: + +* a whitelist of allowed transform operators +* a small safe expression language (parsed, not executed) +* “transform” must reference a named function from a registry, not arbitrary text + +#### B. Stop swallowing exceptions + +In routing/execution: + +* capture exception +* attach it to message metadata +* fail the stream/plan with clear error state + +#### C. Fix async lifecycle correctness + +* do not create new event loops without closing +* prefer `asyncio.run` or properly managed loop policy in one place +* ensure Rx subscriptions are disposed on shutdown and on stream reconfiguration + +#### D. Replace `str.format` templating with a safe template engine + +If templating is needed, use a sandboxed template engine or restrict tokens severely. + +--- + +## 10) Finish the “Plan System” (Actions, Strategize, Execute, Apply) in Storage + CLI + UI + +### Problem (today) + +The analysis describes the current master as still conceptually the linear tell/build/apply pipeline. Meanwhile, intended v3 introduces reusable Actions decoupled from Projects, and separate Strategize/Execute/Apply phases with automation levels. + +### What “done” looks like + +* Actions exist as reusable templates. +* Using an Action creates a plan in Strategize. +* Execute operates on a sandbox. +* Apply commits. +* Plan tree / decision tree is recorded. + +### High-level implementation plan + +#### A. Data model changes + +Add/ensure tables for: + +* `actions` (templates) +* `plans` (instances with phase + state) +* `plan_steps` or `plan_nodes` (for decision tree/subplans) +* `plan_artifacts` +* `plan_events` (structured log) + +#### B. CLI changes + +Implement commands aligned to the lifecycle: + +* `agents create action ...` +* `agents use --project

` +* `agents execute ` +* `agents apply ` + +Keep aliases for old commands for usability, but map them internally. + +#### C. TUI changes (once data exists) + +* show plan tree (ASCII first) +* show phase transitions and states +* show diffs in Execute output +* show approvals for Apply + +This is explicitly a near-term intended UX: visual decision tree + correction ability. + +--- + +## 11) Actor System Completion: Make Actors Actually Define Behavior (Not Just Model Selection) + +### Problem (today) + +Meeting notes and analysis agree that actor CRUD exists or is being ported, but key pieces are missing: + +* graph descriptor not used, +* no per-actor tool access policies, +* no per-actor memory, +* no actor-defined orchestration behavior in practice. + +### What “done” looks like + +An actor should be able to define: + +* model/provider, +* system prompt, +* tool/skill access policy, +* memory policy, +* graph descriptor (if actor is a composite workflow), +* context view policy. + +### High-level implementation plan + +* Treat actor config as the single source of truth for behavior. +* If `graph_descriptor` exists: + + * instantiate a LangGraph runtime graph using it, + * nodes may reference other actors or skills. +* Add a policy layer: + + * this actor can only call read-only skills in Strategize, + * this actor can call write skills in Execute only within sandbox. + +--- + +## 12) Persistence + DB Hygiene (Stability Blocker) + +### Problems (today) + +The analysis lists: + +* database directory creation issues (first run failures), +* missing/messy migrations, +* global mutable provider registry state causing test/config/thread issues, +* memory service defaults to in-memory and loses history. + +### High-level implementation plan + +* Ensure `.cleveragents/` created before DB use. +* Require migrations to exist and be applied (Alembic). +* Remove global registry singletons; make DI container own state. +* Make session memory persistent by default (SQLite is acceptable). +* Store session IDs in DB; never “generate and forget.” + +--- + +## 13) Cost Controls, Rate Limits, and Provider Fallback (Production Readiness) + +### Problem (today) + +The analysis notes there are no cost/rate controls, and the meeting notes acknowledge this is required for practical full automation. + +### High-level implementation plan + +* Track token usage per: + + * plan, + * phase, + * actor, + * session, + * org (future server mode) +* Add configurable budgets and caps: + + * max cost per plan + * max calls per minute + * max retries per node +* Implement provider fallback policy: + + * if provider A fails transiently, retry or fail over to provider B + * preserve determinism where required (e.g., pin for Apply reviews) + +--- + +## 14) Server / Multi-User Readiness (Not Required for Local MVP, But Must Be Designed In) + +### Problem (today) + +The meeting notes say multi-user prompt injection and governance are less relevant for single-user local mode, but become critical for server mode. + +### High-level implementation plan + +* Add permissions at: + + * namespace level (org actions) + * project level (apply rights) + * skill level (dangerous operations) +* Add audit logs for Apply. +* Add prompt-safety hardening: + + * treat user input as data, not instruction overrides + * strict templating and role separation +* Separate “execution happens locally” from “coordination happens on server” (optional architecture). + +--- + +## Suggested Build Order (So You Don’t Get Stuck) + +If you want a pragmatic sequencing that preserves momentum and prevents rewrites: + +1. **Multi-file ChangeSet + structured output parsing** (unblocks everything) +2. **Sandbox + diff + transactional apply** +3. **Wire new graph engine into plan workflow** +4. **Checkpointable skills + rollback** +5. **Real validation pipeline** +6. **Context indexing + actor context views** +7. **Provider + memory persistence fixes** +8. **Security hardening of reactive/router code** +9. **TUI plan tree + correction UX** +10. **Cost controls + server-mode foundations** + +This ordering matches the reality that without multi-file output and safe apply, higher-level orchestration and context improvements won’t matter—the system still can’t “do the work” safely. + +--- + +## Acceptance Criteria for “Fully Functional” (Concrete) + +A realistic “fully functional” bar (aligned to intended v3 behavior) is: + +* Can **strategize** read-only using real context across many files. +* Can **execute** in sandbox, producing a multi-file ChangeSet for non-trivial features. +* Can run **validation** and fail safely without corrupting project state. +* Can show a **diff review** and apply atomically. +* Can **roll back** to a checkpoint during Execute (at least for file/git/shell-in-sandbox). +* Can run multi-project plans without mixing resources. +* Does not silently fall back to fake providers or swallow errors. +* Has no config-driven RCE paths (no eval). +* Has persistent session/memory so iterative CLI use works. + +Everything listed earlier maps directly to closing the gaps documented in the attached analysis and to achieving the behaviors described in the transcript.