project-onboarding-adapter git:20261028.e7fd1dbA

Immutable. This exact content never changes and is served at /api/v1/blob/cc15f7af3f70005a.

---
name: project-onboarding-adapter
description: 'Adapt frontend projects, configure supported agent roles, or diagnose WebDev setup read-only. Excludes app code and model changes during updates.'
id: 'agents.skills.project-onboarding-adapter.skill'
title: 'Project Onboarding Adapter'
doc_type: 'skill'
layer: 'skill'
status: 'active'
publishable: true
local_only: false
skill: 'project-onboarding-adapter'
tags:
    - 'agents/skill-package'
    - 'agents/onboarding'
    - 'frontend/project-context'
parent: []
related:
    - '[[skills/project-onboarding-adapter/references/langfuse-installation]]'
    - '[[skills/project-onboarding-adapter/references/installation-diagnostics]]'
    - '[[skills/project-onboarding-adapter/references/claude-agent-bootstrap]]'
    - '[[templates/project/claude-agent-profile]]'
    - '[[templates/project/model-routing-profile]]'
    - '[[skills/project-onboarding-adapter/references/codex-model-bootstrap]]'
    - '[[skills/project-onboarding-adapter/references/model-workload-matrix]]'
    - '[[common/host-instruction-migration-rules|Host Instruction Migration]]'
    - '[[common/project-fact-provenance-rules|Project Fact Provenance]]'
    - '[[templates/project/verification-profile|Verification Profile Template]]'
    - '[[common/core/runtime-core-policy|Portable Runtime Core Policy]]'
    - '[[common/readme-policy|README Read And Edit Policy]]'
    - '[[profiles/react-typescript/PROFILE|React TypeScript Profile]]'
    - '[[skills/project-onboarding-adapter/references/adaptation-checklist|Adaptation Checklist]]'
    - '[[skills/project-onboarding-adapter/references/path-audit-checklist|Path Audit Checklist]]'
    - '[[common/client-adaptation-policy|Client Adaptation Policy]]'
    - '[[common/tool-capability-model|Tool Capability Model]]'
    - '[[common/mcp-installation-policy|MCP Installation Policy]]'
    - '[[common/target-stack-policy|Target Stack Policy]]'
    - '[[common/skill-applicability-policy|Skill Applicability Policy]]'
    - '[[common/context-compaction-rules|Context Compaction Rules]]'
    - '[[templates/project/client-profile|Client Profile Template]]'
    - '[[templates/project/mcp-profile|MCP Profile Template]]'
    - '[[skills/project-context-adapter/SKILL|Project Context Adapter]]'
    - '[[skills/mcp-toolchain-manager/SKILL|MCP Toolchain Manager]]'
depends_on:
    - '[[AGENTS|Canonical Agent Policy]]'
---

# Project Onboarding Adapter

## Purpose

Adapt this `.agents` bundle to a host frontend project without creating application source files. For React or Next.js, cache normal target-stack facts. For a non-target frontend project, cache only the detected stack boundary and the framework-agnostic skills that remain usable.

Onboarding must also adapt natively to the installed client target. It creates or refreshes the smallest appropriate host pointer, records client facts in local-only `project/client-profile.md`, and records tool capabilities in local-only `project/mcp-profile.md`.

## Natural Language Trigger Aliases

Route adaptation, initialization, and project-context bootstrap commands here, including `адаптируйся`, `инициализируй .agents`, and `Adapt this .agents bundle to my project.` Full Codex onboarding includes model setup; explicit GPT requests also trigger that phase. A facts-only request does not.

## When To Use

- The user asks to check WebDev installation or diagnose inactive subagents.

- The user explicitly requests economical GPT subagent setup or reconfiguration in a supported Codex project.
- The user asks to adapt this bundle to a new React or Next.js project.
- The user asks to adapt this bundle to a non-target frontend project while keeping applicable design, QA, review, lint, planning, MCP, context, and skill-authoring workflows.
- The user asks to create or refresh the host-root pointer, native client pointer, local project overlays, MCP profile, client profile, design-reference profile, verification facts, loop memory, or path indexes.

