Autonomous coding · for multi-milestone projects · v2.17.0

An outsourcing team made of AI agents.
Running by process, 24/7, for large projects.

Astragentic is a scaffold for running a team of AI agents on the orchestrator model. You talk to one representative, the team builds by role, and every piece of work goes through an issue tracker: GitHub Issues, Jira or Linear. The hard parts of running many agents are settled; the rest is yours.

Explore how it works ↓Install it in your repo ↓

A working session with Astragentic: open herdr, launch Thomas, ask how the project is going. Thomas reads the GitHub Issues board, finds three tickets that do not overlap, runs three Builders in parallel on three worktrees, answers the technical question itself, closes each ticket as it lands, then sends you a short report.

AI outsourcing team

What each agent does.

Every member of the team is an agent: a Claude Code session opened from the command line with a fixed role. It takes work, hands back the result when it is done, and can be cloned: several Builders building at once, several QAs checking at once, like a real team.

Each role has a name of its own: Thomas, Shaper, Builder, Rin, QA. The name keeps the agent from drifting out of its role across a long context, and it is the address for sending work, reading a pane, and attaching the right skills.

Model and effort per role

Each role runs on the model and effort its work needs. Thomas and Shaper reason at length, so they run Opus, Shaper at high effort. Builder and QA need speed and low cost, so they run Sonnet. Rin gates on Opus at medium effort.

This table is read straight from .agents/orchestrator.md in your repo. Change one row and that role's runtime, model or effort changes at the next dispatch, with no edit to the role contract.

harness/.agents/orchestrator.md

  1. ## Active assignments
  2. | Role | Runtime | Model | Effort | Advisor |
  3. |---|---|---|---|---|
  4. | thomas | claude | claude-opus-5 | medium | fable |
  5. | shaper | claude | claude-opus-5 | high | fable |
  6. | builder | claude | claude-sonnet-5 | medium | opus |
  7. | qa | claude | claude-sonnet-5 | low | opus |
Five Roles, Five Session Lifespans An architecture diagram generated by Archify. Thomas · resident router · Architecture component · session: resident Thomas resident router session: resident Shaper · grill → spec → tickets · Architecture component · session: unbroken Shaper grill → spec → tickets session: unbroken Builder · implements, own worktree · Architecture component · session: per ticket Builder implements, own worktree session: per ticket Rin · verifies artifact + traces · Architecture component · session: per milestone Rin verifies artifact + traces session: per milestone QA · runs the real product · Architecture component · session: per walk QA runs the real product session: per walk spec, then tickets spec + ticket claim, then dispatch handback + receipt milestone gate gate verdict qa walk walk report Legend Frontend Backend Security External

Scroll sideways for the whole diagram

Thomas runs the whole team: takes your request, brings in the Shaper when a spec is needed, dispatches tickets to Builders, calls Rin’s gate at every milestone and QA’s walk before a merge, then reports back to you. Every arrow in the picture is one exchange there and back.

How you work with the AI team

The operating model.

You are the client, talking to Thomas, the team's representative. The team works around the issue tracker, and everything passes through it so you can read it back at any time.

Day to day, you work with Thomas alone

