| name | capability-matrix |
| description | Use when starting a new project, scoping a feature, or deciding which skill stack to load — provides the canonical Foundation → Implementation → Validation → Companions skill set per technology domain. The lookup table that turns "I'm building X" into "load these skills, in this order". |
| metadata | {"portable":true,"compatible_with":["claude-code","codex"]} |
Capability Matrix
Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.
Use When
- Starting a new project and choosing the initial skill stack.
- Scoping a feature in an existing codebase and deciding which skills should load alongside the platform skill.
- Reviewing a PR or design and asking "what should have been loaded for this work?".
- Onboarding to a new domain (mobile, AI, K8s, GIS) and wanting the canonical recommended set rather than discovering skills one by one.
Do Not Use When
- The work is purely conceptual (writing prose, planning, brainstorming) and no implementation is imminent. Skills are loaded for execution; the matrix is a tool for execution work.
- The domain is genuinely novel (no row applies). Flag the gap and ask the user to clarify; do not guess by stretching an unrelated row.
- A specialist skill's own
Use When already covers the situation completely. The matrix is for stack composition, not single-skill triggering.
Routing Intake Guidance
- The technology domain or domains in scope (web, mobile, API, AI, etc.).
- A clear sense of whether the work is greenfield or brownfield (changes which Foundation skills apply).
- Awareness that Validation entries here are pulled from
validation-contract's seven evidence categories.
Routing Method Detail
- Identify the matrix row(s) that match the work.
- Load every skill in the row's Foundation column first, then Implementation, then Validation.
- Add Companions as the work demands per
references/companion-rules.md.
- If two rows could apply (e.g., AI feature inside a multi-tenant SaaS), load both rows and dedupe.
Quality Standards
- Treat the matrix as the minimum starting set, not the cap. Add more skills if the work warrants.
- Never load a skill from the matrix without also reading its
Use When to confirm the situation actually matches.
- Flag missing rows. The matrix is not exhaustive; an unknown domain is a signal to ask, not to improvise.
Legacy Routing Pitfalls
- Loading every skill in a row without reading their
Use When triggers — the matrix recommends, the skill triggers gate.
- Treating Validation column entries as the only validation needed —
validation-contract defines the full evidence requirement; the matrix lists the canonical contributors per domain.
- Inventing a new row inline rather than updating this skill. The matrix is the single source of truth.
Routing Deliverable Detail
- A loaded skill stack tailored to the domain, ordered Foundation → Implementation → Validation → Companions.
- A clear statement when the matrix has no row for the work, prompting the user to clarify the domain.
References
How to use the matrix
- Identify the domain. Ask: "what is this project / feature primarily?" Match it to one row. If two rows apply (a common case — e.g., "AI feature in a SaaS"), load both rows and dedupe the skill list.
- Load Foundation → Implementation → Validation in order. Foundation skills set up the architecture, contracts, and data shape decisions before framework-level work begins. Implementation skills handle the platform-specific build. Validation skills carry the ship-readiness gates.
- Add Companions as the work demands. Companions are cross-cutting skills that often apply but not always — see
references/companion-rules.md for the trigger rules.
The matrix
| Domain | Foundation | Implementation | Validation | Companions |
|---|
| Web/SaaS | system-architecture-design, database-design-engineering | php-modern-standards, nodejs-development | vibe-security-skill, web-app-security-audit, frontend-performance | git-collaboration-workflow, ux-writing |
| Multi-tenant SaaS | multi-tenant-saas-architecture, database-design-engineering, saas-erp-system-design | php-modern-standards, dual-auth-rbac, modular-saas-architecture | vibe-security-skill, observability-monitoring | saas-business-metrics, subscription-billing, stripe-payments, feature-planning |
| iOS | ios-development, ios-architecture-advanced | swiftui-design, ios-data-persistence, ios-networking-advanced | ios-tdd, ios-app-security, app-store-review | ios-pdf-export, ios-biometric-login, ios-rbac, ios-monetization |
| Android | android-development | jetpack-compose-ui, android-data-persistence, android-room | android-tdd, google-play-store-review | android-pdf-export, android-biometric-login, mobile-rbac, mobile-custom-icons |
| KMP / Compose Multiplatform | |
Domain disambiguation
When two rows could apply, load both and dedupe. Common combinations:
- AI feature inside a SaaS → AI Feature row + Multi-tenant SaaS row.
- Mobile app talking to a backend → iOS or Android row + API/HTTP row.
- GIS dashboard inside a web app → GIS row + Frontend (React/Next) row.
- AI-powered analytics in a SaaS → AI Feature row + Multi-tenant SaaS row + (if Python-based) Python Service row.
- K8s-deployed multi-tenant SaaS → Multi-tenant SaaS row + Kubernetes row + Observability/SRE row.
- Brownfield refactor of any kind → relevant domain row + always add
git-collaboration-workflow and system-architecture-design.
Vertical addenda
Some verticals add a small set of skills on top of whatever rows apply:
- Healthcare → add
healthcare-ui-design.
- POS / Restaurant → add
pos-sales-ui-design, pos-restaurant-ui-standard.
- Payments → add
stripe-payments, subscription-billing.
- Auth surface → add
dual-auth-rbac, mobile-rbac, ios-rbac as platform demands.
- East-African / Uganda compliance → add
uganda-dppa-compliance, dpia-generator, language-standards, east-african-english.
- Reporting / dashboards → add
data-visualization, mobile-reports, mobile-report-tables, report-print-pdf as platform demands.
- Photo / image handling → add
photo-management, image-compression.
- Real-time features → add
realtime-systems.
- PDF / document generation → add
report-print-pdf, python-document-generation, ios-pdf-export, android-pdf-export, professional-word-output, excel-spreadsheets as needed.
- Spec / SDLC docs → add
spec-architect, sdlc-design, sdlc-planning, sdlc-testing, sdlc-user-deploy, sdlc-maintenance, sdlc-post-deployment.
- Systems / process / requirements description → add
systems-process-requirements when work needs system boundaries, workflows, scope, interfaces, data architecture, business rules, states, traceability, or design-system documentation.
Evidence-contract note
The Validation column in every row pulls skills that are themselves declared validation-contract contributors. This matrix tells you which validation skills apply per domain; validation-contract defines what evidence those skills must produce at ship time. Always load validation-contract alongside the matrix when shipping is in scope.
Companion Skills
Workflow
- Discover active entrypoints and identify the task's domain, phase, and deliverable.
- Select the minimum foundation, implementation, and validation route.
- Stop when no active skill matches or required capabilities are unavailable.
- Recover with a qualified route and named gap instead of inventing an entrypoint.
- Add companions only for mandatory cross-domain controls.
Outputs
| Artefact | Consumer | Acceptance condition |
|---|
| Ordered minimum skill route | Orchestrator and task owner | Every selected skill has a stated role and no neighbour is loaded redundantly |
Evidence Produced
| Evidence | Consumer | Acceptance condition |
|---|
| Discovery record and routing rationale | Maintainer and reviewer | All route names resolve to active entrypoints and every companion has a documented need |
Capability Contract
Minimum capability is read-only access to active skill roots and task context. Changing routers, skills, files, or permissions requires explicit authorisation.
Routing Correction Examples
- Loading every related skill. Fix: choose the minimum complete stack.
- Trusting a cached catalogue. Fix: discover active files at routing time.
- Routing by keyword alone. Fix: use intent, phase, and output.
- Inventing an entrypoint. Fix: report a capability gap.
- Omitting validation. Fix: include the applicable release gate.
Routing Scenario
A dataset-cleaning request routes to the data-quality pipeline and validation gate, not the entire report-production and orchestration stack.
Companion Skills
Inputs
| Input | Source/provider | If absent |
|---|
| Task, domain, lifecycle phase, deliverable | Requester and repository | Ask for the missing domain or route provisionally |
| Available skills and capabilities | Filesystem discovery and runtime | Report unmatched capability; do not invent a skill |
Degraded Mode
Fallback when catalogue or runtime state is incomplete: return the smallest qualified route with missing capabilities named and mark unavailable checks not assessed.
Decision Rules
| Choice | Action | Failure/risk avoided |
|---|
| One domain clearly owns the task | Route foundation to validation | Skill sprawl |
| Cross-domain control is mandatory | Add one companion | Missing gate |
| No matching active skill exists | Report a capability gap | Fabricated route |
Anti-Patterns
- Loading every related skill. Fix: choose the minimum complete stack.
- Trusting a cached catalogue. Fix: discover active files at routing time.
- Routing by keyword alone. Fix: use intent, lifecycle phase, and output.
- Inventing an entrypoint. Fix: report the capability gap.
- Omitting validation. Fix: include the applicable release gate.
Worked Example
A dataset-cleaning request routes to the data-quality pipeline and its validation gate, while unrelated report-production and research-orchestration skills remain unloaded.
Companion Skills
world-class-engineering — the production-readiness bar that the matrix's recommendations operate within.validation-contract — defines the seven evidence categories that the Validation column draws from.skill-composition-standards — house style and Inputs/Outputs contracts; load when authoring new skills that should be added to the matrix.
