Concepts¶
Page status: release-ready Source state: shipped-source Applies to: Shepherd v0.2.0 Owner: @docs-system-owner (TBD) Validation: scripts/check_shepherd_docs.py
Concept. The mental model behind Shepherd. Steps live in the quickstart, signatures in the reference.
This section is the mental-model layer of the Shepherd docs. Five ideas carry the shipped framework; each gets one page, and the pages keep linking to each other because the ideas genuinely interlock. Steps live in the quickstart, exact signatures live in the reference, why the framework is shaped this way lives here.
The five ideas¶
| Page | The idea in one line |
|---|---|
| Tasks | A task is a typed function used as a contract; the signature carries the meaning, including its permissions. |
| Effects | Everything a task does to the world crosses one explicit, typed, recorded channel. |
| Runs | Every execution leaves a durable record; debugging is reading that record, not guessing. |
| Permissions | Per-repository grants declared on the signature; the signature is the permission surface. |
| Placements | Where a run's body executes — and therefore whether its grants are OS-enforced or advisory. |
How they interlock: a task declares what should happen and what it may touch; a retained run executes it and records everything; the record is populated by the effects that crossed the boundary; permissions bound those effects, and the placement decides how that bound is enforced.
Two former pillar pages — Workspaces and Providers — taught the ambient model-call surface, which has not shipped; they return when it does. Where that surface sits on the road is mapped on Settlement Core / Dataflow.
If you came here to build¶
You do not need this section to ship your first run — the quickstart gets you to working code without it. Come back when something surprises you, and enter through the question that brought you:
- "Why did editing a docstring change behavior?" → Tasks
- "What did that run actually do?" → Runs
- "Who was allowed to write what, and who enforced it?" → Permissions and Placements
- "What crossed the boundary along the way?" → Effects
Each page is written to stand alone; cross-links fill whatever gaps remain.
If you came here to evaluate¶
Read tasks, runs, permissions, and placements in that order — the unit of work, its record, its authority, and its enforcement — then effects for the channel underneath. For what is deliberately not claimed yet (ambient model service, returned handles, task-as-value delegation), read Settlement Core / Dataflow.