Skip to content
commission

Interop — adopting commission over an existing tracker

You will be able to bring an existing backlog into commission, or run commission alongside a tracker that is still the system of record — binding only the work that genuinely has to reflect outward, and keeping every outbound write supervised.

Commission is a single-source-of-truth product: it’s subtractive, meant to replace scattered boards and status docs with one queryable truth. This document covers the opposite situation — when Commission has to coexist with a system that’s already the source of truth (Jira, GitHub PRs). Treat everything here as an adoption bridge, not part of commission’s daily loop:

  • Use it to migrate work into commission from a legacy backlog, then stop.
  • Or, if a subset of work genuinely must reflect outward to a human system, use the sync layer deliberately and supervised.

None of this activates unless you opt in. No import, no binding → no interop machinery at all. Greenfield and side-project use never touches any of it.

Honest caveat. “Works with Jira” is never generic — every Jira instance is a snowflake of custom fields, workflows, and status names. The adapter is configurable (field ids, status vocabulary, key allowlists), but expect a per-instance configuration pass, and treat the first outbound --plan as something a human reads before anything is pushed.

Importing an existing backlog

# markdown boards (mega-docs style) → a Commission project
commission import mega-docs ~/path/to/mega-docs

# Jira issues → a local commission project
export JIRA_BASE_URL=https://yourco.atlassian.net
export JIRA_EMAIL=you@company.com
export JIRA_API_TOKEN=...        # id.atlassian.com → security → api tokens
commission import jira --slug work
commission import jira --jql "sprint in openSprints() AND assignee = currentUser()"
commission import jira --from-file saved-search.json   # offline / tokenless

No token? If your agent has an Atlassian MCP connector, have it run the JQL search there and save the JSON — --from-file accepts both the REST v3 envelope (issues: [...]) and the MCP/Rovo envelope (issues: { nodes: [...] }).

Jira “Blocks” links become commission deps; statuses map to open/in_progress/ in_review/done; priorities map to p0–p3; components become touches labels (so parallel dispatch avoids collisions); due date, sprint, rank, and severity import when their custom-field ids are configured. Each task links back to the issue.

Bindings + two-way sync (deliberate, supervised)

A task can be bound to the external objects it is — a Jira issue, one or more GitHub PRs across repos. Bindings are the only trigger for sync.

commission bind work-4 --jira RTB-543
commission branch work-4 --checkout      # commission/work-4-... — PRs self-identify
commission sync                          # observe → canonicalize → divergences + plan
commission sync --plan                   # outbound plan as JSON (an agent executes it)
commission sync --push                   # or commission pushes Jira transitions itself
commission sync accept <binding-id>      # side with the external claim instead

Rules, fixed rather than per-project:

  • Signals beat claims. Observable PR reality (draft / open / changes- requested / merged) sets commission’s status; a Jira status field is a claim that auto-applies only when commission hasn’t been moved by an agent.
  • Disagreements become divergences with a one-command fix, surfaced on boards, task pages, commission doctor, and the standup.
  • Safety floors: done tasks never auto-reopen; closed-unmerged PRs never auto-cancel; merged PRs attach evidence and close the task only under autoCloseOnMerge (gates still apply).
  • Plans compare meaning, not names — same-category workflow states (Triaged, Groomed, Awaiting QA…) are the external system’s business and are left alone.

Per-instance configuration & isolation

Config lives in the project’s integrations (settable via commission integrations or a repo’s .commission.json), and it’s an allowlist — a project that doesn’t declare a Jira site / repo / key-prefix cannot bind to it, so one project can never write to another’s systems.

commission integrations --jira-url https://yourco.atlassian.net
commission integrations --jira-field rank=customfield_10023 --jira-field severity=customfield_10390
commission integrations --jira-status in_review="Awaiting QA"     # site vocabulary
commission integrations --add-repo owner/name --auto-close-on-merge on
commission integrations --selection severity,sprint,due,priority,rank,age

Site identity is enforced on observe, push, and import: env JIRA_BASE_URL must match the project’s declared site, or the operation is refused.

Background reconciliation

commission serve --sync 5m    # pull-only poll; outbound plans are logged, never pushed

Pushes always stay explicit (--push, or an agent executing a --plan through its own access) — Commission never writes to an external system unattended.

Import, or bridge?

This page is the bridge: commission running alongside a system that is still the source of truth. If you are moving off that system for good, you want migration instead — it covers Jira, Linear, and markdown boards, what carries over, and when to stop importing.

Choosing wrongly is expensive in one direction only. Importing and then leaving the sync running “just in case” leaves two systems that both believe they are authoritative, which is worse than either alone.

This page is docs/guides/interop.md in the Commission repository, rendered in place — the site keeps no copy of it. The repository is private, so there is no edit link to follow.