# v3.0.0 — Minimal Local Source-Code Workflow (M1) — Overview

**Released:** v3.0.0  
**Milestone:** M1 — Minimal Local Source-Code Workflow  
**Theme:** Establish the foundational CLI, domain model, and persistence layer for local agent-driven code workflows.

---

## Overview

v3.0.0 delivers the first complete end-to-end workflow for using CleverAgents to
manage source-code changes on a local machine. It introduces the core CLI command
groups (`agents action`, `agents resource`, `agents project`, `agents plan`),
a SQLite-backed persistence layer with Alembic migrations, and a git worktree
sandbox that isolates LLM-generated changes until the user approves them.

This milestone establishes the **specification-first** development model: every
feature is driven by a YAML-defined action template, executed through a structured
plan lifecycle (Strategize -> Execute -> Apply), and persisted in a local SQLite
database.

---

## Goals

1. Provide a minimal but complete CLI for local source-code automation.
2. Introduce a typed, versioned domain model using Pydantic v2.
3. Persist all entities (actions, resources, projects, plans) in SQLite via Alembic.
4. Isolate LLM-generated changes in a git worktree sandbox before applying them.
5. Enable plan lifecycle management: create, execute, diff, and apply plans.

---

## Delivered Features

v3.0.0 delivers the following feature groups:

| Feature Group | CLI Commands | Description | Page |
|---------------|-------------|-------------|------|
| **Action Mgmt** | `agents action` | YAML plan templates | [CLI Reference](cli-reference.md) |
| **Resource Mgmt** | `agents resource` | Git repos, filesystems | [CLI Reference](cli-reference.md) |
| **Project Mgmt** | `agents project` | Group resources for plans | [CLI Reference](cli-reference.md) |
| **Plan Lifecycle** | `agents plan` | Strategy-Execute-Apply cycle | [CLI Reference](cli-reference.md) |
| **Git Worktree Sandbox** | (internal) | Isolated LLM change sandbox | [Deep Dive](deep-dive.md) |
| **SQLite Persistence** | (internal) | SQLite + Alembic with 9 tables | [Deep Dive](deep-dive.md) |
| **Pydantic v2 Domain Model** | (internal) | Frozen=True, ULID keys | [Deep Dive](deep-dive.md) |

---

## Architecture Notes

### Layered Architecture

v3.0.0 follows a strict layered architecture (see [ADR-001](../../adr/ADR-001-layered-architecture.md)):

```
CLI Layer           agents action/resource/project/plan
    |
Application Layer   PlanLifecycleService, ActionService, ResourceService
    |
Domain Layer        Action, Resource, Project, Plan (Pydantic v2, frozen=True)
    |
Infrastructure      SQLite + Alembic, GitWorktreeSandbox, ToolRegistry
```

### Dependency Injection

All services are wired via a DI container (see [ADR-003](../../adr/ADR-003-dependency-injection.md)).

### Plan Lifecycle State Machine

Plans follow a strict state machine (see [ADR-006](../../adr/ADR-006-plan-lifecycle.md)):

```
CREATED -> STRATEGIZE/queued -> STRATEGIZE/complete
        -> EXECUTE/queued -> EXECUTE/complete
        -> APPLY/queued -> APPLY/complete -> CANCELLED / ERRORED (terminal)
```

---

## See Also

- [CLI Reference](cli-reference.md) — Full command-by-command documentation
- [Deep Dive](deep-dive.md) — Sandbox, persistence, domain model internals
- [ADR-001](../../adr/ADR-001-layered-architecture.md): Layered Architecture
- [ADR-006](../../adr/ADR-006-plan-lifecycle.md): Plan Lifecycle
