Concepts¶
Page status: release-ready Source state: shipped-source Applies to: Shepherd v1.0-dev Owner: @docs-system-owner (TBD) Validation: scripts/check_shepherd_docs.py
Concept. The mental model behind Shepherd. Steps live in the tutorial, signatures in the reference.
This section is the mental-model layer of the Shepherd docs. Four ideas carry the whole framework; each gets one page, and the pages keep linking to each other because the ideas genuinely interlock. Steps live in the tutorial, exact signatures live in the reference, why the framework is shaped this way lives here.
The four ideas¶
| Page | The idea in one line |
|---|---|
| Tasks | A task is a typed function whose body the model fills in; the signature is the contract. |
| Effects | Everything a task does to the world crosses one explicit, typed, interceptable channel. |
| Runs | Every execution leaves a durable record; debugging is reading that record, not guessing. |
| Workspaces | Context, model, root, shared objects, is ambient but explicit: a scope, not a global. |
How they interlock: a task declares what should happen; a workspace supplies the situation it happens in; calling the task produces a run; and the run's trace is populated by the effects that crossed the boundary along the way. Pull any one of the four out and the other three stop making sense, which is why the reading order below matters less than it looks.
Beyond the four pillars, Providers goes deeper on the model backend a workspace binds.
If you came here to build¶
You do not need this section to ship your first feature, the first Shepherd app tutorial 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
- "Who answered that request, and who else saw it?" → Effects
- "What did that call actually do?" → Runs
- "Where did the model and that binding come from?" → Workspaces
Each page is written to stand alone; cross-links fill whatever gaps remain.
If you came here to evaluate¶
Read the four pages in order, tasks, effects, runs, workspaces. They build outward from the unit of work to its channel, its record, and its context.
The public concept set deliberately stops at the surface these docs exercise: tasks, effects, runs, workspaces, and provider selection. Permission policy, placements, workflow packaging, and live-provider operations stay out of the public build until their product surfaces land.