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.
Open questions keep the plan moving
Planning runs into questions only your team can answer: which rule applies, who is allowed to do this, what happens to the data already there. Those do not have to stop anything.
Save one as an open question and it lands in the spec's Open Questions section with a handle
(OQ1, OQ2, …). The plan carries on around it. You can save a question the agent asks you
instead of answering it, raise one yourself, or let a readiness review add the ones it found.
This works before the plan is written, too. The agent asks its sharpest questions early, when there
is no document to file onto yet. Keep one there and it travels with your answers, so the plan the
agent writes arrives with your question already in its Open Questions.
Every open question can be answered from the document it lives on. "Answer in chat" puts it to you in the conversation, where the agent can explain it and record what you say; the menu beside it can also mark a question answered, mark it as not applicable, or delete one that was noise.
An answered question moves to the Decision Log with who answered it, the date, and the answer. That log is the plan's decision trace: months later it says what was decided and by whom, and it travels with the spec when you push to your issue tracker.
A spec with open questions holds at Shaping, never Ready. Answering the last one returns it to
its own score. Tag a teammate with @ when a question is theirs to answer and they get an email
with the question and a link. Point the agent at a context file instead ("@discovery-call has
the answer") and it reads that document, takes the answer out, and records where it came from.
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 context files plus everything above it.
Context is deliberately not attached to a Spec. If a piece of work needs its own context files, that is the signal it should be a sub-plan.