Workflows

End-to-end examples of Navigator’s v7 workflow. Each one shows the trigger you type, what the hook runtime does with it, and what you have when it’s done. All triggers are natural language — these are the actual strings the runtime responds to, not paraphrases.

1. Session → task → autonomous completion

The default loop for a day of feature work.

Start my Navigator session

The session_start op injects context at session start: project config, open tasks, relevant memories from the knowledge graph, and the active context marker. No manual doc loading — the index plus current task is ~12k tokens instead of ~150k upfront, and the session runs 20+ exchanges.

You pick a task and work it. When implementation is complete, the finish protocol runs without prompting: commit, archive the plan, create a completion marker, suggest compact. You don’t ask for any of this — completion indicators are recorded on the Stop event.

With the completion gate enabled, there’s a backstop: a turn that mutated code but looks unfinished — dirty tree, no test run, no exit signal — gets one forced continuation to close the gap.

Config: stop_completion.continue_enabled (ships off) in .nav-config.json · Autonomous Completion

2. Loop Mode

For work that should run to completion without babysitting.

Run until done: migrate the remaining handlers to the new error type

The runtime activates structured iteration. Each exchange emits a NAVIGATOR_STATUS block and progress moves through phases:

NAVIGATOR_STATUS
Phase: IMPL          (INIT → RESEARCH → IMPL → VERIFY → COMPLETE)
Progress: handlers converted, tests pending

Stagnation detection catches loops that stop making progress, and exit is evaluated on the Stop event by the runtime — not by the model deciding it feels done. You check in on status snapshots instead of every exchange.

Config: loop_mode block in .nav-config.json · Loop Mode · nav-loop

3. Tier-1 zero-token answers

Opt-in. Five exact-match commands are answered by the hook runtime with zero model invocation:

nav stats
show features
list markers
graph health
nav version

The answer renders as a deterministic terminal-style card — 0 tokens, instant, and it can’t hallucinate because it reads project state, not a model. Type the command exactly; anything else goes to the model as usual. Escape hatch: reply ask claude to run the model on the same question instead.

Config: tier1.enabled (ships off), per-command toggles in tier1.rules — .nav-config.json

4. Intent brief on an ambiguous prompt

Ambiguity is not complexity — it gets its own handling.

Clean up the auth flow, it's gotten messy

Task-shaped but ambiguous, so the prompt_brief op injects a NAV-BRIEF at prompt time. Claude renders a one-screen brief — Goal, Scope, Approach, Limits, Verify, Won’t do, Contradict — with at most 2 open questions, and waits for your confirmation before touching any file. Scope disputes happen in the brief, not after 40 edits.

Contradict (v7.1.0) is usually none. When the task really is “improving X worsens Y”, the brief looks up how the graph resolved that shape before, and on a substantial task hands off to nav-triz for three competing candidates.

When you don’t want the brief, say so in the prompt: just do it, quick fix, or skip the brief pass straight through.

Config: brief_hook.enabled, brief_hook.contradiction_field in .nav-config.json · Configuration · nav-brief

5. Navigator → Pilot dispatch

Plan interactively, execute headlessly.

Dispatch TASK-42 to Pilot

The task doc becomes a labeled GitHub issue. Pilot  — the autonomous execution product — picks the issue up and ships a PR. The handoff is one-way by design: Navigator authors the spec, Pilot executes it.

On the executor side, the PILOT_EXECUTOR environment variable turns off all of Navigator’s interactive and blocking gates at a single policy point, so nothing built for a human in the loop blocks the machine that picked the work up.

Config: Pilot integration · .nav-config.json

6. Knowledge capture and recall

Two directions: query and store.

What do we know about auth?

Queries the project knowledge graph across tasks, SOPs, system docs, markers, and memories, and answers with what the project has already learned.

Remember this pitfall: the session cookie is scoped per-subdomain,
staging logins silently fail against the prod cookie

Stores a memory. You don’t retrieve it manually — it surfaces automatically where it matters: at session start (workflow 1) and inside intent briefs (workflow 4), so the next person to touch that code hits the warning before the bug.

Config: knowledge_graph block in .nav-config.json · Knowledge Graph · nav-graph

How these are enforced

None of the above depends on the model remembering prose instructions. Every workflow is enforced by the v7 hook runtime — one dispatcher, 13 events, each behavior an op with a config off-switch. The mechanism is documented at Hooks Runtime.