Onboard existing project

Onboard Existing Project

Onboards an existing project into Agent OS. Reads the current project structure first, pre-fills what it finds, and generates required files without overwriting anything without your approval.

New project? Use /install-agent-scaffold instead. This skill is only for projects that already have files and history.

Trigger

When the user runs /onboard-existing-project, execute the following phases in order.

---

Phase 1: Discovery (Run Silently — No Questions Yet)

Read the following files and paths. Do not ask any questions. Extract as much as possible to pre-fill.

File / Path	Extract
README.md	Project name, description, tech stack hints
package.json / pyproject.toml / Cargo.toml	Name, dependencies → infer stack
src/ / app/ / lib/ structure	Frontend framework, language
api/ / server.ts / routes/	Backend runtime/framework
supabase/ / prisma/ / db/	Database
.env.example	Services and integrations in use
docs/ or context/	Any existing planning or context docs
CLAUDE.md	Existing Claude Code configuration
.claude/agents/	Existing agent definitions
.claude/settings.json	Existing hooks
.gitignore	Worktree path convention in place

Product vision candidates sweep. After reading the table above, scan for: README.md, north-star.md, vision.md, PRODUCT.md, docs/product.md, docs/vision.md, docs/north-star.md. For each that contains meaningful product prose, capture its path into PRODUCT_CANDIDATES. If none exist, set PRODUCT_CANDIDATES to empty.

Assemble a Discovery Report internally — do not display it yet.

---

Phase 2: Conflict Check

Before asking any questions, evaluate:

1. Already initialized? If CLAUDE.md exists and contains Agent OS content → warn: "This project already has Agent OS initialized. Do you want to re-initialize, or just add missing pieces?"
2. Partial setup? If some files exist but others are missing (e.g., no .claude/agents/) → note which files will be created vs. which already exist.
3. Existing docs to migrate? If docs/ or a context/ folder exists → identify files that could serve as plan.md, tracks.md, or product.md and propose the mapping.

---

Phase 3: Focused Interview

Rule: Only ask about what is genuinely missing or ambiguous. For each value below, if it was found in an existing file, mark it CONFIRMED — do not ask again.

Present confirmed values as a silent summary block first:

Already established (no changes needed):

• Project name: [value from CLAUDE.md or README]
• Tech stack: [value from CLAUDE.md]
• Build command: [value from CLAUDE.md or package.json]

Then present only the gaps as a numbered list. Wait for all answers before creating any files.

What I still need from you:

[Only include items that were not found. If all are found, skip this block and proceed to Phase 4.]

• One-sentence description — (Only if not found in README)
• Product vision — If docs/context/product.md already exists and is non-empty, mark CONFIRMED and skip. Otherwise: if PRODUCT_CANDIDATES is non-empty, list them numbered and ask: "Fill in product.md now? Pick a candidate number to synthesize, or type your own 2–3 sentence description. Or type 'skip' to leave the placeholder." If PRODUCT_CANDIDATES is empty, ask: "Fill in product.md now? Type a 2–3 sentence description of what this product is and who it serves, or type 'skip'."

Existing docs (if found and not yet mapped): list docs found and propose how they map to docs/context/. Confirm or reject each mapping. (Skip if docs/context/ already has plan.md, tracks.md, product.md.)

---

Phase 4: Generate Files

After all answers are confirmed, create or update the following. For each file:

• Does not exist → create it.
• Already exists → show what would change and ask: merge, replace, or skip.

4a. CLAUDE.md (root)

Use the lean bootstrap template from install-agent-scaffold Step 4a. Include tech stack section with confirmed values. No [PLACEHOLDER] may remain.

When CLAUDE.md already exists: after confirming the merge/replace/skip decision, run the Skill-reference drift check sub-flow below before writing any changes.

Skill-reference drift check

1. Full-file scan. Collect every skill reference from CLAUDE.md (auto-trigger rows, inline /skill-name mentions, path literals).

2. Resolve each reference. Check whether ~/.claude/skills/<name>/SKILL.md exists for each collected skill name. Skills present in ~/.claude/skills/ but absent from the canonical Agent OS repo are NOT flagged.

