ScuttleBot

scuttlebot / skills / project-setup / SKILL.md

Source Rendered

Blame History Raw 124 lines

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

ScuttleBot

Keyboard Shortcuts