meganemura

Headsign — AI skill for Claude Code

AI community

A tiny phase gate for coding agents: your shell checks decide pass/fail (never the LLM), your workflow routes the agent — advance, retry, escalate, done.

How to install Headsign

This entry records only its repository, not the path inside it, so there is no exact command to give. Open meganemura/headsign and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

What Headsign does

A tiny phase gate for coding agents: your shell checks decide pass/fail (never the LLM), your workflow routes the agent — advance, retry, escalate, done. Runs as a Claude Code or Codex plugin. The agent drives; headsign holds the state.

Alternatives in AI

UltraCode Shim — Give Claude Code's ultracode mode to ANY model you already pay for 422 ★
Ooda Subagents — OODA Loop AI Agents - Observe, Orient, Decide, Act framework for systematic problem-solving 170 ★
Dsh Auto Review — Second-model AI auto-review for DeepSeek Harness approval requests: a read-only reviewer subagent returns stru 155 ★

README

headsign

[日本語](README.ja.md) · [npm](https://www.npmjs.com/package/headsign)

[![npm version](https://img.shields.io/npm/v/headsign)](https://www.npmjs.com/package/headsign) [![CI](https://github.com/meganemura/headsign/actions/workflows/ci.yml/badge.svg)](https://github.com/meganemura/headsign/actions/workflows/ci.yml)

A headsign is the destination display on the front of a train. This one is for agent loops. In each iteration, the agent asks where it may go. headsign runs the gates and answers: proceed, retry, or terminus.

**headsign is a tiny phase gate for coding agents.** Your agent does the work and keeps the conversation. headsign holds the run's state and decides whether the work may move to the next phase. An agent needs one rule: **do the work, run `headsign next`, and obey the first line of the answer.**

It holds only that decision. headsign does not define your phases or how the agent completes a phase. If the agent wants to hand a step to three subagents, or run two things at once, that is its call to make, not this tool's to grant. You or the agent can rewrite the workflow file between runs. Better judgment about agent work will improve that file, and judgment about how to shape agent work is getting better quickly on the agent's side of the line. The loop your agent designs for your repository beats the one a harness author guessed at from outside it. A harness that encodes today's answer would limit later improvements. You can change the graph while the tool stays stable.

TL;AR — Too Long; Agents Read.

A picture based on your repository can help you decide whether you need headsign. Paste the block below into your coding agent. The agent reads the repository, works out the phases itself, draws the loop, and stops there. It runs nothing, installs nothing, and changes no file.

You are looking at a repository. I am considering headsign, a phase gate for
agent work: an agent does the work, then asks a small CLI whether the work