Create New Engineering Playbook

Purpose: Meta-playbook for creating new playbook commands. Ensures every new command meets quality standards, follows conventions, and integrates coherently with the existing ecosystem.

Mindset: Playbooks should exemplify what they preach. Apply /pb-preamble thinking (clear reasoning invites challenge: your playbook should be easy to critique and improve) and /pb-design-rules thinking (Clarity, Modularity, Representation: structure should make intent obvious).

Resource Hint: sonnet - Structured command creation; follows established conventions.

Before writing a playbook, understand what type it is. Classification drives structure.

When to Use

• Creating a new pb- command* - Before writing any new playbook
• Restructuring existing playbook - When refactoring a command
• Reviewing playbook quality - As a reference for standards
• Onboarding contributors - Teaching playbook conventions

Step 1: Classify Your Playbook

What type of playbook is this? Classification determines required sections.

Decision aid:

• Does it have steps to execute? → Executor
• Does it mainly call other commands? → Orchestrator
• Does it explain philosophy/principles? → Guide
• Is it lookup/reference material? → Reference
• Does it evaluate/audit something? → Review

Step 2: Name Your Playbook

Naming Patterns

Naming Rules

• Lowercase only, hyphens between words
• Verb-first for actions (pb-commit, pb-deploy, pb-review)
• Noun-first for concepts (pb-security, pb-patterns)
• Avoid generic names (not pb-do-stuff, pb-misc)
• Match existing family patterns (pb-review-* for reviews, pb-patterns-* for patterns)

Category Placement

Step 3: Required Sections

Universal (All Playbooks)

Every playbook must have:

# [Title]

**Purpose:** [1-2 sentences: what this does and why it matters]

**Mindset:** Apply /pb-preamble thinking ([specific aspect]) and /pb-design-rules thinking ([relevant rules]).

[1-2 sentence orienting statement]

---

## When to Use

- [Scenario 1]
- [Scenario 2]
- [Scenario 3]

---

[MAIN CONTENT - varies by classification]

---

## Related Commands

- /pb-related-1 - [Brief description]
- /pb-related-2 - [Brief description]

By Classification

Executor (Additional Required)

## Process / Steps

### Step 1: [Name]
[What to do]

### Step 2: [Name]
[What to do]

---

## Verification

How to confirm this worked:
- [ ] [Check 1]
- [ ] [Check 2]

Orchestrator (Additional Required)

## Tasks

### 1. [Task Name]
**Reference:** /pb-specific-command

- [What this task accomplishes]
- [Key subtasks]

### 2. [Task Name]
**Reference:** /pb-another-command

---

## Output Checklist

After completion, verify:
- [ ] [Outcome 1]
- [ ] [Outcome 2]

Guide (Additional Required)

## Principles

### Principle 1: [Name]
[Explanation with reasoning]

### Principle 2: [Name]
[Explanation with reasoning]

---

## Guidelines

**Do:**
- [Positive guidance]

**Don't:**
- [Anti-pattern to avoid]

---

## Examples

[Practical examples demonstrating principles]

Reference (Additional Required)

## [Content Type]

### [Category/Item 1]

[Reference content: patterns, templates, etc.]

### [Category/Item 2]

[Reference content]

---

## Usage Examples

[How to apply this reference material]

Review (Additional Required)

## Review Checklist

### [Category 1]
- [ ] [Check item with clear pass/fail criteria]
- [ ] [Check item]

### [Category 2]
- [ ] [Check item]

---

## Deliverables

### [Output 1: e.g., Summary Report]

