---
name: loopd-init
description: Use when the user wants to install or bootstrap loopd in a fresh git repository. Scaffolds .loopd/ (charter, config, per-loop state files, scripts, pre-push hook) in the current repo, interactively gathering project name, main branch, PM worktree, and worker definitions. Safe to re-run — stops if .loopd/ already exists.
---

# loopd-init — scaffold loopd in a git repo

You are setting up loopd (a PM + N-worker parallel development system) in the user's current git repository. This is a conversational install.

## Preconditions (check first)

1. Current directory is inside a git repo. Verify: `git rev-parse --show-toplevel`. If this fails, stop and tell the user to run inside a git repo.
2. `.loopd/` does not already exist at the repo root. If it does, stop and ask the user whether to abort or have them `rm -rf .loopd/` first.
3. The plugin's `template/` directory is available. On Claude Code it lives under `${CLAUDE_PLUGIN_ROOT}/template/` (resolve via the standard plugin path); on Codex, resolve the skill's sibling `template/`. If unsure, ask: "Paste the absolute path to `plugins/loopd/template/`."

## Step 1 — Gather inputs

Ask the user one question at a time. Use sensible defaults derived from the repo.

1. **Project name** — default: basename of `git rev-parse --show-toplevel`. Confirm.
2. **Main branch** — default: output of `git symbolic-ref refs/remotes/origin/HEAD --short 2>/dev/null | sed 's|origin/||'`, falling back to `main`. Confirm.
3. **PM worktree path** — default: the current repo root (PM operates in-place). Confirm.
4. **Workers.** Ask for a space-separated list of worker names (e.g., `backend frontend`). Loopd needs at least one worker. For each worker, derive:
   - **Branch:** default `loop/<name>`. Confirm each one.
   - **Worktree path:** default `<parent-of-pm-worktree>/<project>-<worker>`. Confirm each one.
5. **Create worker branches + worktrees now?** yes/no. If yes, after scaffolding, run for each worker:
   - `git branch loop/<name> origin/<main-branch>` (if branch doesn't exist)
   - `git worktree add <worktree-path> loop/<name>`
   If no, print the equivalent commands for the user to run later.

Show a summary table before proceeding. Get explicit confirmation.

## Step 2 — Render templates

Invoke the render helper to stamp `template/` into `<target>/.loopd/`:

```bash
bash "${TEMPLATE_PARENT}/../scripts/render.sh" \
  "${TEMPLATE_PARENT}" \
  "${TARGET_REPO_ROOT}/.loopd" \
  "PROJECT=<project>" \
  "MAIN_BRANCH=<main>" \
  "PM_WORKTREE=<pm-path>" \
  "WORKER_NAMES_COMMA=<worker, names, comma-separated>"
```

This creates:
- `.loopd/LOOPD.md` (charter)
- `.loopd/config.sh` (runtime config)
- `.loopd/LOOP_PM.md` (PM state)
- `.loopd/pm-round.sh`, `.loopd/setup.sh`
- `.loopd/hooks/pre-push`

Notes:
- `render.sh` preserves the executable bit on `*.sh` and `hooks/pre-push`.
- Only top-level scalars are rendered via `render.sh`. Worker arrays and per-worker `LOOP_<NAME>.md` files are written in Step 3 below.

## Step 3 — Write worker array into config.sh

Edit `.loopd/config.sh` to append the parallel worker arrays. Use the Edit tool to replace the `# WORKERS_APPEND_HERE` marker with:

```sh
WORKER_NAMES=(backend frontend)
WORKER_BRANCHES=(loop/backend loop/frontend)
WORKER_WORKTREES=(
  "/abs/path/to/myapp-backend"
  "/abs/path/to/myapp-frontend"
)
```

(Use the actual values the user supplied. One-line arrays are fine for short lists; line-per-entry for long ones.)

## Step 4 — Render per-worker LOOP_<NAME>.md files

The per-worker template lives in a sibling directory (`template-worker/`) so the global `render.sh` pass in Step 2 doesn't touch it.

For each worker, invoke `render.sh` targeting just that one file:

```bash
bash "${PLUGIN_ROOT}/scripts/render.sh" \
  "${PLUGIN_ROOT}/template-worker" \
  "${TARGET_REPO_ROOT}/.loopd/_worker_<name>" \
  "WORKER_NAME=<name>" \
  "WORKER_UPPER=<NAME>" \
  "PROJECT=<project>" \
  "BRANCH=loop/<name>" \
  "WORKTREE=<path>"

# Move the rendered file to its final name and remove the scratch dir.
mv "${TARGET_REPO_ROOT}/.loopd/_worker_<name>/LOOP_WORKER.md" \
   "${TARGET_REPO_ROOT}/.loopd/LOOP_<NAME_UPPER>.md"
rmdir "${TARGET_REPO_ROOT}/.loopd/_worker_<name>"
```

Alternatively, use the Read → Write pattern (Read template, substitute placeholders in-memory, Write to target) if you prefer not to shell out.

## Step 5 — Install pre-push hook

```bash
cd <target-repo-root>
bash .loopd/setup.sh
```

`setup.sh` copies `.loopd/hooks/pre-push` into each worktree's common `.git/hooks/` directory.

## Step 6 — Create branches + worktrees (if user said yes in Step 1.5)

For each worker:

```bash
git -C <pm-worktree> branch <branch> origin/<main-branch> 2>/dev/null || true
git -C <pm-worktree> push -u origin <branch>
git -C <pm-worktree> worktree add <worktree-path> <branch>
```

Skip the first command if the branch already exists locally.

If the user said no, print these commands to the terminal for them to run manually.

## Step 7 — Verify and report

Run `bash .loopd/pm-round.sh --dry-run` from the PM worktree. Expected: it lists every worker as `up-to-date (behind=0)` or similar. Any error here means config.sh is malformed — fix before handing off.

Print a success summary:
- Files created: list
- Next step: `/loopd pm` (to start PM) or `/loopd <worker>` (to start a worker)
- Docs: `.loopd/LOOPD.md`

## Subagent dispatch (Codex users)

When this skill references tools like Read/Write/Edit/Bash, Codex users should substitute their native equivalents per `references/codex-tools.md`.

## Anti-patterns

- Do NOT auto-create more than 8 worker branches. Loopd scales cleanly to ~6-8; beyond that, the protocol overhead eats the gains. If the user asks for more, push back once and confirm.
- Do NOT overwrite an existing `.loopd/`. That's the user's state; destroying it loses their tracker history.
- Do NOT mock the config. Every value comes from the user; defaults are just defaults.
- Do NOT skip Step 7. Dry-run caught two real bugs during dogfooding (branch-list typos + missing PM_WORKTREE).