Playbook overview template

When to use

• Path: <category>/<subcategory>/<topic>/build/playbooks/<workstream>/index.mdx
• kind: playbook (collection overview — not a numbered step)
• Diátaxis mode: tutorial (multi-part journey; reader learns by following phases in order)
• Readers served: beginners who need the full map; ADHD-friendly progress via <Stepper>; visual learners via stage/phase diagrams; agents that need phase order before drilling into steps

Part of the Playbook set (3 templates): overview → phase hub → step.

Design rationale

• Tutorials need a map before steps — Diátaxis tutorials orient the reader to the whole journey first, then deliver sequenced learning units; the overview is that map (Diátaxis tutorials).
• Stage grouping reduces cognitive load — twelve flat phases overwhelm working memory; grouping into 4–5 stages (Foundation → Build → Ship → …) follows progressive disclosure (NN/g — Progressive disclosure).
• <Stepper> with sub-step <ol> — each phase tile previews what happens inside without forcing a click; supports scan-and-resume behavior for long playbooks.
• Outcome paragraph before machinery — leading with “ZIP → production” answers “why am I here?” before components import (technical writing — lead with user goal).
• Persistent progress (localStorage) — multi-session playbooks need saved position; overview Stepper id must be stable per workstream.
• Lifecycle links at bottom — overview connects to sibling playbooks (continuous deploy, hotfix) without duplicating their steps.

Section	Job	Why it’s here
Intro paragraph	Outcome + AI-assist framing	Tutorial orientation
:::tip[Start here]	Primary CTAs (roadmap, Phase 1, agent skill)	Entry points for different readers
Stage diagram	Phases grouped over time	Relationship / change-over-time visual
Phase <Stepper>	Ordered phases + sub-step previews	Tutorial spine + ADHD progress
CardGrid / links	Deep links to phase hubs	Navigation after orientation
Related playbooks	WF2–WF5 links	IA without prose duplication

Copy-paste skeleton

Use .mdx — requires Stepper, optional StageFlow, CardGrid.

---
title: "<Playbook title>"
description: One sentence — journey outcome (e.g. ZIP → production).
sidebar:
  order: 0
  label: Overview
collection: <collection>
category: <category>
subcategory: <workstream>
collectionOrder: N
kind: playbook
status: current
phase: overview
estTime: ~N hours
tags: [playbook, topic]
prereqs:
  - &lt;prereq 1&gt;
---

import Stepper from '~/components/Stepper.astro';
import StageFlow from '~/components/diagrams/StageFlow.astro';
import { CardGrid, LinkCard } from '@astrojs/starlight/components';

&lt;Outcome paragraph — what this playbook delivers, AI-assisted framing, phase order rule.&gt;

:::tip[Start here]
**[Roadmap &amp; checklist →](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/roadmap/)** — all phases in one view.

**[Phase 1 · … →](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/)** — first actionable phase.

**Prefer an agent?** &lt;Optional skill / orchestrator callout.&gt;
:::

## The phases at a glance

&lt;One sentence on stage grouping.&gt;

<StageFlow
  title="&lt;Collection&gt; — phase pipeline"
  caption="&lt;Gate notes — e.g. Phase 0 folded into Phase 4.&gt;"
  stages={[
    { label: 'Foundation', sub: 'Phase 1 · …', tone: 'core' },
    { label: 'Build', sub: 'Phases 2–3 · …' },
    …
  ]}
/>

:::note[&lt;Cross-cutting prereq&gt;]
&lt;e.g. server bootstrap once per account — not a phase folder yet.&gt;
:::

<Stepper
  id="&lt;collection-workstream-overview&gt;"
  steps={[
    {
      title: 'Phase 1 · &lt;name&gt;',
      body: \`<ol class="zaj-stepper__sublist"><li>&lt;sub-step&gt;</li><li>…</li></ol>\`,
    },
    …
  ]}
/>

## Phase hubs

<CardGrid>
  <LinkCard title="Phase 1 · …" href="/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/" description="…" />
  …
</CardGrid>

## Related playbooks

&lt;Links to WF2–WF5 or sibling workstreams — table or LinkCards.&gt;

Anti-patterns

• Do not use playbook step spine (## TL;DR, stepNumber, :::next) on the overview — no single step number.
• Do not teach step-level commands on the overview — link to phase hubs and steps.
• Do not ship twelve phases with no stage diagram or Stepper (warrant test: change-over-time / process).
• Do not duplicate full phase prose — overview previews; phase hub teaches phase scope.

Worked example

• Set up a New CodeCanyon App — overview
• System docs examples

Sources

• Diátaxis — Tutorials — multi-part learning journey; overview orients before sequenced units.
• Diátaxis — Overview — tutorial vs how-to vs explanation separation; playbook overview = tutorial map.
• NN/g — Progressive disclosure — stage grouping to reduce cognitive load on long workflows.
• Google developer documentation style guide — Introductions — lead with user goal and scope before procedure.
• Writing style → Doc-type spines — Playbook set footnote and Zaj Stepper/sub-step conventions.