Skip to content
Colony Docs

Team Patterns

Colony does not require a particular organization design. These patterns help teams choose boundaries and controls without attributing behavior to Colony that belongs to their code host or operating process.

Choose tenant boundaries deliberately

Section titled “Choose tenant boundaries deliberately”

A tenant is a pipeline, data, and security namespace. Repositories, tasks, credentials, and configuration are associated with it, but tenant membership does not automatically grant every repository or Worker access to every other resource.

Use separate tenants when groups need distinct administrative, credential, data, or configuration boundaries. A shared tenant can simplify common operation of related repositories, but cross-repository access and coordination still depend on registered repositories, credentials, workflows, and Worker eligibility.

Tenant migration is an operational data and configuration change. Do not assume splitting or merging tenants is lossless or automatic; plan it against the capabilities of your deployment.

Start with a diagnosable scope

Section titled “Start with a diagnosable scope”

A focused initial scope makes failures easier to classify. A practical pilot often has:

  • one or a few repositories with clear ownership
  • explicit intake rules, so the team knows which issues Colony will admit
  • configured review commands that already work locally
  • automatic merge disabled until the team understands review and provider behavior
  • cost and attempt limits appropriate to the expected issue size
  • an Operator who watches blocked states and records why humans intervene

These are recommendations, not Colony requirements. Expand based on enough completed and failed work to understand your own risk—not a fixed 30-, 60-, or 90-day rule.

Keep repository guidance coherent

Section titled “Keep repository guidance coherent”

Colony loads repository guidance from .colony/conventions.md. Treat it as shared guidance for the registered repository: stack, architecture, test commands, naming, and patterns agents should avoid.

The built-in loader does not select the nearest folder-level conventions file for each changed file. If different parts of a monorepo need different guidance, explain those boundaries in the repository-level document or use separate repository/workflow/plugin arrangements where appropriate.

Runtime behavior belongs in colony.config.yaml, Cloud settings, workflow definitions, provider policy, or plugin configuration—not in conventions prose.

Coordinate epic work in the issue tracker

Section titled “Coordinate epic work in the issue tracker”

Colony can decompose epic-scale work into linked child issues and keep the parent in waiting-for-subtasks while Sweep tasks monitor completion. Colony does not assign a human “epic owner” or add team-specific reviewers automatically.

If a parent crosses team boundaries, assign ownership and reviewers using your issue tracker and code-host mechanisms. Make dependency and integration expectations explicit in the parent and child issues.

Use provider controls for release policy

Section titled “Use provider controls for release policy”

Colony respects whether the provider permits a merge, including required checks, branch protection, permissions, and conflicts. It does not have a built-in calendar freeze, freeze label, or per-PR do-not-automerge convention.

For a release freeze:

  • enforce the restriction in the code host or required-check system
  • disable Colony automatic merge where appropriate
  • pause individual Colony issues that should not continue
  • resume or merge through the same audited operational process your team uses for human PRs

/colony:pause affects the addressed issue. Repository-, tenant-, or deployment-wide shutdowns require the controls provided by that deployment; they are not scopes of the slash command.

Going deeper

Section titled “Going deeper”