Skip to content
ZajLibrary
prod 352bb92
Browse

Playbook single-Step template

When to use

Section titled “When to use”
  • Shelf: rare standalone executable documents under build/playbooks/.../ with stepNumber in frontmatter.
  • kind: playbook single-Step — use only when the document itself is one action, not a multi-Step Part.
  • Diátaxis mode: focused how-to action inside a tutorial journey.
  • Readers served: authors who need a compatibility shape for a truly single action.

Part of the Playbook set (4 page levels): overview · phase hub · Part · single Step.

For normal playbook execution pages, use the Playbook Part template. Full rules: Writing style → Playbook Parts.

Design rationale

Section titled “Design rationale”
  • Collision avoidance — a document-level unit that contains ## Steps is a Part. A single-Step document uses ## Procedure so the Step level does not collide with the document level.
  • Goal-first TL;DR — how-to docs must state outcome before the action so readers can bail early if wrong doc (Diátaxis how-to guides).
  • Checklist as gate — unchecked boxes are blockers for agents and ADHD closure for humans (checklist manifesto — cognitive aid).
  • Verb-first action heading — procedural docs scan by action, not noun labels (Google style — procedures).
  • # Expected: after commands — separates command from observable success; agents need machine-checkable signals (technical writing — show results).
  • :::next not bare links — consistent exit ramp for sequential tutorials when this rare page is part of a chain (Starlight structural callouts).
  • Actor legend once per playbook — repeating 🤖/👤 on every step adds clutter (writing-style reader profiles).
  • Source labels normalized — when the step is converted from source material, publish the current ZajLibrary phase/step name and keep source task IDs out of reader prose.
  • Project-state writes are explicit — if the step discovers, creates, verifies, or consumes project facts (versions, paths, servers, branches, environment matrix), include a numbered sub-step or checklist item that reads/writes the canonical project-state file. Do not leave expected state updates as implied prose.
  • Agent autonomy is part of the contract — routine verification, tracker updates, and project-state writes are 🤖 work. Mark 👤 only when the human truly owns the action.
  • Machine-checkable by default — every required action has an exact command or observable action, # Expected: output, and an on-fail branch. Mutations include idempotency and rollback notes; async waits include expected duration, poll command, success signal, and give-up threshold; tool-shelling pages include version preflight.

Copy-paste skeleton

Section titled “Copy-paste skeleton”
---
title: "N · Step title"
description: One sentence — what this single Step does and what done looks like.
sidebar:
  label: "N · Step title"
  order: N
phase: "N"
stepNumber: N
estTime: ~30 min
status: current
tags: [playbook, topic]
---


## TL;DR


{Goal first — the outcome this single Step achieves. Then who it's for and what done looks like. Plain language, no undefined jargon.}


:::note[For beginners and agents]
Read the **TL;DR** first, complete the procedure, then check **every** box in the checklist before advancing. Agents: treat unchecked items as blockers — log command output as evidence (`# Expected:` in code blocks).
:::


*Actor legend — 🤖 Agent · 👤 User · 🔀 mix — appears **once** in the playbook overview, not on every step. Steps are agent-doable by default; only 👤/🔀 steps carry a `:::note[Who does this]` callout. Authentication, account creation, and password/secret entry are always 👤; the agent resumes after the session or non-secret state exists.*


## Background


{Optional — plain prose: context, scope, or prerequisites. **Not** a callout under this heading. Delete this whole section when the Step needs no setup.}


## Procedure


### Run the action


One or two sentences: what this Step does and why. *(🤖 agent-doable → no "Who does this" callout.)*


\`\`\`bash
command --flag   # Expected: success message or exit 0
\`\`\`


- Expected: `<what you should see>` — exit 0, a "ready" line, or a new file/row.


### Add your license key


One or two sentences: what this human-owned action does and why.


:::note[Who does this]
👤 **User** — paste it in the vendor dashboard (browser). *(🔀 use **User + Agent** for a mix.)*
:::


…


## Checklist


Do not mark this Step done until **every** box below is checked.


- [ ] First outcome verified (how you know it's done)
- [ ] Second outcome verified
- [ ] No secrets committed; `.env` still gitignored (if applicable)


:::next[Next step]
[Next Part or Step title](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/03-project-constitution/)
:::

Anti-patterns

Section titled “Anti-patterns”
  • Do not ship a :::summary[TL;DR] callout — use the ## TL;DR heading.
  • Do not use ## Completion checklist — it’s ## Checklist.
  • Do not add a ## Steps section here. If the document has multiple Steps, it is a Part and should use playbook-part.
  • Do not use bare ## Gate sections or ✅ prose gates — use - [ ] items.
  • Do not end with a trailing Next: line without :::next.
  • Do not title or describe the Step with source-only task IDs or old phase labels; map them to the current playbook.
  • Do not consume a project fact before a prior Part creates or verifies it. Use create → verify → consume → re-verify, and record unknowable early values as provisional carry-forwards.
  • Do not make a routine tracker or project-state update a user question.
  • Do not leave a required branch as prose like “if needed” without a test command, expected result, and on-fail path.
  • Do not mutate infrastructure, files, database state, or DNS without stating idempotency and rollback behavior.

Worked example

Section titled “Worked example”

Sources

Section titled “Sources”