Open-source project

Quarterdeck

Hand the implementation to AI agents. Keep every decision that shapes the project.

A workflow for developers who want coding agents to take on more of the work — without the project drifting away from the design in their head.

Open source · MIT Claude Code Any language Any task tracker

View on GitHub How it works

The idea

Decisions stay with the developer. Implementation goes to the agent.

Coding agents can now write most of the code in a project. What they cannot do is hold the picture of how the project is meant to work: the boundaries between its parts, the rules of the domain, the reasons behind past decisions. That picture lives in the developer's head. Every time an agent fills a gap on its own — a new dependency, a shortcut across a layer, a guess where the specification was silent — the code drifts a little further from it. Each step looks reasonable. A month later the project is something nobody designed.

The usual answers are to review every line, which throws away most of what delegation was meant to save, or to stop reviewing, which hands the architecture to the model.

Quarterdeck takes a third route: it separates decisions from implementation and draws a clear line between them. Decisions about scope, architecture and product rules stay with the developer and are settled before any code is written. Implementation goes to the agent, which works inside those decisions and comes back the moment a task would need a new one.

The quarterdeck is the part of a ship it is commanded from. Whoever stands there sets the course — and does not row.

For the developer

What changes when you work this way

Your time goes to decisions

You stop watching the agent type. Your attention goes to the questions only you can answer: what to build, how the parts fit together, which trade-off is acceptable.

Implementation follows the plan you approved

Every task starts from a specification you signed off, and the agent builds exactly that. What lands in the main branch matches what you agreed to — not the agent's best guess.

Nothing structural slips through

A change that would touch the architecture, a product rule, a dependency or an interface other parts rely on is never decided quietly. The agent stops, and the question comes back to you.

The design outlives the chat

Decisions are written into the repository — architecture decision records, and a log of the choices made in every pull request — so a month later both you and the agent still know why the project looks the way it does.

How it works

How control is kept

Five rules carry the idea. Where a rule can be enforced by a tool, it is; where it can't, the workflow says so instead of pretending.

Decisions are made before code

A task reaches the agent only after a refinement session: the agent reads every source it can, then interviews you until nothing important is left undecided. You approve the result, and that approval is the last gate before code. Every line of the specification names where it came from, so anything the agent made up is visible at a glance.

Held by: a refinement skill, and a definition of ready the agent must refuse to work without.

The agent knows what it may decide

Naming and file layout it decides on its own. A real choice between defensible options it makes and reports, together with the alternative it rejected. Anything that changes the architecture, a product rule, a dependency or an interface other parts rely on, it does not decide at all — the task goes back to you.

Held by: the agent's instructions, and a CI check that fails a pull request without its decision log.

Blocked means stop, not improvise

When a dependency isn't ready, two sources contradict each other, or the same failure repeats three times, the agent returns the task with a comment instead of working around the problem. You hear about it on the board, not weeks later in the code.

Held by: the agent's instructions — named honestly as judgement, not a gate.

Tests prove the agreed behaviour

Tests come first and are written from the specification — the numbers you agreed to, not whatever the implementation happened to return. Their strength is measured by mutation score rather than coverage, and code that exists only so there is something to test is caught.

Held by: CI checks for tests-first branches and test-only modules, and mutation testing on the main branch.

The merge is yours

The agent opens a pull request that explains what was built, which decisions it made and what it rejected, and shows the architecture diagram when the structure changed. You review the decisions rather than every line. The agent cannot push to the main branch, merge, rewrite history, or mark a task done — every change reaches the project through you.

Held by: a hook that refuses those commands before they run.

Lifecycle

How a task moves

Everything is decided in refinement; everything after it is delegation. The agent can send a task back to refinement at any point — that is the workflow working, not failing.

1 You or agent

Open

A task lands on the board — written by you, or by an agent breaking down a plan you described.
2 You + agent

Refine

The agent researches and interviews you. You settle every open question and approve the specification here.
3 You or agent

Todo

Ready to delegate. You or an agent can pick the task up for implementation.
4 Agent

In progress

The agent writes failing tests first, then the implementation, then runs every check.
5 Agent

In review

A pull request that says what was built and which decisions were made, with the architecture diagram showing what changed.
6 You

Done

You read what was built and what was decided, and merge it yourself.

Under the hood

Why the rules hold

Any rule that must hold is executable, or it does not hold.

A rule written only in a prompt is one a model can talk itself out of. So wherever a guarantee above can be made mechanical, it is — and the few that can't are labelled as judgement instead of being dressed up as gates.

A Claude Code hook refuses pushes, merges, rebases and force-pushes on the main branch before the command runs.
CI fails a pull request whose first commit is anything but failing tests, or whose description lacks the decision log.
A check fails the build when a module is imported only by tests — the shape invented work usually takes, and one dead-code tools miss.
Mutation testing on the main branch replaces coverage as the measure of whether tests catch wrong answers.
When a task changes the structure, the agent regenerates the architecture diagram through the project's diagram tool (Archify, for example), so the pull request shows what the architecture did as a picture.
A setup skill reads the repository, interviews the owner and installs the workflow; a doctor script then proves the install, including firing the hook at commands with known answers.
Language-agnostic and dependency-free: plain Python, and works with ClickUp, GitHub Issues, Markdown files or any tracker the agent can reach.

Claude Code skills Claude Code hooks GitHub Actions Python ADRs Mutation testing Spec-driven development

Deliberately out of scope

It does not run or orchestrate agents. One task at a time; one person reviews one pull request.
It does not write specifications for you. It asks; you decide.
It does not configure your board or install your language tools. It tells you what goes where.

Where it came from

It grew out of my own recent projects. Rule by rule, the way I worked with agents turned into a workflow, and I extracted it as a separate project so I can apply it to any new one — and share it with friends and co-workers. Gaps found in real work still flow back into it, and projects that use it pick them up on the next upgrade.

Try it in any repository

npx skills add panovek/quarterdeck

Then run /quarterdeck-setup in the agent session.

Contact

Want to talk about working with coding agents?

Happy to walk through how I use this day to day — what it catches, and where it still needs judgement.

panov.eduard.k@gmail.com View on GitHub