team-tracking-mcp

team-tracking-plugin

A Claude Code plugin that gives an orchestrator and its specialist subagents a shared, durable view of the work they're driving. Tickets live in your real tracker (Obsidian Kanban or Jira); the plugin's MCP server is the contract between Claude and the board.

See examples/ for a browseable snapshot of an orchestrator-driven board.

How it works

The plugin splits an end-to-end orchestration cycle across three Claude contexts: a main session that supervises in-flight work, a planner subagent that reads the board and decomposes intent into tickets, and specialist subagents that execute one subtask each under a lock. The MCP server is in-process inside the main session and the tracker (an Obsidian vault or Jira) is the durable source of truth — every state change lands there as an event before any caller sees it.

flowchart LR
    subgraph CC[Claude Code session]
      O[Main session - team-tracking-supervise]
      P[Planner subagent - team-tracking-plan]
      S[Specialist subagent - team-tracking-execute]
    end

    subgraph SRV[team-tracking MCP server]
      Service[TicketService - lock state machine and event log]
    end

    subgraph TR[Tracker]
      Vault[(Obsidian Vault)]
      Jira[(Jira)]
    end

    O -- spawns --> P
    O -- spawns --> S
    P -- MCP --> Service
    O -- MCP plus listen CLI --> Service
    S -- CLI or MCP --> Service
    Service -- adapter --> Vault
    Service -- adapter --> Jira

A typical cycle, end to end:

sequenceDiagram
    autonumber
    participant U as User
    participant O as Main session
    participant P as Planner subagent
    participant T as Server
    participant S as Specialist subagent

    U->>O: plan and execute
    O->>P: spawn with PRD and project
    P->>T: list_board
    P->>T: create_ticket and promote parent to Todo
    P-->>O: dispatch_list JSON

    loop each entry in order
      O->>S: spawn with verbatim brief
      S->>T: bash team-tracking acquire
      T-->>S: lock_token plus inlined system_addendum
      S->>S: do the work
      S->>T: bash team-tracking checkpoint per commit
      S->>T: bash team-tracking release Done
      T-->>O: status_change event via background listen
    end

    Note over O,T: On Blocked the main session re-spawns the planner with blocker context

Two design decisions that fall out of this shape:

• The lock contract is the audit trail. Specialists can't commit_checkpoint, report_progress, or release_ticket without first calling acquire_ticket. Every acquire/checkpoint/release is an event on the ticket's append-only log; the visible scalar fields (update, progress_summary, lock) are read caches over that log.
• The protocol is delivered, not assumed. acquire_ticket returns system_addendum — the literal team-tracking-execute SKILL.md body inlined under a --- team-tracking-execute --- divider. Specialists receive the protocol on first acquire regardless of what their dispatching session put in the brief and regardless of which MCP tools the host granted them. The CLI is bash-callable, so the entire executor surface works with only bash granted.

What it ships