Guide

Onboarding an existing codebase

For projects that started without Corpole: the coding agent reverse-engineers the code, tests and documents into findings; people confirm what is intended; governance grows module by module.

For: Team developer, Project lead, Solo builder

Principle

Code says what the system does, not what it should do. Every finding arrives as a Draft with its origin (Tested > Documented > As-built) and evidence. Conflicts between sources become questions; people decide.

How it works

  1. Start onboarding here. Connect the coding agent with the propose permission.
  2. Quick baseline (/corpole:onboard): modules, stack decisions, glossary, existing tests, conflicts, defects and risks. The agent extracts with commands first to keep token use low.
  3. Deep dive per module, typically right before it is changed (govern what you touch).
  4. Review findings per module: confirm as Approved or Authority, mark wrong behaviour as a defect, or reject. A rejected finding is remembered with its reason: agents see it in their brief and cannot submit it again.
  5. Agents may submit at most 300 findings per project per hour, and at most 500 may wait for review; then they stop and ask you to review first.
  6. Govern a module once an Authority record covers it; finish onboarding when the maturity is good enough.

Authority tier

A project brought in with existing code starts in the Shadow tier: agents read Corpole, but the repository's own sources (CLAUDE.md, documents, ADRs) still lead. Use /corpole:handover to move those sources in as proposals, then declare Shared and later Full on the Project settings page.

Advisory or enforced

The tenant chooses (Settings → Agent gates). Advisory: agents warn and Claude Code asks you before an ungoverned module is changed; finishing with open thresholds needs a reason. Enforced: changes to ungoverned modules are refused (MCP and the Claude Code hook) and onboarding finishes only when every threshold is met.