Part 4 — Build the Harness Chapter 19
Repository Custom Instructions
In this chapter
You can answer a question about a spec in three places. The spec supplies the behavior. A command supplies the prompt you want to use each time. The permission rules decide whether that session can edit the spec or its contract.
Continue from the project-instructions exercise or start a new branch at lab-start. Create a short file at docs/review-guide.md.
In a contract review, include a row for state after rejection.
Name the assertion that observes it, or mark that row as unchecked.
Add "instructions": ["docs/review-guide.md"] as a top-level entry in opencode.jsonc. Keep the other entries. The configured file comes after the initial AGENTS.md sources. If the same convention exists twice, edit the files so the directions agree. The model receives combined text and still has to act on it.
Add a command that starts from a spec
Save this template as .opencode/commands/check-spec.md. OpenCode expands $ARGUMENTS when you run the command. The frontmatter selects Plan.
---
description: Match a Task API spec to its contract checks
agent: plan
---
Read the spec at $ARGUMENTS and the related acceptance test.
Return a row for each criterion with a check and expected result.
Flag any criterion without a check. Leave files unchanged.
In a fresh session, run the command.
/check-spec specs/registration-validation.md
Look for reads of both the spec and contracts/registration.test.ts. Check the description of the next-ID assertion and its relationship to state after rejection. If the answer invents a test for the exact 100-character limit, look for that input in the file and correct the report.
Keep permissions in the config
The project configuration asks approval for shell commands and allows specific test commands. OpenCode checks matching permission rules in order and uses the last match. Agent-specific rules come after shared rules. Keep the broad rule above its narrow exceptions.
In your exercise branch, append this object to the project permissions array.
{ "action": "edit", "resource": "contracts/*", "effect": "deny" }
Open a fresh Build session and ask it to attempt to add a harmless comment to contracts/registration.test.ts using the edit tool. The edit should be blocked. Inspect the tool event and run git diff -- contracts/ yourself. A prose refusal gives you no evidence that the permission was checked. Use the tool status and the diff together. End the test session before giving the agent a real implementation task.
Keep /check-spec and the review guidance together if you want to reuse them. The exercise edit rule is an independent choice about what role can reach contract files.
References
- OpenCode maintainers. Instructions, instruction configuration, Commands, Permissions, and permission rules. Official OpenCode 2 documentation.