# Waves Init

> Initialize a workspace or repo for AI-agent work: scan repos, index their rules, run the mandatory scoping interview, generate workspace CLAUDE.md + plans/00-master.md. Use for a new task/workspace, when a repo has no agent instructions, or to refresh a stale workspace setup.

- Skill: `asunalabs/waves-init` (Agent Skill)
- Install (CLI): `npx skillmds@latest add asunalabs/waves-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/asunalabs/waves-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: asunalabs (https://skillmd.com/u/asunalabs)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/asunalabs/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)

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