Plugin contracts
Phillip, Bandum, and Ryoma don't hard-code GitHub, Telegram, or Jira. Each such connection is a kit released on Tara, and the kit must follow the contract of the interface it provides. This page describes each contract so you can write a new kit or understand what an existing kit does.
Summary table
This table is generated automatically from the plugin design document, so it always matches the latest version.
| Interface | api | Capability group | Main functions | Kits available on Tara |
|---|---|---|---|---|
scm | 1 | task | me, issue, issues, assign, setStatus, defaultBranch, pullForIssue, createPull, review, comment (+ optional pullForKey, tokenInfo, checks) | kit-scm-github 1.6.0, kit-scm-gitlab 1.4.0 |
report | createIssue, issuesByLabel | same as above | ||
sync | repoInfo, milestones, changes, events, pull, dirs, file, putFile | same as above | ||
release | latestVersion, tagExists, dispatchRelease, releaseStatus, createRelease, releaseByTag, closeMilestone, branchHead, releases | same as above | ||
notify | 1 | send | check, send | kit-notify-telegram, -email, -slack, -zalo |
tracker | 1 | task | me, sprints, tasks, task, events | kit-tracker-jira 1.1.0 |
write | transition, comment, assign | same as above |
Common to all interfaces
A kit declares the fields provides, api, entry, and credential in metadata.forge.phillip. For what each field means, see Resource format.
A kit doesn't contain secrets and doesn't read secrets from files. The caller passes the token to the connect() function when it connects, and the kit receives only its own part. Each interface has its own api number. If a kit declares an api different from the number the core supports, the core refuses to load it and explains how to upgrade.
A kit package is immutable, locked by sha256, and digitally signed. Before you release a kit or add it to a service's configuration, run ph kit check. This command checks the contract and the required settings.
ph kit check ./kit-notify-teams
ph kit check kit-scm-github --liveFor a kit you're still writing in a directory, pass the path as in the first line. For a kit already on Tara, pass the kit name. With --live, the command makes a real call to me() (scm, tracker) or check() (notify) using the saved token. A notify kit also accepts --send "test" to send a real notification. The token for this command is accepted only through the PHILLIP_KIT_TOKEN variable, not as a command-line argument, so it doesn't end up in shell history.
scm v1
The scm interface connects Phillip to where source code and tasks live, currently GitHub and GitLab. The kit declares matches, the hosts of the origin remote that it serves. If a project uses GitHub Enterprise, add that host through the kit's configuration.
The entry module is an ESM file with no external package dependencies. It exports api = 1 and a connect({ token, repo, settings }) function. This function returns an object with the functions of the task group, as in the table below.
| Function | Purpose |
|---|---|
me() | Returns the login of the token owner |
issue(n), issues({ milestone }) | Reads one task, or lists tasks for the board |
assign(n, login) | Assigns a task to a person |
setStatus(n, s) | Changes the status to in progress, review, approved, or rejected |
defaultBranch() | The repo's default branch name |
pullForIssue(n) | The task's PR (an MR on GitLab), or null |
createPull({ title, head, base, body }) | Opens a PR |
review(pr, event, body, commit) | Approves, requests changes, or comments on a PR |
comment(n, body) | Comments on a task |
Two optional functions are tokenInfo() and checks. ph connect calls tokenInfo() to warn when a token lacks permissions, and for an older kit without this function the core skips the check. A kit can also declare credential.tokenPrefixes to accept additional valid personal-token prefixes beyond the ones the core already knows.
Errors carry a code in ScmError.code so the core handles every provider the same way. The codes are unauthorized, not_found, own_pull (you can't approve your own PR), and conflict. The status: … label names and the GH-n code are Bandum conventions that live in the kit, so GitLab can use scoped labels without changing the core.
Capability groups
A kit declares capabilities in metadata.forge.phillip, and leaving it empty means only task. Adding a new group doesn't change api, so an older core can still load a newer kit.
| Group | Caller | Purpose |
|---|---|---|
task | Phillip | The functions in the table above |
report | Phillip, the ph bandum bug command | createIssue to report a bug outside a task's scope, issuesByLabel to find duplicate issues |
sync | Bandum and Ryoma | Syncs the task copy and records manual test results |
The sync group includes repoInfo, milestones, changes, events, pull, dirs, file, and putFile. Bandum and Ryoma call the read functions with a read-only service token. When a Tester selects Approve or Send back on the Bandum web UI, the write functions run with the token of the person who selected it.
An SCM kit can also include an MCP server for agents. Those tools are on the MCP tools page.
notify v1
The notify interface sends notifications, such as Ryoma quota alerts or Tara submissions awaiting review. A kit doesn't declare matches. The only capability group is send.
The entry module exports api = 1 and connect({ token, settings }), and returns an object with two functions. check() validates the token and the destination without sending anything, then returns a description of the destination. send({ subject, text, to }) sends a notification, where to is the email of the people concerned (a team channel ignores this field).
In settings, any entry with required: true is mandatory, and the service doesn't start if it's missing. A kit that can run without a secret, such as an internal SMTP server, declares credential.optional: true. There are four error codes: unauthorized, not_found (no destination), unavailable (temporary, try again later), and other. Error messages must not contain secrets.
Tara includes four kits: kit-notify-telegram, kit-notify-email, kit-notify-slack, and kit-notify-zalo. How to enable them for a service is in Notifications. Zalo has some limits that come from Zalo OA itself, documented in the kit's README.
tracker v1
The tracker interface lets a service read tasks from a work-management system that isn't an SCM, such as Jira, while the source code stays on GitHub or GitLab. The interface is read-only and has only the task group.
The returned data has a shape close to the scm sync group's tasks, so the Flow metrics code can reuse it without knowing the provider. The entry module exports api = 1 and connect({ token, settings }), where settings.project is the project key and is required. The returned object has five functions.
| Function | Purpose |
|---|---|
me() | Identifies the token owner, in the same form as assignees |
sprints() | Lists sprints, equivalent to scm's milestones() |
tasks({ sprint, since }) | Tasks by sprint, or tasks updated since since, oldest first |
task(key) | One task, with the description as plain text |
events(key) | Status transition history |
The kit maps the task system's statuses to Bandum's status set: todo, in progress, review, approved, rejected, done. A task gets labels such as level: M and type: bug added to labels, so code that already reads level: and type: from labels keeps working unchanged. The history is also mapped to the scm event shape (entering or leaving a status is labeled or unlabeled), so the time in each status and the rework rate are computed as usual.
Tara checks tracker kits a bit more strictly: capabilities can contain only task, there is no matches, and settings.project must have required: true. kit-tracker-jira is a built-in kit that works with Jira Cloud as well as Server or Data Center.
guardrails
A kit that holds policy for Guardrails declares a metadata.forge.guardrails block instead of phillip.
"guardrails": { "schema": 1, "level": "company", "policy": "<path to the rules file in the package>" }level is company or project, and policy points to the rules file in the package. Rules are data, not code that runs: the Guardrails hook server reads this file and evaluates it itself. So you don't need to write an entry module, and there are no functions to implement.
The platform policy is the baseline (the company level, which only platform staff can approve). The policy of an organization or project can only tighten it, never loosen it. Before you submit the package to Tara, run ph guardrails check <package directory>. This command checks the rule format and tells you whether the package tightens or loosens the baseline.
Where kits run and how they're isolated
Different places have different levels of isolation.
On servers, meaning Tara, the Bandum service, and Ryoma, a kit runs in a separate Node.js process with node --permission, which requires Node.js 22.13 or later. The kit can read only the plugin directory. It can't write files, can't run child processes, and can't see environment variables that hold the service's secrets. The kit's tokens and passwords pass through connect(). So a kit that needs to write files or run commands can't run on a server. Rewrite it to use network APIs. A kit's network access isn't restricted yet.
A service loads only kits with the pinned sha256, a valid digital signature, and no entry in the yank list. Signing details are in Signing and revocation.
On your machine, Phillip loads the kit inside your own process, so the kit runs with your permissions and holds your token. Phillip loads only signed kits from your personal store or from an organization on Tara, with the sha256 locked in phillip.lock. It refuses kits from the community channel. Phillip doesn't write tokens to logs and shortens kit errors before printing them.