intake-runbook

Files (2)

• SKILL.md
• intake-target.js · scripts/

SKILL.md (first lines)

# Client Intake

Adopt an externally-hosted client project into your own infrastructure: pull the
code local, re-home it to a fresh GitHub repo and a fresh Vercel project, run
the `onboarding` skill, and apply Arkira standards. The live deployment, the
source remote, and production data are never touched.

## When to Use

- Client hands you a project hosted on Lovable, another GitHub/GitLab org, or a
  zip export, and you need to own it going forward.
- Migrating a project off one platform onto your GitHub + Vercel.
- Taking over an existing dev repo for continued work under Arkira standards.

Not for: a repo already in your org that just needs standards. Use
`arkira-sync` directly. Not for: contributing a PR back to a repo that stays on
the client's infra. Use a normal branch + PR instead.

## Hard Invariants (never violate)

These define "don't touch live." Violating any one means the intake failed.

1. **Source remote is read-only.** Clone or export only. Never push back to the
   source remote. Rename it `upstream-archive` or remove it before the first
   push.
2. **New GitHub repo under the correct org.** Resolve the client in
   `entity-map.json` and use that `github_org`. The new repo becomes `origin`.
3. **New Vercel project, preview only.** Never link to the live project. No
   custom/prod domain on first deploy. The live deploy keeps running, untouched.
4. **Never reuse live data stores.** Stand up your own Supabase (or DB) project;
   migrate schema, swap env. The live database is never linked or written.
5. **Rotate any real secret** found committed or in `.env*` before the first
   push to your origin.
6. **Verify green** (lint / typecheck / test) before pushing.

## Workflow

### Step 0: Resolve the entity

Read the entity map at `entity_map_path` in `~/.arkira/config.json`, or ask
the operator for that path if the key is unset. Find the
client → `type` (client), `github_org`, `workspace`, `drive_root`,
`parent_entity`. The `github_org` is mandatory for Step 3; the `workspace`
decides the clone destination. Repo names in the map may not match on-disk dir
names. Match flexibly. If the client is not in the map, ask the operator for
the target org before proceeding.

Destination parent: the entity `workspace` if set, else
`~/Developer/products`. Resolve it physically before choosing a target.

### Step 1: Get the code local

Apply `governance/file-management-standard.md` before any clone, unzip, or copy:

1. Resolve the destination parent with physical, no-follow semantics. Reject a
   symbolic-link parent or a target outside that resolved parent.
2. Derive one strict repository slug. The target is exactly one child of the
   resolved parent. Reject absolute paths, separators, `.` and `..` segments,
   control characters, and nested existing repositories.
3. The target must not exist. Do not reuse an existing directory, even if it
   appears empty. Use the executable target binder below to create it and its
   private run-state file. The helper records the physical parent and target
   paths plus both device/inode identities. Target creation runs from the
   already-bound parent directory. State publication runs from an independently
   bound, identity-checked private state parent, and that binding remains live
   through creation commit or rollback. It refuses nested repositories,
   symlinked or replaced parents, existing targets, and non-private or replaced
   state.
4. A failed clone, unzip, copy, or validation is terminal. Do not `cd` into the
   target, initialize Git, or run cleanup commands after failure. Report the
   run-created path for explicit cleanup; never infer that a pre-existing path
   is safe to remove.

Create the target through the installed helper. Keep run state outside the
target so a failed acquisition cannot replace it:

```bash
intake_target="${CLAUDE_PLUGIN_ROOT}/skills/intake-runbook/scripts/intake-target.js"
intake_run_dir="$(mktemp -d "${TMPDIR:-/tmp}/arkira-intake.XXXXXX")"
chmod 700 "$intake_run_dir"
intake_state="$intake_run_dir/target.json"
target_physical="$(node "$intake_target" create \
  --parent "$destination_parent_physical" --slug "$repo_slug" \
  --state "$intake_state")"
```

Run every Git, verification, secret-scan, GitHub, and deployment command through
`intake-target.js run`. The helper changes into the proven directory inode
before spawning the command, revalidates the named parent and target after it
exits, and sets `ARKIRA_INTAKE_TARGET=.`. A path exchange after validation
therefore cannot redirect the command. Failed creation removes state and the
target only after same-parent claims prove the exact run-created inodes; state
rollback uses the state-parent binding retained before publication, even if its
pathname is replaced. Never split the helper's check from the consequential
command and never rely on the agent's current working directory.

Pick the source track only after that preflight:

**Lovable**: Lovable syncs to a GitHub repo via its GitHub app, or exports a
zip.
- If GitHub-connected, clone into the already proven empty target with
  `node "$intake_target" run --state "$intake_state" --before empty --after git
  -- git clone --no-hardlinks <source-url> .`. Continue only when the
  command succeeds, the target is a valid worktree, and `origin` exactly matches
  the requested source URL.
- For an export, validate the archive inventory before extraction. Reject
  absolute paths, `..` traversal, device files, and absolute or escaping
  symlinks. Extract only into the proven target. If the export contains one
  wrapper directory, move its children through a contained, no-clobber step.

**Existing git (another org / GitLab / dev project)**: clone it:

```bash
node "$intake_target" run --state "$intake_state" --before empty --after git -- \
  git clone --no-hardlinks <source-url> .
node "$intake_target" run --state "$intake_state" --kind git -- \
  git rev-parse --is-inside-work-tree
node "$intake_target" run --state "$intake_state" --kind git -- \
  git remote get-url origin

From jeanchastel/arkira, MIT.

More from jeanchastel/arkira