Skip to content

docs: make tracker team configuration explicitly consumer-owned #48

Description

@parsakhaz

Problem

Orchestra correctly delegates work-item destinations to each consumer repository, but the template and shared publishing reference do not explicitly warn that workspace and team names are consumer-owned configuration that can change.

A consumer repository can therefore retain a stale team name in its local tracker documentation. Agents then stop or route work incorrectly even when the connected tracker exposes the repository’s valid current team.

Bloom Text exposed this gap after its Linear workspace consolidated to a single Main Team while repository guidance still required a now-absent Engineering team.

Intent

Make the ownership and lifecycle of tracker routing unambiguous: Orchestra defines the publishing protocol; each consumer repository owns its tracker, workspace, team, and workflow-state configuration and must keep that configuration aligned with the live tracker.

Acceptance criteria

  • The AGENTS.md template says tracker workspace/team identifiers belong in consumer-repository guidance, not synced Orchestra skills or references.
  • The shared publish procedure says to resolve routing from the consumer configuration and the live tracker rather than infer or silently substitute a destination.
  • Guidance explains that stale consumer configuration should be corrected in the consumer repository; a user’s explicit correction may be used as current intent.
  • Existing tracker-agnostic behavior remains unchanged.

Starting points

  • templates/AGENTS.md (Work-item tracking)
  • references/publish-work-item.md

The Bloom-specific docs/mcp-linear.md correction belongs in Bloom’s repository and is intentionally out of scope here.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions