Last verified 18 October 2026, with OpenCode Desktop 2.0.32. OpenCode Desktop and the model Space Bunny are free. Space Bunny keeps none of your prompts, but they leave your computer: use made-up plates in the chat. Python and its test tool unittest are free. Details for experts at the end of this book.

The idea in one page

• A spec is a list of decisions. SPEC.md has four parts: what changes (what a user will see), numbered rules, a must-not-change list (what current users rely on), and checks: an input file and its expected result for every rule.
• A test is a small program that runs the script on a test file and compares the result with a file of expected results. python -m unittest runs all of them and reports each as passed or failed.
• Writing the checks finds the gaps. You can write "handle a missing control" without deciding what that means. You can't write its expected result without deciding. In Plan mode OpenCode does this for you: write the check for every rule, and ask me where you can't.
• The answers are yours, and locked. You work out the expected results by hand. Two rules in opencode.json stop OpenCode from editing those files, so it can't make a failing test pass by changing the answer.
• Tests before code. OpenCode writes the tests from your checks. They fail, for one reason: the feature doesn't exist yet. You commit them before any code, so the history shows the answers came first.
• Review by rule, not by taste. Every changed block of code should implement a rule. A block that implements none is questioned, and removed unless it only describes.
• Your own slash commands. A small file in .opencode/commands/ turns a prompt you'd type every time into /check or /spec-review, for everyone who has the repository.

Watch it once (72 seconds)

No sound. A yellow dot points at each part while the caption explains it. Read the tour as text (opens in a new tab).

Worked example: a percent-of-control column

The lab example is told in full; the company version at the end shows what changes. Our run used OpenCode Desktop 2.0.32 and the free Space Bunny model. Your answers will be worded differently; what to look for is the same.

Step 1: Open a new session in the project. In OpenCode, click platereader-summary under Projects, then New session. If colleagues push to the repository too, first get their changes as in T19-L02 · Work on a Shared Gitea Repository From Your Computer With OpenCode.

You should see: on the new-session screen, platereader-summary and the branch label main below the message box, as in T08-L02.

Structure it

Step 2: Write down the request and what "good" means for every user. Mia writes it before she opens anything:

The second line names users who didn't ask for anything. They are the ones a change usually breaks.

Understand it

Step 3: Draft the spec. The project folder is platereader-summary inside your OpenCode workbench folder. Save text files there as in T08-L02: in Notepad choose All files so it doesn't add .txt; in TextEdit first choose Format → Make Plain Text; press Enter after the last line. Save this as SPEC.md. It is Mia's first draft, with its gaps; yours will have some too:

Version 1.1 is the version of the script this spec describes, not of the spec.

Step 4: Make three small test plates. Create a folder tests in the project and save three files there, in the same format as test_input.csv. plate_ctrl.csv, a normal plate with a control:

plate_badctrl.csv, a control that spreads widely, so R4 must warn:

plate_zeroctrl.csv, the same but with the control below the blanks, so R5 must stop:

Choose values like these on purpose: each file proves one rule.

Step 5: Ask Plan to write a check for every rule. Switch to Plan (Ctrl+.) and send:

You should see: a list of checks it could write, then a question box: 1 of 5 questions, each with options, one marked Recommended, and Type your own answer.

The first one changes what gets built: test_input.csv, the file the other groups run every week, has no control. Under R3 as written, their weekly run would stop. The Recommended answer would retire their check. None of the options is ours.

Step 6: Answer in the box. Ours, typed under Type your own answer where no option fitted:

1. Keep both. The column is only added when someone asks for it with --control NAME. Without the option the output stays identical to today: test_input.csv still gives expected_output.csv byte for byte. R3 only applies with --control.
2. Test files: No new fixtures. test_input.csv with --control ctrl is the R3 check. I write test files myself.
3. Messages: Both on stderr. R5: control 'NAME' has a blank-corrected mean of 0 or below (exit 1, no output folder). R4: WARNING: control ctrl CV 18,3% is above 15% - check before using pct_control, also written to warnings.txt in the results folder; exit 0.
4. Matching the name: Exact match on trimmed 'ctrl': CTRL is not ctrl.
5. A control at exactly 0: R5 message (Recommended).

