haft

All Commands

Primary workflow

Command What it does When to use
/h-reason Start structured reasoning — agent auto-selects depth Non-trivial engineering problem
/h-note Record a micro-decision with rationale validation Quick tech choice worth remembering

The five modes

Each mode creates or updates a specific artifact. Use these to drive each step manually, or let /h-reason orchestrate:

Command Mode What it does Creates
/h-frame Understand Frame the problem — signal, constraints, acceptance ProblemCard
/h-char Explore (prep) Define comparison dimensions with indicator roles Characterization on ProblemCard
/h-explore Explore Generate genuinely distinct variants with weakest link SolutionPortfolio
/h-compare Choose Fair comparison with parity enforcement, constraint-aware Pareto Comparison on SolutionPortfolio
/h-decide Execute Record decision as contract with invariants, claims, rollback DecisionRecord

Verify mode

Command What it does
/h-verify Scan for stale artifacts, code drift, pending verify_after claims, and structural invariant violations

Actions available within /h-verify:

  • scan — detect all stale artifacts, drifted files, unverified claims, and invariant violations
  • waive — acknowledge drift as intentional (decision still valid)
  • reopen — mark decision for reconsideration
  • supersede — replace with a new decision
  • deprecate — mark as no longer applicable
  • reconcile — batch scan notes against decisions for deduplication

Dashboard and query

Command What it does
/h-status Text dashboard — active decisions, stale items, recent notes, module coverage
/h-search Full-text search across all artifacts
/h-problems List active problems with Goldilocks readiness and complexity signals

Advanced

Command What it does
/h-view Deterministic projections of the artifact graph for different audiences
/h-onboard Scan existing project for architecture knowledge — READMEs, ADRs, specs

/h-view renders the same artifacts differently depending on audience:

  • engineer — invariants, affected files, drift status, WLNK
  • manager — decision titles, health summary, stale count, coverage
  • audit — full evidence chain, CL tags, verification dates, supersession history
  • compare — side-by-side variant comparison with Pareto front
  • delegated-agent — machine-readable format for autonomous agent consumption
  • change-rationale — why this changed from the previous version, for PR descriptions

CLI commands

These run directly in your terminal, not through an AI agent:

Command What it does
haft init Initialize project. Flags: --claude, --cursor, --gemini, --codex, --air, --all
haft serve Start MCP server (used by AI tools to communicate with haft)
haft agent [goal] Standalone agent with TUI runtime — runs reasoning without an external AI tool
haft sync Sync .haft/*.md markdown projections into local database (team workflow)
haft board Interactive TUI dashboard with four tabs, vim navigation, live refresh
haft doctor Diagnose project setup issues — MCP config, database, permissions
haft check CI-friendly governance scan — stale, drifted, unassessed, and coverage-gap findings
haft fpf search [query] Search the embedded FPF specification

haft board

$ haft board

Interactive TUI with four tabs: Overview (health, activity, depth distribution, coverage), Problems (backlog with drill-in), Decisions (R_eff, drift, glamour markdown detail view), Modules (coverage tree). Live refresh every 3 seconds — run it in a side terminal and it stays current as you work with the agent in another.

Use haft board for a live operator view. For CI or hooks, prefer haft check — it produces a deterministic pass/fail result and optional JSON.

haft check

$ haft sync
$ haft check
$ haft check --json

CI-friendly governance gate. It scans stale artifacts, drifted decisions, unassessed decisions, and coverage gaps. Exit 0 means clean; exit 1 means findings were detected.

haft sync

$ haft sync

Reads .haft/*.md files from git and imports them into the local database. This is the team workflow: decisions commit to git, each engineer pulls and runs haft sync to update their local state. See Team Sync for details.

Recommended protocol

/h-frame  → /h-char  → /h-explore → /h-compare → /h-decide
  what's      what       genuinely     fair         engineering
  broken?     matters?   different     comparison   contract
                         options

You can enter at any step, but the protocol works best in order. /h-char before /h-explore prevents bias (criteria defined before options). /h-compare before /h-decide ensures fair evaluation.

Next

  • Key concepts — R_eff, CL, WLNK, evidence decay, claims
  • FAQ — common questions