loopd-init

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 "${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:

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_.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 "${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

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:

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).