DEV Community: Ian A. Drilon

How to one shot your feature with this orchestration-workers graph engineering in Claude

Ian A. Drilon — Tue, 18 Aug 2026 06:23:09 +0000

I work in a workspace with eight repos. For a long time, every ticket started the same way.

Read the ticket. Read its parent ticket. Grep the same files to check if the field already exists. Start the services. Run lint and tests in each repo. Then make the branches by hand, and open two pull requests that have to match.

I counted the commands once. Fifty four of them are written down across those repos. Most of them I ran again for the next ticket.

I tried to fix this with better prompts. It did not work. One agent with a long prompt still forgets, still guesses, and still hands me code with no proof that it works.

What worked was building a graph.

What "graph" means here

A graph is just boxes and arrows.

A node is one agent with one job.
An edge is a handoff. Agent A finishes, agent B gets the result.
A barrier is a place where nothing moves forward until every branch comes back.
A cycle is an arrow that goes backward. Work that failed goes back to be fixed, then comes around again.

That is all. The rest of this post is how to build one in Claude Code.

The shape we are building

ticket -> plan -> [check] -> survey -> build -> [gate] -> 4 QA lanes -> judge -> PRs
                    |                                         |
                    +-------- backward arrows ----------------+

One command in. A pull request out. If something fails, it loops until it is fixed, or until the round budget runs out.

Step 1: put the harness in its own folder

Do not put this inside a product repo. Make it a sibling folder.

workspace/
  orchestrator/        <- the harness. no product code.
    .claude/agents/
    .claude/commands/
    .claude/workflows/
    docs/
  api-engine/          <- your real projects
  web-pilet/
  tech-docs/
  e2e-suite/

Why: a ticket usually touches two or three repos at once. If the harness lives inside one repo, it can only see that repo. From the workspace root it can see all of them.

Step 2: write down what you keep repeating

This is the boring step, and it is the one that pays.

Every time you explain something to the model twice, write it in docs/ instead. Mine ended up as six files:

which lint, type check and test command belongs to each repo
which service owns which decision
how to check if a query or field already exists before writing a new one
what a plan document must contain
the design rules, including what is not a bug
the words we use for statuses and roles

"The AI does not know our codebase" is not a model problem. It is an unwritten knowledge problem. Once it is written, every agent reads the same copy.

Step 3: write your agents

One file per agent in .claude/agents/. Markdown with a small header.

---
name: qa-backend
description: Reads the server half of a diff and returns a PASS or FAIL verdict. Never edits files.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are QA for the server side.

You read the diff. You do not edit files, and you do not praise.
Your verdict is acted on, so it has to be right in both directions.
A false PASS ships a bug. A false FAIL sends good work back.

Report every finding with a file and a line number, and a severity of
BLOCKER, MAJOR, MINOR or NIT.

Two things matter more than the prose.

Give each agent one job. I have six: a planner, a builder, and four reviewers (server, web, design, browser).

Use tools: to take away what an agent must not do. My two code reviewers have no Write and no Edit. They cannot change the code they are judging, because the tool list does not let them. That is stronger than asking them nicely.

Step 4: write the loop

The loop is one JavaScript file in .claude/workflows/. It starts with a meta block, then plain code.

export const meta = {
  name: 'build-ticket',
  description: 'Plan a ticket, build it, check it, judge it.',
  phases: [
    { title: 'Plan' },
    { title: 'Build' },
    { title: 'Gate' },
    { title: 'QA' },
    { title: 'Judge' },
  ],
};

phase('Plan');
const plan = await agent(
  `Read the ticket ${args.ticket} and its parent. Write the plan to tech-docs/.`,
  { agentType: 'planner', schema: PLAN_SCHEMA },
);

agent() starts a subagent and waits for it. phase() groups the calls so you can watch progress. args is whatever you passed in.

You are writing normal code here. Loops, if statements, counters. That is the point. The control flow is yours, not the model's.

Step 5: type your handoffs

This is the part I would keep if I had to throw everything else away.

Pass a schema and the subagent must answer in that shape. It cannot hand back three paragraphs of maybe.

const FINDING = {
  type: 'object',
  additionalProperties: false,
  required: ['severity', 'file', 'line', 'problem'],
  properties: {
    severity: { type: 'string', enum: ['BLOCKER', 'MAJOR', 'MINOR', 'NIT'] },
    file: { type: 'string' },
    line: { type: 'integer' },
    problem: { type: 'string' },
  },
};

const QA_SCHEMA = {
  type: 'object',
  additionalProperties: false,
  required: ['verdict', 'findings', 'summary'],
  properties: {
    verdict: { type: 'string', enum: ['PASS', 'FAIL'] },
    findings: { type: 'array', items: FINDING },
    summary: { type: 'string' },
  },
};