Thomas runs the team.
Thomas opens a Shaper session when something needs shaping, dispatches tickets to Builders up to capacity, calls Rin’s gate at every milestone and QA’s walk before a merge. You never summon an agent yourself.
Thomas reads the reports for you.
Handbacks, receipts, gate verdicts and walk reports reach Thomas first. Thomas reads them against the ticket and tells you what they say the way the two of you already talk: your language, the level of detail you want, an example in place of a term when you prefer one. The originals stay on the tracker for you to check.
You only have to make Thomas understand what you want.
You state what you want and where it is going; Thomas carries it out with the team and makes the calls along the way. It comes back to you only when a decision is genuinely yours, such as UI/UX or the tech stack, and by then the question has been reduced to a choice you can answer.
One ticket through the team, tracker at the centre An architecture diagram generated by Archify. You, the client · requirements, decisions · Architecture component You, the client requirements, decisions Thomas · representative · PM, BA, secretary · Astragentic outsourcing team Thomas · representative PM, BA, secretary Issue tracker · every task passes here · Astragentic outsourcing team Issue tracker every task passes here Shaper · grill → spec → ticket · Astragentic outsourcing team Shaper grill → spec → ticket Builder · implement, own worktree · Astragentic outsourcing team Builder implement, own worktree Rin · verify artifact + trace · Astragentic outsourcing team Rin verify artifact + trace QA · runs the real product · Astragentic outsourcing team QA runs the real product requirements asks when it is yours to decide frontier, claim, dispatch spec → ticket claim commit, receipt gate milestone qa walk reads, audits Astragentic outsourcing team Legend Frontend Backend Database Security External

Scroll sideways for the whole diagram

How agents talk to each other

Dispatching a ticket opens a conversation with an address.

A ticket is an issue on the tracker, sliced small enough for one Builder to finish in one session. It carries a stable id, a status, an assignee, and blocking edges to the work that must land first.

Thomas dispatches with the dispatch-ticket skill: claim on the tracker, create the branch and worktree, open a herdr pane, launch the agent for the role, send the brief, set a watcher. The chain ticket → assignee → pane → worktree → branch → PR is one to one, so many Builders run in parallel without stepping on each other.

One dispatch of TRA-142: you talk to Thomas, Thomas addresses the Builder by session name over cross-session messaging, answers the technical question itself, and brings the UX decision back to you.

Between Claude Code sessions the main channel is built-in cross-session messaging. Every session has a name; Thomas looks it up with ListAgents and sends straight to it. On the receiving side the message appears as the preview line › Message from @thomas: …, expands with ctrl+o, and the reply travels back to the session that sent it.

A herdr workspace for one project: every agent has a named pane with a detected state, you click to read any of them, and Thomas reads and prompts through the CLI.

herdr is the visible plane and the fallback: one named pane per agent, with a watcher reporting working, blocked, idle. Thomas reads a pane with herdr agent read when a session goes quiet, and prompts a junior pane through the herdr CLI.

  • Technical questions: Thomas answers them for you, from the contract, the spec and the tracker.
  • Design decisions: these come up to you through to-questionnaire, as a question you can answer.
  • Where you stand: on the loop, not inside every step of it.

Issue tracker

Every piece of work goes through the tracker, so none of it drifts.

The state of the work is stored on the tracker, not in chat or in an agent's memory. Thomas asks the tracker what is ready; you open the board and read it.

  • A ticket is data: id, status, assignee, blocking edges, read and written over an API. No more checkboxes in a markdown file that an agent has to remember to tick.
  • A claim is one assignee line, written and read back, so many Builders run in parallel.
  • One ticket is one branch, one worktree, one PR, carrying the same ticket id. After merge the ticket closes and the worktree is cleaned up.
  • A ticket holds the whole story: the work, the approach, the questions asked, the receipts committed. You understand a piece of work by opening its ticket.
  • No new tool to learn: GitHub Issues, Jira and Linear all work.

five requirements on the tracker · verbatim from tracker-contract.md

  1. A stable ticket id in the TITLE
  2. A status with five states — Backlog / Todo / In Progress / Done / Won't fix
  3. An assignee, written and read back atomically
  4. Every precondition as a queryable EDGE
  5. A surface the OWNER can open and read without running a query

linear-issue-trackerLinear

linear-issue-tracker · Linear
Linear

github-issue-trackerGitHub Issues

github-issue-tracker · GitHub Issues
GitHub Issues

jira-issue-trackerJira

