Run a PRD-driven coding loop with Hal

Before you start

Use this guide when a feature is large enough to need requirements, reviewable state, and repeated implementation iterations. A PRD-driven loop is most useful when the agent needs more than a one-shot code change.

You need:

• Hal installed on your machine
• a target repository where the feature should be implemented
• a product requirements document or enough context for Hal to help plan one
• time to review generated state, code changes, and validation output

Hal is designed to coordinate AI coding agents. It does not remove the need for human review, testing, or release judgment. Before you run the loop, decide which checks are mandatory, which files or modules are in scope, and what counts as a successful iteration.

The clearer the PRD, the less the agent has to infer. Include the user problem, expected behavior, edge cases, non-goals, dependencies, and validation commands whenever possible.

Steps

1. Install Hal:

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

2. Open the repository where you want the feature implemented.

3. Initialize the workflow files:

   hal init

4. Create or capture the PRD:

   hal plan

5. Convert markdown requirements into structured runtime state:

   hal convert

6. Validate the workflow before execution:

   hal validate

7. Run implementation iterations:

   hal run

Verify it worked

A healthy loop should leave behind reviewable workflow state and implementation output. Before release, check the PRD, generated plan, changed files, command output, tests, and any manual acceptance criteria that the agent could not verify on its own.

Review the loop before release

A PRD-driven loop is strongest when every iteration has a clear review boundary. Check that the agent changed only files relevant to the requirement, did not silently broaden scope, and left enough context for a future maintainer to understand why the change exists.

Use the PRD as the acceptance checklist. Confirm required behavior, non-goals, edge cases, and validation commands. If the implementation adds public copy, pricing statements, security claims, or competitor claims, run a separate claim review before publishing. If tests fail or validation output is ambiguous, update the PRD or implementation state before asking the agent to continue.

For a one person company, the goal is leverage without losing control. Hal can coordinate the loop, but the founder still decides whether the product behavior, UX, and release risk are acceptable.

Common issues

• If Hal is unavailable after install, open a new terminal session.
• If validation fails, fix the PRD or structured state before running the coding loop.
• If the agent output is not acceptable, review the iteration artifacts before continuing.
• If the PRD is vague, add explicit user stories, constraints, non-goals, and acceptance criteria.

Related pages

• Hal product page
• PRD-driven development
• AI coding agent
• Run PRD-driven coding agents

Sources

• Hal source repository
• Homebrew documentation
• Atlassian: Product requirements document
• Last checked: 2026-05-09