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?)

Standardize (make it consistent)

Harden (make it survive reality)

Verify (prove behavior)

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.

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](https://codanna.dev) -- 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:

• Prompt recipes: PROMPTS.md
• Tutorial walkthrough: TUTORIAL.md
• Glossary: GLOSSARY.md
• Machine-readable skill index: specs/skills-manifest.json

For contributors:

• Repo-level specs (source of truth): specs/000-index.md
• Agent instructions for this repo: AGENTS.md
• Dev quickstart (validation, packaging): specs/quickstart.md
• App-repo integration guide: specs/005-application-integration.md

Templates (copy-first):

• App-repo agent instructions: specs/templates/app-repo/AGENTS.md
• Service spec bundle: specs/templates/service-spec-bundle/
• CI quality gate: specs/templates/ci/github-actions-quality.yml

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.