AI Codebase Takeover and Inventory

Inheriting a codebase from another team is one of the highest-variance moments in software engineering. The system might be cleanly structured with good test coverage and a thoughtful deploy story; it might be a working but unmaintainable artifact held together by the heroics of the previous team. The new team has no way to know which it is from the outside, and the cost of finding out the wrong way is high: shipping a feature that breaks an undocumented invariant, missing a dependency that has been silently outdated for two years, accidentally deleting a configuration that turns out to be load-bearing. The first month on a new codebase is the month where the most expensive mistakes get made because the new team is operating with the least context.

The standard approach to mitigating that risk is the senior engineer who spends their first two weeks reading the code, running the system, asking questions of the previous team if they are still reachable, and producing an internal write-up of what they found. The write-up is the artifact that protects the rest of the team from the early mistakes; without it, every engineer has to develop the same context independently. The discipline is well-known and rarely matched in practice because two weeks of focused reading is two weeks the team is not delivering. The /apex-takeover skill compresses that two weeks into hours by orchestrating the reconnaissance across the full Tonone team simultaneously, producing the same artifact (system map, risk assessment, quick wins, recommended roadmap) without burning the senior engineer's calendar.

Why generalist AI is the wrong tool for takeover

Ask Cursor or ChatGPT to summarize a codebase and you get a description of the README and the package manifest. The description is not a takeover document. It does not tell you what is healthy versus what is at risk, what the load-bearing decisions are versus what is incidental, what is well-tested versus what is held together by goodwill. A generalist tool can read code and produce a summary; it cannot do the cross-cutting analysis that distinguishes a system you can extend confidently from one you should fence off and replace.

The other limitation is that takeover is multi-disciplinary. The infrastructure layer, the security posture, the data layer, the test suite, the deploy pipeline, the observability setup, and the frontend all have their own takeover questions, and each of those questions is best answered by someone who specializes in that layer. A single generalist agent cannot specialize in all of them. The Tonone team has fourteen specialists who each cover a layer; /apex-takeover runs them in parallel against the same codebase and consolidates their findings, producing the comprehensive picture that no individual engineer would have time to assemble.

What a takeover artifact actually requires

A useful takeover document has four sections. First, the system map: what services exist, what each one owns, how they communicate, what data each one holds, what external dependencies they have. Second, the risk assessment: which parts of the system are healthy, which are at risk, what would happen if each at-risk component failed. Third, the quick wins: changes that are clearly worth making in the first two weeks (an outdated dependency with a CVE, a broken alert that should be fixed, a flaky test that is masking a real bug). Fourth, the recommended roadmap: the medium-term work the new team should plan for, ranked by impact, with the rationale for each.

Each section serves a different time horizon. The system map is the persistent artifact that anchors all later work. The risk assessment is the protective layer that prevents the first-month mistakes. The quick wins give the team early credibility ("we shipped X in week one"). The recommended roadmap gives leadership the picture they need to plan resourcing. Each section is the output of a different specialty: the system map is partly the knowledge engineer's work and partly the backend's, the risk assessment draws from security and observability, the quick wins span every layer. Producing all four together is what a takeover requires, and it is what the multi-agent approach makes feasible.

How /apex-takeover works

Step one: dispatch parallel reconnaissance

When invoked, /apex-takeover dispatches the recon skill of every relevant specialist in parallel. /atlas-recon maps the documentation. /spine-recon reads the API surface and the backend services. /flux-recon inventories the data layer. /forge-recon maps the cloud infrastructure. /relay-recon traces the deploy pipeline. /warden-recon audits the security posture. /vigil-recon checks the observability setup. /proof-recon reads the test suite. /prism-recon maps the frontend. The dispatching is the point: each specialist runs independently, produces their own findings, and reports back to Apex for consolidation.

Step two: consolidate the system map

Apex receives the findings from each specialist and consolidates them into the unified system map. The map covers services, data, infrastructure, deploys, security, observability, tests, and frontend in a single document. Where two specialists disagree (the API doc says one thing, the actual code does another), the discrepancy is surfaced rather than silently resolved. The map is also produced as a Mermaid diagram so the team can scan the architecture before reading the prose.

Step three: assess risk

The risk assessment combines findings from every specialist into a single picture: outdated dependencies with known CVEs (from Warden), services without alerting (from Vigil), tests that are skipped or known-flaky (from Proof), schemas missing constraints (from Flux), infrastructure with permissive IAM (from Forge), pipelines without deploy gates (from Relay). Each risk is paired with a severity (what would happen if this bit you), a likelihood (how soon is it likely to bite), and a mitigation (what fix would close it). The risks are ranked so the team knows what to address first.

