/stitch

description: "Build or verify cross-repo STITCH.md linking backend + frontends in a product group. Modes: create, verify, diff, section. Uses CODEMAPs as drift source by default. Trigger: '/stitch create {group}', '/stitch diff {group}'."

/stitch — Cross-repo stitch layer

Generate a cross-repo binding artifact (`STITCH.md`) for a product group (backend + one or more frontends). Tables only, not narrative. Drift detection uses CODEMAP endpoint sections by default with explicit opt-in fallback to grep.

Step 0: Load config

<!-- shared-block: group-loader --> Read `~/.gemini/antigravity/aria-knowledge.local.md`. Parse YAML frontmatter `projects_groups` (multi-line YAML block — see `CONFIG.md` "Skill-only fields" for canonical schema, including the optional `stitch_path` sub-field and custom-role conventions).

Look up `<tag>` in `projects_list` (get `project_root`) and `projects_groups` (get role → folder dict).

• If `<tag>` missing from `projects_list`: stop with *"unknown project tag: <tag>"*.
• If `<tag>` in `projects_list` but missing from `projects_groups` and `<project_root>` has multiple distinct codebases that must stay in sync (separate repo-marker sub-dirs, OR one repo with a shared-contract source + multiple generated/typed clients — see scan below): trigger **auto-propose bootstrap**. The git-repo boundary is NOT the signal — a monorepo with a `contract/` → `ios/`+`android/`+`backend/` seam qualifies just as much as separate repos.
• If `<tag>` is a single undifferentiated codebase (no separate sub-dirs and no contract→multi-client seam): load `<project_root>/CODEMAP.md` only.

**Auto-propose bootstrap** (when `projects_groups[<tag>]` is missing but `<project_root>` contains multiple sync-bound codebases — separate repo dirs or a contract→clients seam): 1. Scan `<project_root>` one level deep for sub-directories with repo or contract markers:

• `openapi.{yaml,yml,json}` / `*.proto` / `schema.graphql` (or a dir named `contract`/`contracts`/`api-spec`/`proto`) → `contract` (the shared source clients are generated from — its drift is what STITCH tracks)
• `manage.py` + `settings.py` → `backend` (Django)
• `composer.json` + `artisan` → `backend` (Laravel)
• `Gemfile` with `rails` → `backend` (Rails)
• `package.json` with `express`/`fastify`/`nestjs` → `backend` (Node)
• `pyproject.toml`/`requirements.txt` with `fastapi`/`pydantic` → `backend` (FastAPI)
• `Package.swift` / `*.xcodeproj` / an `ios` dir → `ios` (Swift/SwiftUI)
• `build.gradle{,.kts}` with an `android` dir → `android` (Kotlin/Android)
• `next.config.*` → `web` (Next.js)
• `app.json` + `expo` in package.json → `mobile` (Expo)
• `package.json` with `react` (no `next`/`expo`) → `web` (React SPA)
• other `package.json` → prompt user for role name

2. Handle role conflicts: if two dirs inferred as same role, prompt user to assign distinct keys (`web`, `web-admin`, etc.). 3. Propose the group structure to user: sub-repo names, inferred roles, YAML block to insert. Show a preview diff of the change to `~/.gemini/antigravity/aria-knowledge.local.md`. 4. On approval, edit the config file to add the `projects_groups[<tag>]` entry, preserving existing fields and YAML structure. 5. On decline, stop with *"proceed after registering group manually"*.

Resolve each `(role, folder)` pair to absolute path: `<project_root>/<folder>`. For each absolute path, read `CODEMAP.md` if it exists. Read `<project_root>/STITCH.md` if it exists. Return resolved path map + warnings for any missing CODEMAPs. <!-- /shared-block: group-loader -->

**For `/stitch` specifically:** the group MUST have **≥2 distinct codebases bound by a shared contract** — at least one contract/backend source role + at least one client role that must stay in sync with it. **Whether they live in separate git repos or one monorepo is irrelevant** — the load-bearing condition is "multiple codebases that drift apart," not "multiple repos." A monorepo's `contract/` → `ios/`+`android/`+`backend/` seam (the dual-native keystone — one OpenAPI/proto/GraphQL source feeding generated clients) is exactly the drift seam STITCH exists to document. Only stop when there's a **single undifferentiated codebase** with no such seam: *"/stitch needs ≥2 contract-bound codebases; this looks like one codebase — use `/codemap`."*

Step 1: Resolve paths & output target

• `BACKEND_ROOT` = `<project_root>/<backend folder>` (the one role=backend entry)
• `FRONTEND_ROOTS` = list of `<project_root>/<folder>` for all non-backend roles
• `STITCH_FILE` = `<project_root>/STITCH.md` by default. Override: if `projects_groups[<tag>]` contains a `stitch_path` field, use that (relative to `<project_root>`).

For `create` mode, require `BACKEND_ROOT/CODEMAP.md` and each `frontend_root/CODEMAP.md`. If any missing, list what's missing and recommend running `/codemap create` in each affected repo first.

Step 2: Load template (create mode only)

Start from `${CLAUDE_PLUGIN_ROOT}/template/stitch/STITCH.template.md`. Fill **Group identity** with:

• Group tag
• Backend repo folder name + `git rev-parse HEAD` if git available
• Frontend repo folder names + revisions
• CODEMAP absolute paths for each repo
• Configured `STITCH_FILE` path

Step 3: Build sections 2–5 (create + section modes)

Using the loaded CODEMAPs, populate:

• **2. Auth stitch** — token path FE → BE. Source: FE auth slice/hook + BE auth middleware/JWT handler. Table rows: step | location (file) | notes. Mermaid optional, keep minimal.
• **3. Endpoint stitch** — union of FE RTK/fetch calls → BE routes. Normalize paths (strip env prefixes, trailing slashes). Table columns: FE hook/client | HTTP method | FE file | Path | BE urls module | View/handler | Permission | Notes.
• **4. Entity stitch** — when traceable from CODEMAP model/serializer/type tables. Columns: Domain | FE type/schema | BE serializer | Model | Notes.
• **5. Integration stitch** — external services from backend CODEMAP's Integra