jira-issue-tracker · Jira
Jira
Three trackers, one way of working: GitHub Issues, Jira and Linear each have their own adapter in the harness, and Thomas loads the right one at session start.
The Frontier Query A data-flow diagram generated by Archify. 01 / Tracker fields 02 / Query 03 / Board 04 / Consume Open Tickets · all tracker items · 01 / Tracker fields Open Tickets all tracker items Blocking Edges · blocked_by graph · 01 / Tracker fields Blocking Edges blocked_by graph Assignee Field · empty or held · 01 / Tracker fields Assignee Field empty or held Frontier Query · asks what is ready · 02 / Query · not remembered Frontier Query asks what is ready not remembered Claimable Board · claimable, unclaimed · 03 / Board Claimable Board claimable, unclaimed Thomas · reruns after merge/handback · 04 / Consume Thomas reruns after merge/handback Builder · claims and works the ticket · 04 / Consume Builder claims and works the ticket Owner · looks at the board · 04 / Consume Owner looks at the board every open ticket state read blockers all done? graph read assignee empty? state read answer written derived session start + ticket closes polled reviews readiness read-only claim, then dispatch writes assignee issue found → new ticket writes Legend data store data flow

Scroll sideways for the whole diagram

Explore the structure →

Ticket lifecycle

A ticket passes through seven stages.

The stages are named, so every measured incident attaches to exactly one of them.

One Ticket, Seven Checkpoints A workflow diagram generated by Archify. 01 / Thomas 02 / Builder Review ladder — one round Claim · assignee written + read back · Thomas Claim assignee written + read back Brief · dispatch into pane, at Base · Thomas Brief dispatch into pane, at Base Merge · Ledger line, assignee cleared · Thomas Merge Ledger line, assignee cleared Implement · commits on ticket branch · Builder Implement commits on ticket branch Code-review · Standards + Spec, one pass · Builder › Review ladder — one round Code-review Standards + Spec, one pass Simplify · simplify(increment): commit · Builder › Review ladder — one round Simplify simplify(increment): commit Cross-vendor arm · arm(ticket): receipt · Builder › Review ladder — one round Cross-vendor arm arm(ticket): receipt handback Legend User UI Agent logic Policy

Scroll sideways for the whole diagram

  1. 01claim

    Assignee written, then read back.

  2. 02brief

    Dispatched into a pane, at Base.

  3. 03build

    The Builder works in its own worktree.

  4. 04code-review

    Rin re-reads the artifact and the traces.

  5. 05simplify

    Markers cleared, the surplus cut.

  6. 06arm

    Codex re-reads; the receipt is bound to a SHA.

  7. 07merge

    One Ledger line written, assignee cleared.

Explore the six measured lessons →

mattpocock-skills

Astragentic runs on mattpocock-skills for both halves of a project.

Matt Pocock's skills cover both halves of a project, and Astragentic attaches each skill to the right role.

  • The management half: wayfinder sets direction, triage sorts the work, grill draws out the requirements, to-spec settles the spec, to-tickets slices it into tickets.
  • The engineering half: implement by TDD, code-review, simplify, diagnosing-bugs.
  • One method for both: Thomas manages and Builder builds by the same rules, from the first requirement to the last PR.
Thomas
triage · wayfinder · to-questionnaire · ask-matt
Shaper
grill-with-docs → to-spec → to-tickets
Builder
implement
Shared
grilling · tdd · code-review · codebase-design · domain-modeling · research · prototype · diagnosing-bugs
The right skill for each ticket A workflow diagram generated by Archify. 01 / Tracker 02 / Thomas 03 / Shaper 04 / Builder Ticket on the tracker · Thomas takes it off the frontier · Tracker Ticket on the tracker Thomas takes it off the frontier Written back to the tracker · new tickets, the answer, the handback · Tracker Written back to the tracker new tickets, the answer, the handback triage · classify: what kind of work? · Thomas triage classify: what kind of work? to-questionnaire · a question for you to decide · Thomas to-questionnaire a question for you to decide wayfinder · direction still foggy · Thomas wayfinder direction still foggy grill-with-docs · draws out the requirement · Shaper grill-with-docs draws out the requirement to-spec · pins the spec · Shaper to-spec pins the spec to-tickets · cuts it into tickets · Shaper to-tickets cuts it into tickets diagnosing-bugs · find the cause first · Builder diagnosing-bugs find the cause first implement · TDD, commits on the ticket branch · Builder implement TDD, commits on the ticket branch code-review · Standards + Spec · Builder code-review Standards + Spec simplify · clean markers, cut the excess · Builder simplify clean markers, cut the excess handback, ticket closed answer written on the ticket new tickets on the board it is a bug no spec yet ready to build owner decision foggy, multi-session direction settled Legend User UI Agent logic Policy External system

