# Workshop Kit

> Workshop-kit — build the crew

- Skill: `manutej/workshop-kit` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add manutej/workshop-kit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/manutej/workshop-kit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: manutej (https://skillmd.com/u/manutej)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/manutej/workshop-kit

---


# Workshop-kit — build the crew

Doctrine (lab-first): participants leave having **done** the thing, proven against a
binary done-when, on **their** stack. Design backward — from what people must do in
production, to the capability that names it, to the assessment that proves it, to the lab
that carries them there. Most teams don't fail for lack of tools; they know *what* tools do
but not *why* systems are built that way. Start at the capability, never at the topic.

Read `../forge/references/evidence-rules.md` (every stat sourced or flagged; unknowns
never guessed) and `../forge/references/design-rigor.md` (participant-facing pieces pass
the QA ladder) before building. Consume `design/tokens.css`.

## H1 · Typed input slots (fill at intake; `UNKNOWN` is legal, never invented)

```
AUDIENCE_ROLES:     list[{role:str, count:int}]     # who + headcount per role
COHORT_SIZE:        int   # = Σ counts; drives debrief math + breakout staffing
SKILL_BASELINE:     str|UNKNOWN   # current level; UNKNOWN → start guided + discovery Q
STACK:              list[str]|UNKNOWN   # tools/langs/platforms labs run on
FORMAT:             {in-person|virtual|hybrid}
DURATION_BAND:      {half-day|1-day|2-day|multi-day|academy}
CHANGE_APPETITE:    {augment|transform|explore}|UNKNOWN   # inherited from SYNTHESIS
CAPABILITIES_TO_GAIN: list[Capability]   # 3–5, each verb+object+condition+standard,
                                         # each traced → tell:<id> | sponsor-goal:<id>
SPONSOR_GOALS:      list[str]
LOGISTICS:          str|UNKNOWN   # room, breakout capacity, tooling access, network
```

Mislabeling any slot changes the kit: wrong `FORMAT` breaks the agenda math (virtual
deltas), wrong `SKILL_BASELINE` picks the wrong difficulty rung, a guessed `STACK` produces
labs that can't run. Any unknown `STACK`/`LOGISTICS` detail → `01-research/UNKNOWNS.md` row
+ a one-sentence discovery question. **Never guess the stack to keep building.**

**Typed outputs** (write to `06-workshop/`): `agenda.md` · `labs/NN-name.md` (one per lab)
· `facilitator-guide.md` · `handouts/crib-sheet.md` + `handouts/monday-morning.md` ·
`slides` (HTML or pptx) · `followup.md`. Plus atoms → `FACTORY/atoms.md`.

## H2 · Artifact specs + acceptance checklists

Schemas and per-piece acceptance checklists live in `references/kit-templates.md` — every
piece has a fixed section contract and a checkable acceptance list. The measurable spine:

- **agenda.md** — block table; header carries computed scheduled-sum, slack %, hands-on
  ratio. Accept when rows sum to the window, slack ≥ 10%, ratio ≥ 0.60, every lab row has a
  done-when.
- **labs/NN-name.md** — setup(prerequisites)/exercise(checkpoints ≤10 min)/done-when/
  stretch/unstick-notes. Accept when no unstated access + self-sufficient.
- **facilitator-guide.md** — minute-by-minute run-of-show + expected-wrong-answers table.
  Accept when every lab/demo has a tech fallback.
- **handouts/** — crib-sheet + one-page Monday-morning checklist. Accept when an absent
  participant completes every lab from them alone.
- **slides** — instructional spine (context→demo→lab launch→debrief), via `pitch-deck`
  machinery. Accept when zero bullet-wall concept slides + every stat sourced.
- **followup.md** — 30/60/90 rows, each metric + owner + date; escalation ladder traced to
  fresh tells (coordinate with `account-copy`).

## H3 · Frame → Do → Review → Capture

1. **Frame** — set slots; extract 3–5 capabilities from SYNTHESIS/tells; state the day's
   thesis in CHANGE_APPETITE's voice (augment → "your workflow, accelerated"; transform →
   "the new way, practiced safely"; explore → "structured discovery").
2. **Do** — design assessments, derive labs (`lab-grammar.md`), compute the agenda
   (`agenda-math.md`), build the kit to the templates.
3. **Review** — the rehearse pass + participant-absence test (below) as blocking gates,
   then the design-rigor QA ladder on participant-facing pieces.
4. **Capture** — mint atoms to `FACTORY/atoms.md`, each typed per `../mint-atoms/references/atom-schema.md`: lab patterns that landed → `template`; **timing
   actuals vs. planned** (feeds the ×1.5 constant per stack/rung) → `benchmark`; and stuck-points → `tell-pattern` (new
   rows for unstick-notes and the wrong-answers table). A delivery that doesn't write down
   what it learned makes the next one no cheaper.

## H4 · Scale-native (a harness for X clients, not one workshop)

- **Module library.** Labs and modules are the reusable unit. A module = capability +
  assessment + labs + slides spine, written stack-parameterized. Store generalized modules
  in the library; instances only bind the client's stack.
- **Client-stack customization is isolated.** The stack-specific surface (commands, repos,
  credentials, screenshots) lives in the setup/crib-sheet layer; the capability and step
  logic stay stack-agnostic. Re-skinning a module for a new client touches only that layer.
- **Parallel kit assembly.** Independent labs are context-complete packets — build them in
  parallel (one agent per lab), then the main pass runs the agenda math and QA across the
  set. Labs never depend on each other's *build*, only on stated prerequisite *order*.
- **Academy = composed bootcamp modules over time.** A multi-week academy is bootcamp
  modules sequenced with spaced reinforcement between them; `followup.md` horizons become
  the inter-module scaffolding. Compose, don't re-invent.

## H5 · Judgment lives in the references

- `references/lab-grammar.md` — backward design as mechanical grammar: capability format,
  assessment design, step derivation, the difficulty ladder, the ≥60% ratio arithmetic.
- `references/agenda-math.md` — block types, duration formulas (debrief scales with cohort;
  lab = solo×1.5 + checkpoint overhead), 10% slack, energy-curve placement, virtual deltas,
  the cut protocol.
- `references/kit-templates.md` — typed template + acceptance list for every artifact.

## H6 · Checkable predicates (machine-verifiable, not vibes)

- **Timebox sum:** Σ(block minutes) = window − slack, and slack ≥ 0.10 × contact time.
- **Ratio:** hands_on_minutes / contact_minutes ≥ 0.60, computed from the block table.
- **Done-when:** every lab has a binary done-when criterion; a lab without one is not done.
- **Checkpoint density:** no >10-minute span in any lab without a `check:` predicate.
- **Handout self-sufficiency:** each lab completable from the crib-sheet alone.
- **Prerequisite closure:** no lab depends on unstated access; unknown stack → UNKNOWNS.

## H7 · References index

| file | when to read |
|---|---|
| `references/lab-grammar.md` | designing any lab; verifying the hands-on ratio |
| `references/agenda-math.md` | timeboxing; virtual conversion; cutting overflow |
| `references/kit-templates.md` | building any artifact; running acceptance checks |
| `../forge/references/evidence-rules.md` | any stat, any unknown |
| `../forge/references/design-rigor.md` | participant-facing QA ladder + tokens |

## H8 · Core invariants

1. Every stat in every material is sourced/dated or flagged `EST` — no plausible-sounding
   numbers (evidence-rules).
2. Unknown stack/logistics details go to UNKNOWNS + discovery questions, **never guessed** —
   a lab on an unverified stack is a lab that fails live.
3. Every claimed outcome is measurable; every capability has an observable assessment.
4. Plain language in all participant-facing pieces; internal machinery stays internal.
5. Artifacts ingest only SYNTHESIS-vetted numbers; refined input ⇒ regenerate, never
   hand-patch.

## H9 · DONE predicate + refusals

**DONE when:** all contracted files exist · timebox sum verified with ≥10% slack · ratio
≥0.60 computed and recorded · every lab has a done-when and ≤10-min checkpoints · absence
test passes · one lab dry-run completed · follow-up has metrics+owners+dates · every stat
cited · Stage-3b corrections applied · ≥1 atom minted.

**Refuse (and say why) when:**
- the agenda is overstuffed — the sum overruns or slack < 10% and the cut protocol hasn't
  been run. Return the cut options, not a padded-looking agenda.
- a lab rests on unverified `STACK` assumptions — surface the UNKNOWNS + discovery
  questions instead of guessing tools/versions/access.
- a "capability" is a topic (no observable verb+standard) or has no tell/sponsor trace.
- difficulty jumps to the open rung on an `UNKNOWN` baseline.

## H10 · Feedback tracing

After delivery/human feedback: log to `FACTORY/feedback-loop.md`; trace each correction to
the slot, formula, or template line that allowed it (e.g. "lab ran 20 min long" → the ×1.5
constant for that stack/rung → update the atom); apply the fix by regenerating; re-test the
change against 2–3 other module instances so tuning generalizes rather than overfits the
last cohort.

## Assembly procedure

1. Fill H1 slots from SYNTHESIS/tells; unknowns → UNKNOWNS + discovery questions.
2. Extract 3–5 capabilities (verb+object+condition+standard), each traced to a tell or
   sponsor goal. Reject topics.
3. Module selection/creation: reuse library modules whose capability matches; else create,
   generalized and stack-parameterized.
4. Design each assessment, then derive labs backward (`lab-grammar.md`).
5. Compute the agenda (`agenda-math.md`): block durations, sum, slack, ratio, energy curve,
   virtual deltas if applicable.
6. Build the kit to `kit-templates.md`; run design-rigor QA on participant-facing pieces.
7. **Rehearse pass (blocking):** re-add every timebox by hand (must equal window − slack);
   re-verify the ratio ≥0.60; **dry-run one lab end to end** on the stated stack, timing it
   against its live budget. If any fails → cut protocol / fix, regenerate.
8. **Participant-absence test (blocking):** hand the handouts to a fresh reader mentally —
   can they complete every lab without the facilitator's voice? Missing context goes into
   the crib-sheet, not left implicit.
9. Capture atoms; mark DONE only when H9 holds.