Skip to content

Core concepts

The building blocks of SpecsGraph and the words these docs use: organisation, project, Main, workstream, artefact, task, proposal, work item and milestone.

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. Your team's own domain vocabulary, such as Reservation, lives in your project's domain glossary instead.

How the pieces nest

Containment hierarchyText
Organisation         Northwind
  Project            shop
    Main             the agreed spec, read-only; only a published task writes it
    Roadmap          milestones M-n, in the order to build them
    Workstream       WS-3 Reserve stock at checkout (Main plus its changes)
      Artefacts      16 kinds: bounded contexts, aggregates, use cases, features...
      Changes        artefacts whose workstream view differs from Main
      Tasks          T-4 changes agreed to ship together; published to Main and Git
        Work items   T-4.1 Implement, T-4.2 Deploy, T-4.3 Verify
      Proposal       what agents staged, waiting for a person (at most one open)
      Threads        comments and questions on artefacts

The spec

ConceptWhat it isRead more
OrganisationYour team: members, roles, teams, Git connections, token policy. Its slug is in every URL.Organisations and projects
ProjectOne spec, addressed by a short key (shop), optionally connected to one repository.Organisations and projects
MainThe agreed spec of a project. Read-only; it advances only when a task publishes.The spec and its kinds
ArtefactOne element of the spec, of one of 16 kinds. Its id never changes; every edit is a new revision.The spec and its kinds
Subdomain, bounded context, termThe business areas, the parts of the system with their own model, and the domain vocabulary.Subdomains and bounded contexts, Domain glossary
Aggregate, value object, enumThe domain model inside a bounded context.Aggregates, value objects and enums
Use case, event handler, scheduled jobWhat the system does: commands and queries, reactions to events, timed work.Use cases, event handlers and scheduled jobs
Data contract, read model, integration eventThe interfaces, what crosses a boundary: payloads, projections, published events.Data contracts, read models and integration events
Feature, roleThe product side: features with scenarios and the use cases that realise them, and who uses the system.Features and roles
Decision, constraintThe architecture records: what was chosen and why, and the qualities the system must keep.Decisions and constraints

Change and collaboration

ConceptWhat it isRead more
WorkstreamA branch of the spec for one effort, numbered WS-n per project. Active, then Completed or Abandoned.Workstreams
Current workstreamThe workstream the app opens for you in a project; Main when you have none.Workstreams
ChangeAn artefact whose view in a workstream differs from Main. Derived, never stored.Changes and conflicts
ConflictA change that overlaps what landed on Main since the workstream read it.Changes and conflicts
TaskT-n: the changes that ship together. Draft, Ready, In progress, Done or Abandoned.Tasks and publishing
Current taskYour Draft task that your direct edits in its workstream join by themselves.Tasks and publishing
Tracker keyThe key of the story in your tracker (KAN-43) on a workstream or task; it names branches and commits.Tasks and publishing
ProposalThe container of what agents staged in a workstream; a person accepts each staged revision.Proposals, plans and review
PlanA group of staged revisions an agent proposes as one task; accepted as a group.Proposals, plans and review
ThreadA comment thread on one artefact in a workstream.Threads, questions and change requests
QuestionA thread asked to a person or team, with options, optionally blocking.Threads, questions and change requests
DecisionAn answered question, recorded in the pull request and the commit when its task publishes.Decisions
PublicationOne attempt to land a task on Main and in Git.Branches and pull requests
NotificationWhat SpecsGraph tells you in the bell and by email.Notifications

Delivery

ConceptWhat it isRead more
Work itemT-n.m: one step of delivering a task, such as implement, deploy or verify. To do, Doing, Done or Dropped.Work items and delivery
DeliveredA task that is Done and has no open work item.Work items and delivery
Deploy tokenA project credential that lets CI report deployments.Work items and delivery
Build statusWhether an artefact on Main is built: from Not started to Verified, or Outdated.Build status
MilestoneM-n: what the team means to build together, in priority order, with progress from build status.Roadmap

Access

ConceptWhat it isRead more
RoleOwner, Admin, Editor or Viewer in an organisation; a project's teams narrow who edits it.Members, roles and teams
Access tokenA secret starting with sgp_ that lets an agent act for you, read only or read and write, for chosen projects.Access tokens and agent sign-in
Agent sign-inSigning an MCP client in with OAuth in the browser instead of pasting a token.Access tokens and agent sign-in

IDs and names

  • Workstreams are WS-n, tasks T-n and milestones M-n, numbered per project and never reused. Work items are T-n.m, numbered per task.
  • Artefacts have no display id: the app shows their names, URLs and the API use their ids, and YAML selectors use names (kind/Name, Context/Name).
  • Branches are spec/<project key>/t-<n>-<slug>; with a tracker key, spec/<project key>/<KEY>-t-<n>-<slug>.

Next steps