Skip to content

enterprise-software-playbook

An opinionated set of agent skills that drive cohesive, high-quality enterprise software: readable, maintainable, testable, and safe to change.

Each skill is a small, self-contained playbook (workflow + checklists + examples) stored in a SKILL.md file. Most skills are language-agnostic; TypeScript is currently the only language-specific style guide.

Why this exists

AI coding agents produce inconsistent output without shared guardrails. Copy-paste prompt snippets drift across teams, and ad-hoc instructions don't compose. This playbook gives agents a structured library of composable skills so that code quality stays high regardless of who (or what) writes the code.

Quick start

  1. Install the skills (pick one): Codex CLI | Claude Code | Antigravity | Vendor via submodule
  2. Add agent instructions to your app repo (start from specs/templates/app-repo/AGENTS.md).
  3. Paste the bootstrap prompt from PROMPTS.md.

You do not need to read this repo cover-to-cover. Start with the three steps above, then open the specific skills/*/SKILL.md playbook(s) you need as you go.

Minimal "try it now" prompt (run this inside your app repo, not this playbook repo):

Use workflow (read skills/workflow/SKILL.md).

Please review this codebase for maintainability and resilience gaps.

What's in here

Skills follow a default workflow: Define > Standardize > Harden > Verify.

Define (what are we building?)

Skill Purpose
workflow Auto-route work across skills; choose appropriate skills even if the user doesn't name them
plan Turn a request into an executable plan (tasks + acceptance + verification)
spec Write specs, contracts, plans, and task lists so agents converge on cohesive solutions
architecture Choose the smallest system pattern(s) for cross-service pressures
design Choose the smallest code pattern(s) for in-process design pressures
archobs Measure coupling, boundary health, and risk hotspots before architecture/refactoring decisions
intel Gather and shape intelligence signals from collected feeds into audience-aware output
forecast Predict likely next developments from internal patterns (git, archobs) and external signals (intel)

Standardize (make it consistent)

Skill Purpose
typescript Runtime safety, explicit boundaries, typed errors, and maintainable module structure
platform Design shared platform packages (packages/shared) without becoming a "utils junk drawer"

Harden (make it survive reality)

Skill Purpose
resilience Timeouts, retries/backoff, idempotency, circuit breakers, bulkheads
security Authn/authz, input validation, injection safety, secrets, SSRF guardrails
observability Logs/metrics/traces correlation, RED metrics, dashboards/alerts
debug Debug workflows (log > trace > metrics) for incidents, regressions, and SLO violations

Verify (prove behavior)

Skill Purpose
testing Consumer-focused tests that raise coverage without asserting implementation details
review Adversarial code review debate (critique > defense > rebuttal > verdict)
finish Definition-of-done pass (verification + boundary spot-check + crisp summary)

Cross-cutting reference material shared across skills lives in skills/references/.

Using these skills

Each skill lives under skills/<name>/SKILL.md. The primary mode is conversational: ask for what you want and let the agent auto-select the right skills. If you want deterministic control, name specific skills explicitly.

For more prompt recipes (including a conversational bootstrap), see PROMPTS.md.

Install

Detailed per-platform instructions are in INSTALL.md.

Platform One-line install
Codex CLI Fetch and follow instructions from https://raw.githubusercontent.com/bricerising/enterprise-software-playbook/refs/heads/main/.codex/INSTALL.md
Claude Code Fetch and follow instructions from https://raw.githubusercontent.com/bricerising/enterprise-software-playbook/refs/heads/main/.claude/INSTALL.md
Antigravity Fetch and follow instructions from https://raw.githubusercontent.com/bricerising/enterprise-software-playbook/refs/heads/main/.antigravity/INSTALL.md
Any tool git submodule add https://github.com/bricerising/enterprise-software-playbook.git tools/enterprise-software-playbook

Scope (and non-goals)

This playbook is optimized for enterprise web apps, especially:

  • HTTP/gRPC services, background jobs, and event consumers
  • Multi-service systems with reliability/consistency pressures

Non-goals:

  • A framework-specific "how to build a React app" guide
  • A complete performance tuning handbook (use it selectively, case-by-case)

Philosophy

These skills bias toward practices that make codebases easier for humans to operate over time:

  • Prefer clarity over cleverness; optimize for the next reader.
  • Make boundaries explicit; validate external inputs at the edges.
  • Keep dependencies and lifetimes explicit; avoid hidden globals.
  • Treat expected failures as data (typed results) instead of exceptions.
  • Use design patterns as names for proven structures, not as goals.

Bundled tools

  • tools/archobs/ -- Architecture observability CLI: measures coupling, boundary health, risk hotspots, and drift. Install with pip install -e 'tools/archobs[full]'. Powers the archobs skill.
  • Codanna -- Companion CLI that generates semantic search embeddings, used by archobs for file similarity. Install with brew install codanna (macOS) or see the archobs README.
  • tools/intelligence/ -- Intelligence collector and query CLI (intel): polls RSS, Hacker News, and SEC EDGAR feeds; stores events in SQLite; exposes trends/search/events via CLI and MCP tools. Install with cd tools/intelligence && npm install && npm run build && npm link. Powers the intel skill.

Docs

For users:

For contributors:

Templates (copy-first):

Terminology

  • Code patterns: in-process patterns (classic creational/structural/behavioral, mostly GoF).
  • System patterns: cross-process patterns (architecture/distributed-systems/ops) dealing with failure, consistency, and integration seams.
  • Operational patterns: repeatable workflows and cross-cutting policies for predictable delivery and operations (spec bundles, shared platform primitives, tests, observability, resilience).

The skill list above is grouped by workflow stage (Define/Standardize/Harden/Verify), not by scope.

Contributing

See CONTRIBUTING.md and the backlog in specs/tasks.md.

Feedback

If you try this playbook in a real codebase, feedback is extremely valuable:

  • Use GitHub Issues for bugs, confusing docs, and feature requests.
  • Include the prompt you used and what you expected vs what happened.

License

Apache 2.0 -- see LICENSE.txt.