Skip to content

Lab 4.2: Peer Test a Custom Command

Goal: Share one command with a peer, watch them try it cold, and improve the command based on what confused them.

Time: 45–60 minutes.

What you'll learn: - Why commands need testing by someone other than the author. - How to spot vague templates and missing assumptions. - How to iterate without making a command too complicated. - How to collect useful feedback from a peer.

Why Peer Testing Matters

Your command may work for you because you know what you meant.

Your peer does not have that context. That is the point.

If your peer runs /write-tests lib/db.js and gets confused, the command has taught you something. Maybe the description is vague. Maybe $ARGUMENTS is unclear. Maybe the command edits too soon. Maybe it assumes a test framework that is not in the repo.

Good commands are not just prompts. They are shared instructions.

Beginner-Safe Warnings

Use a safe testing setup:

  • Do not test on a private or production repo. Use the sample to-do app or a throwaway branch.
  • Do not share commands that include secrets, tokens, client names, or private paths.
  • Do not approve edits blindly during your peer's test. The peer is testing the command, not racing to ship code.
  • Do not let the agent commit unless the lab explicitly requires it. For this lab, it does not.
  • Keep the first iteration small. Improve the command template before adding new agents, models, or shell injection.

Roles

Pair up with another learner.

You will take turns in two roles:

Role Job
Command author Shares one command and watches silently at first
Peer tester Runs the command without extra explanation and says what is confusing

Switch roles halfway through if time allows.

Part 1: Choose One Command to Test

Pick one command from Lab 4.1.

Good choices:

  • /explain-file because it should be safe and read-only.
  • /write-tests because it reveals whether approval and testing instructions are clear.
  • /changelog because it reveals whether the output format is useful.

Avoid testing all three at once. One command tested well is better than three commands skimmed.

Prepare this handoff note for your peer:

Command name: /write-tests
Example invocation: /write-tests lib/db.js
What I expect it to do: Inspect the file, propose tests, ask before editing, then run tests.
What I do NOT want it to do: Rewrite production code or commit changes.

Do not explain more than this before the first run. You want to see what the command communicates on its own.

Part 2: Peer Runs the Command Cold

The peer tester opens the sample repo:

cd ~/Documents/opencode-course/labs/sample-repo-buggy-todo-app
opencode

The command author shares the command config or makes sure it is available in .opencode/opencode.jsonc.

The peer tester runs the example invocation, such as:

/write-tests lib/db.js

The command author should mostly watch. Do not explain every step. Take notes on what happens.

The peer tester should think aloud:

  • "I expected it to ask before editing."
  • "I do not know what argument it wants."
  • "The output is too long."
  • "It picked the wrong test command."
  • "This is clear. I know what to approve."

Part 3: Collect Feedback

After the first run, answer these together.

For the Peer Tester

  1. What did you think the command would do before running it?
  2. Did the result match that expectation?
  3. Was the command name clear?
  4. Was the example invocation clear?
  5. Did the agent ask for approval at the right time?
  6. Did the output format help you decide what to do next?
  7. What is one sentence you would add to the template?

For the Command Author

  1. What assumption did I make that my peer did not share?
  2. Did the command do too much, too little, or the right amount?
  3. Was $ARGUMENTS used clearly?
  4. Did the command stay within its intended safety level?
  5. What is the smallest change that would improve it?

Write the answers down. Do not rely on memory.

Part 4: Iterate the Command

Make one small edit to the command template.

Good edits:

  • Add a clearer argument instruction.
  • Add "do not edit files" to read-only commands.
  • Add "ask for approval before editing" to build commands.
  • Add an output format.
  • Add a verification step.

Avoid these edits for now:

  • Adding five new responsibilities.
  • Switching to a stronger model just because the wording was unclear.
  • Turning a simple command into a custom agent.
  • Adding shell injection before the basic prompt is reliable.

Example iteration:

Before:

"template": "Write tests for $ARGUMENTS"

After:

"template": "Write tests for $ARGUMENTS. First inspect existing tests and list the missing behaviors. Ask for approval before creating or editing files. After editing, run the relevant test command and report pass/fail."

Notice what changed: the new version tells the agent the order of work, the approval point, and the verification step.

Part 5: Retest

Restart OpenCode if needed so it reloads the config.

Run the same command again with the same argument.

Compare the two runs:

Question First Run Second Run
Did the peer understand the command?
Did the agent stay in scope?
Did it ask before editing?
Was the output useful?
What still needs improvement?

You do not need perfection. You need evidence that the second version is clearer than the first.

Success Criteria

You are done when:

  • A peer has run one of your commands without extra explanation.
  • You collected at least three pieces of feedback.
  • You changed the command template based on that feedback.
  • You retested the same command after the change.
  • You can explain why the second version is better.
  • The command does not expose secrets or perform unsafe edits.

Troubleshooting

Q: My peer cannot run my command. A: Check that the command is in the repo's .opencode/opencode.jsonc, the JSONC syntax is valid, and OpenCode was restarted after saving.

Q: The command works on my machine but not my peer's. A: Look for hidden assumptions: file paths, installed dependencies, branch state, test command names, or global commands in your home config. For shared commands, prefer project-local config.

Q: The peer gives vague feedback like "it's fine." A: Ask more specific questions: "What did you expect before pressing Enter?" and "At what point did you know what to do next?"

Q: The command did something unsafe. A: Stop the run. Do not approve edits. Add stricter language such as "Do not edit files" or "Ask for approval before editing." If files were changed, ask your instructor before undoing anything you do not understand.

Q: The command got worse after iteration. A: Revert only your command-template change, not unrelated work. Then make a smaller edit. Usually the problem is that you added too many instructions at once.

Reflection Notes

Before you finish, write 5–7 sentences:

  • What did your peer misunderstand?
  • What did you change?
  • Why is the new version better?
  • What would you test next if you had more time?

Keep these notes for the Week 4 reflection.

Key Insight

A command is reusable only if someone else can run it correctly.

If it only works when you stand beside the user and explain what you meant, it is not finished yet.