Repo Setup

Repo Setup

When to Use

• Starting work in a new project repository for the first time
• /update-docs reports tracker_missing — the project lacks coordination infrastructure
• PM asks to set up project tracking in an existing repo
• Marketplace first-run — new coordinator plugin user setting up their first project
• Creating a NEW repo from scratch (not onboarding an existing folder)? → use coordinator:new-project, which creates + scaffolds a stack + delegates the onboarding half back to this skill.

claude-klabauter is a hard prerequisite — resolved via CLAUDE_KLABAUTER_ROOT / the machine-local repos.claude_klabauter registry entry — for coordinator-claude itself, so it must already resolve before this skill's own fences will run (private repo until its OSS release; the maintainer grants access on request, same model as project-rag).

Setup is sufficient — downstream skills add-to, never create-from-scratch. This skill produces minimum-viable versions of all coordinator artifacts the operator will rely on (state/orientation_cache.md, docs/README.md, CLAUDE.md). Downstream skills (/update-docs, /workstream-start) add to these artifacts as content accumulates, and self-gate against fresh substrate — underlying principle: wiki (produce-not-prescribe). (/workday-start runs unconditionally as session orientation; the produce-not-prescribe axis doesn't apply to it.)

Lanes

Every invocation fires exactly one of three lanes, each a pre-answered round-trip set — see lanes/CONTRACT.md for the shape and lanes/<lane>.yaml for the canonical values; residue/<lane>.md carries the rationale for a human reading the flow:

Which lane fires is an input to this skill, not a decision it makes: the op parameter (or, until the engine op lands, the caller's own answer to p1.repo-classification-ask) names the lane. --batch (§ Batch Mode) is an entry-point mode, not a fourth lane — it drives the add-existing-project lane's answers per repo; see residue/batch-mode.md.

Flag contract

• Default (no flag) — single-repo, new-project or add-existing-project lane. Runs from inside one repo's cwd.
• --root <path> (alias --target <path>) — single-repo only, optional. Onboards a sibling repo by absolute or relative path without cd-ing the session into it — defaults to $(pwd) when omitted. Orthogonal to --batch — --batch reads paths from working-repos.yaml and loops the fleet; --root/--target targets exactly one repo named on the command line. Resolution mechanic: § Procedure below.
• --batch — fleet non-interactive. See residue/batch-mode.md.
• --check-only and --non-interactive are batch-mode-only. If passed to the default single-repo mode (without --batch), the skill exits with the one-line remediation: "--check-only and --non-interactive are only valid with --batch; for non-interactive single-repo setup, set coordinator.local.md first and re-run /repo-setup."

Prerequisites

• You are in the project's working directory (not ~/.claude) — OR pass --root <path> (alias --target <path>) to onboard a sibling repo from a parent repo's session context without cd-ing the session.
• The firing lane's pre-answered values (lanes/<lane>.yaml) or, for add-repo, an already-decided classification.

Procedure

1. Resolve $_TARGET_ROOT (run before everything else). (shape per snippets/resolve-coordinator-bin.md; PowerShell shown) & "$env:COORDINATOR_SETTINGS_HOME\bin\repo-setup-args-and-register.exe" resolve-target-root. It validates the resolved path is an existing directory inside a git repo, printing the absolute path to stdout on success or a fail-loud ERROR: ... line on stderr with exit 1 on failure — mirror that idiom, never silently fall back to cwd. When an explicit --root/--target was passed, change the shell's working directory to $_TARGET_ROOT as the first action; every downstream cwd-relative step then transparently targets the sibling repo. When --root/--target is absent, $_TARGET_ROOT resolves to $(pwd) and this step is a no-op beyond the resolver call.

2. Load the firing lane's directives. Read lanes/<lane>.yaml in full: its round_trip_directives[] supply every value the mechanical procedure below would otherwise need to prompt for, its terminal_offer_defaults[] supply the policy default for every terminal offer, and second_phase_deferred[] names the agent-work steps that stay unresolved for a later phase. Load once, apply throughout — this skill does not re-derive or select among any of these values.

3. Run the lane-independent mechanical procedure. Read residue/mechanics.md and execute it in full — detection, rendering/scaffolding, substrate seeds, optional tripwire installs, and the Phase 4 report shape all run the same way regardless of which lane fired. Substitute the loaded lane's directive/default values wherever the mechanical procedure names a judgment point; take no value from a prompt.

4. UNATTENDED-HALT SET. p3j.1-test-cmd-detect, p3m.verify-reachability, tw.windows-console-verify-run, batch.hook-respect are never pre-answered by any lane (lanes/CONTRACT.md) — return them unresolved to the calling agent/PM exactly as mechanics.md's own procedure surfaces them.

5. Roster. Report the firing lane's roster_slots[] verbatim in the Phase 4 output. Materializing the roster into batons is a later skill/ceremony's job, out of this skill's scope.

6. Sentinel — signal that setup just ran. As the final action, write a session-scoped sentinel so /workstream-start (if invoked in this same session) detects that setup just ran and emits the produce-not-prescribe one-liner instead of re-orienting: create the state/ directory if absent, then touch state/.repo-setup-just-ran. The sentinel is single-shot: /workstream-start's Preflight consumes it on first read (rm -f). It MUST be gitignored — see residue/mechanics.md for the .gitignore line. Per-machine transient marker, never committed.

Optional Tripwire Installs

Install steps are mechanical and lane-independent — see residue/mechanics.md § Optional tripwire installs — mechanical half. Whether an offer fires at all is a value the firing lane's terminal_offer_defaults[] already carries (tw.windows-console-offer, tw.ci-offer); this skill does not decide it inline.

Notes

• This skill creates the skeleton; /update-docs handles ongoing coordination-artifact maintenance, in the same format.
• Any onboarding bug fix needs all three layers to not recur: prevention (fix the install script), reactive repair (doctor-style recovery for users who already hit it), searchable docs (a troubleshooting row keyed on the literal error text). Rationale: wiki.
• Rationale for the extended-substrate seeds and the CLAUDE.md template architecture: wiki.
• Peer-repo citations belong to the workstream record: when a scout dispatch or substrate read yields a file:line citation for a peer repo, land it in the relevant state/workstreams/<id>.yaml entry's specs[] or deliverables[].text (free-text fields per coordinator/schemas/workstream.schema.json) — never in state/orientation_cache.md, whose ## Active workstreams heading is name-only, capped at 10 entries, and schema-forbidden from carrying free-form prose or citations (${CLAUDE_PLUGIN_ROOT}/pipelines/workday-start-internals.md:265, ${CLAUDE_PLUGIN_ROOT}/docs/wiki/tiered-context-loading.md:57).