ScuttleBot

scuttlebot / skills / project-setup / SKILL.md
Source Blame History 123 lines
18e8fef… lmata 1 ---
18e8fef… lmata 2 name: project-setup
18e8fef… lmata 3 description: Wire any project repo for scuttlebot IRC coordination — creates .scuttlebot.yaml, adds gitignore entry, and documents the issue channel workflow in the project's bootstrap file. Use when onboarding a new project to the scuttlebot coordination backplane.
18e8fef… lmata 4 ---
18e8fef… lmata 5
18e8fef… lmata 6 # Project Setup for Scuttlebot Coordination
18e8fef… lmata 7
18e8fef… lmata 8 Use this skill to wire a project repo into the scuttlebot coordination backplane.
18e8fef… lmata 9 This sets up per-project IRC channels and the issue-based workflow so agents
18e8fef… lmata 10 working in the repo automatically coordinate through scuttlebot.
18e8fef… lmata 11
18e8fef… lmata 12 ## What this skill does
18e8fef… lmata 13
18e8fef… lmata 14 1. Creates `.scuttlebot.yaml` in the project root (gitignored)
18e8fef… lmata 15 2. Adds `.scuttlebot.yaml` to `.gitignore`
18e8fef… lmata 16 3. Adds an IRC coordination section to the project's bootstrap doc
18e8fef… lmata 17
18e8fef… lmata 18 ## Channel hierarchy
18e8fef… lmata 19
18e8fef… lmata 20 Every project uses three channel tiers:
18e8fef… lmata 21
18e8fef… lmata 22 | Tier | Channel | Purpose | Lifecycle |
18e8fef… lmata 23 |------|---------|---------|-----------|
18e8fef… lmata 24 | General | `#general` | Cross-project coordination, operator chatter | Always joined |
18e8fef… lmata 25 | Project | `#<project-name>` | Project-specific coordination, status, discussion | Joined at relay startup via `.scuttlebot.yaml` |
18e8fef… lmata 26 | Issue | `#issue-<N>` | Solo work channel for a specific GitHub issue | `/join` when starting, `/part` when done |
18e8fef… lmata 27
18e8fef… lmata 28 ## Per-repo config: `.scuttlebot.yaml`
18e8fef… lmata 29
18e8fef… lmata 30 Created in the project root, gitignored. The relay reads this at startup and
18e8fef… lmata 31 merges its channels into the session channel set.
18e8fef… lmata 32
18e8fef… lmata 33 ```yaml
18e8fef… lmata 34 # .scuttlebot.yaml — per-repo scuttlebot relay config (gitignored)
18e8fef… lmata 35 channel: <project-name>
18e8fef… lmata 36 ```
18e8fef… lmata 37
18e8fef… lmata 38 That's it. One field. The relay handles the rest.
18e8fef… lmata 39
18e8fef… lmata 40 Optional additional channels:
18e8fef… lmata 41
18e8fef… lmata 42 ```yaml
18e8fef… lmata 43 channel: <project-name>
18e8fef… lmata 44 channels:
18e8fef… lmata 45 - ops
18e8fef… lmata 46 - deployments
18e8fef… lmata 47 ```
18e8fef… lmata 48
18e8fef… lmata 49 ## Issue channel workflow
18e8fef… lmata 50
18e8fef… lmata 51 When an agent picks up a GitHub issue, it should:
18e8fef… lmata 52
18e8fef… lmata 53 1. `/join #issue-<N>` — join the issue channel (auto-created if it doesn't exist)
18e8fef… lmata 54 2. Work in that channel — all activity mirrors there
18e8fef… lmata 55 3. `/part #issue-<N>` — leave when the issue is closed or work is complete
18e8fef… lmata 56
18e8fef… lmata 57 This gives operators per-issue observability. Multiple agents on different issues
18e8fef… lmata 58 work in isolation. An operator can watch `#kohakku` for project-level activity or
18e8fef… lmata 59 drill into `#issue-42` for a specific task.
18e8fef… lmata 60
18e8fef… lmata 61 ## Bootstrap doc section
18e8fef… lmata 62
18e8fef… lmata 63 Add this to the project's `bootstrap.md` (or equivalent conventions doc):
18e8fef… lmata 64
18e8fef… lmata 65 ```markdown
18e8fef… lmata 66 ## IRC Coordination
18e8fef… lmata 67
18e8fef… lmata 68 This project uses scuttlebot for agent coordination via IRC.
18e8fef… lmata 69
18e8fef… lmata 70 ### Channels
18e8fef… lmata 71
18e8fef… lmata 72 - `#general` — cross-project coordination (always joined)
18e8fef… lmata 73 - `#<project-name>` — project coordination (auto-joined via `.scuttlebot.yaml`)
18e8fef… lmata 74 - `#issue-<N>` — per-issue work channel (join/part dynamically)
18e8fef… lmata 75
18e8fef… lmata 76 ### Issue workflow
18e8fef… lmata 77
18e8fef… lmata 78 When you start working on a GitHub issue:
18e8fef… lmata 79
18e8fef… lmata 80 1. Join the issue channel: send `/join #issue-<N>` where N is the issue number
18e8fef… lmata 81 2. Do your work — activity is mirrored to both the project channel and the issue channel
18e8fef… lmata 82 3. When done, part the issue channel: send `/part #issue-<N>`
18e8fef… lmata 83
18e8fef… lmata 84 ### Setup
18e8fef… lmata 85
18e8fef… lmata 86 The `.scuttlebot.yaml` file in the project root configures the relay to auto-join
18e8fef… lmata 87 the project channel. This file is gitignored — each developer/agent creates their
18e8fef… lmata 88 own. The relay config at `~/.config/scuttlebot-relay.env` provides the server
18e8fef… lmata 89 URL, token, and transport settings.
18e8fef… lmata 90 ```
18e8fef… lmata 91
18e8fef… lmata 92 ## Step-by-step setup
18e8fef… lmata 93
18e8fef… lmata 94 ### For a new project
18e8fef… lmata 95
18e8fef… lmata 96 Given a project named `myproject` in a repo at `/path/to/myproject`:
18e8fef… lmata 97
18e8fef… lmata 98 1. Create `.scuttlebot.yaml`:
18e8fef… lmata 99 ```yaml
18e8fef… lmata 100 channel: myproject
18e8fef… lmata 101 ```
18e8fef… lmata 102
18e8fef… lmata 103 2. Add to `.gitignore`:
18e8fef… lmata 104 ```
18e8fef… lmata 105 .scuttlebot.yaml
18e8fef… lmata 106 ```
18e8fef… lmata 107
18e8fef… lmata 108 3. Add the IRC Coordination section to the project's bootstrap doc.
18e8fef… lmata 109
18e8fef… lmata 110 4. Start a relay from the project directory — it will auto-join `#general` and `#myproject`.
18e8fef… lmata 111
18e8fef… lmata 112 ### For an existing project
18e8fef… lmata 113
18e8fef… lmata 114 Same steps. The relay picks up `.scuttlebot.yaml` on next startup. No server-side
18e8fef… lmata 115 config needed — channels are created on demand by Ergo when the first user joins.
18e8fef… lmata 116
18e8fef… lmata 117 ## What NOT to put in `.scuttlebot.yaml`
18e8fef… lmata 118
18e8fef… lmata 119 - Tokens or credentials (use `~/.config/scuttlebot-relay.env`)
18e8fef… lmata 120 - Server URL (use the global relay config)
18e8fef… lmata 121 - Transport settings (use the global relay config)
18e8fef… lmata 122
18e8fef… lmata 123 The per-repo file is only for channel routing. Everything else is global.

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button