## When Not To Use

- An existing Kit needs a version update: use `webdev-kit-updater`, preserving
  existing project overlays instead of repeating onboarding.
- Ordinary screenshot-to-code implementation.
- Narrow project overlay refresh after implementation.
- Reusable skill authoring.
- Application scaffolding, package installation, or source file creation.
- Stack-specific React/Next architecture or implementation guidance for a non-target frontend project unless the user explicitly changes the supported stack.

## Diagnostic Branch

For installation checks or questions about inactive subagents, read
`references/installation-diagnostics.md` and follow only that read-only branch.
Do not continue into the adaptation workflow or model bootstrap.

## Required Context

1. Read the host-root native instruction pointer if present and needed for adaptation: `AGENTS.md`, `CLAUDE.md`, or client rules. Inspect the minimal pointer section for detection; read the entire file for requested migration using `common/host-instruction-migration-rules.md`.
2. Read bundle-local `AGENTS.md` when shipped and `common/core/runtime-core-policy.md`. Native plugins use their generated skill prelude; do not require an absent shared-policy entrypoint.
3. Read `common/client-adaptation-policy.md` and only the adapter for the resolved canonical target.
4. Read `profiles/react-typescript/PROFILE.md` and its owning policies only when repository evidence confirms the profile.
5. Read `common/skill-applicability-policy.md` when the detected or suspected stack is outside the target stack.
6. Read `common/tool-capability-model.md` and `tool-capabilities-manifest.json` for capability selection.
7. Read `common/context-compaction-rules.md` when loop memory or resumable workflow setup is requested.
8. Read existing `project/**` overlays when present.
9. Inspect only relevant manifests, configs, source entrypoints, routes, styles, assets, and verification scripts.
10. Read `templates/project/client-profile.md` and `templates/project/mcp-profile.md` before creating those local-only profiles.
11. Read `common/project-fact-provenance-rules.md` and `templates/project/verification-profile.md` before caching verification or capability facts.

Read targeted README sections only when they help identify project intent, setup guidance, or documentation drift. Apply `common/readme-policy.md`, and confirm every cached technical fact through manifests, config, source, CI, package scripts, lockfiles, or real results.

## Tool Contract

- Use the `project_files` capability when available. Prefer configured filesystem/project-files MCP for direct project file reads; use host-native file tools when available; use targeted shell reads only as the fallback.
- Use MDN for HTML, CSS, Web APIs, accessibility, and browser behavior when official web platform facts matter.
- Use `context7` only for detected target-stack libraries or tooling when current docs matter.
- Activate `openai_platform_docs` only when current Codex client, plugin, skill, MCP, or configuration behavior affects onboarding.
- Determine Browser or Playwright availability from the current session tool registry or validated `project/mcp-profile.md` facts. Do not invoke either tool during onboarding or MCP detection.
- Do not infer MCP availability from `package.json`, lockfiles, `node_modules`, a running local app, or Playwright dependencies.
- Do not use Figma MCP.
- Missing MCP installation requires explicit user approval after reporting the official source.

## Workflow

