Adopt — attach the studio to an existing project

Language, <hooks>, agent and command namespaces, gate mechanics (rule 7), the documents-lane commit gate and the hand-off form: docs/coordination-rules.md § Skill conventions. This skill does not list Skill: every command it names is a hand-off (§ Another skill).

Answers not "what exists?" but "will what exists work with the studio's skills?".

Glossary:

• FRAMEWORK_NAMESPACES — the regex alternative docs/stack-reference/<framework>.md names for the detected php_framework (the value docs/templates/php/deptrac.yaml takes).

Mode → phases (argument; no argument = full). "Before Phase 1" runs in every mode.

A phase a mode skips is named as skipped in the result, never silently absent. In docs mode a placeholder technical-preferences.md yields the facts table "not run — /adopt stack" and makes /adopt stack the plan's first item.

Before Phase 1

1. .claude/docs/ missing → one AskUserQuestion: run /web-studio:init (copy mode /init) first (Recommended) · stop. Either answer ends this run.
2. Not a git repository (git rev-parse --show-toplevel fails) → one AskUserQuestion: initialize git now (Recommended) · stop.
   • "stop" → BLOCKED (not a git repository — adoption relies on history and branches); never re-asked in the same run.
   • "initialize" → plain git init, which honours the user's init.defaultBranch. Never pass -b/--initial-branch.

Phase 1: Stack detection (stack / full)

Say "Scanning the project…", then:

