Run your first Hal loop

How do you run a first Hal loop safely?

Run a first Hal loop with one small requirement, a clean branch, validated stories, and a manual review before merge. The goal is not hands-off shipping. The goal is to learn the PRD-native sequence: initialize, plan, convert, validate, run, inspect, and decide what to keep.

1. Start from a clean branch

Create a branch for the experiment before the agent edits files:

git checkout -b hal-first-loop

A clean branch makes every generated change easier to review or discard.

2. Initialize Hal

Run the project setup command:

hal init

This creates the local workflow structure Hal uses for planning, validation, runtime state, and reviewable artifacts.

3. Plan a small requirement

Use a narrow feature that has a visible outcome:

hal plan "add a dark mode toggle with system preference detection"

Review the generated PRD or story output before moving forward. Look for ambiguous scope, missing constraints, and unclear acceptance criteria.

4. Convert and validate

Prepare runtime state and check story quality:

hal convert
hal validate

If validation reports unclear stories, fix the PRD before implementation. A vague story usually becomes a vague diff.

5. Run the implementation loop

When the plan is reviewable, run the loop:

hal run

Hal can run autonomous implementation iterations with the configured engine, but it should still leave state a developer can inspect.

6. Review before merging

Inspect changed files, commits, reports, tests, generated state, and remaining acceptance criteria. Revert or repair anything that does not match the PRD.

Use Hal to make agent work more structured, not to remove developer responsibility.

Verification and review rule

Before adopting Hal, verify the current source repository, install path, release notes, and supported engine behavior. A completed loop is reviewable agent output, not a guarantee that the code is safe to merge.

Related workflow links

Use the PRD readiness checker before planning, read the PRD-driven planning feature, and review whether Hal replaces code review before expanding to larger tasks.