Waves Init

waves-init — workspace initialization

Sets up a workspace as: a workspace root with CLAUDE.md, plans/00-master.md, plans/notes/, docs/, and repos (clones or worktrees) one level down.

Preamble (run first)

"${CLAUDE_PLUGIN_ROOT}/scripts/waves-detect"

Step 1 — determine mode

• New workspace: no WORKSPACE_ROOT detected, or user names a fresh task.
• Refresh: workspace exists — re-scan repos, update the repo table/rule index in its CLAUDE.md, flag drift (worktree copies newer than primaries), leave the rest.
• Repo-only: user is inside a single repo without a workspace — offer a starter repo CLAUDE.md (see Step 5) instead of a workspace.

Step 2 — scan repos (before asking anything)

For each repo that will be part of the workspace:

• git remote get-url origin, current branch, worktree-or-clone (worktrees share object stores with primaries — never delete the primary checkout).
• Does it have CLAUDE.md / .claude/rules/? List the rule files. Do not copy their content — the workspace CLAUDE.md references them (reference, don't duplicate).
• Note repos with zero agent rules as a gap (Step 5 offers to fix it).

Step 3 — the interview (GATE: no files are generated before this is answered)

Ask via AskUserQuestion as decision briefs — ${CLAUDE_PLUGIN_ROOT}/references/decision-briefs.md has the format (batch up to 4 per call; multiple rounds are fine; one recommended option per question, honest tradeoffs per option). Never substitute a guess for an unanswered question. Minimum set:

1. Task identity: canonical task id + tracker URL, title.
2. Goal + deliverable: one paragraph; what does "done" look like?
3. Repos involved: which repos, worktree or fresh clone, base branches.
4. Scope fence: what is explicitly OUT of scope (prevents drift).
5. Deploy/access reality: deploy access for this task? credentials/API keys status per platform? secrets location (outside every repo)?
6. Coordinator override: config defaults (coordinator, blurb language, task cap) apply unless this task differs.

Anything the user can't answer yet goes into the master plan's Open questions section with a proposed default + who must confirm — not into silent assumptions.

Step 4 — generate

From ${CLAUDE_PLUGIN_ROOT}/templates/:

• workspace-CLAUDE.md.tmpl → <root>/CLAUDE.md — fill placeholders from the interview + scan; repo table lists each repo's own rule files as "read before touching code"; include the non-negotiable footguns for the involved repos (at most 6 bullets).
• 00-master.md.tmpl → <root>/plans/00-master.md — locked decisions from the interview; open questions from Step 3; empty wave table.
• The template's ## Skill routing section ships as-is — it's what makes every future session in this workspace reach for the waves skills and decision briefs without being told. In refresh or repo-only mode, when an existing CLAUDE.md has no ## Skill routing section, offer (ask, don't force) to append it from the template.
• mkdir -p <root>/plans/notes <root>/docs.
• If worktrees are needed: create them from the primaries (git worktree add ../<ws>/<repo> -b feature/<topic> origin/<base>), naming branch base = PR target.

Do NOT create any other md files (docs rule: no new docs without asking).

Step 5 — repos with no agent rules

Offer (don't force) a starter repo CLAUDE.md: stack + build/test commands (verified by reading the repo, not guessed), branch/PR conventions, and a pointer to the framework conventions. Keep it under a page; the repo's engineers own it from then on.

Step 6 — report

Summarize what was created, the rule files each agent must read per repo, open questions awaiting confirmation, and suggest /waves-plan as the next step.