The Vinaya process

Thinking

Everything before an agent touches code. Someone who read the code writes a Goal, a tranche or one Issue; Vinaya checks it as it is written and freezes it at dispatch.

Architect

Planner

Principal

Issues

Frozen brief

About Thinking

Thinking is the first of the four stages of the Vinaya process. It answers one question: what enters execution?

Someone reads the code, decides what must change and what must not, and writes it down in a form Vinaya can check. The output is always a GitHub Issue: planned, backlog or hot (see Overview).

Thinking ends when the Issue is rendered into a frozen brief at dispatch. From then on the brief cannot be edited. A change becomes a new Intent version, with a reason (see The loop).

Where to start

There are four ways in. Each works without the one above it.

Start from	Who writes it	What you get	Guide
A goal	Architect	A GitHub Milestone naming its tranches	Deploy complex work
A plan	Planner	A tranche: labelled Issues with dependencies and conflicts	Deploy medium work
One fix	Planner	A backlog Issue	Deploy backlog issues
Now	Principal	A hot Issue	Deploy hot issue now

In this section

Goals and milestones

The Architect declares a Goal as a Milestone

Tranches and tasks

The Planner cuts a tranche into task Issues

Issue kinds

Planned, backlog and hot Issues

Readiness and the frozen brief

Checked facts, dispatch readiness, the brief

How it works

1
Declare a Goal (optional)
The Architect runs vinaya milestone create. The result is a Milestone with ### Tranche intents.
2
Plan a tranche
The Planner runs the readiness step, then the deep dig and sizing, then the topology. Each task becomes one Issue through vinaya issue create, labelled vinaya/tranche:<slug>. An independent plan review in a fresh Planner session follows, then the Principal approves.
3
Or write a backlog Issue
For a single fix, the Planner runs the readiness step and vinaya issue create with no tranche label.
4
Dispatch
The Planner or Principal runs vinaya task brief or vinaya task run. Four dispatch gates are checked, the brief is rendered, the facts are checked again, and the brief is posted frozen as the Issue's aeg:brief:v1 comment.

What holds along the way:

The author runs the readiness step before writing a word. See Readiness and the frozen brief.
Every Issue write goes through vinaya issue create or vinaya issue edit, which validate the body before anything reaches GitHub. --validate-only validates and writes nothing.
A tranche counts as planned only when every task has an Issue, vinaya brief render passes for each, and the independent plan review has no open findings.
Dispatch checks four gates: the Issue exists, dependencies are merged, no conflicting sibling is open, and the render is complete. Then the brief is rendered and posted frozen.

Roles

Role	Does in Thinking	Never does	Person or agent
Architect	Declares a Goal as a Milestone: goal prose, an optional `Release:`, optional `### Tranche intents`	Cut or size a task, plan a tranche, edit or close a Milestone	Agent
Planner	Runs the readiness step; cuts tranche Issues and backlog Issues; declares dependencies and conflicts; moves `todo` tasks between tranches; runs the dispatch act	Write the brief by hand, write status, execute, close a tranche, create a Milestone	Agent
Principal	Approves the plan before dispatch; edits a Milestone's goal; edits objectives after freeze; prepares (freezes) a task; writes hot Issues	Plan tranches, write code	Person
Operator	May submit an Issue for checking with `issue create --validate-only`	Decide scope, facts or objectives; edit an Issue	Agent or person

Hand-offs in this part:

Architect to Planner carries one field: the intent line.
Planner to Developer carries the rationale, rendered into the brief.
Planner to Operator has its own hand-off contract.
Tranche Archivist to Planner feeds Thinking from Retrospecting: a finished tranche must be archived before the next tranche on the same product is planned.

See Roles for every role.

Gates

Most process-specific gates run in Thinking, because the Issue is what they check.

When	Gate	Ring	Refuses
Issue create or edit	`issue-title-grammar`	1	A title outside Vinaya's grammar
	`issue-objectives-numbering`	1	Malformed objective numbering
	`issue-parts-coverage`	1	A Part that cites no valid objective
	`issue-surface-globs`	1	Invalid or unresolvable Surface globs
	`issue-milestone-attach`	1	On edit, a task Issue whose Milestone is not the one its tranche label resolves to (not checked on create)
Milestone create or edit	Milestone shape check (a validator, not one of the 37 checks)	1	A missing goal, a malformed `Release:`, unparseable `### Tranche intents`
Before dispatch	`dispatch-readiness`	1 (also Ring 0 at push)	A task whose Issue, dependencies, conflicts or facts are not ready
At dispatch	Fact recompute	—	A checked fact the parent branch no longer contains. The brief does not freeze

The five Issue checks run inside the validated Issue write, before anything reaches GitHub. A refused write never becomes an Issue. The write also runs the briefSchema.issue builtins and content checks: blast radius, project registry, premises, Surface coverage and pinned-file collisions. Each refusal names its check and the fix.

Hot Issues will pass the same checks with the minimal body. The Principal's recorded readiness check stands in for the Planner's.

See Ring 1 Issue checks for each check.

Configuration

Key	What it changes in Thinking
`briefSchema.issue.sections`	The builtins the Issue write runs. Vinaya's own repository uses `issueRationale`, `objectives`, `briefSections`, `project`
`rings.ring1_forgeWriteInterception`	`false` skips brief-schema validation on Issue and pull-request writes (an empty section set). Default `true`
`planning`	Planning policy. `planning.collisionThreshold` (default 3) decides when shared pinned files require a `Conflicts-with` edge
`blastRadius`	`blastRadius.extraDomains` declares extra collision domains, for example `migrations/` or codegen output
`gateCutovers`	The Issue numbers from which the `objectives`, `briefSections` and Documentation rules apply
`principals`	Who may freeze a brief and edit objectives after freeze
`checks`	Selects and parameterizes checks, including the Issue checks and `dispatch-readiness`

See Vinaya keys.

What gets logged

Act	Log events
Every planning command (`issue create`, `issue edit`, `milestone *`)	`operation` · `completed`, one per command
A check or readiness check that does not pass	`gate` · `checked`, plus one `gate` · `summary` per run
An Architect or Planner agent turn	`dispatch` and `role_attempt`, with `usage` for its tokens

The Log is never written to GitHub and never decides anything. See Events.

What's next

Deploy medium work

Plan and run your first tranche

Tranches and tasks

How the Planner cuts work

Readiness and the frozen brief

What is checked before dispatch

Executing

What happens after the brief freezes