init

the-loop: init

Initialize "the-loop" into the current project repository. Idempotent and safe to re-run: it is driven entirely by the manifest, creates only what is missing, and never overwrites user-owned files.

The authoritative source of what to create — and which files are managed vs. user-owned — is ${CLAUDE_PLUGIN_ROOT}/.the-loop/manifest.yaml (each entry's managed: true|false). Two kinds of file are internal to the-loop and are never copied into the project — they ship with the plugin and are read from there:

• Templates — ${CLAUDE_PLUGIN_ROOT}/skills/the-loop/templates/ (manifest.templatesDir), read when a file needs scaffolding.
• Config schemas — ${CLAUDE_PLUGIN_ROOT}/.the-loop/*.schema.json (manifest.schemasDir), read when a config needs validating or onboarding. They are the plugin's contract, not the operator's data, and a copy in the project only goes stale (issue-220). Each scaffolded config instead opens with a # yaml-language-server: $schema=<published url> line, so the operator's editor validates it with nothing local on disk.

(${CLAUDE_PLUGIN_ROOT} is the installed plugin's root directory; in Cursor, resolve it to the plugin's install directory.)

Modes

• --dry-run — compute and print the report (below) without writing anything and without interacting. Use it to preview an init or an upgrade safely.
• --defaults — non-interactive: skip the guided onboarding (step 2), apply sensible defaults everywhere (existing answer → detected signal → schema default), and list every gap that genuinely needs the user under needs-user in the final report.

Steps

1. Detect the project. Inspect the repo to infer sensible defaults — never stamp the plugin's hardcoded tooling defaults onto an existing project unread:
   • languages present (python / js / ts / go) — from file extensions and manifests (package.json, pyproject.toml/setup.cfg/requirements.txt, go.mod).
   • whether it looks like a monorepo (nx.json, pnpm-workspace.yaml, workspaces) and which tool — default Nx; support non-monorepo (monorepo: false).
   • existing package manager / test runner / linter / type-checker per language, by reading lock files, manifest fields, and dependency lists, per the exact signal table in the the-loop skill's reference/tooling.md → "Tooling detection" (e.g. package-lock.json→npm, yarn.lock→yarn, bun.lockb→bun, pnpm-lock.yaml→pnpm; devDependencies for jest/vitest/mocha, eslint/oxlint/biome, etc.; the Python and Go equivalents).
   • cross-check inferred tooling against .github/workflows/ (or other CI config) — the commands CI actually runs are a strong signal.
   • the git remote / owner / repo for ticketing.
   • candidate custom instruction docs for customInstructions.docs — existing convention files the team already maintains (CONTRIBUTING.md, style/convention guides under docs/). Propose them in the onboarding (never auto-register); the user confirms, adjusts, or adds paths — including absolute per-machine paths detection can never see (see the skill's reference/instructions.md). Where detection is unambiguous, write the detected tool into tooling.<concern>.<lang>. Where it's ambiguous or no signal exists, fall back to the plugin default but mark that line with a trailing # TODO: verify — no signal found, defaulted comment, and surface it in the guided onboarding (step 2) — or, when running non-interactively, in the needs-user section of the final report (step 8) — so the user confirms it before the agent invokes it.