Playbooks & Standards

A Playbook is a set of project standards and conventions that SpecWright generates by analyzing your existing codebase. Once created, the AI agents reference it during specification generation — so your specs follow your team's actual patterns, not generic defaults.

What a Playbook contains

The generated PLAYBOOK.md captures:

• Project structure — Folder organization, naming conventions, file patterns
• Code patterns — State management approach, error handling patterns, component structure
• Technology stack — Frameworks, libraries, and versions already in use
• Development standards — Formatting rules, linting configuration, testing conventions
• Architecture decisions — API structure, data flow, authentication patterns, deployment setup

The Playbook includes version information and a last-amended date so you can track when it was generated or updated.

Generating a Playbook

specwright playbook

How Playbooks improve specifications

When a Playbook exists, the AI agents use it as additional context during specification generation:

• PM agent — Understands existing capabilities and patterns to ask better questions
• Engineer agent — Recommends technologies consistent with your existing stack, avoids suggesting tools that conflict with what you already use
• Issue Breakdown — References your folder structure and naming conventions in task descriptions, accounts for existing components and patterns
• Shipped prompts — Playbook standards are included when you ship to AI tools, so the implementing AI follows your conventions

Updating a Playbook

Your codebase evolves. To keep the Playbook in sync:

1. Navigate to the Playbook page
2. Click Update Playbook
3. SpecWright re-analyzes your codebase and regenerates the Playbook

Or from the CLI:

specwright playbook --update

The update captures new patterns, dependencies, and structural changes since the last generation.

Auditing against your Playbook

SpecWright can audit generated specifications against your Playbook to check for inconsistencies. For example:

• The tech spec recommends a state management library that conflicts with your existing setup
• The design brief uses component patterns that don't match your component library
• Issues reference folder structures that don't exist in your project

To run an audit, click Audit on the Playbook page, or:

specwright playbook --audit

The audit output highlights any conflicts between your specifications and your established standards.

What's next?

• Customizing AI Agents — Fine-tune agent behavior beyond Playbooks
• Ship to AI Tools — See how Playbook context is included in prompts