enterprise-software-playbook

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.