```template
[Format/structure for this deliverable]

[Output 2: e.g., Findings List]

[Format specification]

---

## Step 4: Write Content

### Tone Guidelines

| Do | Don't |
|----|-------|
| Professional, direct | Casual, chatty |
| Concise, specific | Verbose, vague |
| Imperative mood ("Run X") | Passive ("X should be run") |
| State facts | Hedge with "maybe", "might" |

**Banned phrases:**
- "Let's dive in"
- "It's important to note"
- "As you can see"
- "Simply" / "Just" / "Easily"
- "Best practices" (be specific instead)

**Dash discipline:** Single hyphen or ordinary punctuation (comma, colon, period) is the default. `--` is earned, not a stand-in for the em-dash: an em-dash written as `--` carries the same overuse tell. Reach for one only when the break genuinely sharpens the sentence.

**The banned list rots; the shape does not.** That vocabulary ages every model generation, so treat the list as corroborating signal rather than a blocklist. The durable tells are structural: metronomic sentence rhythm, uniform section anatomy, copula avoidance, hedging density. Run `/pb-handcraft` (it fires `/pb-voice` as a required lens) as the last pass before you ship a new command; it catches the structural tells a word list misses.

### Structure Guidelines

| Element | Rule |
|---------|------|
| Title | H1, imperative or noun phrase |
| Major sections | H2, separated by `---` |
| Subsections | H3, no divider needed |
| Lists | Use for 3+ parallel items |
| Tables | Use for structured comparisons |
| Code blocks | Use for commands, examples, templates |
| Checklists | Use `- [ ]` for verification items |

### Cross-References

- Use `/pb-command-name` format in text
- List related commands in dedicated section at end
- Ensure bidirectional links (if A references B, B should reference A)
- Only reference commands that exist

### Examples

Every playbook should include at least one example:

- Make examples practical and realistic
- Show both input and expected output where applicable
- For pattern guidance, show good AND bad examples
- Use real-world scenarios, not "foo/bar" abstractions

---

## Step 5: Scaffold Template

Copy this template and fill in:

```markdown
# [Command Title]

**Purpose:** [What this does and why it matters]

**Mindset:** Apply /pb-preamble thinking ([aspect]) and /pb-design-rules thinking ([rules]).

**Resource Hint:** [Model tier - see /pb-claude-orchestration]

[Orienting statement]

---

## When to Use

- [Scenario 1]
- [Scenario 2]
- [Scenario 3]

---

## [Main Section 1]

[Content]

---

## [Main Section 2]

[Content]

---

## [Main Section 3]

[Content]

---

## Related Commands

- /pb-related - [Description]

Resource Hint by Classification

See /pb-claude-orchestration for full model selection strategy.

Step 6: Validate

Run this checklist before finalizing:

Structure Validation

• Title is H1, clear and specific
• Purpose statement exists and is concise
• Mindset links to /pb-preamble and /pb-design-rules
• “When to Use” section exists with 3+ scenarios
• Major sections separated by ---
• Related Commands section at end
• version and last_reviewed set in YAML frontmatter

Content Validation

• Classification-appropriate sections present
• At least one practical example
• No placeholder text (“TBD”, “TODO”, “[fill in]”)
• No duplicate content from other playbooks
• Specific and actionable, not vague philosophy
• Commands/code are tested and work

Quality Validation

• Passes markdownlint (no lint errors)
• No emojis
• Professional tone throughout
• No banned phrases
• Could be understood by someone new to the playbook
• Resource Hint present and appropriate for classification
• Command is context-budget-appropriate (<300 lines for Standard tier)

Integration Validation

• File in correct category folder
• Filename matches command name (pb-foo.md for /pb-foo)
• All /pb-* references point to existing commands
• Added to docs/command-index.md
• Command count bumped everywhere it is tracked (convention validator, test EXPECTED_COUNT, reference-site summary)
• CHANGELOG entry added now, not batched at release (a new command is a notable change)
• At least one other command references this (edit a related command’s “Related Commands” section to add back-link)
• If command affects CLAUDE.md content, regenerate with /pb-claude-global
• Run /pb-review-playbook quick review on the new command

Final Test

# Lint check
markdownlint commands/[category]/pb-new-command.md

# Install and verify
./scripts/install.sh

# Test invocation (in Claude Code)
# /pb-new-command

Anti-Patterns

Playbook Lifecycle

