/init

name: woterclip-init
description: This skill should be used when the user asks to "initialize woterclip", "set up woterclip", "woterclip init", "configure woterclip for this repo", or runs the /woterclip-init command. Scaffolds a repo with WoterClip config, persona directories, and GitHub labels.
version: 0.1.0

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 `v