Step four: quick wins and roadmap

The quick wins are the items the new team can address in their first two weeks for low effort and high signal. They tend to come from the risk list: the outdated dependency, the broken alert, the flaky test. The recommended roadmap is the medium-term work, ranked by impact: the architectural change that would unlock the next product line, the migration that would reduce on-call burden, the test investment that would let the team ship faster. The roadmap is presented as options the new team can choose from rather than as a fixed plan, because the choice depends on the new team's priorities.

Tonone's /apex-takeover skill orchestrates parallel reconnaissance across 14 specialists to produce a system map, risk assessment, quick wins, and recommended roadmap for an inherited codebase.

When to use /apex-takeover, and when not to

/apex-takeover is the right call when inheriting a codebase from another team, when a previous team has left the company, or when starting a consulting or agency engagement on an existing system. The signal is when the new team has not built the system and does not yet have the context to extend or operate it confidently. Run the skill first, before any planning or development work.

Skip the skill for codebases the team has built and operates day-to-day; the takeover artifact is for unfamiliar systems. For ongoing project status (where are we, what is in flight), /apex-status is the right call. For new project scoping after the takeover artifact is in hand, /apex-plan produces the next step.

A worked example: takeover of a legacy SaaS

Suppose the brief is: we just acquired a small SaaS company; produce the takeover artifact for their main application. Run /apex-takeover and the output is the structured document, abbreviated here.

# Takeover Report: Acme Application
Date: 2026-03-13

## System map
[Mermaid diagram: 6 services, Postgres, Redis, S3, Stripe]

- web (Next.js): customer-facing app
- api (NestJS): main REST API
- workers (NestJS, BullMQ): background jobs
- webhook (Express): Stripe ingestion
- admin (Next.js): internal tool
- analytics (Python): batch reporting

## Risk assessment

### Critical (act in week 1)
- Stripe API key in plain text in api .env (Warden, severity HIGH)
- No alerts on api error rate or latency (Vigil, severity HIGH)
- 14 npm packages with known CVEs in api (Warden, severity HIGH)

### High (act in month 1)
- Postgres on db.t3.medium running at 78% CPU sustained (Flux, Forge)
- 12 E2E tests skipped, all on payment flow (Proof)
- IAM role for workers has s3:* on all buckets (Warden, Forge)
- No CI gating on production deploy (Relay)
- Cache hit rate unmeasured; suspect cold path (Vigil)

### Medium (act in quarter 1)
- Test suite takes 19 minutes; can be parallelized (Proof)
- Frontend bundle is 1.2MB; optimization opportunities (Prism)
- Documentation last updated 2024 (Atlas)
- No ADRs documented (Atlas)

## Quick wins (week 1)
1. Migrate Stripe key to AWS Secrets Manager (4h)
2. Wire api error rate alert to PagerDuty (2h)
3. Run dependabot, merge security updates (1d)
4. Fix the 12 skipped payment E2E tests or document why skipped (1d)
5. Lock down workers IAM to specific buckets (2h)

## Recommended roadmap (next quarter)
- Q2 priority A: stabilize payment flow (E2E + observability)
- Q2 priority B: scale Postgres (read replica + query review)
- Q2 priority C: ADR backfill for top 5 architectural decisions
- Q2 priority D: parallelize CI to <8 minutes

## Doc vs. code discrepancies
- README claims Redis is optional; api requires it for sessions.
- API doc references /v2/billing/* endpoints that do not exist.
- Architecture diagram in /docs is from 2024 and missing
  webhook and analytics services.

The artifact is the input to every decision the new team will make in the first quarter. The week-one quick wins build credibility. The risk list protects against the first-month mistakes. The roadmap gives leadership the planning input they need. The discrepancies section saves the team from trusting the documentation when the code says otherwise.

Related skills

/apex-takeover produces the takeover artifact. After that artifact is in hand, /apex-plan scopes the first major project. /apex-status produces the ongoing status report once the team is operating the system. For onboarding new engineers onto the inherited codebase, /atlas-onboard produces the day-one document that builds on the takeover artifact.

Install

/apex-takeover ships with the Apex agent in the Tonone for Claude Code package. Install Tonone, invoke /apex-takeover from any Claude Code session inside the inherited repository, and the skill orchestrates the parallel reconnaissance and produces the consolidated artifact.

Inheriting a codebase is the moment when the cost of operating without context is highest. The skill is built so the context is available in hours rather than weeks, which is the only way the team avoids the early mistakes.