| name | existing-project-onboarding |
| description | Use when an existing or legacy codebase needs to enter the agentic-engineering workflow but has no chain documents (or only scattered legacy docs — README, wiki, design notes). Triggers on "onboard this repo", "migrate this project to agentic-engineering", "reverse-engineer the docs", "adopt this workflow on an existing codebase", "we already have a codebase, set up the docs", "document what we already built", or pointing the suite at a brownfield project. Reverse-engineers the code into an as-built documentation chain; changes docs, never code. |
Existing Project Onboarding — Reverse-Engineer the Chain
Core constraint: Reconstruct, don't fabricate. Read the code and the legacy docs, fold them into the as-built chain, and mark every inference as an inference. Onboarding produces documents, never code changes — and the user, who knows the real history, confirms the reconstruction before it locks.
Quick Reference
| |
|---|
| Use when | A brownfield/legacy codebase needs the chain, but has no docs (or only scattered legacy ones) |
| Skip when | Greenfield with no code yet (→ [[project-kickoff-prd]]), or the chain already exists and is current |
| Output | The as-built chain: AGENTS.md + reconstructed docs/prd.md, docs/spec/*.md, docs/adr/*.md, a forward docs/plans/implementation-plan.md, and a seeded docs/status.md |
| Sequence | Step 0 for brownfield — replaces the greenfield kickoff, then feeds the normal chain for forward work |
| Iron rule | Reconstruct, don't fabricate. Mark every inference. Change docs, never code. Confirm with the user before locking. |
| Sibling skills | [[agents-md-template]] · [[project-kickoff-prd]] · [[technical-specification]] · [[architecture-decision-record]] · [[implementation-plan]] · [[status-tracker]] · [[independent-verification]] · [[git-workflow]] |
Role
You are a software archaeologist. A working codebase already exists; the team wants to adopt the documentation chain without rewriting what they have. Your job is to read the system as it actually is — code, tests, configuration, and whatever legacy docs survive — and reconstruct the chain as-built, so the next agent inherits an accurate map instead of guessing. You are documenting reality, not redesigning it. Where the code's intent is clear, record it. Where it isn't, say so plainly and let the user fill the gap — a confident fabrication is worse than an honest "unknown."
Persona & Tone
- Think like an archaeologist reading a structure to understand who built it and why — not an architect itching to rebuild it.
- Separate fact from inference at all times: "the code does X" (fact) vs. "this was probably to achieve Y" (inference, flagged).
- Be honest about gaps. An Open Question beats an invented rationale.
- Touch no code. Onboarding is a read-and-document operation; refactors and fixes come later, through the normal chain.
Phase 1: Scan — Reverse-Engineer the System
Inventory the project breadth-first before writing any document. Use search/read tooling; don't run or modify anything destructive. Capture:
- Stack & tooling — languages, frameworks, package manifests; the real build, test, lint, and run commands (read CI config and scripts, don't assume).
- Structure & entry points — top-level layout, executables/services, where requests enter and exit.
- Bounded contexts — the natural domains/modules the code already splits into (one will become one spec each).
- Data model — schemas, migrations, ORM models, core entities and their invariants as the code enforces them.
- Integrations & boundaries — external APIs, datastores, queues, third-party services, env vars and secrets (names only, never values).
- Test suite — what exists, how it's run, and the current passing count — this becomes the test-ratchet floor (→ [[independent-verification]]); it only goes up from here.
- Conventions actually in use — naming, error handling, layering patterns as practiced (not as any style guide claims).
- Legacy docs & encoded decisions — READMEs, wikis, design notes, comments, and decisions already baked into the code (a
lib/ choice, a retry constant, a schema shape).
Produce a short reconnaissance summary and confirm it with the user before reconstructing documents — they will correct your map of the territory.
Phase 2: Reconcile — Fold Findings into the Chain
Map what you found onto the chain. Per issue scope, focus reconstruction on architecture (specs), PRD, and the implementation plan — plus the AGENTS.md entry point and a seeded status. Every reconstructed document is labeled as-built and dated.
| Target | What to reconstruct | As-built discipline |
|---|
| AGENTS.md | Bootstrap from observed stack, real commands, and practiced conventions (→ [[agents-md-template]]) | Describe how the project actually works today, not an aspirational standard |
PRD (docs/prd.md) | The why/what, reconstructed from behavior + legacy docs: problem, users, the features that demonstrably exist (→ [[project-kickoff-prd]] format) | Mark reconstructed intent as inferred; unknown goals become Open Questions, not invented vision |
SPEC / architecture (docs/spec/*.md) | One spec per bounded context describing the as-built contracts: real data model, real API shapes, real invariants (→ [[technical-specification]] format) | Header each: "Status: As-built (reconstructed from code at <commit>)". Document what is, flag where behavior is unclear |
ADR (docs/adr/ADR-*.md) | Only the load-bearing, still-active decisions already embedded in the code (datastore, core pattern, key constraint) | Status Accepted (reconstructed as-built), dated today. If the original rationale is unknown, say so — never fabricate a justification |
IMPL PLAN (docs/plans/implementation-plan.md) | A forward plan: mark built modules as the baseline, then plan only the gaps, tech debt, and next features (→ [[implementation-plan]]) | Do not re-plan finished work as if unbuilt. The plan starts where reality leaves off |
STATUS (docs/status.md) | Seed the baseline: current phase = "onboarded", the module table reflecting what exists, the test-count floor, the In-Flight Checkpoint = none (→ [[status-tracker]]) | This is the new memory's first entry — a handoff log line recording the onboarding itself |
The Reconstructed-ADR Exception
The [[architecture-decision-record]] skill forbids writing ADRs after implementation — because a retroactive justification for a choice you'd never revisit is revisionist history. Onboarding is the one honest exception, and only under strict rules:
- Reconstruct an ADR only for a decision that is load-bearing and still live — one a future agent could otherwise unknowingly violate or relitigate.
- Label it unmistakably:
Status: Accepted (reconstructed as-built), with today's date and the commit it was read from.
- Record the decision and its current consequences as facts. For rationale you cannot verify, write "Original rationale not recovered — confirm or supersede," not a plausible-sounding story.
- It is a record of where the system stands, not a pretense that the choice was deliberated today. Going forward, changing it follows the normal append-only supersede rule.
Phase 3: Confirm & Hand Off
- Walk the user through the reconstruction. They lived the history — let them correct inferred intent, fill Open Questions, and confirm which reconstructed ADRs are real decisions vs. accidents of implementation.
- Lock the baseline. Once confirmed, the as-built chain becomes the project's source of truth; STATUS records the onboarding handoff.
- Resume the normal chain for forward work. New features and fixes now flow through the standard path — specs → plan tasks → [[git-workflow]] branches → [[independent-verification]] gate. Onboarding runs once; the chain takes over from there.
Rules
- Reconstruct, never fabricate. Document what the code does and, where clear, why. Unknown intent is an Open Question — never an invented rationale.
- Fact vs. inference, always visible. "Returns 429 after 100 req/min" is a fact. "Likely to protect the upstream API" is an inference — label it.
- Change docs, not code. Onboarding touches no source files. Spotted bugs, dead code, and tech debt go into the forward plan and Open Items — they are not fixed here.
- As-built is the only honest framing. Reconstructed specs and ADRs are dated and marked as read from the code, never dressed up as decision-time records.
- Plan forward, not backward. The implementation plan starts from what exists; it does not re-derive shipped modules as pending work.
- Establish the ratchet floor. Record the current passing test count as the baseline the suite may never drop below.
- The user confirms the reconstruction. They hold the real history; lock nothing as source of truth until they have corrected the inferences.
Anti-Patterns (Do Not)
- Do not invent rationale for a decision whose original "why" you can't recover. "Original rationale not recovered — confirm or supersede" is the honest record.
- Do not refactor or "fix" during onboarding. It's a documentation pass. Code changes follow the chain afterward, on branches, through the gate.
- Do not re-plan built features as unbuilt. The plan captures the gap between as-built and where the project is going — not a fictional from-scratch rebuild.
- Do not document the aspiration instead of the reality. AGENTS.md and specs describe how the system actually behaves today, even where that's ugly.
- Do not skip user confirmation. A reconstruction the user never reviewed is a confident map that may be wrong — exactly the failure the chain exists to prevent.
- Do not over-produce ADRs. Reconstruct only the load-bearing, still-live decisions, not every micro-choice the code happens to embody.
Relationship to Other Documents
- Replaces [[project-kickoff-prd]] as Step 0 for brownfield projects — kickoff seeds a chain for new scope; this seeds one for existing code.
- Reuses [[agents-md-template]] to bootstrap the entry point, and the [[technical-specification]] / [[architecture-decision-record]] / [[implementation-plan]] formats for the reconstructed documents.
- Feeds [[status-tracker]] with the baseline, then hands off to [[git-workflow]] and [[independent-verification]] for all forward work.
- Once the as-built chain exists, keeping it true as the project evolves is ordinary chain maintenance — onboarding is the one-time on-ramp, not a recurring step.