1. Classify whether this is Plan Mode or approved execution.
2. Detect the installed target or current client surface. In source, resolve aliases through `bundle-manifest.json`; in a generated target, use its sole shipped adapter.
3. Read that one client adapter and apply its native discovery, pointer, tool, sandbox, and configuration rules. For a generic or unknown client, create no pointer unless the user explicitly requests one.
4. If an expected pointer already exists, preserve it unless replacement is explicitly authorized. For requested migration, preserve all host rules in reachable local overlays, retain a backup and coverage map, and validate before writing the minimal pointer. Otherwise propose a merge for nonempty or ambiguous instructions.
5. Detect whether the host project is existing, new/empty, or partially initialized.
6. Detect target-stack fit from manifests, configs, lockfiles, source roots, routes, styles, and entrypoints.
7. If the project fits the target stack, plan or write normal `project/**` overlays for stack, architecture, styling, state, data, verification, design references, MCP profile, client profile, and path indexes.
8. If the user asks for resumable iterative work or loop memory, plan or write local-only `project/loop-memory.md` using `templates/loop-memory.md` as the source pattern.
9. If the project is outside the target stack, continue with limited onboarding: record the stack boundary, skip React/Next path indexes and stack-specific patterns, and write `project/skill-applicability-profile.md` with applicable framework-agnostic skills from `common/skill-applicability-policy.md`.
10. Read `tool-capabilities-manifest.json` for declared capability needs and cache required, available, missing, optional, approved, installed, skipped, or blocked capabilities in `project/mcp-profile.md`.
11. Cache detected client target, native pointer, skill support, and MCP config locations in `project/client-profile.md`.
12. In Plan Mode, return the plan and stop.
13. In execution mode, update the approved pointer and local overlays; complete the matching Codex or Claude phase below. Native plugins write host facts to host `.agents/project/`, never the installed plugin. Do not create dangling pointers or app code.

## Learning Setup During Adaptation

Every full adaptation must reconcile the Langfuse choice using
`references/langfuse-installation.md`: reuse a saved decision or offer connection
versus decline. Offer existing credentials; otherwise open the private credential
file for the user and wait for completion or refusal. After consent, install the
supported integration and hooks, configure project tags and verify ingestion.
Keep this decision separate from local learning capture and private sync.

During full adaptation or re-adaptation, reconcile the existing learning profile,
recording state and client integration. Follow
`skills/agent-self-improvement/references/project-memory.md` (Adaptation State).
Preserve prior opt-in or opt-out, stable project ID, database and caches. A generic
"adapt" request or supplying a sync repository does not authorize raw capture.
If capture intent is unresolved, explain the local collection scope and ask once;
otherwise honor the existing decision without repeated confirmation. Explicit
capture setup already authorizes its documented local hooks; do not ask again.

Offer optional structured snapshots to a user-selected private repository after
each completed learning cycle. Explain that this choice enables bounded uploads,
verify privacy/write access, then configure `--sync-on-finish yes`. Save refusal
with `--sync-on-finish no`: no automatic snapshots or outbox entries. Keep local
memory available. Existing address-only configuration requires a consent choice.
Store decisions and separate setup/verification states in host-local
`.agents/project/learning-profile.md`; link it from the approved host pointer for
project-scoped recall. Recall never enables capture or sync. Report capture
opt-out as a valid completed choice, unresolved consent as pending, and installed
but unobserved hooks as unverified. Never call the whole learning pipeline active
merely because recording is enabled or tests pass.

An update alone preserves these decisions and does not reopen onboarding.
Plan Mode only describes changes. Never upload during adaptation, alter native trust,
install tooling without authority or embed a user's repository in the Kit.

## Codex Model Setup During Onboarding

A full onboarding request authorizes missing project-local GPT role setup,
narrow native enablement and tiny read-only activation checks without a second
confirmation. Read `references/codex-model-bootstrap.md`, inspect current facts,
show the scoped change summary, then execute within that request. Preserve
existing working bindings; do not reselect models or rewrite caches on each run.
Explicit facts-only, no-model-change, preview/Plan Mode requests, kit updates
and non-Codex clients never write model settings or run canaries.

Confirm actual catalog, supported format and dispatch interface. Missing spawn
before configuration does not block preparation; runtime verification needs a
callable supported interface. Resolve genuine conflicts, missing evidence or
authority before writes; never change trust, global/primary models, MCP or
security controls. Record separate configuration, dispatch-mode and runtime
evidence in `templates/project/model-routing-profile.md`. Missing runtime
evidence leaves the affected route inactive, without an expensive fallback.

## Claude Native Roles During Onboarding

