wotai-dev/woterclip/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:

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)

1. 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 ``

1. 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/

1. 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

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.

1. Otherwise ask the user: overwrite (fresh start), merge (add missing personas only), or cancel.
2. For merge: only create persona directories and labels that don't exist yet.
3. For overwrite: back up existing config to config.yaml.bak before writing.