Chough

A portable development workflow kit for coding agents: skills, human intent, specs, testing, and local context for resumable work.

Chough (pronounced chuff, as in chuffed: how you feel when it merges) is a portable agent skill with a small Rust helper. It is current-agent-first and agent-neutral: the same skill and records are meant for capable GPT/Codex, Claude, Grok, Kimi and local-model hosts. You keep working with the agent you already use. Chough gives it a shared stage workflow and a checkpoint in plain project files. HI keeps the human's wording and criterion IDs, SpecSync owns contracts and the native change lifecycle, and Fledge runs tasks. Chough records what stage work is in, what was decided, what was actually checked (with the revision and environment), which bugs are open, and the next valid action.

Chough is a public CorvidLabs repository. Release history is in CHANGELOG.md. Nothing is hosted or deployed.

How Chough works

Give your agent a goal; it drives the workflow using Chough. The agent you are already talking to runs HI, SpecSync and Fledge itself while following the skill, and Chough keeps the checkpoint that lets any agent resume. There is no separate auto-driver: nothing runs the pipeline unattended, and no stage advances itself. The agent moves stages with chough stage …, and native SpecSync status, not a saved label, decides what each move is allowed to do. The loop is:

1. You state the goal; the agent captures it in HI. Where intent or authorization already exists, it is used; you are asked only when a real decision is missing.
2. The agent drafts the native SpecSync change, filling its technical interview fields from your intent and the repository. You approve scope once, where your prior or standing authorization does not already cover it. When you decide at that gate, Chough records SpecSync's approval in your name, from your configured identity; when earlier authorization covers it, the agent records the approval in its own name and quotes you.
3. The agent builds, tests and advances the stages.
4. You review the implementation. Your decision at the review gate records SpecSync's review in your name, and the agent ships, closing the gate with your words as a relayed claim.

chough next tells the agent (or you) the focused next valid action; it is routing guidance, not an unattended runner. chough change new/answer/check/status pass SpecSync's output, refusals and exit code through unchanged and write nothing under .chough/; only chough change ship also closes the review gate and moves the session to done. What you always decide yourself: the intent, any visual design, scope when authority is missing, implementation acceptance, merge, and any release or deploy.

Install

Chough needs Rust 1.88 or later. Install a released version from crates.io (the releases are listed in CHANGELOG.md):

cargo install chough --locked
chough --help

To run unreleased work from main, install from the repository:

cargo install --git https://github.com/CorvidLabs/chough --locked

or from a clone:

git clone https://github.com/CorvidLabs/chough.git
cd chough
cargo install --path . --locked

The skill bundle is embedded in the binary; chough init copies it into your project.

Install the toolchain

Chough works with HI, SpecSync and Fledge. One command installs the versions CI uses:

cargo install --locked [email protected] [email protected] [email protected]

This command needs Rust 1.89 or later, because SpecSync 6.3.0 declares it. Cargo skips a tool already installed from crates.io at that version and replaces a different version (--force reinstalls). The binaries are hi, fledge and specsync. Install Chough itself as shown in Install.

Start here

For a new project without them, the order is: write the intent as an HI file and run hi check; create each module's contract with specsync init and specsync scaffold <module>; turn SpecSync's change gates on with specsync change adopt (specsync init leaves them off, and until then stage moves pass ungated); then run chough init as below. New project walks through each step, and A new project and its first change shows a minimal HI file, a baseline specs/<module>/requirements.md and what a change's delta looks like. In a Git project with HI criteria and SpecSync module contracts:

chough init --objective "Free shipping from fifty dollars" \
  --intent-scope CHECKOUT --module shipping --host claude
chough next --environment local

This is the beginning of the README. Read the rest at the original. Read the full README ↗