Skip to content

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

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:

PromptText
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_ask and can mark it blocking.

Next steps