Guide

Onboarding an existing codebase

For solutions that started without CorPole: the coding agent reverse-engineers the code, tests and documents into design drafts; people confirm what the solution is; governance grows module by module. The work runs as the solution's "Onboard …" initiative.

For: Team developer, Project lead, Solo builder

Principle

Code says what the system does, not what it should do. So findings describe the solution as it is: each arrives as a design draft of the repository's component — FDR for functions, NFDR for qualities and compliance, TDR for technical design (every module becomes a TDR module draft), BDR for business rules — with its origin (Tested > Documented > As-built) and evidence. Objectives, needs and business or project constraints stay requirement drafts. Conflicts between sources become questions; people decide.

How it works

  1. Start onboarding here; CorPole opens the Onboard … initiative with its demand, and work during onboarding goes to it. Connect the coding agent with the propose permission.
  2. Onboard each repository separately (/corpole:onboard in that repository; the plugin tells CorPole which one). Module paths are per component, so two repositories may both have src/. Quick baseline first: 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 the drafts per module: Confirm as the design, Wrong behaviour → defect (the draft is retired and a defect opened), 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 solution per hour, and at most 500 may wait for review; then they stop and ask you to review first.
  6. Govern a module once a confirmed design record or an Authority record covers it; finish onboarding when the maturity is good enough. The Onboard initiative then closes if it has no open work.

Authority tier

A solution 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 Solution settings page. With several components each can move at its own pace; the solution's tier is the lowest.

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.

Feedback for CorPole