# v3.1.0 — Quick Start Guide

Common workflows: actor definitions, MCP setup, skills, & validation gates.

---

## Step-by-Step Workflow

```bash
# 1. Define a graph actor YAML
cat > actors/tdd.yaml << 'EOF'
version: "3"
name: assistants/tdd
type: graph
model: gpt-4
route:
  nodes:
    - id: planner; type: agent; name: Planner
      config: { model: gpt-4, prompt: "Plan tasks from requirements." }
    - id: implementer; type: agent; name: Implementer
      config: { model: gpt-4, prompt: "Write clean tested code." }
  edges: [{from_node: planner, to_node: implementer}]
  entry_node: planner
  exit_nodes: [implementer]
EOF

# 2. Create an action using the actor
cat > review-action.yaml << 'EOF'
name: local/code-review
description: Review code changes
execution_actor: assistants/tdd
definition_of_done: |
  All changes reviewed for correctness and style.
EOF
agents action create --config review-action.yaml

# 3. Configure MCP tool server in ~/.cleveragents/config.toml

# 4. Register a skill
agents skill add --config my-skill.yaml

# 5. Execute plan with validation gate
agents plan use local/code-review my-project
agents plan execute                    # runs validation before apply
agents plan diff
agents plan apply --yes               # blocked if required validations fail
```

---

## Actor Creation Checklist

- [ ] `version: "3"` specified
- [ ] Valid type: `llm`, `tool`, or `graph`
- [ ] Name follows `namespace/name` format
- [ ] All referenced actors and tools are resolvable
- [ ] Graph actors have valid entry/exit nodes and acyclic edges

---

## Skill & Validation Quick Tips

- Skills can include other skills for composition
- Agent Skills Standard discovers skills from filesystem paths in `agent_skills_paths`
- Validations run deterministically: alphabetical (resource, mode, name) order
- Run with `max_workers=1` in CI for predictable sequential validation
