Skip to content

Core concepts

Definitions of the SpecsGraph building blocks: workspaces, projects, bounded contexts, requirements, scenarios, proposals, revisions and access tokens.

These are the building blocks of SpecsGraph and the words these docs use for them. Each one links to the page that covers it in depth. Examples come from the Northwind Commerce sample workspace. Your team's own domain vocabulary, such as Reservation, lives in your project's domain glossary instead.

How the pieces nest

The model is a hierarchy. A workspace holds projects, a project holds the contexts of one system, and requirements with their scenarios sit at the bottom:

Containment hierarchyText
Workspace          Northwind Commerce
  Project          Shop
    Context        Orders (key ORD, core subdomain)
      Service      Checkout
        Requirement  ORD-12  Reserve stock for every line item at checkout
          Scenario   Checkout stops when a line item cannot be reserved

Some things link across the hierarchy rather than sitting inside it. Glossary terms, actors and relationships connect contexts to each other. Proposals, decisions and workstreams point at any nodes they touch.

The model

ConceptWhat it isRead more
WorkspaceThe top level. It holds members, roles, the GitHub connection and one or more projects. Example: Northwind Commerce.Workspaces and projects
ProjectThe model of one system, connected to the repository it publishes to.Workspaces and projects
System graphEvery node in a project and the links between them. You zoom from contexts to services to single requirements.The system graph
ContextA bounded context: a part of the system with its own model and vocabulary, such as Orders or Billing. Its key (ORD) prefixes requirement IDs.Bounded contexts and subdomains
SubdomainThe kind of business area a context serves: core, supporting or generic. SpecsGraph records it as a field on each context, not as a node of its own. Orders is core; Identity is generic.Bounded contexts and subdomains
ServiceA deployable unit or module inside a context, such as Checkout inside Orders. It also groups related requirements.The system graph
RequirementA single statement of what the system must do, with an ID made of the context key and a number: ORD-12, ORD-13, BIL-04. Each requirement is published as one Gherkin feature.Requirements and scenarios
ScenarioAn acceptance example for a requirement, written as Given, When, Then.Requirements and scenarios
ActorA person, external system or agent that interacts with the system: a Customer, a Payment provider, a Warehouse picker.Actors
Glossary termA word from your domain with one agreed definition, such as Reservation, linked everywhere the model uses it.Domain glossary
RelationshipA typed link between two contexts that says which one depends on the other and how, for example Orders upstream of Fulfilment.Context relationships

Change and collaboration

ConceptWhat it isRead more
ProposalA set of changes to the graph waiting for review, drafted by an agent or a person. Each has a status and a branch name, such as spec/checkout-reserve.Proposals and reviews
Review threadA discussion attached to one node in a proposal, where reviewers question the change and the author, person or agent, answers.Proposals and reviews
DecisionA record of why a change was made, linked to the proposal and requirements it explains.Decision log
WorkstreamA track of related work with a number such as WS-3, bundling tasks and the proposals that serve them.Workstreams
TaskOne unit of work inside a workstream, with a status that people and agents update.Workstreams
RevisionA published version of the model. Every revision is a Git commit you can diff and review; you roll one back by restoring an earlier version through a proposal.History and versions

Access and output

ConceptWhat it isRead more
Personal access tokenA secret starting with sgp_ that lets an agent act for you over MCP. It never lets the agent do more than you can.Personal access tokens
Spec folderThe specsgraph/ folder SpecsGraph writes into your repository: Markdown for people and graph.json for tools.Spec files in your repository

Other terms

TermWhat it meansRead more
Requirement stateProposed while a requirement exists only in an unpublished proposal, Active once published, Retired once removed from the current spec. Separate from proposal statuses.Requirements and scenarios
Owning teamThe team named on a context as responsible for it, so reviewers know who should look at a change there.Bounded contexts and subdomains
LinkA connection from a requirement to the terms, actors, decisions and other requirements it depends on.Context relationships
Base branchThe branch proposal branches start from and pull requests target. It defaults to the repository's default branch.Workspaces and projects
Publish modePull request (the default) or Direct commit: how an approved proposal reaches the base branch.Branches and pull requests
Token access and projectsWhat a token may do: read only, or read and write, limited to the projects you select.Personal access tokens
Token policyWorkspace rules for tokens, such as the longest expiry members may choose.Personal access tokens
Archived projectA read-only project whose graph and history stay readable. SpecsGraph stops publishing to its repository.Workspaces and projects
Shared termA glossary term that means the same thing in every context, such as Customer.Domain glossary
Alias to avoidA word the team agreed not to use for a glossary term, such as basket for Cart.Domain glossary
Superseded decisionA decision a later one replaced. It stays in the log unchanged, with a link to its replacement.Decision log

IDs and names

  • Requirements join the context key and a number, assigned as described in Requirement IDs. ORD-12 is a requirement in Orders; its ID stays the same when its text changes.
  • Workstreams use the WS- prefix, as in WS-3.
  • Proposal branches use the spec/ prefix, as in spec/checkout-reserve.
  • Decisions are numbered in the order they are recorded, and the file name carries a short title, as in 0007-reserve-stock-before-payment.md.

Next steps