--- name: arc-adopt description: Adopt Arc on an existing codebase by reading the current API surface and drafting `.arc/` contracts that match it. Use when the user wants to "introduce Arc to this project," "scaffold .arc/ contracts from existing code," or after running `arc init` on a real codebase. The inverse of arc-fix — instead of editing code to match the contract, this skill drafts the contract to match the code, then runs `arc check` to surface any drift the codebase was already carrying. --- # arc-adopt The inverse of `arc-fix`. Where arc-fix says "given the contract, fix the code," arc-adopt says "given the code, draft the contract — then surface whatever drift the codebase is already carrying." This is the v0.1 path to adopting Arc on an existing project. v0.3 plans an automated `arc init --infer` CLI; for now, an AI agent does the inference and an experienced human reviews the result. ## When to use - User says "introduce Arc to this project / repo / codebase." - User just ran `arc init` (which scaffolds an empty starter) and wants the next step. - User has an existing FastAPI + TypeScript API and wants to consolidate the four-files-per-contract sprawl (Pydantic + TS interface + Zod + OpenAPI) into one source of truth. - Project already has OpenAPI YAML / Pydantic models / TS types — the contract is implicit in code, not yet explicit in `.arc/`. ## When NOT to use - The project already has a `.arc/` directory with schemas and components. Use `arc-fix` instead — the contract exists; fix drift. - The codebase has no typed API boundaries (raw `dict`s everywhere, no schema discipline). Arc needs something to anchor on; if there's truly nothing typed, scaffold a couple of schemas manually and grow from there. - The user wants a code refactor more than a contract introduction. Refer back to whatever skill they invoked first. ## Setup check 1. Is `arc` on PATH? Run `arc --version`. If not, the user hasn't installed it; redirect to `npm i -g arc-contract` (or pnpm/yarn equivalent). 2. Is `.arc/arc.yaml` already present? If yes — this project IS already an Arc project. Switch to arc-fix. 3. If no, run `arc init` to scaffold the starter. The user should accept the default language outputs unless they have specific requirements. ## The workflow ### Step 1 — Survey the API surface Read these files to understand what the contract looks like *today*: - **Python backend** (typical FastAPI): - `**/main.py`, `**/api.py`, `**/routes/*.py`, `**/routers/*.py` — handler functions with `@app.` decorators - `**/models.py`, `**/schemas.py` — Pydantic models / SQLAlchemy types - `pyproject.toml` / `requirements.txt` — confirm framework - **TypeScript frontend** (typical React + Zod): - `**/types/*.ts`, `**/types.ts` — handwritten interfaces - `**/api/*.ts`, `**/client/*.ts` — fetch wrappers - `**/schemas/*.zod.ts`, `**/*.schema.ts` — Zod validators - `**/openapi.yaml`, `**/openapi.json` — if there's an existing OpenAPI spec, use it as the strongest source of truth - **Existing contract artifacts:** - OpenAPI / Swagger YAML — these are gold; the schemas and endpoints translate almost directly. - JSON Schema files — same. - Protobuf — out of v0.1 scope but worth noting. Use `arc_scope` if `.arc/` already exists (post-init) to see what Arc already knows. Otherwise, grep for `@app.` and `interface ` and `z.object(`. ### Step 2 — Draft schemas For each Pydantic model / TypeScript interface / Zod object you identified, write one `.arc/schemas/.arc.yaml`: ```yaml arc_version: "0.1" kind: schema id: # PascalCase, matches the existing Python class / TS interface name description: # pull from the docstring or write something honest fields: : type: required: nullable: ``` Rules of thumb: - **Field types:** map Python types → Arc types directly. `int → int`, `str → string`, `bool → bool`, `UUID → uuid`, `datetime → timestamp`, `float → float`, `Literal[...] → enum`, `List[X] → array of X`, `Dict[str, Y] / TypedDict → object`. For refs across schemas, use `type: ref, ref: .`. - **`required`** in Arc means "must be present in the JSON" — equivalent to Pydantic's non-Optional field with no default. **Fields are optional by default** in Arc (counterintuitive — most schema languages default to required). Be explicit. - **`nullable`** means "the value `null` is allowed" — equivalent to `Optional[X]` in Python or `X | null` in TS. - **Enum values** → `type: enum, values: [a, b, c]`. Preserve case. - **If the existing types disagree** (Pydantic says required, TS interface says optional), pick the stricter side and let `arc check` surface the drift in step 5. That's the whole point. ### Step 3 — Draft components For each logical endpoint group (typically one component per FastAPI router or top-level resource), write one `.arc/components/.arc.yaml`: ```yaml arc_version: "0.1" kind: component id: # snake_case, semantic name (e.g. tasks, users, billing) description: endpoints: - id: # snake_case, matches the handler function name when possible method: GET | POST | PUT | PATCH | DELETE path: /... request: # optional — only if there's a body response: # optional but recommended auth: required | optional | none # if you can detect it from the handler bonds: endpoints: : handlers: - /.py:: clients: # optional — if there's a frontend client - frontend/api/.ts:: tests: # optional — if there are tests - tests/.py:: ``` Rules of thumb: - **One component per coherent endpoint group.** A component with 50 endpoints is too big; a component with 1 endpoint is usually too small. Aim for 3–15 endpoints per component. - **Bond paths are relative to the project root**, forward-slash even on Windows. Do not use `..`, absolute paths, or drive letters — those get rejected by `arc check`. - **Bond symbols must be top-level identifiers.** v0.1 does not support class-qualified symbols (`api.py::TaskService.create`). If your handlers are methods on a class, either refactor to module-level functions or bond to the class instance method's outer wrapper. - **`forbidden_paths`** on a component is the architectural fence — globs of paths that NO file bonded to this component is allowed to import. Use sparingly and only when you have a real architectural rule to enforce. - **`depends_on`** lists other component IDs whose code this one is allowed to import. Default is "only its own bonded files plus standard library." Document the real coupling. ### Step 4 — Validate the drafted contract Run `arc_check`. Expect **a lot** of drift on the first pass. That's good — every drift is a real disagreement between the four places the contract used to live, which Arc has now made visible. Walk each drift: - **`signature_mismatch`** — the handler's parameter or return annotation doesn't match the contract. Usually means the existing code used `dict` instead of the typed class, or used a slightly different type name (`UserResponse` vs `User`). Pick which is correct (usually the contract) and note that the code needs to follow. - **`bond_unresolved`** — the bonded symbol doesn't exist in the file. Usually means the symbol's nested inside another function (v0.1 limitation), got renamed, or the bond points at the wrong file. - **`route_mismatch`** — `@app.` decorator disagrees with the contract path/method. Usually means a copy-paste-and-edit bug. - **`unresolved_ref`** — the contract references a schema or field that doesn't exist. Usually a typo in the YAML you just wrote. - **`generated_file_stale`** — generated artifacts don't exist yet. Expected — you haven't run `arc compile`. - **`no_generated_files`** — info-severity banner saying "run arc compile." Expected on a fresh adoption. - **`forbidden_import` / `import_outside_depends_on`** — only fires if you wrote `forbidden_paths` / `depends_on`. If you didn't, you won't see these. ### Step 5 — Decide, don't paper over For each drift, **decide which side is correct:** - **Contract is correct, code needs to change** — this is the common case for "untyped `dict` handler." Note the fix in your report; do NOT apply it as part of this skill. Hand the user a list of file:line locations where code needs to follow the contract. - **Code is correct, contract was wrong** — happens when you guessed wrong about a field's type or optionality. Edit the `.arc/` file. Re-run `arc_check`. - **Both are wrong** — rare, but it happens. Surface to the user. Do NOT weaken the contract to make `arc check` pass. Lowering `required: true` to `required: false` so a buggy handler stops drifting is exactly the failure mode the benchmark scores against. ### Step 6 — Run `arc compile` Once `arc check` is either clean or the only remaining drifts are "code needs to change": ``` arc compile ``` This generates typed artifacts (Pydantic classes, TypeScript interfaces, Zod validators, JSON Schema). The user can choose whether to migrate handlers and frontend code to use the generated types or to leave them as-is. The contract is now the source of truth either way. **If `arc compile` warns about missing Python tools** (`datamodel-codegen`, `ruff`), offer to install them via the project's `.arc/requirements.txt` and re-run compile. Announce what you're about to do, then run: ``` pip install -r .arc/requirements.txt ``` After the install completes, re-run `arc compile`. If the install fails (no `pip` on PATH, no internet, permission error), surface the failure clearly and fall back to the user — don't loop. Acceptable fallbacks: `pipx install datamodel-code-generator && pipx install ruff`, or skip Python codegen entirely (Node-side artifacts already shipped). The Node-side codegen (`json-schema-to-typescript`, `json-schema-to-zod`, `prettier`) is bundled with `arc-contract` and works out of the box — Python is the only external tooling. Do NOT install Python tools without announcing it first. `pip install` mutates global Python state by default (unless the user has a venv active); some users prefer `pipx install` for isolation. Ask first if the project's environment is ambiguous. ### Step 7 — Report back Hand the user: 1. **What you scaffolded** — number of schemas, components, total LOC of YAML. 2. **What `arc check` found** — drift counts by kind, with file:line for each error-severity drift. 3. **What to fix next** — a prioritized list. Usually: tighten the handlers' parameter and return annotations first (signature_mismatch fixes), then run `arc compile` to verify codegen produces sensible output. 4. **Honest limitations** — if you couldn't infer something (e.g., the project has a nested-function pattern Arc v0.1 doesn't trace), say so. Don't fabricate. ## Iteration policy - Don't iterate more than 3 times on `arc_check` during the initial adoption pass. If after 3 drafting iterations the contract still doesn't reflect reality, the codebase has more drift than the agent should silently absorb — escalate to the user with the open questions. - If you find yourself adding `nullable: true` and `required: false` to make drift go away, **stop**. You're weakening the contract instead of describing reality. Re-read the source code; the answer is almost always "the contract is right, the code is sloppy." ## Red flags / common rationalizations | Thought | Reality | |---|---| | "I'll just write `required: false` to skip this drift" | You're fabricating the contract. The point of Arc is to make implicit contracts explicit; you just made them more wrong. | | "The Pydantic model uses `Optional[X]` so I'll mark it nullable: true and required: false" | `Optional[X]` is ambiguous: it means "X or None." In Arc terms: required if there's no default, nullable if None is the value. Check both. | | "There's no Pydantic class for this dict-typed handler" | Then there's no contract yet. Either skip this endpoint or invent the most plausible schema and let `arc check` confirm. | | "The TS interface and Pydantic model disagree" | That's a real bug. Pick the stricter one, surface to the user. | | "OpenAPI says X but the actual handler returns Y" | Real bug. Surface. Don't average. | | "I'll just bond to a class method by writing `file.py::Class.method`" | Not supported in v0.1. Either refactor to module-level or skip. | | "I drafted 80 schemas in one pass" | Stop. Draft 5, validate, iterate. Drafting at scale before validating is how fabricated contracts ship. | | "I'll just `pip install` to fix the Python warning" | Announce it first. `pip install` mutates global Python state by default. Confirm the user wants `pip` (not `pipx` or a venv), then run. | ## Reference: tool wire shapes Arc's MCP tools used by this skill: - **`arc_check()`** → `{ drifts: Drift[] }`. Run after every contract edit. - **`arc_scope({ files })`** → `{ components, schemas, bonds, forbidden_paths, tests, unmatched_files }`. Use to discover what Arc already knows about a file path you're considering bonding. - **`arc_explain({ drift_id })`** → `{ source_excerpt, code_excerpt, related_schemas, dependency_chain, why_it_matters }`. Use for any drift whose meaning isn't obvious from `arc_check` alone. `arc_propose_fix` and `arc_validate_patch` are less useful for the adoption workflow (they're tuned for "fix existing drift on existing contract," not "draft the contract"). Call them if you want, but the workflow above is the canonical adoption loop. --- **Honest scope statement:** this skill works for FastAPI + React/TypeScript projects (v0.1's supported stack). Django, Flask, Go, and other stacks have partial or no extractor coverage — the skill will produce drafts but `arc check` won't catch as much drift on them. v0.2 expands the extractors; v0.3 ships `arc init --infer` as a CLI shortcut. For now, the agent-driven path is the adoption path.

arc-adopt

Install this skill

Comments