How Topogram models delivery as an SDLC graph
Audience: Organizations who need traceable work (requirements → proof → completion) without treating “the wiki” as the system of record.
Summary: Topogram can represent software delivery artifacts as typed records inside the same graph as your product intent. This post is a high-level tour of what that graph contains, how projects adopt it, and why declarative source and command-owned state are kept separate.
Repo: Topogram on GitHub
Dogfooding: Topogram uses its own SDLC in-tree. You can browse the adopted records under topo/sdlc/ in the repository (pitches, requirements, tasks, acceptance criteria, bugs, policy sidecars, and history the CLI maintains).
What “SDLC graph” means here
Your repository already holds many kinds of information: product concepts, contracts, tasks, tests, and process notes. When those live only in prose or scattered tickets, relationships are implicit — useful for humans, weak for automation.
Topogram’s SDLC graph is the subset of the overall Topogram model made of lifecycle records: pitches, requirements, acceptance criteria, tasks, plans, bugs, decisions, and verification hooks that tie work to observable proof. Like the rest of the model, these records live under topo/ (commonly under topo/sdlc/ paths such as pitches/, requirements/, acceptance_criteria/, tasks/, and so on — see the project docs for the recommended layout).
The parser normalizes everything under topo/ into one graph, so SDLC nodes can link to each other and to the wider model (rules, capabilities, decisions, etc.) with explicit references — not only narrative links.
The chain of proof (how records relate)
Topogram encourages the smallest record that tells the truth, with a typical reading order:
| Record | Purpose (high level) |
|---|---|
| Pitch | Why a theme or investment matters. |
| Requirement | Durable behavior the project commits to. |
| Acceptance criterion | Observable proof; approved criteria use explicit given / when / then wording. |
| Task | Implementation-sized slice tied back to requirements and criteria. |
| Verification | Command, test, check, or gate that provides evidence. |
| Decision | A durable choice that stabilizes future work. |
| Bug | A violation of an accepted rule, requirement, or verified expectation. |
| Plan | Optional nested execution notes for a task. |
Done tasks are expected to line up with the graph: valid references to what they satisfy, approved acceptance refs, and valid verification refs — so “closed” means something checkable, not only a status change in a tracker.
Adoption and enforcement (policy, not vibes)
Projects opt in with topogram.sdlc-policy.json. If the policy is missing, SDLC commands may still run, but gate behavior can report not adopted until you pass flags such as --require-adopted (see your project’s docs and policy file).
A policy can declare protected paths (areas where changes should be tied to SDLC items) and required item kinds (for example task, bug, requirement, pitch), with room for documented exemptions when reality does not fit the template. That turns “we should link work to specs” into machine-checkable expectations aligned with your repo’s rules.
How teams use it day to day (conceptual loop)
The workflow is designed so humans and agents can preview state transitions before anything mutates:
-
Discover available work (
query sdlc-available, policy explanation). -
Open a task packet (
sdlc startin read-only mode) — linked requirement, criteria, blockers, decisions, verification targets, and suggested queries. -
Apply transitions deliberately (
sdlc start ... --writeonly after review) so status/state changes stay auditable. -
Check proof gaps before declaring completion (
query sdlc-proof-gaps, then complete with explicit verification).
Commit and integration steps can include sdlc prep commit and sdlc gate so a branch’s changes are compared against policy and the declared graph — reducing “merged without a defensible thread from spec to proof.”
For copy-paste command examples, use the repository’s SDLC concept documentation: docs/concepts/sdlc.md.
Declarative source vs. command-owned state (why writers should care)
You can edit *.tg source directly: pitches, requirements, acceptance wording, and structural links live there as declarative text.
Stateful workflow data — history, transitions, archives, trust hashes, release evidence, and similar sidecars — is intended to move through Topogram commands so drift is detectable and reviews have a clear audit trail. Hand-editing sidecar JSON to “make CI green” undermines the model; the tooling is built to expose that.
For documentation practice, the payoff is straightforward: the story and the process metadata stay aligned because the same CLI surfaces both the narrative graph and the lifecycle state.
Benefits
- Stable anchors: requirements and acceptance criteria that are first-class nodes, not orphaned pages.
- Traceability from intent → work → proof without maintaining a separate trace matrix by hand.
- slices and packets (task-scoped context) instead of full-repo archaeology.
Bottom line
Topogram’s SDLC graph is not a separate ticketing system; it is a typed, linkable slice of your product graph where pitches, requirements, criteria, tasks, verification, and decisions form a chain of proof the CLI can query, gate, and keep honest.
If you are new to the project, start with topogram init --with-sdlc and read the repo’s SDLC and agent brief docs before changing protected paths.
Top comments (0)