About Goals
A Goal is a product outcome and the tranches that serve it. It lives as a real GitHub Milestone. It is the one level above the tranche, and it is optional: most tranches have no Milestone and need none.
To plan work from a Goal end to end, follow Deploy complex work.
How it works
- 1
Declare the Goal
The Architect declares the Goal once, naming its tranches up front in
### Tranche intents. A tranche that already exists can also be adopted later. This is the only stage a human decision truly gates. - 2
Tranches run
Each named tranche runs its own flow: plan, dispatch, archive. The Milestone does not orchestrate; the Principal or a thin dispatch script decides when each tranche starts.
- 3
Close
When every declared tranche is complete, the Milestone reads
complete. Cutting a release for theRelease:version is a separate, largely manual act.
When an open Milestone names a tranche's slug, vinaya issue create attaches each new task Issue to that Milestone by itself. The Planner takes no step.
The Milestone description
The Milestone's title is free text for people. It is never parsed. The description carries three parts:
| Part | Required | Grammar | Meaning |
|---|---|---|---|
| Goal | Yes | Prose: whatever remains once the two parts below are removed | The product outcome |
Release: | No | Line-anchored, ** optional on both sides, code fences stripped first, first match wins | The only source of the target version. Never the title |
### Tranche intents | No | One bullet per tranche: - | Which tranches serve this Goal and what each contributes |
A tranche's goal is derived, never stored. It is the intent line whose slug matches the tranche's label, found by searching every Milestone's description. An intent line for a slug with no Issues yet is a real tranche in the planned state.
Commands
| Command | What it does | Who |
|---|---|---|
vinaya milestone create - | Checks the body's shape, then writes one Milestone through the GitHub API | Architect |
vinaya milestone edit <n> - | Same check as create, then rewrites the description | Principal |
vinaya milestone adopt - | Reattaches every Issue carrying each named tranche label to the target Milestone, then closes (never deletes) each slug's old legacy Milestone | No role is named |
vinaya milestone status <n> | Read-only. For each - <slug>: line, prints the slug, its derived lifecycle and its Issues' counts (merged, open, not planned) | Anyone |
vinaya milestone close - | Finds the tranche's Milestone, checks every Issue carrying vinaya/ is attached to it, refuses naming each unattached or foreign Issue, then closes it | Tranche Archivist |
milestone adopt refuses the whole call, before any write, on an unknown slug, a slug with no Issues, a missing or closed target, or a slug already adopted elsewhere.
Lifecycle
The state is derived from the Milestone's tranches. It is never written to the Milestone.
| State | When |
|---|---|
planned | Every named tranche is planned, or the Milestone names no tranches |
active | At least one named tranche is active |
complete | Every named tranche is complete. A Milestone naming zero tranches never reads complete |
Roles
| Role | Does | Never does |
|---|---|---|
| Architect | Creates the Milestone, once, with vinaya milestone create. Invoked by hand, on demand; no dispatch queue, no brief format | Cut or size a task, decide edges, read a version from the title, edit, move or close a Milestone, write status |
| Planner | Reads the derived goal as context when planning | Edit a Milestone description, treat an intent line as an instruction on sizing or edges, create a Milestone |
| Principal | Corrects a written Milestone's goal or Release: with vinaya milestone edit, as a product call | — |
| Tranche Archivist | Closes the Milestone at tranche close. See Tranche and Milestone close | — |
The Architect refuses when the goal is absent, when Release: is present but not a version, when ### Tranche intents does not parse, or when asked to cut a task, size a task or read a version from the title.
The hand-off from Architect to Planner carries exactly one field: the intent line, matched by slug. It carries no sizing, edges, traps, agent class, stop conditions, documentation list or status.
Gates
| Gate | When | Refuses |
|---|---|---|
| Milestone shape check | milestone create and milestone edit, before any GitHub call | A missing goal; Release: present but not a version; unparseable ### Tranche intents |
| Adopt check | milestone adopt, before any write | An unknown slug, a slug with no Issues, a missing or closed target, a slug already adopted |
issue- | Issue edit (Ring 1) | On edit, a task Issue whose Milestone is not the one its tranche label resolves to (not checked on create) |
| Attachment check | milestone close, before closing | Any tranche Issue not attached to the Milestone |
No config flag ever turns off the Milestone shape check.
Configuration
| Key | Effect |
|---|---|
briefSchema. | Extra sections a Milestone write must carry. Vinaya's own repository does not set it |
principals | Who may edit a Milestone's goal |
What gets logged
| Act | Log events |
|---|---|
Every milestone * command | operation · completed |
| An Architect agent turn, when dispatched | dispatch, role_attempt, usage |
There is no pull request to carry the Architect's token count, so it reports tokens wherever it reports back, as Tokens: milestone — Architect — <model> — in/.