# `Agentic.Persistence.Plan`

Behaviour for CRUD operations on structured plans with step-level status tracking.

The `:local` implementation stores JSON files at
`<workspace>/.agentic/plans/<plan_id>.json`.

# `plan_struct`

```elixir
@type plan_struct() :: %{id: String.t(), goal: String.t(), steps: [step_struct()]}
```

# `plan_summary`

```elixir
@type plan_summary() :: %{
  id: String.t(),
  goal: String.t(),
  step_count: non_neg_integer(),
  completed_count: non_neg_integer()
}
```

# `step_struct`

```elixir
@type step_struct() :: %{
  index: non_neg_integer(),
  description: String.t(),
  tools: [String.t()],
  verification: String.t(),
  status: :pending | :in_progress | :complete | :failed
}
```

# `create`

```elixir
@callback create(plan :: plan_struct(), opts :: keyword()) ::
  {:ok, plan_struct()} | {:error, term()}
```

# `get`

```elixir
@callback get(plan_id :: String.t(), opts :: keyword()) ::
  {:ok, plan_struct()} | {:error, :not_found}
```

# `list_plans`

```elixir
@callback list_plans(workspace :: String.t(), opts :: keyword()) ::
  {:ok, [plan_summary()]} | {:error, term()}
```

# `update_step`

```elixir
@callback update_step(
  plan_id :: String.t(),
  step_index :: integer(),
  updates :: map(),
  opts :: keyword()
) :: {:ok, plan_struct()} | {:error, term()}
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*