Prose can be vague. "Severity is one of BLOCKER, MAJOR, MINOR, NIT" cannot be vague. Set additionalProperties: false everywhere, so an agent cannot slip in a field you never asked for.

Eleven of my twelve agent calls are typed this way. I will come back to the twelfth.

Do not trust the verdict on its own. A schema is happy to accept verdict: PASS next to a BLOCKER finding. So check the evidence yourself, in code:

const BLOCKING = ['BLOCKER', 'MAJOR'];
const blockingOf = (qa) => (qa?.findings ?? []).filter((f) => BLOCKING.includes(f.severity));

// PASS only counts when the findings agree with it.
const passed = (qa) => Boolean(qa) && qa.verdict === 'PASS' && blockingOf(qa).length === 0;

Step 6: one barrier, in the right place

Run things at the same time when they do not need each other. Use parallel().

phase('QA');
const lanes = [
  () => agent(prompt('qa-backend'),  { agentType: 'qa-backend',  schema: QA_SCHEMA }),
  () => agent(prompt('qa-frontend'), { agentType: 'qa-frontend', schema: QA_SCHEMA }),
];
if (hasDesign && touchedFrontend) lanes.push(() => agent(prompt('qa-design'), { agentType: 'qa-design', schema: DESIGN_SCHEMA }));
lanes.push(() => agent(prompt('qa-e2e'), { agentType: 'qa-e2e', schema: E2E_SCHEMA }));

const results = await parallel(lanes);   // <- the barrier. nothing moves until all four return.

parallel() waits for everything. That is a barrier, and I only have one, because only one decision needs all of the answers at once.

Two lessons from getting this wrong:

Run the test suites once, before the lanes, not inside them. Four reviewers running the same test suite at the same time fight over the same test database and the same test cache. You get failures that are not real, and good work gets sent back.

A lane that could not run did not pass. My browser lane can return NOT_RUN when the app will not start. NOT_RUN blocks the round. It is not a neutral answer, and it is never a pass.

Step 7: point the backward arrows at the right node

Here is the mistake I shipped and later fixed.

I said "a failed review goes back to planning". That sounded wise. It was wrong, and my own diagram said it too.

What actually makes sense:

if (qaFailed) {
  // Design is the planner's call. A builder who decides a 4px gap is fine
  // has removed the only check on it.
  if (designNeedsAdjudication) {
    await agent(replanPrompt, { agentType: 'planner', schema: REPLAN_SCHEMA });
  }
  continue;   // <- back to build, with the findings attached
}

Most failures go straight back to the builder. Only the ones that are really an argument about the plan go to the planner. If you send every failure through planning, you rewrite the plan for a typo. If you send none, the builder gets to overrule the design.

Four different failures point back at build in my loop: a failed test run, a failed review, a design fix, and an incomplete judgement. That is what makes it settle instead of drifting.

Step 8: keep git out of the loop

The loop never commits, never pushes, and never opens a pull request. My builder agent is told this in plain words, and the agent that owns git is a separate command with one confirmation step.

Rules I wrote down and do not bend:

one branch per repo that changed, never a shared branch
never merge
never force push
never open a pull request from a loop that did not finish
ask again next time, because approval for one ticket is not approval for the next

The reason is simple. The loop is fast and I am not reading every line as it goes. So the last step before anything leaves my machine is a human saying yes.

Step 9: install it so every project sees it

The harness resolves agents from the session's .claude/ folder. Sessions run from the workspace root. So link the files up one level:

# from workspace/orchestrator/
mkdir -p ../.claude/agents ../.claude/commands ../.claude/workflows
for kind in agents commands workflows; do
  for f in .claude/$kind/*; do
    ln -sfn "../../orchestrator/.claude/$kind/$(basename "$f")" "../.claude/$kind/$(basename "$f")"
  done
done

Use per file links, not one folder link. The workspace .claude/ may hold other settings, and other tools add files of their own. Use a relative target so the folder can be moved.

Symlinks mean an edit in the harness takes effect on the next run. No copy step to forget.

Step 10: run it

/build-ticket TKT-1234
/build-ticket TKT-1234 --plan-only
/build-ticket TKT-1234 --rounds 3 --dry-run

One note if you build this in Claude Code: workflows are not started on their own. You ask for one, or a command asks for one. Nothing here runs while you are asleep.

What it cannot do

Be honest about this part, in your README and to your team.

The one agent with no typed output is the builder. The only node that writes code hands back prose, and that prose gets quoted into the review prompts. I have not worked out a good shape for "here is what I changed and why". It is the weakest edge in my graph.

I also have no hours saved number. Nothing in the harness measures duration, so I will not invent one. What I can say is what changed in shape: I type one command and confirm once, instead of running fifty four commands across eight folders. I still read the diff myself.

The short version

Own folder, next to your projects, no product code in it.
Write down the things you keep repeating.
One agent, one job. Take away the tools it must not use.
Write the loop as code, so you own the control flow.
Type every handoff, and then check the evidence in code anyway.
One barrier, where the decision really needs everything.
Send failures back to whoever should fix them, not always to the top.
Keep git behind a human yes.

If you build one, I would like to know where you put your barrier, and where your backward arrows point.

Unlocking Seamless Development: Mastering SSH Key Setup for Bitbucket and GitHub in WSL2

Ian A. Drilon — Sat, 10 Jun 2023 12:29:25 +0000

Why use ssh?

Using SSH as more secure option and HTTPS for basic, password-based Git usage. Since SSH is more secure than entering credentials over HTTPS, it is recommended for business dealing with sensitive and critical data. Once you generate you generate and connect your ssh key to your bitbucket/github, you can freely push and pull or make changes to your project repository

Why i'm doing this? 🤔🤔

As your fellow developer, i was once struggling to setup my own SSH key to the version control that we are using in a company, by studying and discovering it on my own. I want to share how i setup my own SSH key and connect to the repository with no hassle.

Let's get into it 🔥

Make sure openssh-server is installed in your WSL Distro (In my own case i use Ubuntu.22.04 LTS)



 sudo apt install openssh-client

Once the openssh-client installation is complete, in the terminal, check that openssh-client has been successfully installed by running the following command:



ssh -V

the output will show the version of openssh you installed

Start the SSH agent

To allow git to use your SSH key, an SSH agent needs to be running in your machine. to do this, write this command in your terminal



ps -a | grep ssh-agent

to start the agent:



eval $(ssh-agent)

you might need this to add in your ~/.bashrc so that if you restart your terminal it will automatically run in the background

Create an SSH key 🔑 pair (private/public)

Open your terminal and navigate to your home by writing this command



cd ~

Generate your SSH key pair using ssh-keygen, write this command:



ssh-keygen -t ed25519 -b 4096 -C "username@emaildomain.com" -f ssh-key-name

The username@emaildomain.com is the email you are using in bitbucket or github
the ssh-key-name is the name of you ssh key example work-ssh

After adding those command, the terminal will ask for you passphrase, you can either provide a phrase for a password or leave it blank, if you input a password each time SSH is used, such as using git command that contact Bitbucket/Github (such as, pull and fetch). Providing password will prevent other users with access to the device from using your keys.

Once you completed the command above, it will output two files such as

ssh-key-name - the private key
ssh-key-name.pub - the public key

These files will be stored in your home directory, the ssh-key-name.pub that is the one we will be using to connect in bitbucket/github

Add your key 🔑 to the SSH agent

We will now add our key to the ssh agent, write this command:



ssh-add ~/ssh-key-name

Ater adding our ssh key to ssh agent, we will now be able to add our ssh public key to the bitbucket/github

Provide Bitbucket Cloud with your public key 🔑

At bitbucket, select your avatar (Your profile and settings) from the upper right screen of your monitor
Under Settings, Select Personal Settings
Under Security tab, select SSH key
in the Add SSH Key it will prompt you a dialog box, where in you can add your ssh key example:



ssh-ed25529 LLoWYaPswHzVqQ7L7B07LzIJbntgmHqrE40t17nGXL71QX9IoFGKYoF5pJKUMvR+DZotTm user@example.com

you will find this key inside of your ssh-key-name.pub file just copy and paste, don't forget your label. For example Work Machine. this will help you identify old or unwanted keys in the future.

after adding your ssh public key, if you received an error that SSH key is invalid, double check that you copied the entire contents of the public key (.pub file)

Check that your SSH authentication works

To test your ssh key if successfully, open a terminal on your machine and add this command



ssh -T git@bitbucket.org

if SSH can successfully connect with Bitbucket using your SSH keys, the command will produce output similar to



authenticated via ssh key.

You can use git to connect to Bitbucket. Shell access is disabled

Provide Github with your public key 🔑

Adding SSH key in your github is more simple than you expected

Copy your SSH public key in your .pub file
In the upper right corner in your github profile you can click your avatar, and click the Settings

In the SSH and GPG keys Click the New SSH key
it will redirect you to the page like this

Similar to the bitbucket we mentioned earlier, add your public key to the key section and some descriptive title that will help your determine the old and new keys in the future
Select the type of key, either authentication or signing. For more information about commit signing you can refer to this link here.
after adding all the necessary information, click the add SSH key
If everything went well, github will send you the confirmation access directly to your account. For more information, see Sudo mode

Congratulations 👏👏👏

Congratulations on adding your first SSH key to your favorite or chosen version control system. By this blog post, i hope we can help more developers who are struggling on setting up their first SSH keys on your side projects, side hustles or company project.