3. Report. If no unresolvable references: state "All skill references resolve — no drift detected." and proceed.

   If unresolvable references found:

   Skill-reference drift detected in CLAUDE.md:
   | Skill name   | Line | Context                       |
   |--------------|------|-------------------------------|
   | old-skill    | 42   | `| User says ... | /old-skill` |
   

4. Per-reference targeted patches. For each unresolvable reference, offer a specific fix. Present each patch individually — confirm or decline before moving to the next.

5. Apply. Apply only confirmed patches. All other content preserved verbatim.

4b. claude/skills/orchestrator/SKILL.md

If this file does not exist in the project, create it by copying from the canonical source. If it already exists and is current, skip silently.

4c. .claude/agents/ — Role agent files

Copy the following canonical agent files into .claude/agents/ if not already present:

• technical-architect.md
• qa.md
• task-coder.md
• task-researcher.md
• task-writer.md

For each that already exists, show the diff and ask: replace, or skip.

4d. docs/context/plan.md

If the user approved a doc migration, copy the source file and prepend:

<!-- Migrated from [original path] — review and update stale content. -->

Otherwise create the standard blank template.

4e. docs/context/tracks.md

Initialize with:

## Track 0 — Project adoption

**Status:** DONE — adopted into Agent OS ([TODAY'S DATE])

**Goal:** Onboard existing project into Agent OS.

**Files:**
- `CLAUDE.md` (new or updated)
- `docs/context/plan.md` (new)
- `docs/context/tracks.md` (new)
- `docs/context/product.md` (new)
- `.claude/agents/` (populated)
- `.claude/settings.json` (new or updated)

4f. docs/context/product.md

Apply exactly one of the following branches:

1. Already exists and is non-empty — Leave untouched.

2. Does not exist — Create the skeleton first, then apply the user's Phase 3 response:

   Skeleton:

   # Product Context
   
   <!-- TODO: fill in product context — what is this product, who does it serve, why now? -->
   
   ## Vision
   [To be filled in.]
   
   ## Current Focus
   [To be filled in.]
   
   ---
   
   *Last updated: [TODAY'S DATE]*
   

   • User picked a candidate file → Synthesize a 2–3 sentence summary, overwrite the skeleton placeholders, prepend <!-- Synthesized from [candidate path] — review and refine. -->. End-state: created (filled).
   • User typed a description → Overwrite the skeleton placeholders with the user's text verbatim. End-state: created (filled).
   • User deferred ('skip') → Leave skeleton in place. End-state: created (skeleton — needs fill).

4g. .claude/settings.json

If already exists: merge — do not remove existing entries.

If does not exist, create with the standard template from install-agent-scaffold Step 4g.

4h. .gitignore additions

Append .worktrees/ and .claude/settings.local.json if not already present.

---

Phase 5: Adoption Summary

## Project Adoption Complete

**Project:** [PROJECT NAME]
**Files created:** [list]
**Files updated:** [list, or "None"]
**Skipped (no changes needed):** [list]

**Existing docs migrated:**
[list of original path → docs/context/X.md, or "None"]

**Next steps:**
1. Review CLAUDE.md — confirm the tech stack and configuration are correct.
2. Update docs/context/plan.md with your current sprint objective.
3. Review any migrated docs and remove stale content.
4. Run `/start-sprint` to open your first sprint.

**Verification:** Run [BUILD COMMAND] to confirm the build is clean before starting work.

**Activate skills:** Close and reopen your IDE window — installed skills load on session start.

---

Verification Checklist (Internal — Run Before Reporting Complete)

• Discovery phase ran before any questions were asked
• No existing file was replaced without explicit user approval
• No [PLACEHOLDER] values remain in any generated file
• Migrated docs include the <!-- Migrated from --> header
• .claude/settings.json merge preserved any pre-existing hooks
• If CLAUDE.md was preserved, every skill reference resolved or was offered a targeted patch
• Phase 4f produced a docs/context/product.md in one of three valid end-states
• Phase 5 Adoption Summary labels the docs/context/product.md end-state explicitly