Playbooks

Procedural operational specifications

A playbook is an atomic procedural expertise unit — not documentation, not a prompt, not informal instructions.

It formalizes executable domain procedure:

---

Playbook anatomy

Example: pb.documents.docx-generation

apiVersion: sdlc.jambu.ai/v1
kind: Playbook
metadata:
  id: pb.documents.docx-generation
  version: 1.0.0
  domain: [documents, docx]
  tags: [python-docx, ooxml, document-contract]
  load_context: on_provision

objective: >
  Generate native Microsoft Word (.docx) files from a structured
  document-contract.yaml using python-docx 1.2.0.

runtime:
  requires:
    capabilities: [python-docx, yaml-parse]
  budget:
    max_adaptive_steps: 5

constraints:
  - Library MUST be python-docx==1.2.0 pinned in venv requirements.txt
  - Output MUST be .docx OOXML — MUST NOT emit legacy .doc binary

inputs:
  output_dir:
    type: string
    required: true
  document_contract_path:
    type: string
    required: true

procedure:
  - id: init-venv
    mode: deterministic
    objective: Create isolated Python venv with pinned python-docx
    action: >
      In {output_dir}, create requirements.txt with python-docx==1.2.0.
      Run python3 -m venv .venv && .venv/bin/pip install -r requirements.txt.
    validate:
      - .venv/bin/python -c "import docx" succeeds

  - id: generate-docx
    mode: adaptive
    objective: Render document from contract
    action: >
      Read document_contract_path. Apply styles from contract.template if set.
      Write output to {output_dir}/output.docx.
    validate:
      - output.docx exists and opens as valid OOXML zip

Key sections:

Section	Purpose
metadata.id	Stable identifier — pb.{domain}.{name}
load_context	on_provision — loaded only when explicitly provisioned
runtime.requires	Capabilities the executing agent must have
constraints	Hard rules — agent must not violate
procedure[]	Ordered steps — deterministic or adaptive mode
procedure[].validate	Checks that must pass before step is complete

JSON Schema: .sdlc/playbooks/playbook.schema.json

---

How playbooks are consumed

Not loaded at sessionStart. Retrieval path:

# Summary counts only — safe for hydration
python3 .sdlc/bin/sdlc_playbook.py catalog --summary

# Resolve full playbook content
python3 .sdlc/bin/sdlc_playbook.py resolve --id pb.documents.docx-generation

# Inject into agent context for a run
python3 .sdlc/bin/sdlc_playbook.py provision \
  --run-id my-run \
  --playbooks pb.documents.docx-generation

Provision triggers:

• Workflow stage declares playbooks_when: matching domain tags
• Spec carries domain_tags: resolved at feature start
• User invokes /sdlc:learn and later wires with --wire
• Skill frontmatter declares playbooks: (new skills only)

Default: playbooks sit in catalog until explicitly provisioned. No automatic contamination of agent context.

---

Acquisition: /sdlc:learn

When domain expertise does not exist yet:

Phase	Name	Output
F0	Deep Research	.sdlc/playbooks/.research/{run_id}/report.md
F1	Critical Synthesis	One winning choice per decision
F2	Materialization	.pb.yaml + INDEX registration
F3	Delivery	Prerequisites manifest — no feature implementation plan
F4	Wire (opt-in)	Attach to workflow stage via --wire

F0 blocked by research-gate if research quality fails. F3 blocked by contamination-check if learn touched agents, rules, skills, hooks, or application code without authorization.

F4 forbidden targets: global sessionStart hydration, existing skill files, agent personas. Allowed: workflow playbooks_when:, command stage provision:, manifest required_playbooks:.

---

Playbooks in the composition stack

Playbook (.pb.yaml)       — domain procedure
    ↑ composes into
Skill (SKILL.md)          — SDLC orchestration (optional playbooks: frontmatter)
    ↑ composes into
Command / Workflow stage  — declares skills and/or playbooks_when
    ↑ delegates to
Agent                     — executes one stage; does not embed playbooks in persona

Agents execute stages. Skills orchestrate SDLC ops. Playbooks hold domain expertise. Keeping them separate prevents procedural monoliths in agent personas and controls token budget.

---

Sample playbooks in the catalog

The authoring repository includes reference playbooks demonstrating patterns:

ID	Domain	Pattern demonstrated
pb.documents.docx-generation	Documents	Python venv + contract-driven generation
pb.documents.pptx-generation	Documents	Template-based slide deck
pb.compose.scaffold	Project setup	Greenfield app scaffold after init
pb.webdesign.visual-fidelity-gate	QA	Pixel diff gate for clone mode

Catalog index: .sdlc/playbooks/PLAYBOOKS.md (lazy — not in sessionStart hydration).

Consumer projects start with an empty or minimal catalog. Playbooks accumulate via /sdlc:learn or manual authorship.

---

Playbooks and the DSL

Playbooks extend the DSL without modifying it. The DSL defines:

• Where playbooks live (.sdlc/playbooks/)
• How they are retrieved (sdlc_playbook.py)
• When they load (load_context: on_provision)
• Micro-gates (research-gate, contamination-check)

Workflow YAML references playbooks by id in playbooks_when: blocks — same pattern as integration slot references in the DSL. The core contract stays stable; domain knowledge accretes in the playbook library.

---

Operational consequences

Quality depends on F0 research. Mitigated by deterministic research-gate schema.

Lazy by default. Playbooks not needed in a session consume zero tokens.

Two “done” concepts. Playbook done (domain artifact exists) vs workflow done (SDLC gates pass). A provisioned playbook can fail validation while the workflow stage remains incomplete.

Catalog grows per project. Unlike workflows (identical across projects), playbook libraries are project-specific expertise accumulated over time.