Docs

Guides

Deploy complex work

Ship a product outcome that spans several features: one milestone, several tranches, many tasks, built in parallel and merged by you.

Complex work
Architect
Planner
Operator

Before you start

  • Vinaya is installed in the repository. See Get started.
  • The product work is specified upstream, for example as projects in Linear or epics in Jira.
  • You are the Principal: you approve the plan, rule when a run pauses for you, and merge.

The flow

Deploy complex work · the flow
OUTSIDE VINAYA · PRODUCT MANAGEMENT · defines the what, hands specs to engineering
Linear
Initiative → Project → Project milestone → IssueProject = the specced featureTeams own Issues; Cycles time-box them
Jira
Initiative → Epic → Story / Task / Bug → Sub-taskEpic = the specced feature · Release (Fix version)Jira Project = container, like a Linear Team · Sprints
STAGE 1 · THINKING · architect and planner
Architect
Execution Milestone: code direction+ tranche intents (drafts)⎇ milestone integration branch
Planner · per tranche
Reads real specs + real code,materialises intent into tasks⎇ tranche branch → milestone branch
TR-02planned
#418
#419
#420
#421
Planned tasks: each an Issue with a brief (Surface, objectives, test plan) — the contract the loop executes
STAGE 2 · EXECUTING AND RETROSPECTING · the loop, the gates, closure and the record: all automatic
Developer–Review LoopDRIVEN BY THE OPERATOR
dev-review-loop.tssends the work, reads the result, decides the next step
MULTI-AGENT ORCHESTRATION · THE DRIVER
Developer agent
implements the brief
Reviewer agents
judge it against its Surface and objectives
Atta Engine · LangGraph runtimeCHECKPOINTS · HALT AND RESUME · RECOVERY
Claude CodeSANDBOXED
CodexSANDBOXED
macOSsandbox: Seatbelt
Linux / Unixsandbox: seccomp
GATES · at every step, the doors to GitHub · same for planned and hot · cannot be skipped
Ring 0 · commit + push hooks
last door before GitHub
Ring 1 · CI on the PR
same checks, merge blocked while red
Ring 2 · audits
after merge, always on
BEFORE CLOSURE · REPLAN, RECOVER, MERGE
Ready? → Review and merge
Gates green on the pull request.Required reviews report.The Principal merges. Nobody else does.MERGED → ARCHIVE · REFUSED → EXECUTE / REPLAN
RETROSPECTING · on every merge, automatic
Archivist
Closes each task on mergeRecords what shipped and why
Tranche Archivist
Closes the tranche when its last task lands
Milestone close
When its tranches have closed
Retrospective record
What shipped and why
STAGE 4 · SELF-IMPROVEMENT · the Log teaches the process
Report: what the Log says
Written from every run of the deploy. Example figures.
34 mintime per task
19 of 52second rounds
418problems caught
WHERE THE TIME GOES
Developer 84% · Reviewers 16% · most extra rounds come from one gate · a vague Surface doubles the rounds
Improver
Reads the report, proposes what to changeBACK TO LINEAR / JIRA · THE PRINCIPAL APPROVES
Project: run the doc gate before pushFix · cuts an expected 0.7 rounds per task
Project: surface check at planning timeFix · catches vague briefs before dispatch
Project: resume preview in StudioNew feature · shows what a ruling will change

Steps

  1. 1

    Turn the product work into a milestone

    In your agent (Claude Code or Codex), run /vinaya architect. Describe the outcome and the projects behind it. The Architect declares one Goal as a GitHub Milestone and names its tranches. You decide the parts together.

  2. 2

    Plan every task

    Run /vinaya planner and ask it to plan every part of the milestone. The Planner reads the real code first, then writes each task as a GitHub Issue with its objectives, Surface, checked facts and test plan, and declares dependencies and conflicts. You approve the plan before anything is written. Every Issue passes the Issue checks as it is written.

  3. 3

    Run the tasks

    Run /vinaya operator. The Operator starts each ready task through the loop: a Developer works in a sandbox, the gates run at commit, push and on the pull request, and two fresh reviewers judge the result. Independent tasks run in parallel; dependent ones wait. See The loop.

  4. 4

    Answer when a run pauses for you

    A run that needs a decision pauses and says who must act. Infrastructure problems retry by themselves, and the Operator repairs the environment. A policy or scope question is yours: answer it with vinaya pr rule. See Pauses and rulings.

  5. 5

    Merge

    Each pull request ends ready for merge, with every gate green and both reviews current. You merge. Nobody else does.

What you get

  • One reviewed pull request per task, each landed on its parent branch.
  • Each task closed on merge, each tranche closed when its last task lands, and the milestone closed when its tranches have. See Retrospecting.
  • Every act in the Log, live in Studio.

What's next

Deploy medium work

One feature, no milestone

Thinking

How work is shaped before execution

Executing

The loop, batches and the Operator

Roles

Who does what

The whole process

Every flow on one diagram, from product work to merge and back.