agents.md

Use when building any UI, HTML component, slide, document, or design asset that will represent SBP visually — applies the Schuberg Philis visual brand identity (colors, typography, logo, stylization, grids, photography, iconography) to ensure brand-consistent output without manual reminders.

Use when conducting a security review, reducing dependency surface, or when dependencies may pose supply-chain, bloat, or maintainability risks.

Use when deploying to production — verifies rollback readiness, monitoring, and change communication against mission-critical criteria and produces a go/no-go decision.

Use when a production incident has occurred — structured blameless post-incident analysis that reconstructs timeline, assesses impact, finds root causes, and produces concrete action items.

Use when verifying monitoring, alerting, and logging coverage — checks the four pillars (metrics, logs, traces, alerts), produces a coverage matrix with gaps, severity ratings, and recommended actions, and applies the 3 AM test to every component.

Use when existing code needs to change shape before a feature, or when code drift is making further work expensive — improves structure and readability without changing observable behavior.

Use when generating operational runbooks from code and infrastructure — produces runbooks that work at 3 AM, covering common failure scenarios with specific diagnosis and resolution steps, copy-pasteable commands, and clear escalation paths.

Use when planning a high-risk production change — classifies the change, assesses risk, runs pre-flight checks, builds an execution plan with rollback triggers, and verifies after completion.

Use when reviewing code in mission-critical systems — checks OWASP Top 10, authentication and authorization, input validation, secrets handling, dependency vulnerabilities, cryptography, and security logging, framing findings by blast radius and customer impact.

Use when designing test coverage before writing code, or when adding tests to existing untested code — especially in mission-critical systems where coverage gaps become incidents.

Use when preparing for a design review or when evaluating security posture — identifies assets, maps attack surfaces, assesses risks, and produces a prioritized threat matrix with concrete mitigations.

Review multi-agent system designs for correctness, resilience, and safety — map components to the three-layer reference model, evaluate against responsibility checklists, check cross-cutting concerns, and flag common anti-patterns. Use when designing or reviewing agentic systems.

Review system architecture for mission-critical concerns — single points of failure, blast radius, rollback paths, observability gaps, and operational readiness. Use when designing new systems or reviewing existing ones.

Systematically investigate, reproduce, and fix software bugs — frame the symptoms, reliably reproduce, isolate the root cause, write a regression test, then fix. Use when chasing a bug, especially in mission-critical systems where "works on my machine" is not an acceptable resolution.

Explain unfamiliar code, infrastructure, or architectural patterns in context — trace data flow, identify patterns, surface design decisions, and teach the reasoning behind the implementation. Use when onboarding, reviewing, or debugging.

Build a new feature using test-driven development — clarify requirements, plan test coverage, drive implementation through red/green/refactor, integrate, and verify. Use when starting any feature that will reach production, especially in mission-critical systems where untested code is a liability.

Write tests that prove functionality works and catch regressions — structure each test clearly, exercise real behavior, cover happy paths and failure modes, and keep the suite fast and reliable. Use when writing new tests, adding coverage to existing code, or fixing flaky or low-value tests.

Explain the reasoning behind SBP engineering conventions — connect rules to real failure modes, show the trade-offs, and make the case with concrete examples. Use when an engineer asks why a convention exists or when onboarding new team members.

Author or structurally review a Schuberg Philis MCAF Terraform module (`terraform-<provider>-mcaf-<name>`). Use when creating a new MCAF module, modifying an existing one, or reviewing a PR against one. This skill layers MCAF-specific rules on top of the generic `terraform` skill — start there for baseline guidance (module layout, variable/output design, testing, CI, security) and come here for the Schuberg Philis specifics (`terraform.tf` not `versions.tf`, reuse of `mcaf-github-workflows`, `var.tags` on every taggable resource, native `terraform test` with `mock_provider`, conventional-commit PR labels, release-drafter flow, and the recurring anti-patterns observed across the 91-module corpus). For a full qualitative review producing good/bad/verdict reports, use the `review-mcaf` skill instead.

Generic Terraform / OpenTofu guidance — module structure, variable + output design, block ordering, version pinning, native `terraform test`, CI/CD, security scanning, and state hygiene. Use when authoring or reviewing any Terraform/OpenTofu module, making IaC architecture decisions, picking a testing approach, setting up pipelines, or debugging state. For Schuberg Philis MCAF modules, the MCAF-specific overlays live in the `mcaf-module` and `review-mcaf` skills — use this one for baseline rules that apply regardless of organisation.

Perform a qualitative MCAF module review covering best practices, usability, lifecycle currency, supply chain, security defaults, and design smells — and produce a good/bad/verdict markdown report. Use when the user asks for an "MCAF review", wants to assess whether a module is ship-ready, wants to triage multiple MCAF modules, asks "is this module any good?", or references `REVIEW.md`. For a single repo the skill produces one markdown section; for many it dispatches parallel subagents and stitches them into one file.