Factory
Pages

5. Build your first task

This page takes one small change from an idea to a merged pull request. You press each button of the factory once. The reason is to prove that the checks work, so choose something small. Your part takes about 20 minutes.

You start with: the Factory tab of your hub open in Herdr, and the first task from the last page.

You finish with: a merged pull request, a task at done, and proof that a bad change fails the checks.

The examples use a health check. Use it if your list has no other small task.

#The steps

  1. #Press New

    Press New at the top right of the panel. A tab named New work opens, with an intake session. It asks what the new work is. Paste this:

    A health check. GET /health returns 200 with {"status":"ok"}, with no login. Keep it small, and don't check the database.

    The agent says the work again in its own words, and asks if that is right. It can ask up to three questions at a time.

    You should see: the agent names a new file, tasks/T-001-health-check.md, and tells you that the next step is probe. A card appears in the Draft column.

    Type /exit to close the session.

  2. #Press Probe

    Click the card. Press Probe, then Follow in a tab.

    The agent reads the task and the code. It finds what the task leaves open, and asks you in numbered questions, with a recommended answer for each one. For the health check, it can ask if the route must ignore a login token, so that it never reads the database.

    Its last question is which agent builds the task. Accept the default.

    You should see: the status changes to ready. The card moves to Ready. Type /exit.

  3. #Press Build

    Open the card, and press Build. You do not need to watch this session. A small task takes about 5 minutes.

    The agent makes a branch, writes the code and the tests, runs lint, types and tests, and opens a pull request. Then it writes its evidence in the task.

    You should see: the card moves to Review, with a PR 1 mark. It can take up to a minute to move.

    If the card moves to Draft with the status blocked, the build needs your decision. Press Probe, answer it, then press Build again.

    Open the session, read its last message, and type /exit.

  4. #Read the pull request

    Press GitHub ↗ on the card. Wait about 3 minutes for the two checks.

    CheckIt passes when
    ci/codebuildLint, types and tests pass
    flow/reviewThe review has no critical or major finding

    Each finding of the review is a comment on its line. Read the diff, as you read any pull request. The task file has the evidence for each acceptance criterion, under ## Evidence.

  5. #Ask for changes, if you want any

    Write comments on the pull request, then press Triage. It reads your comments and the findings, and answers on the pull request. For a change, it sets the task to ready, and the card moves to Ready.

    Then press Build. It works on the same branch. Then press Review, because a push does not run the review again.

    Close each session with /exit before you press its button again. While a session is open, the button only says that it is running.

  6. #Merge

    When both checks pass and you are happy, merge the pull request on GitHub. The panel has no merge button.

  7. #Press Accept

    In the panel, press Refresh. The card now has an Accept button. Press it, then Follow in a tab.

    The agent shows the goal and the evidence, and asks you to accept or reject. Then it shows each item under ## Context changes, such as a new rule. You accept, change or drop each one. Only what you accept reaches context/.

    You should see: the card moves to Done. Any work that the build noticed and did not do is now in the Inbox tab. Type /exit.

  8. #Prove that a bad change fails

    Now check that a gate stops a bad change. In the app, add a test that fails on a new branch, and open a pull request:

    cd ~/code/fieldnote/fieldnote
git switch -c gate-test

    Add a failing test, then commit and push it, and run gh pr create --fill.

    You should see: ci/codebuild turn red after about 2 minutes. Close the pull request, and delete the branch:

    gh pr close --delete-branch

#You are done when

  • The task is in Done.
  • ci/codebuild went red on a bad change, and green on a good one.
  • flow/review ran on a pull request.

#Next

You trust the checks now. Go to 6. Explore.