Skip to content

README.md

Latest commit

 

History

History
126 lines (94 loc) · 10 KB

README.md

File metadata and controls

126 lines (94 loc) · 10 KB
Raw

Workshop map

One app, Worksheet Studio, with two workshops: Claude Code, beginner to pro, and the Software Factory. Both share the levels and the labs. Pick yours with make lab PATH_ID=pro or make lab PATH_ID=factory, then take its parts in order.

Learning on your own or with a team? Follow learn in two days, then keep the patterns.

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
Auth modes sign in with an API key or a subscription token docs/factory/auth-modes.md
Visual guide the factory in pictures docs/factory/visual-guide.md
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. Step-by-step walkthroughs: start, daily, team, advanced, factory. Progress sits in .labs/, which git ignores.

make lab PATH_ID=pro   choose your workshop once (pro or factory)
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 GUESS="..."   save your guess to the Predict question before you run
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

Which lab goes with which module:

Lab Module
factory-01 F1 Plan
factory-02 F2 Design
factory-03 F3 Build
factory-04 F8 Workflows
factory-05 F4 Test
factory-06 F5 Review
factory-07 F7 Maintain
advanced-05 F11 Cloud sessions

Modules with no lab yet are read-only: F0, F6, F9, F10, F12 and F13.

4. Cloud sessions

F11 to F13 are in the table above. Read F13 before you leave a session unattended, and pull a finished session back with claude --teleport <session-id>.

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.