# 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.

<Cards>
  <Card title="Team">
    Your workspace. People, billing, and the conventions everyone shares.
  </Card>

  <Card title="Project">
    A product or a body of work. Holds plans, and the issue tracker they push to.
  </Card>

  <Card title="Plan">
    One piece of work being planned. The unit you converse with and push.
  </Card>

  <Card title="Spec">
    A single dev-ready item, with its acceptance criteria. Where Plansmith stops.
  </Card>
</Cards>

## Plans and Specs both nest [#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](/docs/sub-plans-and-dependencies).

## A Spec is the smallest unit [#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-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.

<Cards>
  <Card title="Context sources" href="/docs/context-sources">
    What to attach, at which level, and how inheritance works.
  </Card>

  <Card title="Sub-plans and dependencies" href="/docs/sub-plans-and-dependencies">
    When to nest a plan instead of adding another Spec.
  </Card>
</Cards>