Click Next after each, Submit after the last. Ours then asked four more:

We chose File first, then --control, warnings.txt not created unless there is a warning, the same line as stderr in it, and the control's name interpolated into the R3 message. It didn't ask how to round the percentage, so we said it ourselves, in Build:

Nobody had made any of these decisions. That's what a spec is for. Byte for byte means identical down to the last character. An option is an extra word you add to the command, here --control ctrl. Exit 1 means the script ends with an error code the tests can see. stderr is where a script prints its messages. A fixture is OpenCode's word for a test file.

Step 7: Read the spec it wrote, like code. Press Ctrl+Shift+R for the Review panel and read SPEC.md line by line.

Ours had two mistakes. OpenCode bumped the version to 1.2 on its own. And it grew the spec to 244 lines with eleven checks, two of which no test can run (source and repository state); Jonas would never read it. So we sent:

You should see: the corrections, and nine checks that read like this:

C2 is one we hadn't thought of: with --control A, sample A becomes 100,0 and the others move with it. In 2.0.16 the same request once turned the formula upside down; this time it was right, and we checked anyway.

The assistant writes the spec quickly and well, and it still makes mistakes you only catch by reading. A spec error is worse than a code error: the tests will check the wrong thing.

Step 8: Work out the answers yourself. In a spreadsheet, as in T08-L02: blank mean 0,052; subtract it; per sample, mean, CV = STDEV.S / AVERAGE × 100 (German Excel: STABW.S / MITTELWERT), and pct_control = sample mean / control mean × 100, from the unrounded means. Then create a folder expected inside tests and type two files there in Notepad or TextEdit; never save them from Excel, which changes the separators. plate_ctrl.csv:

plate_badctrl.csv:

OpenCode had already worked out these numbers in step 5. Ours matched; that's a bonus, not the check. The expected files come from your own calculation. C2's four lines stay in SPEC.md; you check them by hand too.

