An OSS Checker Born from AI-Agent Operations

When AI agents enter real development work, conversations quickly move beyond model names and prompts. Teams have to decide who owns implementation, what each role may change, who reviews the work, and what exactly is being handed over.

Netsujo extracted one reusable part of that operating practice and released it as Agent Role Contracts v0.1.0 under the MIT License.

• GitHub: suirindo/agent-role-contracts
• npm: @netsujo/agent-role-contracts
• Version: `0.1.0`
• License: MIT

What does it check?

Before work is assigned to an agent, Agent Role Contracts checks whether the declared team and task contradict each other.

The public checker covers declarations such as:

• roles and authority
• separation between implementer and reviewer
• explicit routing for task types
• requested task write scope
• handoffs between roles

A minimal contract might say:

```text

implementer

write: src/**

reviewer

read-only

```

If a task routed to the implementer requests `secrets/production.txt`, the checker rejects the declaration because the requested scope is outside the declared write authority.

It does not change filesystem permissions. Its job is earlier in the workflow: compare the work you are about to request with the authority you said the role should have.

Where is it useful?

One AI implements, another reviews

A team can declare logical roles first:

```text

implementer -> write_scoped

reviewer -> read_only

human -> final approval

```

At runtime, Claude Code, Codex, or another tool can be assigned to those roles. Changing the runtime does not require redefining the logical contract.

Several agents own different write scopes

```text

frontend-agent -> src/frontend/**

backend-agent -> src/backend/**

```

If a task falls outside the scope of its routed role, the mismatch can be found before the agent starts changing files.

A handoff needs an explicit boundary

The `handoff` command can check a handoff document against the task and declared role relationships, including task identity, objective, from/to roles, and status.

That gives a team something more precise than “continue from the previous chat”: the transfer itself becomes data that can be checked.

Try the starter in five minutes

The repository includes a deliberately small starter. Use Node.js 22.5 or newer.

```sh

git clone https://github.com/suirindo/agent-role-contracts.git

cd agent-role-contracts

git checkout v0.1.0

node bin/agent-role-contracts.mjs validate \

--bundle examples/starter-bundle.json

node bin/agent-role-contracts.mjs explain \

--bundle examples/starter-bundle.json \

--task examples/starter-task.json \

--format text

```

Then run the intentionally out-of-authority task:

```sh

node bin/agent-role-contracts.mjs explain \

--bundle examples/starter-bundle.json \

--task examples/starter-task-outside-scope.json \

--format text

```

That case fails with `TASK_WRITE_SCOPE_OUTSIDE_AUTHORITY`.

For integration into your own project, the package is available from npm:

```sh

npm install @netsujo/agent-role-contracts

```

What a PASS does — and does not — establish

A PASS is not an execution authorization.

It says that the declarations supplied to that command did not violate the consistency rules the command implements. It does not establish runtime permission enforcement, identity, code correctness, secret scanning, merge authority, or deployment approval.

The three commands also receive different inputs. `validate`, `explain`, and `handoff` therefore establish different things. If your workflow uses a handoff document, run the `handoff` command with that document; an `explain` PASS does not validate a handoff it never received.

Keeping that boundary narrow is useful in practice. Each gate can say exactly what it checked and pass the unresolved questions to the next layer.

From community discussion to a runnable artifact

At Miyako de IT, AI-agent discussions tend to become operational very quickly: where did the workflow stop, how were roles separated, what remained a human decision, and what changed after a failure?

Agent Role Contracts grew out of that same layer of work.

A problem appears in real operations. A mechanism is built. Company-specific pieces stay private. A reusable boundary is extracted. Other people can run it, challenge it, and send improvements back through Issues or Pull Requests.

Technical communities do not have to share only articles and talks. When a lesson can be made reusable as code, the artifact itself can become part of the exchange.

Agent Role Contracts v0.1.0 is intentionally small. Run the examples first, then decide whether a declaration checker has a useful place in your own agent workflow.

• Browse the code and examples on GitHub
• View the npm package

If you find a missing refusal case or a declaration that should be checked differently, the public repository is the place to open an Issue or Pull Request.