Updating Existing Playbooks

When modifying an existing playbook:

1. Minor updates (typos, clarifications): Update directly, bump patch version
2. New sections or features: Update, bump minor version, note in commit
3. Breaking changes (renamed, restructured, different behavior): Bump major version, document migration path

Deprecating Playbooks

When a playbook is no longer needed:

1. Add deprecation notice at top: **DEPRECATED:** Use /pb-replacement instead. This command will be removed in vX.Y.
2. Update referencing commands to point to replacement
3. Remove from docs/command-index.md (or mark deprecated)
4. After grace period, delete file and remove symlink

Version Convention

Version lives in the YAML frontmatter version field (MAJOR.MINOR.PATCH), the single source of truth. There is no separate footer.

• MAJOR: Breaking changes, significant restructure
• MINOR: New sections, expanded content
• PATCH: Typos, clarifications, minor fixes

Example: Creating a New Playbook

Scenario: Create a playbook for setting up linting in a project.

Step 1: Classify

• Runs a workflow with steps → Executor

Step 2: Name

• Action-oriented → pb-lint-setup
• Category → development/ (daily workflow)

Step 3: Required Sections

• Universal sections (Purpose, When to Use, Related)
• Executor sections (Process/Steps, Verification)

Step 4: Write

# Lint Setup

**Purpose:** Configure linting for consistent code style...

## When to Use
- Starting new project
- Adding linting to existing codebase
- Standardizing team code style

## Process

### Step 1: Choose Linter
[Based on language...]

### Step 2: Install
[Commands...]

### Step 3: Configure
[Config files...]

## Verification
- [ ] Linter runs without errors
- [ ] Pre-commit hook installed

## Related Commands
- /pb-greenfield - Project initialization

Step 5: Validate

• Run checklist
• Test with markdownlint
• Install and invoke

Playbook Quality Tiers

Reference for appropriate depth:

Match depth to purpose. Simple commands don’t need 500 lines.

Appendix: Review-Skill Design – Scope-Locked Passes

When authoring a new /pb-review-* skill (or extending one), use scope-locked passes rather than omnibus reviews.

Anti-pattern – the Omnibus Review: one skill or prompt asked to evaluate correctness AND simplicity AND duplication AND performance AND security AND style AND tests in a single pass. Symptoms: mixed-severity bullet lists, no natural stop condition, earlier findings bleed into later ones (“already flagged complexity; I’ll go lighter on duplication”).

Pattern – Named Passes with Explicit Refusal: split the review into passes, each with a narrow mandate. Each pass declares what it does AND what it refuses, routing refused concerns to another pass.

Canonical pass division:

Why it works:

• Clean stopping signal per pass (“found nothing more to simplify” → stop).
• Findings are type-sorted by construction.
• Bounded iteration per pass; natural early-exit when a pass finds nothing.
• Different passes can use different reviewer personas or models.

Refusal-language template (include in the skill’s Scope section):

## Scope

This pass **does**: flag duplicate code introduced by the diff; propose reuse of existing shared utilities.

This pass **does not**: evaluate correctness, style, performance, or security. If the dedupe requires a behavior change, flag it and stop -- do not fix it. Correctness/style/perf/security belong to other passes.

Warning signs when reviewing an existing skill for drift:

• “Also consider X” (where X is a different domain) – omnibus drift
• “As a bonus, this skill can also…” – scope creep
• “Comprehensive review of…” – omnibus by name

Existing playbook alignment: the code-simplifier, silent-failure-hunter, type-design-analyzer, pr-test-analyzer, and code-reviewer subagents all refuse by prompt training. The /pb-review-* skills refuse by doc-only convention – make that refusal explicit in skill prose.

Related Commands

• /pb-evolve – Quarterly evolution cycles for updating the playbook ecosystem
• /pb-review-playbook – Review existing playbooks for quality and conventions
• /pb-standards – Code and content quality standards applied during validation
• /pb-documentation – Writing guidelines for clear, maintainable documentation