# v3.0.0 — Action, Resource, Project & Plan CLI Reference

Complete command documentation for all CleverAgents v3.0.0 CLI commands.

---

## Action Management (`agents action`)

Actions are reusable plan templates defined in YAML. They specify which actors
handle each phase of the plan lifecycle and what arguments the plan accepts.

### `agents action create`

```bash
agents action create --config ./my-action.yaml
```

**Minimal action YAML:**

```yaml
name: local/code-coverage
description: Increase code coverage to the target percentage
strategy_actor: openai/gpt-4
execution_actor: openai/gpt-4
definition_of_done: |
  Line coverage reaches the target percentage for all modules under src/.
arguments:
  - name: target_coverage
    type: integer
    required: true
```

**Full action YAML:**

```yaml
name: local/refactor
description: Refactor a module to follow SOLID principles
strategy_actor: openai/gpt-4
execution_actor: anthropic/claude-3
estimation_actor: openai/gpt-4
invariant_actor: anthropic/claude-3
automation_profile: trusted
definition_of_done: |
  All classes follow Single Responsibility Principle.
  No method exceeds 20 lines.
invariants:
  - "No reduction in test coverage"
  - "All public APIs remain backward compatible"
arguments:
  - name: module_path
    type: string
    required: true
```

### `agents action list` / `show` / `archive`

```bash
agents action list                              # all actions
agents action list --namespace local            # filter by namespace
agents action list --state available            # filter by state
agents action show local/code-coverage          # show action details
agents action archive local/old-action          # soft-delete action
```

---

## Resource Management (`agents resource`)

Resources are external entities (git repos, directories, mounts) that plans
can read or modify.

### `agents resource add`

```bash
agents resource add git-checkout local/my-repo --path /home/user/projects/my-repo
agents resource add fs-directory local/data  --path /data --read-only
```

**Built-in resource types (v3.0.0):** `git-checkout`, `fs-directory`, `fs-mount`

### `agents resource list` / `show` / `remove`

```bash
agents resource list                            # all resources
agents resource show local/my-repo              # resource details
agents resource remove --yes local/my-repo      # remove resource
```

---

## Project Management (`agents project`)

Projects group resources together for plan execution context.

### `agents project create` / `link-resource` / `list` / `show`

```bash
agents project create local/my-project   --description "My application"
agents project link-resource local/my-project local/my-repo
agents project list
agents project show local/my-project
```

---

## Plan Lifecycle (`agents plan`)

Plans are the central execution unit. Lifecycle: **Strategize -> Execute -> Apply**.

### `agents plan use` — Create a plan

```bash
agents plan use local/code-coverage my-project --arg target_coverage=80
agents plan use local/lint proj-1 proj-2                        # multiple projects
agents plan use local/refactor my-project \                     # with automation profile & invariants
  --automation-profile trusted   --invariant "No new warnings"
agents plan use local/code-coverage my-project \                # with actor overrides
  --strategy-actor openai/gpt-4   --execution-actor anthropic/claude-3
```

### `agents plan execute` / `diff` / `apply` — Run and merge changes

```bash
agents plan execute                       # Strategize -> Execute phases
agents plan diff 01HXYZ...                # preview proposed changes
agents plan apply --yes                   # merge changes (skip confirmation)
```

### `agents plan list` / `status` / `cancel` — Manage plans

```bash
agents plan list --state complete         # filter plans
agents plan status 01HXYZ...              # plan details
agents plan cancel 01HXYZ... --reason "Requirements changed"
```

---

## See Also

- [CLI overview (v3.0.0)](index.md) — Goals, architecture notes, feature table
- [Deep Dive](deep-dive.md) — Sandbox, persistence, domain model internals