Troubleshooting & FAQ

“My new rule isn’t blocking anything”

Most often one of these:

  • The hook isn’t live yet. A newly added agent hook isn’t active in the session that added it — your agent captures hooks at startup. Start a fresh session and try again. The commit-time gate doesn’t have this caveat.
  • A script errored and failed safe. By design a broken rule exits cleanly and lets the edit through, so a bug looks like “nothing happened”. Run just test-rules — a failing self-test points straight at it. To watch the hook live, set SIGNPOSTS_DEBUG=1 and check the trace log.
  • when: excludes the trigger. If you set when: [commit] it won’t fire pre-emptively. Leave when: off to get the default [edit, commit].
  • The on: glob doesn’t match. Check the path pattern against the real file path (relative to the repo root).

“It’s blocking things it shouldn’t”

  • Tighten on: (or deny: / ban:) so the rule only fires where you mean it to.
  • Add a valid sample to the rule’s .test.yml (a legal case the engine must pass) that covers the case being false-flagged — then fix the rule until signposts test is green.
  • For a deliberate one-off, the rule’s message always tells you the way out (e.g. a safety guard’s explicit escape).

The debug trace

# the agent hook, run with SIGNPOSTS_DEBUG=1, logs each stage:
  …  invoked · stdin 633B
  …  Write: reconstructed src/feed.ts (113B)
  …  eval → DENY (1)

FAQ

Can I run with only signs, or only rules?

Yes. They’re independent halves. Many setups are mostly signs with a handful of rules for the things that truly must not happen. Concepts →

Does any of my code leave the machine?

No. Every check runs locally, in-process, inside the hook. Nothing is sent anywhere.

Will the pre-emptive check slow my agent down?

No meaningfully — scripts parse the reconstructed file in-process (no temp files, no spawned linters). It’s built to sit on every write.

What if I don’t use git hooks?

The edit-time block still works (it’s an agent hook). You lose the commit-time backstop — the half that catches mistakes made without the agent.

A rule is irrelevant to this repo — do I delete it?

No need. A rule whose on: glob never matches simply sleeps. Carrying your whole stack everywhere is the intended model.

I updated Signposts but my /signposts skill is missing a mode

The skill (SKILL.md) and the coach agent are copied into your project’s .claude/ at setup time — your agent loads them from there, not from node_modules — so they’re a snapshot, and updating the installed package doesn’t refresh them. Run npx signposts refresh — it re-copies both from the updated package (or re-scaffold with npx signposts) — then restart your agent session so the new skill loads.