agent-playbook-template

Use for general product implementation work that is not primarily backend architecture, pure integration wiring, or screenshot-driven design-to-code.

Use when the main deliverable is maintainable documentation such as repository rules, onboarding guides, runbooks, ADRs, or architecture notes.

Use on first entry to a new repository to run environment scanning and ask targeted boundary questions before implementation.

Use after writing or modifying code to enforce the mandatory write → test → fix → repeat validation cycle.

Use before committing to a design or plan to force assumption-surfacing. The agent challenges your design, questions edge cases, and flags gaps — you patch vague decisions. Prevents the failure mode where a design "feels explained" but contains hidden flaws that only appear during implementation.

Use to establish and maintain a shared domain glossary (UBIQUITOUS_LANGUAGE.md). Creates a single source of term definitions that all agents, prompts, and documents must use — preventing semantic drift and repeated re-explanation across sessions.

Use when encountering compile errors, test failures, runtime exceptions, or unexpected behavior during implementation.

Use immediately after codebase discovery to classify task scale and determine which workflow steps are required vs. optional.

Use when a request needs system-level planning before implementation, especially for cross-module, high-risk, or ambiguous work.

Use to maintain persistent context across agent sessions — decision logs, architecture memory, and constraint tracking.

Use when backend work requires contract-first thinking, schema changes, permission checks, side-effect analysis, or test planning.

Use when the user provides screenshots, mockups, or design assets and wants implementation that stays visually close to the source.

Use to verify MCP tool server availability before relying on external tools, and to manage fallback strategies when tools are unavailable.

Use at the end of each task loop to emit a trace record for auditability, debugging, and future CI-based agent evaluation.

Use to maximize prompt cache hit rates across LLM providers by enforcing a stable instruction loading order and file size discipline.

Use before any implementation to understand the codebase structure, existing patterns, dependency graph, and project conventions.

Use after producing a deliverable and before handoff to run a fixed-rubric self-critique and revise cycle. Reduces hallucination and drift.

Use to generate a new SKILL.md file from a user-described capability. Meta-skill for extending the playbook when a recurring workflow gap is identified.