Agentic engineering · for multi-milestone projects · v2.8.0

An outsourcing team made of AI agents.
Running by process, around the clock, for large projects.

Astragentic puts you in the client's seat at a complete software development unit: one representative to talk to, a team of agents with clearly defined roles to build, and an issue tracker at the centre so every piece of work leaves a trace. You keep the decisions and full oversight; the execution belongs to the team.

Explore how it works ↓Understand why Astragentic exists →

simulation
A simulated 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.

Agent

Each agent is an independent runtime session with a role and a contract of its own.

Every agent is a working session of Claude Code, Codex or OpenCode, launched from the command line with a defined role. It takes a task the way an employee does, hands back the result when it is finished, and can be cloned into several sessions running side by side: 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 role from drifting across a long context, and it is the address for sending work, reading a pane, and attaching the right skills.

A role is a declaration file in each runtime’s own format, loaded into the system prompt when the session opens; runtime, model and effort per role are declared in one place, orchestrator.md. The path of each file is on the Structure page.

Start an agent over the CLI on three runtimes

  1. claude   --dangerously-skip-permissions --agent builder --model <model> --effort <low|medium|high|xhigh|max>
  2. codex    --profile builder            # model and model_reasoning_effort live in the profile TOML
  3. opencode --agent builder -m <provider>/<model>   # no effort flag
Meet the AI team →

AI outsourcing team

What each agent does.

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 because grilling and spec are where the thinking happens; Builder and QA build and test, so they run Sonnet for speed and cost; 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 |
  3. |---|---|---|---|
  4. | thomas | claude | claude-opus-5 | medium |
  5. | shaper | claude | claude-opus-5 | high |
  6. | builder | claude | claude-sonnet-5 | medium |
  7. | rin | claude | claude-opus-4-8 | medium |
  8. | qa | claude | claude-sonnet-5 | low |
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

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

How agents talk to each other

Dispatching a ticket opens a conversation with an address.

A ticket is an issue on the tracker: a task, a feature or a requirement sliced small enough for one Builder to finish in one session. Each ticket carries a stable id in its title, a status, an assignee, and blocking edges to the work that must land first. Shaper creates tickets from the spec with the to-tickets skill; Thomas dispatches only the ones that are ready.

Thomas dispatches through the dispatch-ticket skill: claim on the tracker, create the branch and worktree, open a herdr pane, launch the role, send the brief, arm the watcher. The chain ticket → assignee → pane → worktree → branch → PR is one-to-one, so several Builders work in parallel without treading on each other.

simulation
A simulated 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.

When the roles all run Claude Code, the main channel is Claude Code’s built-in cross-session messaging. Every Claude Code session has a name; Thomas looks up the Builder’s with ListAgents and sends to exactly that name. In the receiving session the message shows up as a one-line preview, › Message from @thomas: …, expanded with ctrl+o, and the answer travels back into the session that sent it. A blocked Builder asks; Thomas reads the question, answers through that same channel, then sets a fresh Monitor and waits for the signal that the work is done. That is how the loop of dispatch, question, answer and handback runs unbroken, with nobody sitting and watching it.

Driving a Builder on Codex through herdr

  1. herdr agent start "builder-TRA-142" --kind codex --pane <id> -- codex --profile builder
  2. herdr agent prompt <pane-id> "<brief>"
  3. herdr agent read   <pane-id>
simulation
A simulated 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, including a Builder running Codex.

herdr is the visible plane and the fallback path: one named pane per role, a watcher reporting working, blocked, idle. Thomas reads a pane with herdr agent read when a session falls silent, and steers a Builder on Codex or OpenCode through the herdr CLI, where there is no cross-session messaging.

Learn more about dispatch →

The issue tracker

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

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

No more task lists in markdown with checkboxes an agent has to remember to tick. A ticket has an id, a status, an assignee, blocking edges; read and written through an API, so everyone gets the same answer.

A claim is an assignee line written and read back, so several Builders run in parallel. An issue found mid-work becomes a new ticket instead of getting lost in a message.

One ticket is one branch, one worktree, one PR, all named after the ticket. One worktree per Builder; once merged, the ticket closes and the worktree is cleaned up.

Each ticket keeps what the work was, how it was done, the questions asked, the receipt committed. You understand a piece of work by opening its ticket. GitHub Issues, Jira and Linear all work; there is no new tool to learn.

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
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
  1. 01claim

    Assignee written, then read back.

    AST-131

  2. 02brief

    Dispatched into a pane, at Base.

  3. 03build

    The Builder works in its own worktree.

    AST-097AST-092

  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.

    AST-015

  7. 07merge

    One Ledger line written, assignee cleared.

    AST-074AST-056

Explore the six measured lessons →

mattpocock-skills

Astragentic adopts mattpocock-skills as its framework for running and building a project.

Matt Pocock’s skill set covers both halves of a project. The management half: wayfinder sets direction, triage sorts the work, grill draws out the requirement, to-spec pins the spec, to-tickets cuts it into tickets. The development half: implement with TDD, code-review, simplify, diagnosing-bugs. Astragentic assigns each skill to the right role, so Thomas manages and the Builder builds inside one framework, 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
Learn more about the choice →

Why

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, like an engineer sitting next to you. Once execution is no longer the bottleneck, the engineer's value moves elsewhere: setting the right requirement, making the right call, and keeping the whole 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 to exploit a speed and a volume no human team can sustain.

Explore every design decision →

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, 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. Claude Code, Codex and OpenCode all support agent profiles at this level.

    Read more →
  • Four Layers, One Harness An architecture diagram generated by Archify. Claude Code · runtime · RUNTIME Claude Code runtime Codex · runtime · RUNTIME Codex runtime OpenCode · runtime · RUNTIME Roles · Thomas · Shaper · Builder · Rin · QA · HARNESS Skills · 16 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 · CONTEXT.md · ADR · YOUR PROJECT

    One process, several runtimes.

    Claude Code is the required base; Codex and OpenCode come in when you want a second vendor or another model. Which role runs on which runtime is declared in orchestrator.md; changing the runtime does not change the process.

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

    Read more →
  • RoleRuntimeModelEffort
    Thomasclaudeclaude-opus-5medium
    Shaperclaudeclaude-opus-5high
    Builderclaudeclaude-sonnet-5medium
    Rinclaudeclaude-opus-4-8medium
    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 for four reasons: it lives long (several releases, a codebase still edited months after launch), it is wide (several modules or subsystems worked on at once), it has dependencies (this must finish before that), and it carries risk (real users, regressions that cost). Astragentic has exactly four mechanisms for those four things: 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. Without all four, this machinery is overhead, and 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.

Four required, one optional, one pick-one. 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 and a fallback runtime. 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.2.3required

    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.

Install

Five steps to put the team into your repo.

Check the requirements, install the harness, let Claude Code adapt it to the repo, configure mattpocock-skills once, then open Thomas's session. From there, everything goes through Thomas.

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.8.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 CONTEXT.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