Skip to content

README.md

Latest commit

 

History

History
106 lines (78 loc) · 8.56 KB

README.md

File metadata and controls

106 lines (78 loc) · 8.56 KB
Raw

Workshop map

One app, Worksheet Studio, learned in a straight line: the levels, then the Software Factory modules, then the labs that make you do each step. Take each part in order.

Set up

  1. make doctor checks your machine.
  2. npm ci
  3. make check runs the whole gate. It needs no API key.

Behind on a level? make levels LEVEL=<name> writes a finished copy to supplied/<name>/. Open it and carry on.

1. Levels, hand-built to capstone

Each level adds one layer and ends with a proof: make prove LEVEL=<name>. Each doc runs the same steps: the problem, the run without the config, the config, the run with it, the proof, an exercise.

Level What you learn Run
hand-built the app before any AI helps: every band renders and lints make prove LEVEL=hand-built
boundary a secret lives in one process, enforced by hooks make prove LEVEL=boundary
context AGENTS.md and path-scoped rules give Claude the standards make prove LEVEL=context
skills pinned skills hit every band under a token budget make prove LEVEL=skills
execution every agent and stage has a model, turn cap and budget make prove LEVEL=execution
verification a fix is real only if its test bites make prove LEVEL=verification
delivery tickets flow to a pull request, a human merges make prove LEVEL=delivery
sharing the factory installs in any repo as one plugin make prove LEVEL=sharing
workflows one engine, a workflow per kind of task make prove LEVEL=workflows
capstone rebuild a feature through your own factory make prove LEVEL=capstone

2. Software Factory modules, F0 to F13

The same path as a ticket-to-merge pipeline. Questions: factory FAQ.

Module What you learn Open or run
F0 Overview the whole path from a ticket to a merged pull request make factory ISSUE=1 FLAGS=--dry-run
F0.1 Anatomy every file the factory reads docs/factory/f0-1-anatomy.md
F1 Plan intent, triage and the risk tier docs/factory/f1-plan.md
F2 Design the spec is the first test docs/factory/f2-design.md
F3 Build explore, plan, code inside a fence docs/factory/f3-build.md
F4 Test evidence the model cannot talk its way past docs/factory/f4-test.md
F5 Review lenses, voting verifiers and a capped loop docs/factory/f5-review.md
F6 Deploy risk tiers, merge queue, CI and release docs/factory/f6-deploy.md
F7 Maintain bands, incident to eval, retro and metrics docs/factory/f7-maintain.md
F8 Workflows write a workflow and choose one per task docs/factory/f8-workflows.md
F9 Capstone rebuild the workbook and template features docs/factory/f9-capstone.md
F10 Assignments pick an assignment, file it, run it docs/factory/f10-assignments.md
F11 Cloud sessions run the factory away from your laptop docs/factory/f11-cloud-sessions.md
F12 Model routing the right model for each stage docs/factory/f12-model-routing.md
F13 Spend and safety caps, credit, keys and hooks docs/factory/f13-spend-and-safety.md

3. Labs, noob to advanced

The labs are hands-on, one goal and one proof each. Full table and rules: labs. Progress sits in .labs/, which git ignores.

make progress          the lane map with a bar per lane
make next              show the next lab without running anything
make lab               show the current lab, run its proof, record a pass
make lab HINT=1        reveal the next hint, one per call
make lab ID=daily-03   work on any lab, in any order
Lane What you learn Run
start ask about the repo, run the gate, plan first, local memory make lab ID=start-01
daily resume work, scoped rules, skills, hooks make lab ID=daily-01
team deny rules, review rules, proof receipts, plugin packaging make lab ID=team-01
factory ticket to intent, acceptance first, dry run, workflow contract make lab ID=factory-01
advanced reviewer subagent, cost per call, worktrees, tree-wide checks make lab ID=advanced-01

4. Cloud sessions

5. Agent track

Learn the loop under the product and under Claude Code: one call, manual loop, tool runner, mini Claude Code, Agent SDK.

6. Electives

Each extends a level: agent teams, status line, fast mode, chrome, screenshots, ide, built-in help, loop and routines.

Reference

How the levels are kept correct

Levels are derived, not branches.

  • Everyone edits main. That is the only copy.
  • levels.json says which files each level adds. A test fails if any file has no owner or two owners.
  • make levels builds each level's copy from main and drops any hook that points at a script the level does not have yet.
  • CI generates every level, installs it, and runs its full gate.
  • Learners clone a dated release tag, such as workshop-2026-10. A tag never moves.

To fix something: change it on main, give new files an owner in levels.json, run make check, and release.

After the workshop

take-home.md is the assignment: multi-page worksheets, built through your own factory. make prove-homework stays red until your run builds them.