Roles

Vinculum uses a five-tier role model: General, Colonel, Major, Lieutenant, Grunt. Each tier has a different scope, different responsibilities, and different tools it reaches for.

Why three tiers?

One tier doesn't scale — a single session that orchestrates, implements, and reviews its own work has no external check. Five tiers is bureaucracy. Three tiers match the natural shape of large software work: someone who sets direction, someone who owns execution of a wave, and someone who ships individual pieces.

The five roles map cleanly to the substrate: Generals write high-level decisions and specs, Colonels write directives and reviews, Majors coordinate parallel work streams, Lieutenants review and commit, Grunts write implementations and checkpoints. The graph structure reflects the organizational structure.

The five roles

General

The General is the orchestrator. It sets priorities, decides what gets built and when, approves or rejects colonel-level decisions, and reads the full graph to maintain a picture of project health. Generals typically run in the primary interactive session — the one you're talking to.

A General's primary tools: get_briefing, get_directive_tree, write (for decisions and specs), resolve_attention.

Colonel

A Colonel owns a wave of work. It receives a high-level spec from the General, breaks it into directives, spawns grunts to implement those directives, reviews the grunt outputs, and commits code to the repo. The Colonel is the only role that runs git commands.

A Colonel's primary tools: write (for directives), spawn_grunt, amend_directive (review stage), get_grunt_context, git_diff, git_log.

Grunt

A Grunt claims one directive and implements it. That's it. A grunt session boots, runs the bootstrap protocol, claims the directive, works, writes checkpoint entries as it goes, and finishes with an implementation entry that lists every file it touched. Then it stops.

A Grunt's primary tools: claim_directive, amend_directive (checkpoint and implementation stages), write (for questions), read_file, read_entry.

Rank vs role

Vinculum distinguishes between substrate roles and vocabulary ranks. The substrate roles are the three above — they determine what a session can write and what permissions it has. The vocabulary ranks are the full military ladder (General, Colonel, Major, Lieutenant, Sergeant, Grunt) used in prose and session labels for human readability.

In practice: a session labeled “Sergeant” is still a grunt-role session. “Lieutenant” is a colonel-role session that specializes in review. “Major” sits between Colonel and General. The substrate only cares about the three tiers.

How sessions get their role

When a grunt is spawned, the spawn request specifies its role. The grunt's system prompt is generated with that role's conventions injected. The claim_spawn tool registers the session and returns the role.

Human sessions (the one you're running interactively) default to General unless you explicitly set a different focus via declare_focus.

Next: Spawning

Roles come alive through spawning. Read about the spawn cycle →