Start from an existing codebase
Build a first spec of a system that already runs: an agent reads the code and stages contexts, aggregates and use cases, then you accept and publish them.
Starting from code is the common case. The spec does not need to be complete to be useful: start with the parts you are about to change.
Plan the first pass
- One workstream for the first pass, for example Initial model. Everything the agent stages lands there, never on Main, until a task publishes it.
- Outside in. Subdomains and bounded contexts first, with their context map, then what lives inside the contexts you work on now (domain model, behaviour, interfaces), then the product side (features, roles and the glossary), and the decisions and constraints the code already follows.
- Small stagings. One context and its artefacts per call, so each review stays short.
Let the agent read the code
Connect your agent (Agents and MCP) with Read and write access to the project, then give it the order of work. A prompt that works:
Use the specsgraph MCP server, project shop, workstream WS-1.
Read spec_schema first. From the code in this repository, stage
the bounded contexts with a one-line summary each, then for the
Orders context its aggregates (properties, invariants, domain
events) and its command and query use cases. Stage one context
per spec_apply call and tell me what you could not infer.The agent writes YAML documents in spec format 1 (spec_schema), one per artefact, and stages them with spec_apply. References between documents of one call are resolved in order, so a context and its aggregates can be staged together.
Review what the agent staged
Open Proposals. Each staged revision shows its document and, for an artefact the workstream already has, a diff. Accept what reads right, comment where the model is wrong (the agent reads threads with thread_list) and withdraw what does not belong. Accept all accepts every pending revision you filtered, in dependency order. The agent can group its staging into plans, one per task; Accept group accepts a plan and scopes it into its task in one step. See Proposals, plans and review.
A spec drawn from code describes what the system does today, bugs included. Review it with that in mind:
- Ask for sources. Have the agent name the files and tests behind each artefact, in its summary or in reply to your threads.
- Ask what it inferred. Anything it guessed rather than read deserves a closer look.
- Do not accept a rule nobody can confirm. Leave a thread on the artefact until someone can.
Publish the baseline
Scope the accepted changes into a task (Changes, then Add to task), mark it Ready and publish. The YAML files land in the spec folder of your repository; from then on Main is the baseline every workstream starts from. See Tasks and publishing.
The code for that baseline already exists, so tell SpecsGraph: on the Build page, select the artefacts the code implements and choose Mark as implemented, with a note. Only a person can do this. From then on the build status shows them as Implemented (baseline), and an edit on Main shows them as Outdated until the code follows. If the first task got work items you do not need, drop them.
Keep it current
- Open a workstream per story or change request (one per epic when stories share new artefacts).
- Ask the agent to read the workstream (scope
workstream:WS-n) while the spec is in flight, and Main for what shipped. - Questions for people go in threads on the artefact; an agent asks a question with options using
thread_askand can mark it blocking.
Next steps
- The spec and its kinds: what each of the 16 kinds holds.
- Proposals, plans and review: how staged changes are accepted.
- Tasks and publishing: from Ready to Main.