Init

WoterClip Initialization

Initialize WoterClip in the current repository. This creates the .woterclip/ directory with config, persona templates, and corresponding GitHub labels.

Prerequisites

Before starting, verify the gh CLI is ready:

1. Run gh auth status — must exit 0 (installed and authenticated)
2. Run gh repo view --json nameWithOwner — must resolve (the current directory is a repo with a GitHub remote)
3. If either fails, stop and instruct the user:
   • Install: brew install gh (or the platform equivalent)
   • Authenticate: gh auth login
   • Run from a checkout whose origin points at GitHub
   • Re-run /woterclip-init

Initialization Procedure

Step 1: Gather GitHub Context

1. Run gh repo view --json nameWithOwner --jq .nameWithOwner to resolve the target repo
2. Run gh api user --jq .login to identify the authenticated user
3. Present findings and ask the user to confirm:
   • The repo whose issues drive the heartbeat (default: the current checkout's repo)
   • The Board user's GitHub login for @-mentions in comments (pre-filled from gh api user)

When the confirmed Board user equals the authenticated login (the common single-account setup), warn: GitHub does not notify a user of their own comments, so blocked-escalation @-mentions will not produce notifications — the Board should watch the repo or rely on /woterclip-status. A separate bot/machine account for gh auth avoids this.

Step 2: Choose Persona Preset

Ask the user which persona set to scaffold:

Preset	Personas Created
engineering (default)	Orchestrator, CEO, Backend, Frontend
full	Orchestrator, CEO, Backend, Frontend, Infra, QA
minimal	Orchestrator, CEO only
custom	Orchestrator, CEO + user-specified personas

For "custom", ask the user to name each persona and its GitHub label.

Step 3: Create GitHub Labels

GitHub labels are flat (no groups). Create the WoterClip labels on the target repo:

1. Check what already exists: gh label list --repo <owner/name> --limit 200
2. Create each missing label with gh label create <name> --repo <owner/name> --color <hex> --description "<desc>":
   • agent-working (color 0E8A16) — state label for active work
   • agent-blocked (color B60205) — state label for blocked issues
   • in-progress and in-review — status labels the heartbeat writes on state transitions
   • priority:high and priority:low — priority labels the Orchestrator writes when bumping sub-issues
   • One label per persona that has a non-null label (e.g., backend 1D76DB, frontend 5319E7)
3. Skip creation for any label that already exists (matching on name).

All labels above are created unconditionally — the heartbeat and Orchestrator write them (gh issue edit --add-label fails when a label doesn't exist on the repo). Only the human-managed backlog and todo status labels are optional — offer them, but the heartbeat treats unlabeled open issues as eligible without them (see ${CLAUDE_PLUGIN_ROOT}/references/status-mapping.md).

Step 4: Scaffold Config & Personas

1. Create the directory structure:

   .woterclip/
   ├── config.yaml
   └── personas/
       ├── orchestrator/
       │   ├── SOUL.md
       │   ├── TOOLS.md
       │   └── config.yaml
       ├── ceo/
       │   ├── SOUL.md
       │   ├── TOOLS.md
       │   └── config.yaml
       ├── backend/          (if selected)
       │   ├── SOUL.md
       │   ├── TOOLS.md
       │   └── config.yaml
       └── frontend/         (if selected)
           ├── SOUL.md
           ├── TOOLS.md
           └── config.yaml
   

2. Copy templates from the plugin's templates/ directory:

   • Read each template file from ${CLAUDE_PLUGIN_ROOT}/templates/
   • Replace {{USER_NAME}} with the Board user's GitHub login
   • Replace {{REPO}} with the target repo (owner/name)
   • Write to .woterclip/

3. Update config.yaml personas section to match the selected preset — remove entries for personas that weren't scaffolded.

Step 5: Offer Schedule Setup

Ask the user if they want to set up a recurring heartbeat:

• Yes, unattended → Suggest /schedule 30m /heartbeat. This is the default recommendation because it survives a closed session.
• Yes, while I'm working → Suggest /loop /heartbeat with no interval, which self-paces from what each beat finds but is in-session only.
• Not now → Explain they can run /heartbeat manually or set up a schedule later

The full trade-off, and the ~2h threshold for treating a quiet repo as stopped, are in ${CLAUDE_PLUGIN_ROOT}/references/beat-economics.md § Scheduling Preconditions.

Step 6: Print Summary

Display what was created:

WoterClip initialized!

GitHub labels created on owner/name:
  ✓ agent-working
  ✓ agent-blocked
  ✓ backend
  ✓ frontend

Config: .woterclip/config.yaml
Personas:
  ✓ orchestrator → default (no label)
  ✓ ceo          → "ceo" label
  ✓ backend  → "backend" label
  ✓ frontend → "frontend" label

Next steps:
  1. Review .woterclip/config.yaml
  2. Customize persona SOUL.md files for your project
  3. Run /heartbeat or /schedule 30m /heartbeat

Error Handling

Error	Response
gh not installed or not authenticated	Stop. Print install/auth instructions (brew install gh, gh auth login).
No GitHub remote on the current repo	Stop. Ask user to run from a GitHub-hosted checkout or pass the repo explicitly.
Label creation fails	Log the error, continue with remaining labels, report at end.
.woterclip/ already exists	Check the config version FIRST (see Re-initialization & Migration below — a version: 1 config must migrate before any overwrite/merge/cancel choice). Then ask: overwrite, merge, or cancel. Default to merge (skip existing files).
Template file missing from plugin	Log warning, create a minimal placeholder, continue.

Re-initialization & Migration

If .woterclip/config.yaml already exists, read the config version first — before offering any overwrite/merge/cancel choice (a merge that "skips existing files" must never skip the migration):

1. Read the existing config version.
2. If version: 1 (Linear-era config), run the v1→v2 migration:
   • linear.user_name → ask the user for their GitHub login — a Linear display name is not a GitHub login; never guess. Pre-fill from gh api user --jq .login.
   • linear.team → discarded; github.repo comes from gh repo view (confirm with the user).
   • linear.project → discarded (no equivalent; GitHub milestones are out of scope).
   • labels.group → dropped (GitHub has no label groups; labels are flat).
   • labels.working / labels.blocked and the heartbeat section carry over unchanged.
   • Migrate every scaffolded persona config: in each .woterclip/personas/*/config.yaml, replace mcp__claude_ai_Linear in required_tools with gh (heartbeat step 5 now validates gh via gh auth status; a leftover Linear entry would auto-block every issue for that persona). Flag Linear-era TOOLS.md files for regeneration from the plugin templates.
   • Write version: 2. Back up the old config to config.yaml.bak first.
   • Create the GitHub labels (step 3) — Linear labels are not migrated automatically.
   • Post-migration check: re-parse the migrated config and confirm no required_tools entry anywhere under .woterclip/personas/ still references mcp__claude_ai_Linear.
3. Otherwise ask the user: overwrite (fresh start), merge (add missing personas only), or cancel.
4. For merge: only create persona directories and labels that don't exist yet.
5. For overwrite: back up existing config to config.yaml.bak before writing.