Quickstart

Run your first Hal loop

Start with a small requirement on purpose. Initialize the repo, plan the work, validate the stories, run the loop, and inspect every change before merging.

1. Install Hal

brew tap j-yw/tap && brew install --cask hal

2. Initialize a repository

hal init

This creates the local Hal workflow files used to plan, validate, run, and preserve loop state.

3. Plan a small requirement before code

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

Keep the first task narrow enough to review in one sitting. If the plan feels too broad, split it before running implementation.

4. Convert, validate, and run the loop

hal convert
hal validate
hal run

5. Review before merging

Inspect changed files, commits, test output, reports, and any remaining stories. Hal can run the coding loop, but the human still owns acceptance.