On Windows, Notepad ends each line the Windows way (its status bar shows Windows (CRLF)), and the tests compare byte for byte. Open the terminal panel (**Ctrl+**, or /terminal) and convert your answer files, including expected_output.csv` from T08-L02, with this one line:

It changes only the line endings. On a Mac, TextEdit already saves them the right way.

Step 9: Lock the answers. Save this as opencode.json in the project folder:

Each rule names an action (here edit), the files it applies to, and an effect: allow, ask or deny. Everything not named stays allowed. When several rules match a file, the last one wins. Then test the lock with a real change. Send:

You should see: Blocked and Permission denied: edit. Use a real change as the probe: our first try, add one empty line at the end, never reached the lock, because OpenCode's editing tool can't express that change. It worked at once, in the same session. AGENTS.md asks the assistant not to edit a file; opencode.json stops it. The lock covers OpenCode's editing tool. A command typed into the shell could still change a file, which is why you also look at the list of changed files in every review.

Choose tools

• OpenCode, Plan then Build, with Space Bunny Free and made-up plates.
• Python's unittest for the tests. It comes with Python, so Jonas installs nothing.
• opencode.json for the lock, and two custom commands for the checks you'll run again and again. Both are files in the repository, so every colleague gets them.

Build it: the checks before the code

Step 10: Have OpenCode write the tests. Still in Build, send:

You should see: C7 passes and eight fail, all for the same reason: the option doesn't exist yet. That's what you want. C7 passing proves the tests really run the script. Eight failing for one named reason proves they test something that isn't built. A test that passes before the code exists tests nothing. OpenCode also added an almost empty file, tests/__init__.py; without it, python -m unittest finds no tests in the tests folder and reports NO TESTS RAN.

You don't need to read the test code. You need to know that each test compares with your files, and that it fails now.

Step 11: Make a /check command. A folder name that starts with a dot is awkward to create by hand, and a Mac's Finder refuses it. So open the terminal panel and type mkdir -p .opencode/commands (it works in PowerShell, Git Bash and on a Mac). Then save this as check.md in that folder:

On a Mac, write python3 instead of python. The part between the dashes describes the command; agent: plan runs it in Plan, which doesn't edit files. The line starting with ! runs the tests when you use the command and puts their output into the message. @SPEC.md adds the spec. Type / in the message box.

You should see: /check with your description, right away. Next to it, OpenCode's own /review, which reviews uncommitted changes in general; step 18 makes one that reviews them against your rules.

Step 12: Run /check. Choose /check and press Enter twice.

You should see: 1 pass, 8 fail, each with the rule it protects. The agent label under the message box now says Plan: the command switched it. Switch back to Build (Ctrl+.) before the next step.

Step 13: Commit the checks before the code. Send:

__pycache__ is a folder Python creates when it runs the tests; it doesn't belong in Git.

You should see: the commit, and summarise.py is not in the commit. From now on the history shows that the answers and tests came before the code. Your AGENTS.md said no test framework, keep it that way, from T08-L02; now you've asked, so it must say so, or the next session follows the old rule.

Build it: plan, code, review

Step 14: Ask for a plan with a rule for every step. Switch to Plan and send:

You should see: numbered steps, each headed with the rules it implements. Ours had nine, from 1. Parse the option, M2 to the new column. A step without a rule is your cue to ask why. One step is worth noticing: it checks the control's mean before the loop that computes every sample, because that loop already stops on a mean of exactly 0 with an older message. R5's wording would otherwise never be reached.

Step 15: Read what it left out. Scroll to the end of the plan.

You should see: what it left out, and the calls it made on its own. Left out is what you asked for: things no rule covers. Decide on each. We wanted the script's own description (its docstring) and the usage line kept correct, and README and AGENTS.md updated at the end. Two calls I had to make are small new gaps: an empty name or the name blank both get R3's message. We accepted that.

Step 16: Build it. Switch to Build and send:

You should see: Ran 9 tests … OK and one changed file. Ours reported two mistakes of its own that it caught and fixed before the tests ran; read that part, it tells you where the code was fragile. If yours doesn't and asks to change an expected file, the lock refuses; answer that the code is wrong until proven otherwise.

Step 17: Look at the Review panel. Press Ctrl+Shift+R. The icons above the file switch between side by side and Unified diff, one column, which is easier to read.

You should see: Files Changed 1. Look at the file list before any code: a changed file in tests/expected/, a new file you didn't ask for, or a test file changed after step 13 is the first thing to question. Close the panel.

Step 18: Review it rule by rule with /spec-review. Save a second command as .opencode/commands/spec-review.md:

git diff lists every line changed since the last commit. Type /spec, choose /spec-review and press Enter twice.

You should see: every block with a rule, and the answer files unchanged. Ours found six blocks with no rule: all are descriptions or the option's own name, which stay. A block of code with no rule is the one that surprises a user six months later: remove it, then run /check.

Step 19: Run it yourself. Open the terminal panel (Ctrl+**, **Cmd+ on a Mac, or /terminal) and type:

Use today's date in the last line; on a Mac, type python3.

You should see: OK, the warning, and the same table as your tests/expected/plate_badctrl.csv. Afterwards delete the results-… folder inside tests in File Explorer (Finder on a Mac), so a rerun today isn't refused, and close the panel.

Hand it over

Step 20: Update the spec, the changelog and the README, and commit. /spec-review left the session in Plan: switch back to Build (Ctrl+.) and send:

You should see: one commit with summarise.py, the three files and .opencode/commands/spec-review.md. Ours swept in the command file and said so in the next step, suspecting a scratch file; it's meant for the whole group, so it belongs in the commit.

Step 21: Tag the version and push. A tag is a name for one exact state of the code. Send:

You should see: the tag on the commit with the code. origin is your Gitea copy of the repository. Git doesn't send tags with a normal push, which is why the prompt names it. Never move a published tag: if something is wrong, make a new version. Step 23 does exactly that.

Step 22: Name the session. Click ⋯ next to the session title, Rename, type Percent of control (1.1), Enter. Then click the square icon at the top left (Home).

You should see: one session per change, named after the version. Next year's question, why is the control matched exactly?, starts here.

Step 23: Watch Jonas rerun it, and fix what breaks. (Jonas's screen.) Jonas clones the repository on his Windows laptop, where Git was installed with its default settings, and runs python -m unittest. Three of nine fail. Those settings convert line endings to the Windows style on the way out of Git, so his tests/expected/plate_ctrl.csv no longer matches the script's output byte for byte. We reproduced exactly this with a Windows default clone. Back on Mia's computer, send:

Ours confirmed the cause first (exactly C1, C5 and C7 compare a checked-in file byte for byte), then wanted to try a Windows clone in a temporary folder outside the project:

You see this question only with the rule from T08-L01 in your workbench; without it, OpenCode goes ahead. Click Deny: a clone with your files outside the project is yours to check, not the assistant's. Deny ends the answer (Interrupted), so send the rest again:

You should see: a one-line file .gitattributes (* -text: never convert line endings), a new tag, and v1.1 unmoved. Ours also owned up to a scratch copy it had left in the temporary folder before the Deny; delete such copies (OpenCode tells you where). We checked the rest ourselves: a fresh Windows default clone passes all nine tests, and so does Jonas's old copy after git pull and the two commands above. Those two commands throw away anything changed in that copy, so he runs them only in a copy he hasn't edited. Or he simply clones again.

A colleague without Git clicks Releases, then Tags, then ZIP next to the newest version, and runs python -m unittest in the extracted folder: we did that too, and all nine passed. Lena then runs her real plate, kept outside the folder, with --control ctrl, and the two other groups run theirs without the option and get last week's layout.

You should see (on Jonas's computer): OK after nine tests. CHANGES.md answers what changed and why without anyone opening the code, and the version under every table Lena presents traces it to this exact code.

Company: returns per quarter

An illustration of how the same steps play out; we ran the lab version.

• Steps 2 to 4: the request is returns per product per quarter, compared with the same quarter last year. Test rows include returns on 31 March, 1 April, 30 June and 1 July, with made-up customer numbers.
• Step 5: Plan asks which quarter 31 March is in. Finance answers: the financial year starts on 1 April, so 31 March is Q4 of the previous year. It also asks what to do with a return date in the future; the answer becomes a rule: stop with the line number.
• Steps 10 to 16: the tests fail first; the first build puts 31 March into "Q0", and the boundary test catches it. The second attempt passes. /spec-review finds an "optional" export with English column names that no rule asks for; it's removed.
• Steps 20 to 23: version 1.2, because the quarterly table is new and the monthly report is unchanged. The repository is on the company's GitHub, where tags and ZIP downloads work the same way.
• Where it stops: when the head of quality wants the report to update itself every Monday, it needs a service account, a protected main branch and automatic checks. That's T08-L04 · Use OpenCode Desktop on Your Organisation's Real Repositories and T08-L05 · Run Automatic Checks, an AI Reviewer and Releases You Can Roll Back.

Working with OpenCode day to day

• Custom commands live in .opencode/commands/, one Markdown file each; the file name is the command. ! followed by a command in backticks runs it and inserts its output, @file inserts a file, and $ARGUMENTS inserts what you type after the command. Commit them: the whole group gets them.
• agent: plan in a command runs it in Plan, and leaves the session in Plan. Switch back before you ask for changes.
• opencode.json in the project is read at once and travels with the repository. It is the right place for locks the whole group needs.
• /review is OpenCode's own review of uncommitted changes; /spec-review is yours, against your rules. Use either before every commit.
• /fork starts a new session from an earlier message, when you want to try another way without losing this one.
• One session per version, named after it (step 22).

Where your build stops

A spec, locked answers, tests, tags and a colleague's rerun are enough for a script a few groups run by hand. Bring in your organisation's developers or IT, or move to Level 4, when:

• The code runs without a person: on a schedule, on a server, or triggered by another system.
• Other systems read its output directly: a dashboard, a database, the LIMS (the lab's sample-tracking system) or the ERP (the company's business system).
• Several people change the code, so changes need pull requests and someone other than the author approving them: T19-L03 · Propose, Review and Merge Changes With Pull Requests and T08-L04 · Use OpenCode Desktop on Your Organisation's Real Repositories.
• The tests should run on every change by themselves: T08-L05 · Run Automatic Checks, an AI Reviewer and Releases You Can Roll Back.
• A wrong result would reach a patient, a customer or a regulator. Then the rules need an accountable sign-off, not just yours.

What goes wrong

The spec leaves a decision open. Symptom: the result differs from your spreadsheet in the last digit, or a group's weekly run suddenly stops. Fix: ask Plan to write a check for every rule and to ask where it can't (step 5). Answer every question in the spec, not only in the chat.

The assistant's spec is wrong. Symptom: a formula upside down, a version changed, a spec nobody can read. Fix: read SPEC.md in the Review panel line by line, like code (step 7). The tests will faithfully check whatever the spec says.

The answers get changed to match the code. Symptom: a file in tests/expected/ appears in the Review panel. Fix: the lock in opencode.json (step 9) and the file list before the code (step 17). If it happened anyway, for example through a shell command, ask Build to restore tests/expected/ from the last commit and show git status.

No tests run. Symptom: Ran 0 tests or NO TESTS RAN. Fix: keep tests/__init__.py, and start python -m unittest from the project folder, not from tests.

The tests pass for you and fail for a colleague. Symptom: only the byte-for-byte checks fail, only on Windows. Fix: .gitattributes with * -text (step 23); a colleague's existing copy needs a fresh clone, or git pull and the two commands in step 23.

Your own answers fail. Symptom: C1, C5 and C7 fail on your computer though the numbers look identical. Fix: your answer files have Windows line endings from Notepad; convert them with the line in step 8.

Deny ends the answer. Symptom: after Deny, the answer stops with Interrupted. Fix: send the rest of the request again with stay inside this project folder (step 23).

Code with no rule. Symptom: /spec-review lists a block that implements nothing. Fix: remove it and run /check, or, if the group really needs it, add the rule and a check first.

A published version is changed. Symptom: the same tag points at different code on different days. Fix: never move a tag; make a new version with a CHANGES.md entry (step 23).

Do it yourself (2½ hours, two sessions)

1. Structure it (10 min): step 2, naming every current user.
2. Understand it (60 min): your draft spec and three small test files (steps 3 and 4); the gaps from Plan and the requester's answers (steps 5 and 6); read and correct the spec (step 7); your answers by hand, and the lock (steps 8 and 9).
3. Choose tools (5 min): where the tests live, which files to lock, which commands the group needs.
4. Build it, checks first (25 min): steps 10 to 13. Don't go on until the tests fail for one named reason and are committed.
5. Build it, plan and code (30 min): steps 14 to 19.
6. Hand it over (20 min): steps 20 to 22, then sit next to your colleague for step 23 and say nothing.

Exit check

What you hand in: a repository on your group's server with SPEC.md (rules, must-not-change list, one check per rule), test files and hand-worked expected results locked in opencode.json and committed before the code, tests that run with python -m unittest, the two commands in .opencode/commands/, .gitattributes, the changed script, a CHANGES.md entry, an updated README and a version tag.

It passes when your colleague, on their own computer and using only the README, gets OK from all tests, and can point to the rule in SPEC.md behind any changed block of code you show them.

Rule to remember

If you can't write the check, you haven't made the decision.

Details for experts

Checked on 18 October 2026. You don't need this to follow the book; it's for setting things up or answering a colleague.

Further reading and tools

• T08-L02 · Get a Script Your Colleague Can Rerun, Without Being a Developer: the script, README and known answer this book builds on.
• T08-L04 · Use OpenCode Desktop on Your Organisation's Real Repositories: team configuration, permissions and agents.
• T08-L05 · Run Automatic Checks, an AI Reviewer and Releases You Can Roll Back: tests on every change without anyone remembering.
• T19-L03 · Propose, Review and Merge Changes With Pull Requests: a second pair of eyes before a change goes in.
• T03-L03 · Put a Test Set Under the Prompt Your Team Depends On: the same known-answer idea for prompts.
• OpenCode: Taught. Plan and Build, questions, opencode.json permissions, custom commands, /review, the Review panel and the terminal.
• Git: Taught. Commits before code, tags and .gitattributes.
• Gitea: Taught. Tags and ZIP downloads for each version.
• GitHub: Catalogued. The same handover for the company variant.