Skip to content
Coro Docs

Review intelligence proposals

propose_change is the only sanctioned path for agents to mutate tenant or repo markdown intelligence (/guides/tenant-overlay/, /guides/repo-overlay/). Each call validates payloads, pushes a branch (coro/proposal/<jobId>-<layer>-<slug>), opens a Git PR via your SCM plugin, and records metadata for UI / list_proposals.

Why human review matters

Agents cannot silently change how teammates route jobs, escalate risk, interpret compliance, or document production pitfalls. Merge gates keep SOC2-style change control: every behavioural edit is reviewer-attributable Git history identical to library code changes.

Runtime also enforces one proposal per (jobId, layer) bundle — if you see duplicates, escalate tooling bugs rather than merging twice.

What to scan in each PR

  1. Ownership & routing — confirm paths intentionally target .coro/... (repo) versus tenant root (agents/, memory/, …). Mis-routed overlays silently affect the wrong repos.
  2. Diff size vs budget — memory entries must honour evaluator caps (known-pitfalls shorter than narratives, actionable recipes).
  3. Secret leakage — redact credentials, bearer tokens, customer data. Markdown should reference vault names, not payloads.
  4. Behaviour changes — for agents/*.md edits, skim before vs after for tool allowlist drift, escalate rules, reviewer obligations.
  5. Skill scope — new .claude/skills/*/SKILL.md files remain focused (description: field matches actual content). Bloated encyclopaedias degrade Skill tool retrieval.
  6. Append-only merges — memory-update entries should merge cleanly with existing headings; curator PRs intentionally rewrite — treat those like refactors (/guides/manage-memory/).

Approval workflow

Typical SCM flow:

  1. CI (if configured on intelligence repo) — lint prose or custom policy checks optional.
  2. Area owner approvals — platform team for cross-cutting workflows, component lead for scoped skills.
  3. Merge → next job resolves new overlay automatically (gitRemote tenants pull on refresh; rerunning coro start suffices).
  4. Close loop — if the originating job awaited human yes/no, acknowledge in dashboard commentary so operators know autopilot resumed.

Reject or request changes when the PR violates guardrails (proposal-markdown-only, etc.—see /guides/configure-guardrails/).

Relationship to application PRs

Intelligence PRs ride in their own repos distinct from coding PRs opened by Coders (scm_create_pr). Keep naming conventions distinguishable (“coro proposal …” branches are automatic). Link back to originating job IDs logged in dashboard when auditing.

  • /reference/cli/ — inspecting jobs that produced proposals (/reference/cli/).
  • /guides/webhooks/ — proposals do not substitute for webhook-driven merges of application PRs — both coexist.