Skip to content
ZajLibrary
prod 352bb92
Browse

Playbook phase hub template

When to use

Section titled “When to use”
  • Shelf: build/playbooks/<collection>/<workstream>/0N-phase/index.mdx
  • kind: playbook (phase hub — not a numbered Part; no partNumber or stepNumber)
  • Diátaxis mode: tutorial (phase-level unit within a larger journey)
  • Readers served: readers entering one Phase; agents routing to the correct Part; kit users who need shortcut callouts (Parts N–M)

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

Design rationale

Section titled “Design rationale”
  • Phases are tutorial chapters — within a Diátaxis tutorial, each chapter has its own orientation before exercises (Parts); the phase hub is that chapter front matter (Diátaxis tutorials).
  • “Why this phase first” callout — motivation block (:::tip) answers perfectionist “why can’t I skip?” without bloating every step (learning objective upfront).
  • Relationship diagram when the phase installs a system — e.g. AI System boot flow warrants Mermaid or SVG; prose-only for multi-component phases fails the warrant test (ZajLibrary visuals gate).
  • <FileTree> for target repo shape — when the phase materializes files, show the end-state tree once on the hub; steps link back instead of repeating (Google — file structure in procedures).
  • Kit shortcut as honest partial path — Good Docs install pattern applies to kits that shortcut Parts 3–6, not the whole Phase; callout must name remaining Parts (Good Docs installation guide).
  • Numbered Part list at bottom — redundant with Stepper but gives a printable, agent-parseable manifest without JavaScript.
  • Expected work lives in Part documents — if a reader must do it before advancing, it needs a numbered Part with partNumber, ## Steps, and ## Checklist; the hub only previews and links.
  • Project-state ownership is visible — when a Phase creates, verifies, consumes, or re-verifies project facts, the hub may orient readers to that chronology, but the actual read/write/update work must live on numbered Parts or checklist gates.
  • Entry blockers orient, Parts execute — hubs may list “Before you start” blockers, but each blocker must point to the Part/checklist that clears it. Do not make the hub the only place with machine-checkable work.
SectionJobWhy it’s here
Intro + :::tip[Why…]Phase motivationTutorial chapter framing
What X actually isConcept + bullet listExplanation before procedure
<FileTree> / diagramStructure or flowWarrant test for relationship/process
Phase <Stepper>Part previews in PhaseProgress within Phase
Kit shortcut calloutOptional install pathLinks kit without replacing verify Part
Parts listPlain 1. linksAgent + print friendly
Committed vs gitignored tableOne-time policyReduces repeated step prose

Copy-paste skeleton

Section titled “Copy-paste skeleton”

Use .mdx when using Stepper, FileTree, or diagrams.

---
title: "Phase N · &lt;Phase name&gt;"
description: One sentence — what this phase delivers and why later phases depend on it.
sidebar:
  label: Phase N overview
  order: 0
phase: "N"
category: <category>
subcategory: <workstream>
collectionOrder: N
kind: playbook
estTime: ~N min
status: current
tags: [playbook, topic]
prereqs:
  - &lt;phase or env prereq&gt;
---


import Stepper from '~/components/Stepper.astro';
import { FileTree } from '@astrojs/starlight/components';


&lt;Intro — what this phase does in the larger playbook.&gt;


:::tip[Why this is Phase N, not an afterthought]
&lt;2–4 sentences — risk, dependency, or speed rationale.&gt;
:::


## What "&lt;phase subject&gt;" actually is


&lt;Bullet list of artifacts / outcomes.&gt;


&lt;Optional FileTree or ```mermaid``` when structure or boot flow warrants it.&gt;


## The flow at a glance


<Stepper
  id="&lt;workstream-phase-N&gt;"
  steps={[
    { title: '&lt;Part title&gt;', body: 'One-line preview. See <a href="…">Part slug</a>.' },
    …
  ]}
/>


## Skip the typing — use the kit


&lt;Only when a kit exists for this phase.&gt;


:::note[Kit shortcut — Parts X–Y]
Download the **[&lt;Kit name&gt;](/tech-stack/laravel/codecanyon/resources/kits/ai-system/)**, copy to project root, run **`seed.sh`** as an alternative through Parts X–Y (after Parts 1–2). Details in **[Part title](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/03-project-constitution/#alternative--kit--seedsh)**. Still finish **[Verify Part](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/07-verify-and-gate/)**.
:::


➡️ **[Kit link](/tech-stack/laravel/codecanyon/resources/kits/ai-system/)** — one-line install summary.


## Parts


1. [&lt;Part&gt;](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/01-project-setup/) — one-line
2. …


## &lt;Optional policy section — e.g. committed vs gitignored&gt;


| File | Committed? | Why |
| --- | --- | --- |
| … | … | … |

Anti-patterns

Section titled “Anti-patterns”
  • Do not add partNumber or stepNumber frontmatter on the phase hub.
  • Do not use :::next on the hub — reserve for Part/single-Step documents.
  • Do not imply a kit replaces verify/gate Parts without explicit links to them.
  • Do not bury required work in a caption, prereq, callout, or phase intro; create or link a Part instead.
  • Do not import source-only phase labels or task numbers into the published hub. Translate source names to current ZajLibrary phase/step names.
  • Do not skip the diagram when the phase explains a multi-component boot or ownership model.
  • Do not let the hub be the only place that says to update project-state files, trackers, or environment matrices.
  • Do not use an entry blocker as a vague warning; name the evidence, the owning step, and the on-fail path.

Worked example

Section titled “Worked example”

Sources

Section titled “Sources”