Skip to content
Coro Docs

Repository overlay

The repo overlay is a .coro/ directory at the root of the repository being automated. It participates in the same three-layer stack as the tenant overlay (/concepts/architecture/), but scoped to one codebase.

Minimal layout mirrors the tenant repo (see examples/repo-overlay/ in coro-web):

.coro/
  agents/
  workflows/
  memory/
  .claude/
    CLAUDE.md
    skills/

Resolver timing (why .coro/ “appears” mid-job)

Materialisation happens at job start and again at every phase boundary. The agent usually clones the target repo in early phases, which means the .coro/ tree might not exist for the first materialisation pass. Subsequent phases automatically pick up the repo layer once .coro/ is on disk — you do not need a separate knob.

Coro deliberately does not merge your product’s native .claude/ tree into _intelligence. Project-level Claude Code discovery still walks the checkout at SDK cwd. Repo overlay is for Coro-managed workflows, agents, memory, and Coro .claude/skills/.

When to use repo vs tenant

Use tenant overlay when …Use repo overlay (.coro/) when …
The rule applies to every repo in the organisation.The behaviour differs per service or monorepo package.
You want procurement / owners to approve one intelligence repo for all engineers.You want changes to ride in the same PR as the application change (or at least the same Git history).
You centralise conventions (“how we deploy Go services”).You capture exceptions (“this Ruby service skips the dotnet conventions skill”).

Example: Tenant memory documents “default CI is GitHub Actions and required checks are …”. Repo overlay adjusts one legacy repo with different branch protection or adds a thinner FAST workflow tuned for microservice boilerplate churn.

Merge semantics (quick recap)

  • Repo wins over tenant on replace-mode paths (agents/*.md, workflows/**/*.md, .claude/skills/**/SKILL.md, …): last-wins in the resolver stack.
  • Append paths behave the same as elsewhere: memory/**/*.md and .claude/CLAUDE.md concatenate with provenance banners — nothing fully erases a lower layer’s contribution.

Writes: propose_change routing uses path prefix defaults (.coro/ → repo layer, tenant paths→ tenant layer — see /guides/review-proposals/); agents never edit _intelligence directly.