Skip to content

Lab 1: Explorer -> Builder Workflow

Goal

Build a two-agent workflow where one agent investigates a bug and another agent implements the fix.

The point of this lab is not to create a complicated agent system. The point is to practice a clean hand-off: one agent explores, another agent builds.

What You Will Practice

  • Writing a bounded subagent request
  • Keeping investigation separate from editing
  • Turning an explorer report into a builder prompt
  • Checking whether a multi-agent workflow helped or added noise

Prerequisites

You should have completed Module 6 and created at least one custom subagent.

You also need a small repo to work in. Use a disposable copy of the course sample app:

mkdir -p ~/opencode-labs
cp -R labs/sample-repo-buggy-todo-app ~/opencode-labs/todo-app-module-07
cd ~/opencode-labs/todo-app-module-07
git init
git add .
git commit -m "Initial lab state"

If your local course copy does not include that lab repo yet, use any small project with a visible bug, failing test, or confusing behavior. Choose something small enough that one file or one feature area is probably involved.

Scenario

The todo API has a bug in its completion behavior.

Users report this:

When the API receives a task ID from an HTTP JSON body, it arrives as a string.
The app fails to complete an existing task because the data helper compares the string ID too strictly against numeric IDs.

You are going to solve this with two roles:

  • Explorer: read-only investigator. It finds the root cause and writes a plan.
  • Builder: edit-enabled implementer. It applies the plan and verifies the result.

Step 1: Create Or Choose An Explorer Subagent

Use an existing read-only subagent from Module 6, or create a new one.

Recommended explorer behavior:

You are an explorer subagent. Your job is to investigate code and report findings.
You do not edit files. You do not run destructive commands.
Return concise findings with file paths, line references when possible, and a short implementation plan.

Recommended permissions:

read: allow
bash: optional, only for safe inspection commands
write/edit: deny

If you are unsure whether bash should be allowed, deny it. You can still learn the workflow with read-only investigation.

Step 2: Write The Explorer Hand-Off

In OpenCode, ask the primary agent to delegate to the explorer.

Use a prompt like this:

@explorer Investigate the todo completion bug.

Reported behavior:
- Completing task id "1" for user "u1" returns no task, even though task 1 exists.
- The failing test is named "completeTask accepts an id from an HTTP JSON body".

Scope:
- Only inspect files related to task completion, request body parsing, and task ID comparison.
- Do not edit files.
- Do not review unrelated styling, package configuration, or tests unless they directly explain the bug.

Return exactly:
1. Suspected root cause
2. Files involved
3. Evidence from the code
4. A 3-step fix plan for a builder agent

Notice the contract:

  • The role is investigator.
  • The scope is todo filtering.
  • The permission expectation is no edits.
  • The output shape is fixed.

Step 3: Review The Explorer Report

Before you ask any agent to edit files, read the explorer's answer.

Check for four things:

  • Did it stay in scope?
  • Did it name specific files?
  • Did it give evidence, not just guesses?
  • Did it produce a builder-ready plan?

If the answer is vague, do not move to building yet. Ask a tighter follow-up.

Example follow-up:

@explorer Narrow the report to the task completion path only. Name the exact function that compares task IDs. Do not discuss unrelated task creation bugs.

Step 4: Convert The Report Into A Builder Prompt

Now ask the primary build agent, or a builder subagent, to implement the fix.

Use the explorer's output as the source of truth.

Implement the todo completion fix using only this explorer report:

<paste the explorer's 3-step plan here>

Constraints:
- Do not refactor unrelated files.
- Do not rename public functions unless the fix requires it.
- Keep the smallest correct change.
- After editing, run the narrowest available verification command.

Return:
1. Files changed
2. Verification run
3. Whether the reported bug is fixed

The builder should not re-open the whole problem. It should apply the plan unless it finds a clear contradiction.

Step 5: Verify The Result

Run the app or tests if the project supports it.

Run the focused test command if the project supports it:

npm test

The completion test should pass after the fix. Other intentionally failing tests may still fail if you only fixed this one bug.

Record the result in your notes.

Step 6: Draw The Message Graph

Write the workflow as a small graph.

Example:

User
  -> Primary agent
      -> @explorer: investigate filter bug, no edits
      <- Explorer report: root cause + 3-step plan
  -> Primary/builder: implement explorer plan
  <- Final report: files changed + verification

This graph is the simplest way to see whether the hand-off was clean.

Deliverable

Submit a short lab note with these sections:

# Lab 1 Notes

## Explorer Prompt

<the exact prompt you used>

## Explorer Report Summary

<root cause, files, evidence, plan>

## Builder Prompt

<the exact prompt you used>

## Result

<files changed and verification result>

## Message Graph

<your graph>

## Reflection

Did the explorer-builder split help? Why or why not?

Pass Criteria

You pass this lab if:

  • The explorer did not edit files.
  • The explorer report had a clear root cause and bounded fix plan.
  • The builder prompt used the explorer report instead of starting from scratch.
  • The final change was limited to the bug.
  • You verified the behavior or explained why verification was not available.

Common Mistakes

  • Asking the explorer to "fix" the bug.
  • Letting both agents edit the same files.
  • Giving the builder a vague prompt like "make it work."
  • Skipping verification because the agent sounded confident.
  • Treating the explorer's answer as correct without checking evidence.

Stretch Challenge

Add a third read-only reviewer after the builder finishes.

Prompt it like this:

@reviewer Review only the final diff for the todo filter fix. Do not suggest unrelated refactors. Return: correctness risk, missing test risk, and one improvement if needed.

Then decide whether the third agent improved the workflow or made it heavier than necessary.