Adopt

Adopt Skill

ZERO CODE CHANGES during adoption. This skill only reads code and creates/updates documentation and kit config files. If you find yourself editing source files, tests, or configs that existed before adoption — stop.

---

Step 1 — Audit the repository

Read the codebase to understand what exists. Run these in order:

# Structure overview
find . -maxdepth 3 -not -path '*/.git/*' -not -path '*/node_modules/*' \
       -not -path '*/__pycache__/*' -not -path '*/dist/*' -not -path '*/build/*' \
       | sort

# Existing docs
ls -1 *.md docs/ README* CHANGELOG* 2>/dev/null

# Package / dependency files
cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || \
cat go.mod 2>/dev/null || cat Cargo.toml 2>/dev/null

# Git history summary (last 20 commits — reveals what's already been built)
git log --oneline -20 2>/dev/null

# Existing test locations
find . -name '*.test.*' -o -name '*.spec.*' -o -name 'test_*.py' \
   -not -path '*/node_modules/*' | head -20

From this audit, infer:

• Tech stack (languages, frameworks, major deps)
• Repo structure (monorepo / single-app / polyrepo service)
• What features appear to already be implemented
• What tests exist and what framework they use
• Whether a CHANGELOG, README, or docs folder already exists

---

Step 2 — Fill BOOTSTRAP_FORM.md from what you found

Create .claude/BOOTSTRAP_FORM.md if it doesn't exist. Pre-fill every field you can confidently infer from the audit. Mark genuinely unknown fields with ~.

After writing the file, print a summary:

Inferred from codebase:
  Project name:      <name>
  Structure:         <monorepo|single-app|...>
  Frontend:          <yes — Next.js | no>
  Backend:           <yes — FastAPI | no>
  Database:          <PostgreSQL | ~>
  Package manager:   <pnpm>
  ...

Fields marked ~ need your input. Edit .claude/BOOTSTRAP_FORM.md before continuing.

Stop and wait for the human to confirm the form is correct before proceeding.

---

Step 3 — Draft SPEC.md

Create SPEC.md at the project root. This is a draft — the human must review it.

Overview section: Write one paragraph describing what the project does based on the README, package description, and git history.

Tech Stack section: Fill from the confirmed BOOTSTRAP_FORM.md.

Features — Done section: List what already exists as [x] items, grouped by area. Infer from: directory structure, route files, component names, git log, existing tests. Be conservative — only mark [x] if you are confident it exists and works.

Features — Backlog section: If the README, open issues, or TODO comments reveal planned features, list them as [ ] items with a default priority of P2. Leave priority tags for the human to set.

Out of Scope: Leave blank — the human fills this.

Open Questions: List anything you could not confidently infer:

- [ ] Is <X> already implemented or still in progress?
- [ ] What is the intended deployment target?

After writing SPEC.md, print:

Draft SPEC.md written. Before running /new-feature:
  1. Review the Done section — correct any features wrongly marked [x] or missing
  2. Set P1/P2/P3 priority tags on backlog items
  3. Fill in Out of Scope
  4. Resolve Open Questions

Stop and wait for human confirmation.

---

Step 4 — Reconcile existing docs

If a CHANGELOG already exists:

• Do not delete or overwrite it
• Add a comment at the top of docs/CHANGELOG.md:

  <!-- History before kit adoption: see <original file> -->
  

• Create docs/CHANGELOG.md starting from today as [Unreleased]
• Leave the original CHANGELOG file in place

If a README already exists:

• Do not modify it
• Note in SPEC.md Overview: (see README.md for full detail)

If docs/DECISIONS.md already exists:

• Read it and preserve all existing content
• Append a header comment if not already ADR format:

  <!-- Entries below this line follow ADR format managed by the kit -->
  

If none of these exist:

• Create docs/CHANGELOG.md and docs/DECISIONS.md using the standard templates

---

Step 5 — Create kit files (non-destructive)

Create only files that do not already exist. Never overwrite:

.claude/rules/approval-gates.md      ← create if missing
.claude/rules/commit-rules.md        ← create if missing
.claude/rules/definition-of-done.md  ← create if missing
.claude/rules/doc-sync.md            ← create if missing
.claude/skills/*/SKILL.md            ← create all skills if missing
CLAUDE.md                            ← create if missing

If any of these already exist, skip them and note which were skipped.

---

Step 6 — Log adoption as ADR

Add to docs/DECISIONS.md:

## ADR-001: Adopt agentic coding starter kit
**Date:** <today>
**Status:** Accepted
**Context:** Existing project onboarded into the agentic coding starter kit
**Decision:** Added .claude/ structure, SPEC.md, and docs/ kit files without
modifying existing source code, tests, or configuration
**Consequences:** Future development follows the kit workflow: /new-feature for
feature work, /commit for commits, /milestone at group completion

---

Step 7 — Initial commit

Stage only the new kit files (never stage existing source changes):

git add CLAUDE.md SPEC.md docs/ .claude/
git status   # verify only kit files are staged
git commit -m "chore: adopt agentic coding starter kit"

If git status shows unexpected files staged, unstage them and stop.

---

Step 8 — Print handoff summary

Adoption complete.

Files created:
  CLAUDE.md
  SPEC.md              ← REVIEW THIS before running /new-feature
  docs/CHANGELOG.md
  docs/DECISIONS.md
  .claude/             ← full kit structure

Files left unchanged:
  <list any pre-existing docs that were preserved>

Next steps:
  1. Review SPEC.md — correct Done items, set priorities, fill Out of Scope
  2. Answer the Open Questions in SPEC.md
  3. Run /new-feature when ready to build