41 added, 170 removed. Audit A to A.
---
name: repo-setup
description: "First-time setup for an EXISTING repo, single or fleet-wide (--batch)."
- version: 1.0.0
+ version: 2.0.0
allowed-tools: ["Read","Write","Edit","Bash","Grep","Glob","Agent","Skill","AskUserQuestion","TaskCreate","TaskUpdate","TaskGet","TaskList"]
---
# 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.)
- ## Flag contract
-
- - **Default (no flag) — single-repo interactive.** Runs from inside one repo's cwd. PM-present; asks the 3 cold questions when needed; full Phase 1 → Phase 4 flow as documented below.
- - **`--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: § Phases preamble below.
- - **`--batch` — fleet non-interactive.** Reads `~/.claude/working-repos.yaml` and loops the single-repo flow per repo. Phase-2 cold-asks substituted by detected defaults (Phase 1 marker scan + Phase 1.5 substrate) OR skipped via lazy-creation discipline when the target artifact already exists. See § Batch Mode below.
- - **`--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."` Never silently pick a meaning for an ambiguous flag combination — detect it and fail loud instead.
-
- ## Batch Mode (--batch)
-
- Batch mode runs fleet-wide setup non-interactively, driving the single-repo phases per repo read from `~/.claude/working-repos.yaml`. For the full per-repo flow, idempotency contract, hook-respect, and the summary table shape, read `residue/batch-mode.md` before running with `--batch`.
-
- ## 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; see § Phases preamble below.
- - PM is available for 3 questions (Step 2)
-
- ## Phases
-
- **Target-root resolution (run before Phase 1).** Resolve `$_TARGET_ROOT` — the `--root`/`--target` value extracted from `${ARGUMENTS:-}` if given, else cwd — via `"${COORDINATOR_SETTINGS_HOME:-$HOME/.coordinator-claude-settings}/bin/repo-setup-args-and-register" 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, before Phase 1 begins. Every downstream cwd-relative step
- then transparently targets the sibling repo — no per-site path-variable threading. Only the shell
- cwd for scaffolding moves; the session's conversational and plan context stays put. When
- `--root`/`--target` is absent, `$_TARGET_ROOT` resolves to `$(pwd)` and this preamble is a no-op.
-
- ### Phase 1: DETECT — Survey Existing State
-
- Before scaffolding, check what already exists. **Never overwrite existing files.**
-
- Check for each of these and record status (exists / missing / incomplete):
-
- ```
- ├── CLAUDE.md — project conventions
- ├── docs/README.md — documentation index (wikis, research, specs, reference)
- ├── docs/wiki/ — wiki guides (EAGER, seeded — see audit table below)
- ├── docs/wiki/DIRECTORY_GUIDE.md — guide index with decision record mapping
- ├── docs/plans/ — implementation plans (EAGER, seeded — see audit table below)
- ├── docs/research/ — research outputs (EAGER, seeded — see audit table below)
- ├── state/lessons/ — engineering patterns, one per-entry YAML file (LAZY — created by coordinator:workstream-complete on first lesson)
- ├── archive/completed/ — completion archive (LAZY — created by coordinator:workstream-complete on first completion)
- ├── state/handoffs/ — session continuity (EAGER, seeded — see audit table below)
- ├── CONTEXT.md — domain glossary (LAZY — never scaffold; produced when first term is resolved)
- ├── DIRECTORY.md — source index
- └── .gitignore — check for .claude/settings.local.json entry
- ```
-
- **If `CLAUDE.md` already exists:** its presence alone does not prove the scaffold is complete — a repo can carry a hand-authored `CLAUDE.md` while the load-bearing scaffold (`docs/coordinator-currency.yaml`, `cross-repo/inbox/`) never ran. Check BOTH for presence.
-
- - **Tracker exists AND both markers present:** the scaffold is genuinely complete. This skill becomes a health check — verify the tracker format matches the standard template, flag deviations, and skip to Phase 4 (REPORT).
- - **Tracker exists but either marker is absent:** the repo is only partially onboarded. Do NOT skip to Phase 4 — proceed through Phase 2/Phase 3 scaffolding as normal to fill the gap. This is safe: every Phase 3 helper is idempotent / no-clobber, so re-running scaffolding against a partially-onboarded repo only creates what's missing and never overwrites the existing tracker or `CLAUDE.md`.
-
- **Global detection:** Check if `~/.claude/CLAUDE.md` exists. If yes, the generated CLAUDE.md will include an "extends global" reference. If not, the template is fully self-contained — no dependency on global config.
-
- **Repo classification (PM ask):** Check if `.gitignore` excludes session infrastructure directories (`tasks/`, `archive/`, `state/handoffs/`). Capture this as a hint string — do not make a decision from it:
-
- - 2+ of these are gitignored → hint = `_(detected: 2+ of 3 session dirs gitignored — looks like a distribution repo)_`
- - Fewer or none gitignored → hint = `_(detected: standard working-tree layout)_`
-
- Always ask the PM:
-
- > **Is this repo:**
- > - **(a) a working repo** — for active development, with session artifacts tracked
- > - **(b) a published artifact / template** — distributed for downstream consumers; no session infrastructure
- > - **(c) both** — a working repo that publishes itself as the artifact
- >
- > _(detected: {hint})_
-
- **Branch on the PM's answer:**
-
- - **(a)** → proceed to Phase 1.5 / Phase 2 unchanged. No injection.
- - **(b)** → STOP. Do not proceed to Phase 2. Report:
- > _"You answered (b) — distribution repo. Onboarding infrastructure doesn't belong here. Track work on this repo from your parent project's tracker instead."_
- - **(c)** → proceed exactly like (a), AND inject a one-line note in the generated CLAUDE.md (Phase 3a) and the generated tracker (Phase 3b):
- > _"This repo is published as its own working artifact — consumers see the full directory shape including `tasks/` and `archive/`."_
-
- Report what exists and what needs to be created before proceeding.
-
- **Project type short-circuit, `cross_platform` inference, the runtime marker scan, the derived-type rules, and `coordinator_whoami` availability** — read `residue/phase1-detection-details.md` before running Phase 1 against a repo you haven't onboarded before. Short version: `coordinator.local.md`'s `project_type` (if present) short-circuits Phase 2 question 2; cross-platform-ness is detected then offered, never auto-written; the runtime marker scan and derived-type rules feed the PM's Phase 2 prompt as advisory detection; and the `coordinator_whoami` package is probed and installed idempotently so the Phase 4 binding probe works.
-
- ### Phase 1.5: INVESTIGATE — Read substrate, draft proposals
-
- Skip when Phase 1 found a genuinely empty repo (no README, no CONTRIBUTING, no top-level manifest).
-
- **Substrate-first onboarding.** Read the project's accumulated institutional memory before asking the PM cold: `README.md`, `CLAUDE.md`, `state/lessons/`, `state/improvement-queue/` if present (1.5a); most-recent 5 handoffs for stack/tooling clues if `state/handoffs/` exists (1.5b); sibling `CLAUDE.md` files for stack-shared conventions via the central state repo-registry (resolved via `coordinator-state-root.py --central`'s `<central-state>/repo-registry.md`, claude-klabauter-resident) `stack_tags` (1.5c). Output: a 5–10 line substrate snapshot. Cold-ask is the fallback when substrate is empty.
-
- **Roadmap orientation (run immediately after the substrate snapshot):** Query the completed archive for recent roadmap items — especially valuable when joining cold. Resolve the claude-klabauter root the same way the rest of this skill does (`REPO_CLAUDE_KLABAUTER` / `CLAUDE_KLABAUTER_ROOT` / the machine-local registry pointer; fail loud with remediation if unresolved), then invoke `<claude-klabauter-root>/coordinator/bin/lib/records_query.py completion "nature=roadmap" markdown-list 10 --sort "-loe.tshirt" --since "90d"` via `${COORDINATOR_PYTHON:-python3}`.
-
- Render under `#### Recent roadmap (last 90d, top-10 by size)` in the Phase 4 REPORT — count-always, so `(none)` is expected and rendered explicitly on new repos, never omitted. Otherwise:
-
- 1. Read top-level `README.md` / `README.rst` / `README.txt` if present.
- 2. Read `CONTRIBUTING.md` if present.
- 3. Read top-level manifests: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `*.uplugin`, `*.uproject`, etc. — whichever exist.
- 4. Skim recent commit subjects: `git log --oneline -20`.
-
- Draft proposals from what you read:
-
- - **Project name** — from README H1 or repo directory name.
- - **Project type + subtypes** — from manifest signals + README role description, reconciled with Phase 1 runtime-marker output. If proposal differs from `detected_type`, surface both with proposal winning and emit:
-
- > *Detected stack suggests `{detected_type}`. README/manifests suggest `{proposed_type}`. Going with `{proposed_type}` — confirm or override.*
- - **Initial workstreams (1-3)** — derived from README "what this does" + recent commit subjects + any "Roadmap" / "TODO" / "Status" sections. If the repo names sibling repos (path on disk, GitHub URL, or "split" / "addon" / "upstream" / "downstream" language), capture each as `peer_repo_candidates`.
-
- Present proposals to the PM for ratification:
-
- > Before I scaffold, here's what I found:
- >
- > **Project name:** {proposed}
- > **Project type:** {proposed}{, subtypes: [...] if any}
- > **Workstreams (proposed):**
- > 1. {WS1} — {2-3 deliverables}
- > 2. {WS2} — {...}
- >
- > **Sibling repos referenced:** {list with file:line citations from README/CONTRIBUTING}
- >
- > Ratify, correct, or say "go cold" to skip this and ask from scratch.
-
- On ratification: skip Phase 2's name + workstreams questions; only ask if PM corrected something or said "go cold."
-
- On peer-repo presence: ask once whether to dispatch parallel Explore scouts (recommended). If yes, dispatch each with: *"Read README, CONTRIBUTING, and recent commits. Identify shared schemas, integration contracts, and shipped vs in-flight work relevant to {this repo's name}. Reply with file:line citations."* Wait for results before drafting tracker workstreams.
-
- ### Phase 2: ASK — PM Input
-
- **Skip questions Phase 1.5 already ratified. Phase 1.5 may have already pinned project name and/or workstreams; only ask the questions whose answers are still missing.** **If `coordinator.local.md` was found in Phase 1**, skip question 2 — project type already pinned. Ask:
-
- > **1. Project name** — short name (e.g., "example-repo MVP", "example-sim-repo")
- > **2. Initial workstreams** (1-3) — name, 2-3 deliverables, optional deps/blockers. Say "stubs" for placeholders.
-
- **If `coordinator.local.md` was NOT found** (cold-ask path), present all three:
-
- > **1. Project name** — short name (e.g., "example-repo MVP", "example-sim-repo")
- > _(detected stack: <one-line summary>)_
- > **2. Project type:**
- > - `game-dev` — Game development (adds the Game Dev Reviewer reviewer, game-dev domain agents)
- > - `web-dev` — Web frameworks (adds the Front-End Reviewer for front-end review, the UX Reviewer for UX)
- > - `data-science` — Notebooks, pipelines (adds the Data Science Reviewer reviewer)
- > - `general` — Standard conventions only
- > **3. Initial workstreams** (1-3) — name, 2-3 deliverables, optional deps/blockers. Say "stubs" for placeholders.
-
- Wait for PM response before proceeding.
-
- ### Phase 3: GENERATE — Create Missing Files
+ ## Lanes
- Create only what's missing. Use the templates in this skill's `templates/` directory as the base.
+ 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:
- #### Lazy-creation discipline
+ | Lane | Data | Rationale |
+ |---|---|---|
+ | `new-project` | `lanes/new-project.yaml` | `residue/new-project.md` |
+ | `add-existing-project` | `lanes/add-existing-project.yaml` | `residue/add-existing-project.md` |
+ | `add-repo` | `lanes/add-repo.yaml` | `residue/add-repo.md` |
- Only scaffold files that have **meaningful day-1 content**. A placeholder header trains agents to ignore the directory; empty scaffolding has zero signal value. Create files and directories only when there is a real artifact to write.
+ 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`.
- A seed clears that bar — and is EAGER rather than LAZY — only when it satisfies **all four**
- conditions: it (a) names what writes into the directory, (b) names what event fills it, (c) names
- which skill owns it, and (d) carries NO frontmatter — schema-inert by construction, so it cannot
- trip the directory's own schema'd consumer (plan scanner, review-trail parser, handoff hook) on
- day one.
+ ## Flag contract
- **Phase 3 scaffold classification.** EAGER items (`CLAUDE.md`,
- `docs/README.md`, `docs/exec-summary.md`, `.gitignore` entry, post-commit hook, `cross-repo/`,
- `state/orientation_cache.md`, `state/handoffs/`, `docs/wiki/`, `docs/plans/`, `docs/research/`,
- `state/review-trail/`) are scaffolded now from `canonical-structure.yaml`'s `readme:` block.
- LAZY items are NOT created here — each is created on first use by its owner: `state/lessons/`
- (first session), `archive/completed/` (first ship). Full per-item audit and
- reasoning: wiki.
+ - **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."`
- **Phases 3a–3g — CLAUDE.md, docs/README.md, docs/exec-summary.md, and DIRECTORY.md.** Read `residue/phase3-core-docs.md` before scaffolding any of these; it carries the render-template invocations, the workstream-block formatting, and the exec-summary generator contract.
+ ## Prerequisites
- **Phases 3e–3f.6 — directories, .gitignore, and the git-hook installs.** Read `residue/phase3-infra-hooks.md` before running the `canonical-structure.yaml` scaffold or touching `.gitignore`, the post-commit hook, the session-id trailer hook, git config hardening, the meta-repo pre-commit gate, or the VS Code read-only guard.
+ - 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.
- **Phases 3h–3m and 3x — the currency stamp, orientation cache, extended substrate seeds, install manifest, strategic self-description skeleton, guard-regression tripwire tests, and fleet memo-destination registration.** Read `residue/phase3-substrate-seeds.md` before running any of these — they are ALWAYS-run, idempotent seeds, not optional offers, so skipping the reference is not the same as skipping the step. This is also where the extended substrate seeds land: `fast_test_cmd`/`full_test_cmd`, `state/health-ledger.md`, the RAG-index decision, and the fnm Node-version pin.
+ ## 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.cmd" 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.
- ### Phase 4: REPORT
+ **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.
- Read `residue/phase4-report-template.md` before writing this report — it carries the declared word-budget exemption (this is a once-per-repo walkthrough, not a recurring status report; do not shorten it), the `coordinator_whoami` status-row routing, the report-by-exception rule for `### Already Existed`, the full report template (`### Created` / `### Already Existed` / `### Needs Attention` / `### Recent Roadmap` / `### What's next`), and the coordinator-binding verification procedure.
+ **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.
- ### Sentinel — signal that setup just ran
+ **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.
- As the final action of `/coordinator:repo-setup`, 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`.
+ **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.
- The sentinel is single-shot: `/workstream-start`'s Preflight consumes it on first read (`rm -f`). It MUST be gitignored — see Phase 3f for the `.gitignore` line. Per-machine transient marker, never committed.
+ **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
- After Phase 3 scaffolding completes, offer to install coordinator-standard tripwire tests into the consuming repo's test suite — the Windows console-subprocess tripwire (offered), the widened `.py`/`.ps1` spawn tripwire (always installed, non-optional), and the cross-platform CI reference (offered when `cross_platform` is declared or inferred-and-confirmed). Read `residue/tripwire-installs.md` for the install steps, suppression-marker conventions, exemption mechanisms, and the language-aware install branch for the CI reference before running any of these — it carries no inline steps here, to avoid duplicating that file.
+ 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 tracker maintenance, in the same format.
+ - 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 Phase 3j extended-substrate seeds and the CLAUDE.md template architecture: 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
+ (`coordinator/pipelines/workday-start-internals.md:265`, `coordinator/docs/wiki/tiered-context-loading.md:57`).