Check your tools
Use macOS or Linux with Git, Bun and the four CLIs installed. These commands only print versions.
git --version bun --version hi --version specsync --version fledge --version chough --version
One development lifecycle. The whole team.
Product, design, development and QA. See how people and coding agents work together, one step at a time.
task list demo recorded workflow terminal
Read this chapter’s transcript
Reopen a task. Keep its earlier changes.
Product starts with a goal for a tiny to-do list. Plain-language guides explain how hi keeps the request, spec-sync checks parts of the project, and fledge runs the app and its tests. See where design and planning fit.
This example's written plan is a draft. Its spec-sync check covers files and module links; separate tests check what the app does.
Read this chapter’s transcript
A mistake slips in. A test catches it.
See where development and QA meet: we deliberately make a reopened task forget its earlier changes, watch a real test fail, restore the original code, then run the same tests again.
The mistake and repair are prepared for this recording. A person still reviews and accepts the change.
Read this chapter’s transcript
Remember the work. Find the next step.
chough keeps the goal, decisions and past results available to the coding agent. Inspect the next human review step and learn how acceptance and optional release fit the wider workflow.
This shows saved project context. We have not measured how well a new agent understands it in these videos.
Scripted recordings. Method and limits.
Keep the goal, the code contract and the checks in your repo. Start the next session with a clear next step.
From a tiny task transition to a failing test and a useful checkpoint. Play any chapter, then run the same sample yourself.
Scripted demonstrations of real installed CLIs in an isolated project. No commands run in your browser. Recording details and limitations.
The development lifecycle
One lifecycle for
the whole team.
One workflow for people and coding agents.
Shape the request, review the experience, build, check and decide what goes out. People contribute through their coding agent and by reviewing the records and results. One person may wear several hats.
You can describe a goal and review the work without learning terminal commands. chough gives the coding agent a workflow to follow in your existing project.
-
Intent
What should change?
- People
- Product and stakeholders describe the problem and what success looks like.
- Coding agent
- Ask questions and save the request in hi, keeping the person's words available.
- Result or decision
- A clear goal and success criteria that a person approves.
In the tiny to-do example
Reopen a finished to-do without losing its earlier steps.
-
Design
When visuals or interactions change
How should it feel and behave?
- People
- Designers review a rendered prototype, including how it works on a phone.
- Coding agent
- Make the prototype and explain its choices so people can inspect the actual experience.
- Result or decision
- A person approves the rendered design and its notes, or asks for changes.
In the tiny to-do example
If reopening a task needs a new button, review its wording, placement and keyboard behavior.
-
Plan
What will we build and how will we check it?
- People
- Developers help bound the work. Product and QA agree what the result must do.
- Coding agent
- Break the work into small tasks, document the agreed rules with spec-sync and choose useful checks.
- Result or decision
- A bounded plan. Use existing human authorization, or ask for a scope decision where it is missing.
In the tiny to-do example
Keep the same task and its full list of earlier changes; test that after reopening.
-
Build
Make the agreed change.
- People
- Developers guide implementation and review the code and its tradeoffs.
- Coding agent
- Write the code within the agreed scope and preserve the project's rules.
- Result or decision
- A working change ready to check, with the decisions recorded.
In the tiny to-do example
Update the reopening behavior without erasing the task's earlier steps.
-
Test
Does it do what we asked?
- People
- QA defines meaningful cases, tries the result and reviews failures with the developer.
- Coding agent
- Use fledge to run the project's chosen checks and keep the actual results, including failures.
- Result or decision
- Evidence of what passed and failed. A check of code structure and a test of behavior answer different questions.
In the tiny to-do example
A test is a small program checking expected behavior. Here it checks that every earlier task change is kept.
-
Accept
Is this the result we wanted?
- People
- Product, design and reviewers inspect the actual result and the evidence.
- Coding agent
- Present what changed, what was checked and what remains uncertain. Record the person's actual decision.
- Result or decision
- The person accepts the implementation or requests changes. Passing tests do not make that decision.
In the tiny to-do example
Try reopening the task and inspect its history before deciding whether the result is right.
-
Release
Optional, with authority to proceed
Should this go out now?
- People
- The maintainer or release owner decides whether and when to deliver the change.
- Coding agent
- Prepare the requested delivery and run the required checks, using explicit or standing authority.
- Result or decision
- Merge, publication and deployment each keep their own decision. Acceptance alone does not authorize delivery.
In the tiny to-do example
The terminal sample stops before delivery. Nothing is published by watching or running it.
Try it with your coding agent
Make one small change.
Describe what you want in plain words, then review the result. For a hands-on example, this tiny task-list project includes the request, code, checks and saved progress from the videos.
The complete task demo
Source, local Git history, specs, tests and reproduction instructions. A disposable sample, with an intentional regression you can repair.
Requires Git, Bun, HI, SpecSync, Fledge and chough. Recorded on macOS arm64. Install the workflow tools and Bun first. See platform and host guidance for Linux or Windows through WSL 2.
Run the sample
Download the sample ZIP first. It includes a Git bundle so the sample keeps its local history. Run these in the download directory.
unzip beginner-corvid-task-demo.zip git clone corvid-task-demo.bundle task-demo cd task-demo fledge run verify fledge run demo
Catch the mistake yourself
Run only inside task-demo. The first command deliberately breaks the sample. The final command should fail because earlier task changes are missing.
fledge run inject-regression fledge spec check --strict fledge run test
Repair and resume
The repair task restores the sample implementation. Verify it again, then inspect the checkpoint and the remaining human gate.
fledge run repair fledge run verify chough next --environment local
Ready for your own project? Give your agent a goal.
Start in your existing Git project
Replace [my goal]. Your agent checks the setup, helps agree scope and keeps your acceptance decisions with you.
My goal: [my goal] Use the chough workflow in this repository. Read its skill first: https://github.com/CorvidLabs/chough/blob/main/skills/chough-workflow/SKILL.md Inspect the existing instructions, project records and installed tools. If setup is missing, explain what is needed before installing or changing configuration. Help me agree on a small scope. Use HI for my intent, SpecSync for the contract and Fledge for the project's actual checks. Keep decisions, evidence and the next action in the project. Work within the scope I approve, then show me the changed behavior and test results. Keep acceptance, merge and release decisions with me.
Start with a need.
Choose your tools.
Use hi, SpecSync or Fledge on its own. chough connects human intent, code contracts and project checks into a workflow your coding agent can follow.
hi
hi/Keep the original intent.
Plain sentences about what you want, with permanent criterion IDs. A reference point that survives changes to the code.
spec-sync
specs/Give the work a contract.
Markdown module specs, structural drift checks and a change lifecycle. Make the agreed scope and verification state inspectable.
fledge
fledge.tomlMake good checks repeatable.
Run the tasks and verification lanes your project defines. The agent and the human can use the same commands.
chough
.chough/Leave the next step clear.
A workflow for your coding agent, with decisions, evidence, bugs and a resumable checkpoint kept in the project.
Explore what each project record contains
Four records. One shared thread.
“Let me reopen a completed task.”
hiThe human's words
Start with what you want.
Keep the human request in plain words, before it becomes an implementation plan.
hi/tasks.md
TASK-1
I can reopen a completed task
without losing its history.The criterion keeps its identity as the implementation evolves.
A clear goal to build toward
spec-syncThe agreed behavior
Make the change explicit.
Turn the agreed scope into a contract the agent can implement and you can review.
specs/tasks/tasks.spec.md
reopenTask(id)
completed → open
preserve the task's history
unknown id → an explicit errorSpecSync checks supported structural facts and tracks the change lifecycle. Behavior still needs tests.
A contract with clear boundaries
fledgeSeparate kinds of evidence
Run the checks that matter.
The agent writes the change. Fledge runs the project's declared tasks, including its actual tests.
Illustrated verification record
Structural check API matches the spec
Behavior test reopening keeps history
Error-path test unknown id is rejected
Review still a human decisionA contract check and a passing application test answer different questions. Keep both results with the change.
Evidence you can inspect
choughContext for the next session
Pick up the thread.
When work pauses or changes hands, the next agent can find the goal, decisions, evidence and next action.
chough checkpoint
Goal reopen a task, keep its history
Decision keep the existing task model
Evidence inspect the recorded test run
Next present the change for reviewchough guides the workflow through project records. It keeps approval, acceptance and release decisions with the human.
A reviewable change, with its context
Illustrated example. No tools or AI models run on this page.
See the work.
Including the rough edges.
Read the commands, failures and recovery notes from the project's own exercises before you commit to a workflow.
Maintainer-run examples with recorded environments, outcomes and limits.
Play, use, inspect
Five small things you can make your own.
Try two games and three everyday apps, then explore their source, real Git histories and beginner build stories.
Explore the examples Feature and bugA boundary test fails. The workflow stops.
Follow a small shipping rule through an intentional bug, a repair and later passing tests. Sample approvals are explicitly simulated.
Read the exercise Fresh agent“Resume the work in this repository.”
Inspect the cold-start record: what the incoming agent recovered, what got in the way and what still needed a human.
Read the handoffThe workspace is yours
Bring your agent.
Keep your setup.
chough is a workflow your agent follows. You stay in your existing editor or terminal, with the project's records available to the next session.
Need persistent terminals?
Herdr Core runs programs and coding agents in terminals you can return to, inspect and take over. An optional place to run the work.
Read about Herdr CoreGive agents shared guidance.
The CorvidLabs skills catalog provides reusable operating guidance, including HI, chough routing and Herdr Core.
Browse the skillsBefore you try it.
Can I use this if I do not write code?
Yes. Product can describe the goal, designers can review a prototype, and QA can choose cases and inspect results. Work through your coding agent and review the files and running project it shows you. The terminal is where the agent runs the tools; this is not a separate team dashboard.
Do I need all four tools?
You can use HI for intent, SpecSync for contracts or Fledge for tasks independently. The complete chough workflow connects all three. Start with the part that solves a problem you already have.
Does this replace my coding agent?
You keep your agent and editor. chough supplies a skill and project records for the agent to follow. Skill discovery varies by host; check the integration guide and tested limits.
Will a green check prove my feature works?
SpecSync checks supported structural facts and lifecycle records. Your project's behavioral tests check what the code does. Agents still have to choose meaningful assertions, and you still review the result.
What if I already have tests and CI?
Keep them. Fledge can run the commands your project defines, and SpecSync adds contract checks. The integration guide shows how the pieces connect. Adopting the complete change lifecycle is a separate setup step.
Is there another subscription or AI service?
The four tools are MIT-licensed open source. chough does not host a model or require a provider API. Your coding agent keeps its own costs and permissions; optional Fledge AI features use the provider you configure.
Help shape the next iteration.
Try one change. Tell us where the workflow helped and where it got in the way. If chough earns a place in your setup, star the repository so you can find it again.
MIT licensed. Project files. Your coding agent.Intent stays readable. Evidence stays inspectable. Decisions stay yours.