Plan, build, review

Project 2: HADR agent

Use the same workflow for each change in this course:

  1. Read the requirements.
  2. Ask Claude for a plan.
  3. Review the plan.
  4. Ask Claude to build the change.
  5. Run the tests.
  6. Ask a teammate to review the pull request.
  7. Merge the pull request.

In this activity, you will use this workflow to build the report store and the incident store.

Expected result

At the end of this activity, each participant must have:

  • a working ReportStore;
  • a working IncidentStore;
  • all 11 supplied @warmup scenarios passing;
  • all pytest tests passing; and
  • two pull requests that a teammate approved before the merge.

Do not build intake, report matching, dispatch, or replanning in this activity. You will build these parts later in the course.

Use Claude safely

Claude can write code quickly. Claude can also write incorrect code. You must control the scope and check the result.

  • Give Claude a clear outcome and clear limits.
  • Ask Claude to read the repository before it makes a plan.
  • Do not let Claude edit code until you approve the plan.
  • Keep each change small.
  • Check the code and the test results.
  • Put permanent repository rules in CLAUDE.md.
  • Put repeatable checks in hooks.
  • Use /rewind if you must remove an incorrect change.
  • Use @claude as a second reviewer. A teammate must still make the approval decision.

You can use plan mode for the planning step. You can also publish a plan or report as an Artifact.

Write the product brief

Project 1 introduced product interviews and PRDs. Do not repeat the full interview here. Use the evidence from MCP Play to agree on the HADR operator’s first need.

As a team, review your two play transcripts and answer:

  • Which decision was hardest?
  • Which missing or unreliable information caused it?
  • What was the most serious failure?
  • Which decisions can the agent make, and which require a person?
  • How will you measure a useful result?

Then ask Claude:

Use our MCP Play evidence to write a one-page HADR product brief. Include the operator, supported decision, unreliable information, most serious failure, human control points, success measures, and non-goals. Cite the observed play failure behind each important requirement. Do not include implementation details.

Review the brief as a team. Remove each statement that the team cannot support. Keep the agreed text. Each participant will add it to the report-store branch as product-brief.md.

The product brief gives product context. It is not the technical specification for this activity.

What you will build

The report store holds evidence from public contacts. A stored report does not change. You will implement these methods:

  • add;
  • get;
  • all; and
  • find_reports.

The incident store holds the agent’s current beliefs. An incident can change when the agent receives more evidence. You will implement these methods:

  • open;
  • get;
  • all;
  • find;
  • update;
  • link; and
  • close.

The starter supplies the data classes and the method signatures. Keep each store as a dictionary with a JSON log.

Do not decide how a report maps to an incident. You will make this decision in the later reconciliation activity.

Understand the supplied specification

The starter repository already contains the technical specification. Do not ask Claude to write a second specification.

The specification has two parts:

  1. The Gherkin files define the required behavior.
  2. The method docstrings define the detailed contracts and edge cases.

Read these files before you write code:

  • features/reports.feature
  • features/incidents.feature
  • features/steps/report_steps.py
  • features/steps/incident_steps.py
  • features/steps/common_steps.py
  • src/hadr_agent/stores/reports.py
  • src/hadr_agent/stores/incidents.py

A Gherkin scenario gives one example of required behavior:

  • Given defines the initial state.
  • When defines the action.
  • Then defines the expected result.

Behave runs each scenario as an acceptance test. Gherkin states what the code must do. It does not state how to implement the code.

The supplied scenarios are the minimum requirements. Do not delete them or make them less strict.

Check the starting state

Course setup instructed you to clone the course starter into your own private repository. Run these commands in that repository:

uv sync
uv run pytest
uv run behave --tags=@warmup

pytest must pass. The @warmup scenarios must fail because the store methods are not implemented.

If Behave reports No module named 'hadr_agent', run uv sync in the repository and try again.

Do not run uv run behave as the completion check. That command also runs scenarios for later course activities.

Each participant works in a separate repository. Give your teammates permission to review your pull requests. Never share your OpenCode key.

Add a team scenario

As a team, compare the product brief with the supplied store scenarios. Look for one important store behavior that the supplied scenarios do not test.

