Keep your AI coding agent on the rails
Signposts catches the mistakes your AI coding agent makes before they land — and learns new guardrails from you as you work.
Every agent has habits you keep correcting: the wrong date default, hand-editing a generated file, a command that wipes uncommitted work. Signposts turns each of those corrections into a signpost — a small, durable piece of steering that lives in your repo and applies on every future session, for you or anyone who clones it.
A signpost is a sign or a rule
Every signpost does one of two jobs. The difference is whether it blocks.
A nudge
A note the agent reads the moment it touches a relevant file — “mind the shape here”. It steers; it never blocks. Good for guidance that’s a judgement call, not a hard line.
A block
A check that blocks the mistake. The headline trick: it fires the instant the agent tries to write the bad code — before the file is saved — with a written reason, so the agent fixes itself. A second check backs it up at git commit.
Signs and rules are two halves of one job: beating context drift. Early in a session an agent follows guidance faithfully; as the context grows, it slips. A sign gives it the best chance to get things right first time — delivered just in time, the moment it reads a file in that area — and a rule catches it when it drifts anyway. Use either alone, but they’re strongest together. The mental model →
It learns your guardrails — the loop
Signposts isn’t a fixed ruleset you install once. You npx signposts to scaffold it, develop normally, and run /signposts reflect at the end of a session; a coach reads what happened and proposes new signposts — “this drift → a sign” or “this mistake → a rule”. You pick, you apply, and it steers every session after. See the loop →
All the pages
npx signposts and watch the agent get blocked + self-correct.The loopHow you use it day-to-day — and how it learns from you.ConceptsSign vs rule, context drift, just-in-time context.SkillsRunning it — npx signposts and the /signposts skill.The config fileOne signposts.yaml, section by section.RulesThe core scripts — pick one, fill in config, done.SignsWriting just-in-time guidance for an area of your code.AuthoringWrite your own rule — the calling contract, JS & shell.PacksShare & reuse rules across repos — install from any repo.How it wiresHooks → engine → git hooks, and how config reaches a script.TroubleshootingWhy a rule isn't firing, the debug trace, and the FAQ.