Lab 7.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 Week 6 and created at least one custom subagent.

You also need a small repo to work in. Use the course sample app if it is available:

labs/sample-repo-buggy-todo-app

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 app has a bug in its filtering behavior.

Users report this:

When I click "Active", completed todos sometimes still appear.
When I click "Completed", active todos sometimes still appear.

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 Week 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 filter bug.

Reported behavior:
- "Active" sometimes shows completed todos.
- "Completed" sometimes shows active todos.

Scope:
- Only inspect files related to todo state, filtering, and rendering.
- 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 filtering logic only. Name the exact function or component that decides whether a todo appears. Do not discuss styling or storage.

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 filter 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.

If there is no test suite, do a manual verification:

1. Create one active todo.
2. Create one completed todo.
3. Click All and confirm both appear.
4. Click Active and confirm only the active todo appears.
5. Click Completed and confirm only the completed todo appears.

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 7.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.