DEV Community

Cover image for SDLC in Topogram: process, benefits, and trade-offs
John Attebury
John Attebury

Posted on

SDLC in Topogram: process, benefits, and trade-offs

#agents #ai #tooling

Topogram's main job is a living app map in topo/: intent, contracts, ownership, proof. SDLC is how project work lives in that same graph when you opt in. Not a second product. Not a folder of markdown tickets that forget the codebase.

I use it on the engine repo (mostly me and agent models). This post is the general shape: process, benefits, trade-offs.

What you're opting into

  • Records under topo/sdlc/ (pitches, requirements, acceptance criteria, tasks, bugs, decisions, plans)
  • Policy in topogram.sdlc-policy.json (adopted, mode, profile, protected paths)
  • CLI commands that own status, history, and verification receipts
  • Links into capabilities, rules, and verifications elsewhere in topo/

SDLC is optional. No policy file → commands still run; gates report not_adopted unless you pass --require-adopted.

Process (normal loop)

1. Adopt (once)

topogram init . --adopt-sdlc
# or add topogram.sdlc-policy.json + topo/sdlc/** yourself
Enter fullscreen mode Exit fullscreen mode

Typical policy:

  • mode: "enforced" or "advisory"
  • profile: "standard" (lighter) or "audit" (stricter proof)

2. Shape and pick work

topogram query sdlc-backlog ./topo --json   # drafts, pitches, requirements in flight
topogram query sdlc-ready ./topo --json     # claimable tasks + proof posture
Enter fullscreen mode Exit fullscreen mode

3. Start a task (read-only first)

topogram sdlc start <task-id> . --actor <actor-id> --json
Enter fullscreen mode Exit fullscreen mode

Packet includes requirement, acceptance criteria, decisions, rules, blockers, verification targets, suggested commands.

topogram sdlc start <task-id> . --actor <actor-id> --write --json   # after you read it
Enter fullscreen mode Exit fullscreen mode

4. Close with proof

pitch → requirement → acceptance_criterion → task → verification
Enter fullscreen mode Exit fullscreen mode 
topogram query sdlc-proof-gaps ./topo --task <task-id> --json
topogram sdlc verify record <verification-id> . --task <task-id> --actor <actor-id> \
  --command "<what you ran>" --status pass --write --json
topogram sdlc complete <task-id> . --verification <verification-id> --actor <actor-id> --write
Enter fullscreen mode Exit fullscreen mode

5. Before commit (when enforced)

topogram sdlc prep commit . --base origin/main --head HEAD --json
topogram sdlc gate . --require-adopted --json
Enter fullscreen mode Exit fullscreen mode
You edit in git CLI owns
.tg record text Status transitions, .topogram-sdlc-history.json
Pitches, tasks, AC wording Verification run JSONL receipts

Don't hand-edit sidecars because a gate failed. That's how audit trails die.

Benefits

  • One graph for product and work; agents query slices instead of re-reading the whole repo
  • Task-start packets restate scope when the chat thread or model changes
  • Given/when/then acceptance criteria tie "done" to observable proof, not closure in a UI
  • Verification receipts you can query later (query verification-runs, proof gaps)
  • Rules in the packet so engineering law isn't only in AGENTS.md or the last conversation
  • Protected paths + gate so "skip process on a tired day" has to be an explicit exemption, not the default
  • Profiles: standard for day-to-day; audit when you want risk_class, change_type, and tighter exemption rules

Trade-offs

  • Overhead on small changes if protected paths are wide. Narrow them to what actually needs traceability.
  • You maintain records in git. The CLI won't write good pitches for you.
  • Enforced mode can frustrate until habits match (start task, record verification, run gate). advisory exists if you want signal without hard fails.
  • Not Jira/GitHub Issues. No built-in notifications, assignee UX, or non-technical dashboards. You get graph links and queries.
  • Not compliance in a box. Enterprise exports, signed immutable history, and similar ideas are future profile work, not what standard promises today.
  • Agents still need review. sdlc start helps; it doesn't replace reading the packet before --write.
  • Curated discipline on ongoing requirements (ongoing vs satisfied) or grooming queries add process surface you have to learn once.

When it's worth it

Situation Lean toward
Solo dev + agents, context keeps resetting Adopted SDLC + sdlc start packets
Small script, rare changes Skip or advisory only
Release/engine/infra paths you must explain later Enforced + protected paths + verification refs
Regulated audit trail tomorrow Look at audit profile; don't pretend standard is enough

Try it 

npm install --save-dev @topogram/cli
topogram init . --adopt-sdlc
topogram sdlc policy explain --json
topogram agent brief --json
Enter fullscreen mode Exit fullscreen mode

Top comments (0)