enterprise-software-playbook

Design or refactor multi-service system architecture (domain boundaries, service decomposition, event-driven vs request/response, CQRS, sagas, API gateways, data ownership). Use when work spans multiple processes/services, needs eventual consistency, or requires clearer integration seams. NOT for in-process code structure like GoF patterns (use design); NOT for applying timeouts/retries/breakers to a single call (use resilience).

Run architecture observability analysis on a git repository to measure coupling, boundary health, risk hotspots, and temporal drift. Use when you need empirical data about code structure before making architecture or refactoring decisions, or to validate that changes improved boundary discipline. NOT for choosing architecture patterns (use architecture); NOT for choosing code patterns (use design); NOT for adversarial code review (use review); NOT for trajectory prediction or trend forecasting from cluster activity (use forecast).

Run a structured adversarial code review (critique → defense → rebuttal → verdict) with evidence-backed findings and stable IDs. Use when you want a thorough, multi-perspective review of code changes, a PR, or a design — produces actionable findings ranked by severity. NOT for writing or expanding tests (use testing); NOT for final ship-readiness (use finish).

Triage and diagnose production or local issues by following logs → traces → metrics (HTTP/gRPC/async). Use when investigating errors, latency spikes, 5xx responses, SLO violations, or regressions in an instrumented app. NOT for adding new instrumentation (use observability); NOT for applying resilience patterns (use resilience).

Pick the right in-process code pattern for a refactoring or extensibility need (GoF creational/structural/behavioral), and access implementation guides for specific patterns. Use as a decision workflow when unsure which pattern family fits, or go directly to pattern references when you already know. NOT for multi-service/distributed architecture (use architecture).

Run a final "definition of done" check before shipping: verify correctness, tighten contracts/docs, and produce a change summary. Use at the end of non-trivial work to confirm nothing was missed before merge/release. NOT for writing tests (use testing); NOT for adversarial code review (use review); NOT for initial planning (use plan).

Predict likely next developments from internal development patterns (git history, archobs clusters) and external signals (intel feeds). Use when you need forward-looking intelligence — what's GOING to happen, not what already happened. NOT for gathering raw signals (use intel); NOT for static code-structure analysis (coupling, boundary health, risk scores — use archobs); NOT for implementation planning (use plan).

Gather and shape intelligence signals from collected feeds (RSS, HackerNews, EDGAR) into audience-aware output. Use when you need current context on a technology, industry trend, or domain — or when you need to present signals to a specific audience. NOT for forward-looking predictions (use forecast); NOT for architecture analysis (use archobs); NOT for writing specs (use spec).

Add or change observability instrumentation (structured logging, OpenTelemetry traces/spans, RED metrics, dashboards, alerts). Use when adding logs/metrics/traces to code, defining telemetry field contracts, or building monitoring runbooks. NOT for diagnosing existing issues with existing telemetry (use debug); NOT for security-specific logging concerns (use security).

Break a request into a scoped implementation plan with ordered tasks, risk flags, and verification steps. Use before starting non-trivial, cross-cutting, or ambiguous work to align on approach and prevent rework. NOT for writing spec artifacts or contracts (use spec); NOT for auto-routing across multiple skills (use workflow).

Design and maintain shared platform libraries (e.g. packages/shared) that standardize cross-cutting concerns (auth wrappers, config, HTTP/gRPC helpers, typed errors, retry policies, lifecycle hooks). Use when multiple services duplicate boundary logic or need a golden-path primitive; prevents "utils junk drawer" anti-pattern. NOT for single-service code structure (use typescript); NOT for choosing resilience patterns for one call (use resilience).

Apply fault-tolerance patterns to outbound calls and async consumers (timeouts, retries with backoff+jitter, circuit breakers, bulkheads, idempotency keys, graceful degradation). Use when a service calls external dependencies, processes queues/events, or needs hardening against partial failures and flaky upstreams. NOT for diagnosing existing failures (use debug); NOT for multi-service architecture decisions (use architecture).

Apply security guardrails (authentication, authorization, input validation, SQL/XSS/command injection prevention, secrets management, SSRF protection, secure logging, dependency auditing). Use when adding/changing endpoints, auth flows, data access, file/network I/O, or handling user input and sensitive data. NOT for resilience/fault-tolerance patterns (use resilience); NOT for observability instrumentation (use observability).

Write and maintain spec-first artifacts (service specs, API contracts via OpenAPI/protobuf/WebSocket schemas, ADRs, task lists, quickstarts). Use when creating specs/*.md, apps/*/spec/ bundles, or contracts/ docs, especially before major behavior changes or multi-agent collaboration. NOT for implementation task breakdown without spec artifacts (use plan); NOT for choosing system or code patterns (use architecture or design).

Create or expand test suites for microservices (unit, integration, consumer-contract tests for HTTP/gRPC handlers, service flows, event consumers, caches, jobs). Use when adding tests, raising coverage, writing regression tests, or validating consumer-facing behavior. NOT for adversarial code review (use review); NOT for final ship-readiness checks (use finish).

Write, review, and refactor TypeScript for readability, type safety, and runtime correctness (Node.js/React/shared libs). Use when creating TS modules, modeling domain types, handling errors (Result/Either), validating external inputs (Zod/io-ts), organizing imports, or preventing cyclic dependencies. NOT for choosing design patterns (use design); NOT for shared platform library design (use platform).

Auto-select and orchestrate playbook skills end-to-end for feature, bug-fix, or refactor work. Use when the user gives a general request without naming a specific skill — workflow picks the right skills, sequences them, and keeps overhead proportional to the change size. NOT for creating a standalone task breakdown (use plan) or writing spec artifacts (use spec).