haft

Your first useful task

Do not begin by formalizing the whole repository. Pick one question whose answer would be expensive to get wrong or annoying to reconstruct next month. That is enough to find out whether Haft helps you.

1. Connect Haft to your agent

cd /path/to/project
haft init --claude           # or: haft init --codex

Bare haft init opens a host picker in a terminal. Then fully restart the coding agent. Run haft version and haft doctor if the host does not show the Haft skills or MCP tools. The install page covers core-only and advanced host options.

2. Bring one costly question

Good first questions have uncertainty, trade-offs, or memory value:

  • “We keep patching cache invalidation. What problem are we actually solving?”
  • “Compare keeping the monolith with splitting this service. Make the weakest link of each option visible.”
  • “We decided to keep this API synchronous. Does that decision still hold after the queue migration?”
  • “Where is the retry policy specified, why was it chosen, and which code implements it?”

3. Ask normally; use h-reason when the route is unclear

/h-reason We need to replace the cache layer. First work out the
actual problem, the affected system boundary, and the real options.
Keep this conversational unless later work has a concrete reason to rely on it.

h-reason is useful when the question is ambiguous or may need an FPF pattern. If you already know the shape of the work, use a narrower capability directly:

  • /h-frame — the problem itself is unclear;
  • /h-diagnose — a concrete failure has several plausible causes;
  • /h-explore — you need genuinely different approaches;
  • /h-compare — the options already exist and need a fair comparison;
  • /h-verify — an old decision or claim must meet current evidence;
  • /h-status — you want to know what currently needs attention.

These are entry points, not stages. A simple reversible edit with clear acceptance may need none of them.

4. Look for a useful result, not a pile of records

For a costly question, a good result usually makes four things clearer:

  1. the actual problem, object, scope, and constraints;
  2. the real alternatives and the weakest link of each;
  3. which option the human selected, if a choice was actually made;
  4. what evidence would support the result and when it should be revisited.

Haft does not require all four on every task. A diagnosis can stop at the supported cause. An exploration can stop with several live options. A mechanical fix can stop when the test passes.

5. Save only what later work will use

Keep local, reversible reasoning in the conversation. Save a non-binding observation with /h-note when you explicitly want it remembered. Save a human choice as a decision when another session, person, audit, or expensive reversal will rely on it. Haft should not turn every answer into project bureaucracy.

6. Ask the project what changed

After the project has accumulated useful records, /h-status becomes valuable. It is a short attention view: stale evidence, drifted code links, specification issues, and active work. A warning means “look here,” not “the project is broken.”

When you need a precise read

Question Surface
What needs attention?/h-status
Which FPF source is relevant?haft fpf query|lookup|inspect
Where is this behavior implemented?haft graph explore
What is known about this exact project thing?haft memory resolve|neighborhood|recall
Are the project specifications structurally healthy?haft spec check
Should deterministic governance findings fail CI?haft check

Advanced: setup status

Ask for /h-onboard only when setup is the problem. Haft installs the default project-memory model automatically and can detect a simple single-scope codebase without asking you to choose an internal schema. Ambiguous or multi-scope projects may require you to identify the intended software scope. Onboarding ready means setup is available; it is not a verdict on the specifications, code, or evidence.

Next