Connect

Writing a role

Follow this page from top to bottom and you end with a working role in your graph that an assistant can be called as. Each step fills in one or two properties.

Before you start

• An assistant connected to Vinc over MCP (Connect over MCP), or a write key (vinc_sk_) if you will write from code.
• Check the four default roles first (Agents). If one is close to what you want, change it instead of writing a near copy.

As the example, this page builds a release notes writer: a role that drafts release notes from merged pull requests and leaves publishing to a person.

1. Write the job in one sentence

Start with mission. One role is one job that one owner could answer for. If you need "and" twice to describe it, it is probably two roles.

Write the role in English, as GRAPH.md asks. Say what the role produces and where the work stops ("leave them as a draft"). Copy the same sentence into one_liner; hosts show it in the role list.

2. Pick the seat

tier says what kind of seat the role takes. Pick the one that matches what the role leaves behind.

The release notes writer makes a file, so it is execute. A role that only reviews the notes would be a separate verify role: one seat should not both write and approve the same work.

3. Name it and file it

4. Draw the lines

never is what the role must not do at all. person_only is a step that has to happen, but a person takes it. Both are lists.

Write each item as something you could check afterwards. "Be careful" cannot be checked; "describe a change that is not in a merged pull request" can.

5. Choose the model level

rung is one of strongest, strong, fast and cheapest. Never write a model name here. Choose by how costly a wrong answer is, not by how big the job is.

• A wrong answer is expensive and hard to notice (a security review): strong or strongest.
• A wrong answer is cheap to spot and fix (a draft a person reads anyway): fast.
• A mechanical check with a clear right answer: cheapest.

Release notes are a draft a person reviews, so fast. Which model each level uses is on Roles and teams.

6. Give it what it needs

Put the house style in a document and list it in reads, rather than pasting the style into mission. Then several roles can share it, and changing the document changes every one of them.

7. Limit its tools

• disallowed_tools: tools the host must not give this role. A verify role should list Edit, Write and NotebookEdit.
• tools: tools or MCP servers the job needs. It is a list of what to have ready; the role returns the work if one is missing.
• isolation: worktree gives the role its own copy of the repository in Claude Code.

These are instructions to the host. Vinc does not block a tool by itself; the host has to apply the list.

8. Put it in a team (optional)

team, team_role (lead, coordinator or member) and job_title group roles in the app's Agent view. The order between roles is a link: prerequisite_of when one must finish before the other starts, relates_to for roles that work side by side. More on Roles and teams.

The whole role

Steps 1 to 7 together make this node. Lists stay JSON arrays: a single string is read one character at a time.

[
  {
    "id": "concept:agent-release-notes",
    "type": "concept",
    "title": "Release notes writer",
    "domain": "agent",
    "tags": [
      "agent",
      "execute",
      "role"
    ],
    "one_liner": "Write the release notes for a tagged version from its merged pull requests, in the house style, and leave them as a draft for review.",
    "props": {
      "mission": "Write the release notes for a tagged version from its merged pull requests, in the house style, and leave them as a draft for review.",
      "tier": "execute",
      "rung": "fast",
      "never": [
        "publish the notes",
        "describe a change that is not in a merged pull request"
      ],
      "person_only": [
        "publishing the release"
      ],
      "reads": [
        "doc:release-notes-style"
      ],
      "gates": [
        "every entry links its pull request",
        "no entry is longer than two sentences"
      ],
      "repos": [
        "my-app"
      ],
      "paths": [
        "CHANGELOG.md"
      ],
      "disallowed_tools": [
        "Bash"
      ],
      "writes_graph": [
        "episode"
      ]
    }
  }
]

9. Add it to Vinc

Choose one of four ways.

Read this graph's GRAPH.md with vinc_conventions first.
Then create an agent role in Vinc:
- id concept:agent-release-notes, topic agent, title "Release notes writer"
- mission: Write the release notes for a tagged version from its merged
  pull requests, in the house style, and leave them as a draft for review.
- tier execute, rung fast
- never: publish the notes; describe a change not in a merged pull request
- person_only: publishing the release
- reads: doc:release-notes-style
Search for an existing role first, write it with vinc_ingest,
show me the warnings, then read it back with vinc_graph.

from vinc import VincClient, VincPartialWrite

vinc = VincClient(api_key="vinc_sk_...")   # a write key
role = {...}                               # the node above
try:
    vinc.ingest([role])
except VincPartialWrite as e:
    print(e.result["warnings"])            # stored anyway; fix and resend

10. Check it

Read the warnings in the write result. The write checks each of these and still stores the role, so the warnings are the only thing that tells you something is off.

• The name after concept:agent- has characters other than lowercase letters, digits and hyphens.
• The topic is outside agent (or vinc/agent), more than one level below it, or missing on a new role.
• The title starts with "Agent role:".
• A required property is missing, or a new role has no properties.
• tier or rung has a value not listed above.
• A list property is not a list.
• one_liner and mission differ.

Then call the role. In Claude Code, run /mcp__vinc__agent-release-notes; elsewhere ask the assistant to read concept:agent-release-notes. The assistant receives the role written out like this:

# Release notes writer

Tier execute, rung fast.

## Mission
Write the release notes for a tagged version from its merged pull requests, ...

## Surface
Repositories: my-app
- CHANGELOG.md

## Read before the first edit, in this order
1. doc:release-notes-style

## Gates that must pass before the pull request
- every entry links its pull request
- no entry is longer than two sentences

## Never
- publish the notes
- describe a change that is not in a merged pull request

## Only a person does this
- publishing the release

If something reads wrong here, fix the property it came from, not the text.

11. Change it later

• Properties are replaced whole on every write. Read the stored role first (vinc_graph on its id), change what you need, and send all of it back. Anything you leave out is deleted.
• When you change reads, gates, never or person_only, write a decision in the same call: why, and what the value was before, linked to the role with about.

{
  "nodes": [
    {
      "id": "decision:agent-release-notes-add-breaking-gate",
      "type": "decision",
      "title": "Release notes flag breaking changes first",
      "domain": "agent",
      "props": {
        "choice": "Add the gate 'breaking changes are listed first'.",
        "reason": "Two releases buried a breaking change in the middle of the list.",
        "replaced": "gates had two items"
      }
    }
  ],
  "edges": [
    {
      "from": "decision:agent-release-notes-add-breaking-gate",
      "to": "concept:agent-release-notes",
      "type": "about",
      "evidence": "Release 2.3 and 2.4 notes"
    }
  ]
}

That way the role keeps its own history: open the role in the app and the decisions about it are linked right there.

All properties