Scroll sideways for the whole diagram

Learn more about the choice →

Approach

AI is now a real developer. Astragentic puts you in charge of that developer team.

A coding agent today takes the work, writes the code, runs the tests and fixes until they pass. Once execution is no longer the bottleneck, the engineer's value moves elsewhere: setting the right requirement, making the right call, keeping the process on course.

Astragentic is built so that you do exactly that part. It organises agents into an outsourcing team under the familiar SDLC discipline, and redesigns dispatch, review and handback for a speed no human team can sustain.

Explore the whole approach →

Features

Six things a team can do that a single agent cannot.

Each card opens the page that explains the mechanism behind it.

  • The Cross-Vendor Arm A sequence diagram generated by Archify. Builder · own worktree · Sequence participant Builder own worktree Codex · adversarial-review · Sequence participant Codex adversarial-review Ticket Branch · HEAD · Sequence participant Ticket Branch HEAD Thomas · resident router · Sequence participant

    A review gate in two layers, two AIs from two vendors.

    Every ticket goes through a code review against Standards and Spec on Claude Code, then a cross-read on Codex. Two models from two vendors read the same diff before the merge, so quality does not rest on a single model.

    Read more →
  • The Frontier Query A data-flow diagram generated by Archify. Open Tickets · all tracker items · 01 / Tracker fields Blocking Edges · blocked_by graph · 01 / Tracker fields Assignee Field · empty or held · 01 / Tracker fields Frontier Query · asks what is ready · 02 / Query · not remembered Frontier Query asks what is ready not remembered Claimable Board · claimable, unclaimed · 03 / Board Claimable Board claimable, unclaimed Thomas · reruns after merge/handback · 04 / Consume Builder · claims and works the ticket · 04 / Consume Owner · looks at the board · 04 / Consume blockers all done? answer written derived

    Continuous operation around the issue tracker.

    Every requirement, spec and ticket sits on the tracker. When a review finds new work, it is written up as a new ticket. The team runs around the clock without you watching it, and nothing falls outside the system.

    Read more →
  • Five Roles, Five Session Lifespans An architecture diagram generated by Archify. Thomas · resident router · Architecture component · session: resident Shaper · grill → spec → tickets · Architecture component · session: unbroken Shaper grill → spec → tickets session: unbroken Builder · implements, own worktree · Architecture component · session: per ticket Builder implements, own worktree session: per ticket Rin · verifies artifact + traces · Architecture component · session: per milestone QA · runs the real product · Architecture component · session: per walk

    A team with names, roles and contracts.

    Thomas represents you, the Shaper shapes, the Builder builds, Rin holds the gate, QA accepts. Each role carries its own contract and system context, so responsibility is clear and nobody does someone else's job.

    Read more →
  • Four Layers, One Harness An architecture diagram generated by Archify. Claude Code · runtime · RUNTIME Claude Code runtime Codex · cross-vendor arm · RUNTIME Codex cross-vendor arm Grok Build · junior pane (optional) · RUNTIME Roles · Thomas · Shaper · Builder · QA · Junior · HARNESS Skills · 18 packaged skills · HARNESS Memory / Ledger · what actually happened · HARNESS Hooks · 4 lifecycle hooks · HARNESS Tracker · GitHub · Jira · Linear · COORDINATION herdr · one pane per agent · COORDINATION git worktrees · one checkout per ticket · COORDINATION Your Project · repo · GLOSSARY.md · ADR · YOUR PROJECT

    One runtime, a second vendor to read it back.

    Every role runs on Claude Code. Codex comes in when you want a second vendor to re-read the diff, and a Builder may hand the typing to a junior pane on another runtime. Model and effort per role are declared in orchestrator.md.

    harness/.agents/orchestrator.mdbuilder · claude · claude-sonnet-5 · medium

    Read more →
  • RoleRuntimeModelEffort
    Thomasclaudeclaude-opus-5medium
    Shaperclaudeclaude-opus-5high
    Builderclaudeclaude-sonnet-5medium
    QAclaudeclaude-sonnet-5low

    The right model for the right work.

    Sonnet for the Builder and QA, where fast and cheap matters; Opus for Thomas, the Shaper and Rin, where long reasoning matters. Cost and quality are balanced per role instead of one model for everything.

    Read more →
  • Every Agent Gets Its Own Pane An architecture diagram generated by Archify. Thomas · resident router · HERDR WORKSPACE ticket:TRA-139 · Builder · HERDR WORKSPACE ticket:TRA-139 Builder ticket:TRA-142 · Builder · HERDR WORKSPACE ticket:TRA-142 Builder spec:TRA-87 · Shaper · HERDR WORKSPACE qa:TRA-125 · QA · HERDR WORKSPACE rin:TRA-125 · Rin · HERDR WORKSPACE

    Full oversight, no need to take over.

    The tracker board, the herdr panes, the designs and the decisions can all be read back. Thomas comes back to you at the points that matter: UI/UX, and the choice of tech stack. You decide, the team builds.

    Read more →