For Claude Code, read `references/claude-agent-bootstrap.md`. Use the installed
plugin's 21 skills and native agents; record discovery, model/effort capability
and observed dispatch in host `.agents/project/claude-agent-profile.md`.
Preserve existing custom roles, global settings, permissions and the primary
model. Full onboarding may exercise tiny read-only approved bindings; facts-only,
no-model-change and Plan Mode requests do not run canaries or change settings.
Do not run the Codex TOML helper or write host facts into the plugin cache.

## Output Contract

Final response: return only facts that affect the user's understanding, confidence, or next action. Omit empty fields and workflow narration.

```text
Installed package target or detected client
Native pointer action
Project type and stack facts
Target-stack fit
Applicable framework-agnostic skills when outside target stack
Docs and MCP capability choices
Client profile action
MCP profile action
Overlays to create or update
Loop memory setup
Verification commands
Validation run or blocked
Unknowns
```

## Product Language Context

When product terms affect the task, read `common/domain-glossary-rules.md`.
Reuse a confirmed host glossary or maintain a populated local-only
`project/domain-glossary.md`; do not create one during read-only planning.
Record consequential reasons in the existing decision log and load only the
relevant domain. Glossary maintenance never renames code or edits host docs.

## Validation Gates

- `project/**` overlays remain local-only.
- `project/client-profile.md` and `project/mcp-profile.md` are created from templates and marked local-only in copied overlays.
- Native pointers remain small. Claude uses the exact `@.agents/AGENTS.md` import when shared project policy is approved; other pointers reference `.agents/AGENTS.md` instead of mirroring the full policy.
- Existing host instructions are not overwritten without approval.
- README may supply targeted context but never the sole technical fact; README and host docs are not edited during onboarding unless the current user explicitly requests that documentation change.
- Loop memory stores tried, verified, and open facts only in local-only project files.
- Non-target frontend overlays do not claim React/Next implementation support.
- Non-target frontend projects list applicable framework-agnostic skills instead of reporting the whole bundle unusable.
- Capability detection uses `tool-capabilities-manifest.json` and does not depend on Codex-only `agents/openai.yaml` files.
- Full Codex onboarding includes narrow model setup; explicit exclusions and higher-level restrictions win. Written TOML is not runtime verification.
- No application source files are created during onboarding.
- No package, MCP, UI library, styling system, or framework change is made without explicit approval.
- Changed Markdown keeps graph frontmatter and English reusable rules.

## Trigger Evals

Should trigger:

- "Configure economical GPT subagents for this Codex project."
- "Adapt this Claude plugin to my project and verify its native roles."
- "адаптируйся"
- "Adapt this .agents bundle to my project."
- "Plan onboarding for this frontend repo."
- "Adapt this bundle to an Astro project but keep only the skills that still apply."
- "Set up local loop memory for this project."
- "Detect whether this install is Codex, Claude, Cursor, or VS Code and create the right pointer."

Should not trigger:

- "Implement this visual spec."
- "Refresh project overlays after this component change."
- "Create a new skill package."
- "Scaffold a new React app."

## Reference Map

- `references/installation-diagnostics.md` - read-only setup and subagent checks.

- `references/claude-agent-bootstrap.md`: native Claude plugin adaptation and role verification.
- `templates/project/claude-agent-profile.md`: local-only Claude routing evidence.

- `references/model-workload-matrix.md`: select capability tiers and reasoning
  efforts, including architecture and light/deep variants, during model setup.

- `common/client-adaptation-policy.md`
- `common/codex-official-docs-policy.md`
- `common/tool-capability-model.md`
- `common/mcp-installation-policy.md`
- `common/target-stack-policy.md`
- `common/skill-applicability-policy.md`
- `common/context-compaction-rules.md`
- `common/readme-policy.md`
- `tool-capabilities-manifest.json`
- `templates/project/client-profile.md`
- `templates/project/mcp-profile.md`
- `templates/loop-memory.md`
- `skills/project-context-adapter/SKILL.md`
- `skills/mcp-toolchain-manager/SKILL.md`