haft

First Steps

You've installed haft and run init. Now what?

Ask the agent to explain itself

The fastest way to learn haft is to ask your AI agent:

/h-reason explain how to work with haft
effectively — what commands exist, when to use
each one, and what's the recommended workflow

The agent has full knowledge of all haft tools and will walk you through them in context of your specific project. This is not a canned tutorial — it's a live conversation with an agent that understands both haft and your codebase.

Existing project? Run onboarding

If you're adding haft to a project that already has code, architecture docs, or ADRs: 

/h-onboard

The agent will:

  • Scan your README, architecture docs, ADR directories
  • Record discovered decisions as notes
  • Frame unresolved architectural tensions as problems
  • Run module coverage analysis (which parts of your codebase have decisions, which don't)
  • Suggest what to tackle first

Have existing specs or design docs in a gitignored folder? Point the agent to them: "scan the docs in .specs/ and record what you find." The agent can read any file in your project — it's not limited to git-tracked files.

Set up a project prompt for better results

haft works without any project-level prompts. But adding a prompt file with haft-aware instructions makes the agent significantly better at using the tools proactively. See Agent Prompt Setup for details. 

# Claude Code
curl -fsSL https://raw.githubusercontent.com/m0n0x41d/quint-code/main/CLAUDE.md > CLAUDE.md

# Cursor → .cursorrules, Codex → AGENTS.md (same content, different filename)

This file teaches the agent: communication style (direct, no cheerleading), thinking principles (weakest link analysis, reversibility checks), the FPF decision workflow, and key concepts like R_eff and evidence decay.

Adapt it to your project — remove sections that don't apply, add project-specific context. The haft-specific sections (FPF Mode, Commands, Glossary) are the important parts.

Two ways to make decisions

Quick mode: /h-reason

The fastest way. Describe your problem, the agent handles the rest: 

/h-reason we need to add caching to our API.
Latency matters, team is 3 people, we're on AWS.

The agent frames the problem, generates options, compares them, and records the decision — all in one conversation. Good for getting started and for decisions where speed matters more than thoroughness.

Honest trade-off: /h-reason runs the entire cycle in one conversation. With long context, the agent can lose focus — comparison criteria may blur, variant generation may become superficial, the verification gate may get rushed. This is not a haft limitation; it's how LLMs work with large prompts. The context fills up, and quality at each step can degrade.

Full manual cycle (recommended for important decisions)

For decisions that are hard to reverse, affect the team, or have real consequences if wrong — drive each step yourself through all five modes: 

/h-frame  → /h-explore → /h-compare → /h-decide → /h-verify

Each command loads its own focused prompt with specific guidance for that step. The context stays clean. You think through each step deliberately — and the structured process works for your brain too, not just the AI's. Defining the problem forces clarity. Setting criteria before seeing options prevents bias. The verification gate catches weak reasoning.

This is where haft delivers the best results. Start here for anything that matters. See the five modes walkthrough for details on each step.

What happens after a decision?

This is the part most people ask about. After the agent records a decision:

  • A markdown file appears in .haft/decisions/ — commit it with your code
  • The decision carries claims — verifiable statements with verify_after dates that can be checked against reality
  • The decision tracks affected files — if those files change later, drift detection flags it
  • Evidence can be attached — test results, benchmarks, user feedback. Evidence has an expiry date.
  • R_eff (trust score) is computed — based on evidence quality and claim status. Expired evidence and failed claims degrade the score.
  • Stale decisions surface — /h-status and haft board show what needs review

You don't need to do anything extra. The system is self-correcting: when decisions go stale, they surface. When you work on files covered by a decision, the agent can mention it. The decide, measure, reframe loop runs naturally as part of your workflow.

See your project at a glance

Run haft board in a side terminal. It shows decision health, module coverage, problems pipeline, drift alerts — and refreshes automatically every 3 seconds as you work with the agent in another terminal. No agent session required.

Add a CI gate

When the repo already tracks .haft/ artifacts, add a lightweight CI step: 

./haft sync
./haft check

haft sync imports the tracked markdown projections into the local SQLite state. haft check then fails the build on stale, drifted, unassessed, or coverage-gap findings. Use --json if you need machine-readable output.

Team workflow

Working with other engineers? The .haft/ directory is git-tracked — commit it with your code. When teammates pull, they run haft sync to import the latest markdown projections into their local database. No shared database, no merge conflicts on binary files. Each person has a local copy that stays in sync through your normal git workflow.

Day-to-day usage

Situation What to do
Big feature, architectural choice /h-reason [describe the problem]
Quick tech choice during coding The agent auto-records notes when it notices decisions
Start of a work session haft board or /h-status
"Why did we do it this way?" /h-search [topic]
Reviewing a PR with decisions Read the .haft/decisions/ markdown files in the diff
Decision feels outdated /h-verify — check claims, waive, reopen, or supersede
New teammate joins haft sync — imports all decisions into their local DB

Next steps