1. Read the manifests and configs: go.mod (Go version, router, pgx/sqlc, gqlgen), composer.json (PHP, yiisoft/*, Symfony/Laravel, graphql-php), package.json (Angular/Vue/Nuxt/Vite versions, TS, three, pixi, GraphQL clients), angular.json, nuxt.config.*, vite.config.*, gqlgen.yml, *.graphql, *.graphqls, openapi*.yaml, compose*.yaml, Dockerfile*, .github/workflows/*, Chart.yaml, kustomization.yaml, deploy/k8s/**, charts/** (deploy target kubernetes), the OpenTelemetry/Prometheus/logging packages in the manifests (references/fill-technical-preferences.md → Observability), renovate.json / .github/dependabot.yml, existing deploy/advisor skills in .claude/skills.
2. Versions: compare with .claude/docs/stack-reference/index.md. Outdated majors → a table "now → current → upgrade path (reference section)".
3. Go projects: read references/detect-go.md; record go_layout, go_architecture (tree and dependency graph, never folder names alone), go_router, graphql_models and the findings it names. Restructuring is a plan item (/refactor layout), never done here.
4. PHP projects: read references/detect-php.md; record the PHP version, php_framework, php_architecture (tree and dependency direction), php_static_analysis, php_cs_tool, deptrac presence and the findings it names. Moving to layered or another framework is a plan item (/refactor layout / /refactor framework --dry-run), never done here.
5. Contract: api_contract_path from the schema: entry of gqlgen.yml, or the OpenAPI file's real location; never from the studio default.
6. Fill technical-preferences.md in this run: read references/fill-technical-preferences.md (field list, deploy target/delegate detection by deploy-target-contract.md, shared-host questions) and draft every field the files answer from the facts. [TO BE CONFIGURED] may remain only for fields no file answers.
7. Unknown fields: ask them (project type, API style, layout — whatever is still unknown) in one AskUserQuestion before the write gate, never in the same message.
8. Write gate, in rule 7's exact order (§ Skill conventions → Gates): show the draft as a table field · value · source fact — technical-preferences.md is still the untouched init placeholder at this point — then "May I write .claude/docs/technical-preferences.md?" as one AskUserQuestion: write (Recommended) · adjust first · not now. Write/Edit only after the "write" answer, never before. After the "write" answer: touch .claude/.write-consent.
9. Do not defer to /setup-stack: after /adopt the stack counts as chosen — the template says "while [TO BE CONFIGURED] remains, skills treat the stack as not chosen".

Phase 2: Artefact audit (docs / full)

1. Classify: BLOCKING (a skill would fail or lie), HIGH (traceability lost), MEDIUM, INFO. A roadmap kept by a companion advisor skill in its own format is INFO ("not migrated"), never a migration item.
2. Format gaps. A HIGH that is a format gap (a roadmap in a foreign format, story cards without a criteria table, ADRs without options) gets the plan item /migrate <type> --dry-run, never "rewrite by hand"; the artefact itself is left untouched.
3. Every BLOCKING and HIGH gets a sink, not only a row in the plan: one AskUserQuestion per item — record it in production/findings.md (template findings.md; id ADOPT-NNN, severity, area, the decision needed) (Recommended) · story stubs now via /create-stories · plan only. The row is written only after the "record" answer.
4. "Story stubs" is a hand-off, not a call: the item becomes the plan's first open item with /create-stories as its command, offered first by the closing question. /help, /create-stories and /sprint-plan read production/findings.md; only /help reads the adoption plan (first open item).
5. A BLOCKING or HIGH item that is neither recorded nor turned into a story is named as unrecorded in the verdict line.

Phase 3: Settings (settings / full)

1. .claude/settings.web-studio.json present → show a diff with settings.json for hooks, permissions, statusLine and propose a merge: never drop foreign hooks; merge arrays.
2. CLAUDE.md without the studio block → propose inserting the Language/Studio/Stack/Principles sections from the kit's templates/CLAUDE.md.template (generated from technical-preferences.md when the template is unavailable); insert, never overwrite the existing file.
3. .gitignore must list production/session-state/, production/session-logs/, .claude/settings.local.json and .claude/agent-memory-local/ (the same four lines /init and install.sh add); propose the missing lines.
4. Companion skills detected (advisor, deploy) → propose noting them in the Tier 0 row of .claude/docs/agent-roster.md.
5. Show the proposals, then one AskUserQuestion: "May I write the changes above?" — write (Recommended) · show the draft/diff first · not now. After the "write" answer: touch .claude/.write-consent.

Phase 4: Adoption plan

1. Draft docs/adoption-plan-<date>.md from .claude/docs/templates/adoption-plan.md: verdict, the facts table, the artefact audit and a numbered plan where every item is a checkbox - [ ] N. <priority> — <command> → <artefact>. /help offers the first open item; items are ticked [x] when done.
2. Stage: /init writes production/stage.txt in its own write gate, so after a completed /init it exists; propose it from the facts (build / operate) only when it is missing, and only with the plan's consent, never automatically.
3. Write gate: show the plan in the chat, then "May I write docs/adoption-plan-<date>.md (and production/stage.txt)?" as one AskUserQuestion: write (Recommended) · show the draft/diff first · not now. After the "write" answer: touch .claude/.write-consent.

Phase 5: Commit (documents lane)

Right after the last write of the run, one commit gate (§ Skill conventions → Documents-lane commit gate; .claude/docs/git-workflow.md § Documents): docs: adopt web studio (<mode>), staging exactly the documents this run wrote — .claude/docs/technical-preferences.md, production/findings.md, CLAUDE.md, .claude/docs/agent-roster.md, docs/adoption-plan-<date>.md, production/stage.txt — whichever of them the earlier gates covered.

• .claude/settings.json and .gitignore (Phase 3) are toolchain work, not documents: they never ride the docs: commit; name them in the result and offer the chore lane (git-workflow.md § Chore / infra).
• Before asking, <hooks>session-state.sh set Gate "/adopt Phase 5: commit?"; after the answer, <hooks>session-state.sh set Gate "—".

Nothing is committed without the answer; a run that wrote no document has no commit gate.

Verdict: COMPLIANT | NEEDS MIGRATION (N blocking), followed by the unrecorded BLOCKING/HIGH items when there are any.

Next step — one AskUserQuestion. The plan so far reflects only the artefact gaps; nobody has asked the owner what they actually want, and an owner who installs the studio on a working project always has an intent (tidy it up, a new feature, security, an upgrade). Options:

• the plan's first open item (Recommended);
• "describe your goal for this project in your own words" (free text): reorder the plan around the answer, goal items first, and only then recommend a command;
• /help;
• stop here.