diff --git a/README.md b/README.md index 7f08e3e..514369a 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,16 @@ Go top to bottom. The full map with every link is [docs/README.md](docs/README.m 5. Agent track and electives: [docs/README.md](docs/README.md#5-agent-track). 6. After the workshop: [take-home](docs/take-home.md). +## Use this template + +This repo is a GitHub template. Click "Use this template", then set these in your copy before CI is useful: + +- Secret `CLAUDE_CODE_OAUTH_TOKEN` (your own subscription) or `ANTHROPIC_API_KEY` (a team workspace key). The review job needs one; without it that job fails and the rest still run. See [auth modes](docs/factory/auth-modes.md). +- Labels `factory:triage`, `factory:planned`, `factory:ready`, `plan:approved` and `assignment`. The factory moves a ticket between them. +- `levels.json` owns every file a level ships. A new source file needs an owner there, or `make check` fails. + +Teaching it? Use the [run of show](docs/run-of-show.md). + ## Install the factory in your own repo ``` diff --git a/docs/README.md b/docs/README.md index 9d4f152..53a329c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,6 +2,8 @@ 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. +Teaching a room? Open the [run of show](run-of-show.md). + ## Set up 1. `make doctor` checks your machine. diff --git a/docs/factory/f13-spend-and-safety.md b/docs/factory/f13-spend-and-safety.md index 60b5483..9556c11 100644 --- a/docs/factory/f13-spend-and-safety.md +++ b/docs/factory/f13-spend-and-safety.md @@ -105,6 +105,17 @@ printf '%s' '{"tool_input":{"command":"cat .env"}}' > /tmp/call.json && node .cl Expect the "Blocked" message and `exit 2`. Your own Claude Code session may refuse to run this line for the same reason. If so, run it in a plain terminal. +## When a CI agent fails at zero dollars + +A review job can fail while the account shows credit. Four things this repo hit: + +- **"Credit balance is too low".** The API key's balance did not cover the Claude Code client in CI. `review.yml` uses `CLAUDE_CODE_OAUTH_TOKEN` for that reason. Check the error text before you top up anything. +- **A shared token is not individual use.** A team should put an API key from its own workspace in the secret ([auth modes](auth-modes.md)). +- **`push` events are refused** by the review action. Trigger it on `pull_request`, as `review.yml` does. +- **`show_full_output: true` leaks.** It prints the agent's tool output into a public log. Never merge it to a public repo. + +A failed agent job is a signal, not a blocker: the gate jobs do not depend on it. + ## Discussion - The run cap stops new calls at 75 percent by default, and the last call can still use the rest. Is that the share you would choose, and is `capUsd` an amount you would accept losing on a bad night? diff --git a/docs/run-of-show.md b/docs/run-of-show.md new file mode 100644 index 0000000..d1452cd --- /dev/null +++ b/docs/run-of-show.md @@ -0,0 +1,36 @@ +# Run of show + +Two workshops share this repo. Pick the one you teach. Every block has one live command and a fallback if it misbehaves. + +Before the room fills: `make doctor`, `npm ci`, `make check`. Fallback for a slow laptop: `make levels LEVEL=` writes a finished copy to `supplied//`. + +## Claude Code, beginner to pro + +Learners run `make lab PATH_ID=pro` once. Lanes: `start`, `daily`, `team`, `advanced`. + +| Block | Teach | Live command | Fallback | +| -------- | ---------------------------------- | ------------------------- | ---------------------------------------------------- | +| Open | the app and the gate | `make check` | read `docs/README.md` aloud | +| Start | ask, plan first, local memory | `make lab ID=start-01` | [walkthrough-start](labs/walkthrough-start.md) | +| Daily | rules, skills, hooks | `make lab ID=daily-01` | [walkthrough-daily](labs/walkthrough-daily.md) | +| Team | deny rules, review rules, plugin | `make lab ID=team-01` | [walkthrough-team](labs/walkthrough-team.md) | +| Advanced | reviewer subagent, cost, worktrees | `make lab ID=advanced-01` | [walkthrough-advanced](labs/walkthrough-advanced.md) | +| Close | what to take home | `make progress` | [take-home](take-home.md) | + +Individuals work at their own pace with `make next`. A team splits by lane and compares `make progress`. + +## Software Factory + +Learners run `make lab PATH_ID=factory` once. Lanes: `start`, `daily`, `factory`. + +| Block | Teach | Live command | Fallback | +| -------- | ------------------------------------ | -------------------------------------- | -------------------------------------------------- | +| Open | the path from ticket to merged PR | `make factory ISSUE=1 FLAGS=--dry-run` | [F0](factory/f0-overview.md) | +| Contract | intent, acceptance first | `make lab ID=factory-01` | [walkthrough-factory](labs/walkthrough-factory.md) | +| Checks | evidence the model cannot argue with | `make lab ID=factory-05` | read [F4](factory/f4-test.md) | +| Review | three voters, two needed | `make lab ID=factory-06` | read [F5](factory/f5-review.md) | +| Maintain | a metric outside its band | `make lab ID=factory-07` | read [F7](factory/f7-maintain.md) | +| Spend | caps, keys, hooks | `make factory ISSUE=1 FLAGS=--dry-run` | [F13](factory/f13-spend-and-safety.md) | +| Close | pick an assignment | `make progress` | [F10](factory/f10-assignments.md) | + +Individuals use the dry run and never need a key. A team that runs live uses a workspace API key with a spend limit, and reads [when a CI agent fails at zero dollars](factory/f13-spend-and-safety.md#when-a-ci-agent-fails-at-zero-dollars) first. diff --git a/levels.json b/levels.json index c3cef48..2f37b71 100644 --- a/levels.json +++ b/levels.json @@ -194,6 +194,7 @@ "scripts/prove/sharing.ts", "docs/levels/sharing.md", "docs/when-to-use-what.md", + "docs/run-of-show.md", "tests/structure/when-to-use-what.test.ts", "docs/recordings/sharing.cast", "docs/recordings/sharing.gif",