Core concepts
Team, Project, Plan and Spec: the four words every other page in these docs uses.
Four containers, nested. Everything else in Plansmith hangs off them.
Team
Your workspace. People, billing, and the conventions everyone shares.
Project
A product or a body of work. Holds plans, and the issue tracker they push to.
Plan
One piece of work being planned. The unit you converse with and push.
Spec
A single dev-ready item, with its acceptance criteria. Where Plansmith stops.
Plans and Specs both nest
A Plan can contain sub-plans, to any depth. A Spec can contain child Specs. Both can also depend on each other: "this needs that first".
That gives you two ways to break work down, and choosing between them is the one structural decision worth understanding. It comes down to Context, and it has its own page: Sub-plans and dependencies.
A Spec is the smallest unit
Every Spec has a title, a body, and numbered acceptance criteria, the checklist that says what done means. It also carries two judgements the agent makes and you can correct:
| What it means | How it reads | |
|---|---|---|
| Readiness | How build-ready this Spec is right now | Rough · Shaping · Ready |
| Effort | Rough size, for ordering and planning | Low · Med · High |
Readiness is the more useful of the two. A plan full of Rough Specs is a plan that needs another conversation, and the agent will tell you which ones and why.
Context sits alongside
Context is the material the agent reads: documents you attach, and code repositories you connect. It attaches at Team, Project or Plan level and flows downward, so a Plan sees its own sources plus everything above it.
Context is deliberately not attached to a Spec. If a piece of work needs its own sources, that is the signal it should be a sub-plan.