The right size of project

For long-lived projects with many parts running in parallel.

A project is not large because it has sprints or stories. It is large because it is long-lived, wide, dependent and risky, and Astragentic has one mechanism for each: the tracker and receipts keep state outside any agent's memory, claims and worktrees let several Builders run in parallel, blocking edges and the frontier query keep the order, Rin's gate and QA's walk stop a merge before it hurts. With none of the four, an ordinary agent session is enough.

A fit when

  • There is a roadmap of several releases; the codebase lives on for months after launch.
  • Several modules or subsystems (app, backend, admin, integrations) are built in parallel.
  • Work depends on other work and needs ordering; real users make regressions a risk.

Not needed when

  • One deliverable, done when delivered.
  • One person working sequentially would keep up; nothing runs in parallel.
  • No dependencies between pieces of work, no release after this one.

Tech stack

Seven things to have before you install.

Five required, one optional, one pick-one-of-three. The check-requirements.sh script checks all of them for you before the install.

Required tech stack

  • Claude Code CLIrequired

    Runtime for the roles. Rin's milestone gate runs only on Claude, so without it nothing can gate.

  • Codex CLIoptional

    Second vendor for the cross review. Without Codex the team runs single-provider.

  • Git ≥ 2.5 with worktreerequired

    The isolation boundary: one checkout per Builder, nobody moves anyone else's HEAD.

  • herdr ≥ 0.8.0 and the herdr skillrequired

    One pane per agent. Thomas sees which agent is running and sends or waits on messages through the herdr CLI.

  • mattpocock-skills ≥ 1.3.1required

    The SDLC method the team follows: grill, spec, tickets, implement, code review.

  • Issue tracker: GitHub Issues, Jira or Linearpick one

    The team's shared memory. Every task, claim and receipt passes through it.

  • python3required

    Runs the git-guard hook and the contract reload after compaction.

Start an agent over the CLI

  1. claude   --dangerously-skip-permissions --agent builder --model <model> --effort <low|medium|high|xhigh|max>

Install

Five steps to put the team into your repo.

Astragentic installs from your checkout into each project folder, not onto the machine. One checkout serves many projects, and every customisation you make there reaches them by this same install path.

