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
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 artefactsThe spec
Change and collaboration
Delivery
Access
IDs and names
- Workstreams are
WS-n, tasksT-nand milestonesM-n, numbered per project and never reused. Work items areT-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
- How the spec workflow works: the path from an edit to Main.
- The spec and its kinds: the 16 kinds in detail.
- Domain-driven and behavior-driven foundations: the methods behind these concepts.