Add one scenario only if it meets these conditions:

  • It supports a decision or constraint in the product brief.
  • It applies only to the report store or the incident store.
  • You can test it without intake, report matching, dispatch, or replanning.
  • You can explain the failure that it prevents.

Examples of correct scope include:

  • a search includes a report that is exactly on the radius boundary;
  • a search includes reports on the start and end ticks;
  • closing an incident stores the reason and the update tick;
  • an update with an unknown field causes an error; or
  • an update does not remove linked report IDs.

Do not add a scenario only to complete this step. Use the supplied scenarios if the product brief does not identify a missing store behavior.

If the team adds a scenario, each participant must add the same scenario to the applicable feature file. Add or change a step definition only when the scenario needs it. Run the feature and make sure that Behave does not report an undefined step.

Build the report store

Complete the report store first.

1. Create a branch

git switch master
git pull
git switch -c feat/report-store

Add the agreed product brief to this branch as product-brief.md.

If the team added a report scenario, add it to this branch before Claude changes the store.

2. Ask for a plan

Start Claude in the repository. Use this request:

Read features/reports.feature, features/steps/report_steps.py, features/steps/common_steps.py, and src/hadr_agent/stores/reports.py. The Gherkin scenarios and method docstrings are the specification. Propose a small implementation plan for ReportStore. Do not edit files. Keep the dictionary store and the JSON log. Do not change later-stage code.

Review the plan. Check these items:

  • It covers STORE-R1 through STORE-R5.
  • It covers the team scenario, if the team added one.
  • It follows each method docstring.
  • It keeps reports immutable.
  • It does not add unrelated behavior.
  • It includes the correct test command.

Reject or correct the plan if one of these items is missing. Approve the plan only when you can explain it.

3. Build and test

Ask Claude to implement the approved plan. Then run:

uv run behave features/reports.feature
uv run pytest
git diff --check

Read the code changes. Do not change a supplied scenario only to make a test pass.

If a test fails, ask Claude to explain the cause before it changes the code. Repeat the tests after each correction.

4. Review and merge

Commit the change and push the branch. Open a pull request to your own master branch.

List STORE-R1 through STORE-R5 in the pull request. Also list the team scenario if you added one. Include the test commands and their results.

Ask @claude to review the pull request. Then ask a teammate to check:

  • the behavior in the Gherkin scenarios;
  • the edge cases in the method docstrings;
  • changes outside the report store;
  • changes to tests; and
  • the test evidence.

Correct each valid problem. Run the tests again. A teammate must approve the pull request before you merge it.

Build the incident store

Merge the report-store pull request before you start this unit. Then create the next branch:

git switch master
git pull
git switch -c feat/incident-store

If the team added an incident scenario, add it to this branch before Claude changes the store.

Use the same plan, build, test, and review process. Use this planning request:

Read features/incidents.feature, features/steps/incident_steps.py, features/steps/common_steps.py, and src/hadr_agent/stores/incidents.py. The Gherkin scenarios and method docstrings are the specification. Propose a small implementation plan for IncidentStore. Do not edit files. Keep the dictionary store and the JSON log. Do not change later-stage code.

The plan must cover STORE-I1 through STORE-I6 and the team scenario, if the team added one.

Run these checks after Claude implements the approved plan:

uv run behave features/incidents.feature
uv run pytest
git diff --check

Open a second pull request. List STORE-I1 through STORE-I6 and the test results. Ask @claude and a teammate to review it. Correct valid problems and run the tests again. Merge only after a teammate approves it.

Optional review test

Do this only after you complete the required work. Ask a teammate for permission before you create the pull request.

Open a pull request that contains one deliberate error. For example, remove a test or add an incorrect return value. Do not use a real secret. The pull request must not merge.

Ask @claude to review the pull request. Compare its findings with the teammate’s findings. Close the pull request. Post the error and the review result to the Padlet.

Completion check

Pull a current copy of your own master branch. Then run:

git switch master
git pull
uv run behave --tags=@warmup
uv run pytest

You are finished when:

  • STORE-R1 through STORE-R5 pass;
  • STORE-I1 through STORE-I6 pass;
  • each added team scenario passes;
  • pytest passes;
  • the report and incident pull requests have teammate approval; and
  • no later-stage code changed.