Skip to main content

​
What is a Playbook?

A playbook is your project’s knowledge base stored in .brv/ace/playbook.json. It captures patterns, best practices, and learnings as structured “bullets” that can be searched and reused.

​
Structure

The playbook has three parts:

​
1. Bullets

Individual knowledge items stored as objects: 
"project-00001": {
  // The "content" field here is just for demonstration purpose.
  // The actually content of each bullet is stored in `.brv/ace/bullets`
  // for your ease of updating them.
  "content": "Description of the pattern or practice",
  "id": "project-00001",
  "metadata": {
    "relatedFiles": ["src/file.ts"],
    "tags": ["manual"],
    "timestamp": "2025-11-01T10:34:48.293Z"
  },
  "section": "Project Structure and Dependencies"
}
Fields:
  • content - What you learned (be specific and actionable)
  • id - Unique identifier: {prefix}-{number} (e.g., project-00001)
  • metadata.relatedFiles - Related file paths
  • metadata.tags - Classification tags
  • metadata.timestamp - When created/modified
  • section - Category this bullet belongs to

​
2. NextId

Counter for generating unique IDs: 
"nextId": 6

​
3. Sections

Groups bullets by category: 
"sections": {
  "Project Structure and Dependencies": ["project-00001", "project-00005"],
  "Best Practices": ["best-00002"],
  "Testing": ["testing-00004"]
}

​
Common Sections

  • Project Structure and Dependencies- Setup, configuration
  • Best Practices - Recommended patterns and approaches
  • Code Style and Quality - Code organization and standards
  • Testing - Testing patterns and frameworks
You can define your own sections when prompting the agent or customize them with custom rules.

​
ID Prefixes

project- - Project structure items best- - Best practices code- - Code style items testing- - Testing patterns If you define your own sections, the ID prefix will reflect your preference. 
{
  "bullets": {
    "best-00002": {
      // The "content" here is for demonstration purpose.
      "content": "Health check endpoint implementation pattern: Create GET /health endpoint that returns JSON with status, timestamp, and uptime. Use Express Router for organization.",
      "id": "best-00002",
      "metadata": {
        "relatedFiles": ["src/routes/health.ts"],
        "tags": ["manual"],
        "timestamp": "2025-11-01T10:34:50.432Z"
      },
      "section": "Best Practices"
    }
  },
  "nextId": 3,
  "sections": {
    "Best Practices": ["best-00002"]
  }
}