Your First Capability Model
A capability model is a structured map of what your organisation's software does, expressed as a hierarchy of business capabilities with repositories mapped underneath. It is the foundation of SGD governance — the thing that turns a flat list of 100 repos into a comprehensible picture.
The Hierarchy
The capability model uses three levels. Not every capability needs all three — start as shallow as makes sense and add depth where it helps.
| Level | Purpose | Examples | Colour |
|---|---|---|---|
| L1 — Domain | Top-level business domain. Usually maps to a department or value stream. | Payments, Client Management, Risk, Compliance | Blue |
| L2 — Capability | A distinct business function within the domain. Usually maps to a team or squad. | Card Processing, Billing, Onboarding, Portfolio View | Purple |
| L3 — Sub-capability | A specific feature area. Usually maps to one or a few repositories. | 3D Secure, Refunds, Invoice Generation, KYC Verification | Pink |
Repositories attach at whatever level makes sense. A shared types library might attach at L2 (used by all sub-capabilities in Card Processing). A single-purpose microservice attaches at L3.
Platform Suggests, You Confirm
The platform builds the initial model automatically during onboarding (whether you came via Path A or Path B). Your job is a 10-15 minute review:
- Scan the L1 domains — Do these match your organisation's language? Rename anything that feels wrong.
- Check the L2 groupings — Are repos grouped with the right siblings? Drag any misplaced repos.
- Ignore L3 for now — The platform may or may not suggest L3 sub-capabilities. If it does, glance at them. If it does not, add them later when you need finer-grained governance.
- Check Uncategorised — Repos in this bucket are not governed at the capability level, but they still get health scores and compliance checks. Move obvious ones out; leave the rest.
The review is not a design exercise
You are not building a perfect enterprise architecture diagram. You are confirming that the platform's groupings are close enough to be useful. Spend 10-15 minutes, not 10-15 days.
Tips for a Good Model
Don't over-engineer. Three to eight L1 domains is typical for a mid-size engineering org. If you have more than twelve, you are probably going too deep at L1.
Start coarse. You can always split a capability later. Merging two capabilities that were split too early is harder because governance history becomes fragmented.
Uncategorised is OK. Tooling repos, spike projects, documentation sites, and infrastructure modules often do not belong to a business capability. Leaving them uncategorised is an honest answer, not a failure.
The model evolves. As teams change, products launch, and priorities shift, the capability model should change with them. The platform tracks history across restructures — moving a repo from one capability to another does not lose its governance data.
Use your organisation's language. If your teams say "Payments" not "Financial Transaction Processing," the model should say "Payments." The model is a communication tool, not an academic taxonomy.
What Happens Without a Model?
Everything still works. If you skip the capability model entirely:
- Repositories still get health scores
- PRs still get governance checks against design system rules
- CLAUDE.md files are still generated with per-repo context
- Compliance checks still run
What you lose is cross-repo context:
- Coherence scoring (how consistent are repos within a capability?) is not available
- Feature specs cannot target a capability — they target individual repos instead
- The ROI dashboard cannot roll up metrics by business domain
- AI agents do not receive capability-level context (sibling repos, shared patterns)
The platform nudges but never blocks
If you have not set up a capability model, the platform will periodically suggest one based on new scan data. It will never prevent you from using governance features. The model adds context — it is not a gate.
What's next?
- Write your first feature spec See Writing Your First Feature Spec
- Understand how your team uses SGD See Roles: How Your Team Uses SGD
- Dive into governance layers See The Six Governance Layers