five steps · in order

  1. Check the machine has the tech stack

    ./check-requirements.sh

  2. Install the harness into your repo

    Run it from the Astragentic folder, pointing at the project folder. It only copies one release into that project's .astraler/releases/ and edits none of your files. One Astragentic checkout serves many projects; you tune and upgrade the harness in one place, then install it again per project.

    ./install.sh /path/to/your-repo

  3. Let Claude Code adapt the harness to the repo

    Reads and executes ADAPT-HARNESS.md: tracker name, ticket prefix, docs paths.

    cd /path/to/your-repo
    claude "Read .astraler/releases/2.9.0/ADAPT-HARNESS.md completely and execute it."

  4. Configure mattpocock-skills for the repo, once

    This skill declares the tracker, the triage label set and where GLOSSARY.md and ADRs live; the engineering skills read that configuration afterwards.

    claude
    /mattpocock-skills:setup-matt-pocock-skills

  5. Open Thomas's session

    Thomas runs without per-command permission prompts so it can route continuously; model and effort follow the thomas row in orchestrator.md.

    claude --dangerously-skip-permissions --agent thomas --model claude-opus-5 --effort medium

Customise

Everyone works with AI differently. Astragentic is the scaffold for those who work by agent orchestration.

There is no single right way to work with AI. Astragentic does not choose for you.

  • The full SDLC loop: five roles, a gate at every milestone, a QA walk before merge.
  • The minimal shape: two agents, one representative and one builder.
  • Your own stack: swap the tracker, swap the runtime, add a review step of your own.

Customising means editing files in your checkout. Each role is a contract, each skill a folder, each hook a script.

The path from a change to a project is the release path: bump VERSION, add an entry to RELEASE-NOTES.md, then reinstall with install.sh. Inside the project the adaptation step compares the new release with the one running and keeps the files that belong to you, such as orchestrator.md.

Customize once, re-install every time Immutable: a staged release never changes at the same VERSION, and staging touches no project file; a change means a new VERSION. 01 / Astragentic checkout 02 / Your project Edit the scaffold · roles · contracts · skills · hooks · Astragentic checkout Edit the scaffold roles · contracts · skills · hooks Bump VERSION · adds `# Astragentic <version>` · Astragentic checkout Bump VERSION adds `# Astragentic <version>` ./install.sh <project> · stages `releases/<version>/` · Astragentic checkout ./install.sh <project> stages `releases/<version>/` ADAPT-HARNESS.md · compares vs. applied release · Your project ADAPT-HARNESS.md compares vs. applied release Your files kept · kept: orchestrator.md; drift flagged · Your project Your files kept kept: orchestrator.md; drift flagged Runs new release · applied-version recorded · Your project Runs new release applied-version recorded Observe the team · panes, receipts, lessons · Your project Observe the team panes, receipts, lessons stage next change Legend User UI Agent logic External system

Scroll sideways for the whole diagram

Self-repair

The scaffold learns from every loop, and the rule it draws goes straight into a file agents read.

A team of agents repeats its own mistakes when nothing writes them down. Here something does: every incident is one line in an append-only ledger, with a fixed id, never renumbered and never deleted.

A line that yields a rule puts that rule straight into a role contract, a skill or a hook — the files an agent reads at the start of its session. At the next dispatch the whole team behaves differently, not because anyone remembered, but because the text changed.

The foot of a merge commit

  1. Pass: code-review, simplify, arm
  2. Ledger: AST-136 — --grep is BASIC regex, and every marker kind
  3.         in this system contains parentheses
  • It closes at merge: the merge commit carries a Ledger: line naming what went in. Ledger: none is valid; its absence is not.
  • No build step: the rule lives in the contract file itself, which the agent reads at session start. A hook re-arms the contract after a session compacts.
  • Append-only: a line that has not yielded a rule yet stays where it is. An open record is more honest than a ledger holding only the things already solved.

The same property lets an agent customise the scaffold for you. All of Astragentic is text — contracts, skills, hooks — no binaries, no config schema to learn. You open a session inside the checkout, describe how you want to work, it proposes a diff, you approve it.

Read the whole mechanism →