collaborating
Skill56 starsChanged 8 months agoMITView on GitHub
Hackathon-native multiplayer collaboration mode -- brain-dump together, claim tasks across machines, flag decisions async. Drives the subcommands of /forge:collaborate.
- Reads credentials
- Installs packages
- Commits and pushes
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- backpropagationSkill
- brainstormingSkill
- caveman-internalSkill
- design-systemSkill
- executingSkill
- graphify-integrationSkill
- karpathy-guardrailsSkill
- planningSkill
- reviewingSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
31 rules. About 0 are common, 7 are distinctive, and 24 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
24
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 20
All brainstorm + consolidated + categories + questions + flags artifacts live under .forge/collab/ and are committed to git so late joiners …
- Very specific: line 26
Read the first word of the user's arguments.
- Very specific: line 38
If this throws because there is no origin remote, tell the user to add one and stop.
- Very specific: line 44
Ensure .forge/collab/ exists (mkdir -p .forge/collab).
- Very specific: line 46
Write .forge/collab/participant.json with {handle, session_id, started: <iso>}.
- Very specific: line 50
Write .forge/collab/.enabled as an empty marker file.
- Very specific: line 66
If it isn't, start throws "forge:collab realtime mode requires the ably peer dependency." Surface this check BEFORE calling …
- Very specific: line 73
If the probe fails, print the install command and stop with a non-zero exit unless the user also passed --polling.
- Very specific: line 90
Call lateJoinBootstrap with the transport and the current unblocked task IDs (read from .forge/plans/*-frontier.md):
- Distinctive: line 93
Do a git pull on the current branch.
- Distinctive: line 94
Read the plan frontier to list task IDs.
- Very specific: line 111
Ask 3-5 clarifying questions one at a time to draw out the user's ideas, priorities, and constraints.
- Distinctive: line 117
After each answer, summarize what you've captured.
- Very specific: line 119
When the user says accept (or "looks good", "write it", etc.), call the primitive via an inline Node script:
- Very specific: line 132
If a consolidated.md already exists, tell the user "Your input has joined the brainstorm.
- Very specific: line 144
If the call returns { held: true }: report the task count and categories breakdown (coding vs research vs decision).
- Very specific: line 146
If { held: false, holder }: tell the user "Consolidation in progress by <holder>.
- Distinctive: line 153
Call the primitives to build a status report:
- Very specific: line 157
Read .forge/collab/participant.json -> current handle
- Very specific: line 158
Read .forge/collab/categories.json if it exists -> task count
- Very specific: line 188
Wait for them to finish or run /forge:collaborate status to see what else is claimable."
- Very specific: line 195
Call listFlags('.forge/collab', { status }) with an optional status filter.
- Very specific: line 214
Read .forge/collab/participant.json for the handle.
- Very specific: line 226
If the transport has a disconnect() method, call it.
- Very specific: line 270
After any mutation, print a short summary of the actions array so the user knows exactly what changed.
- Distinctive: line 273
Never auto-apply without prompting.
- Very specific: line 283
Never bypass the consolidation lease: Every write to consolidated.md or categories.json must go through writeConsolidatedUnderLease.
- Very specific: line 286
Always inherit push behavior from
.forge/config.json: Use gatedPush when pushing from this skill, never a raw git push. - Very specific: line 288
Never broadcast a targeted message: When routing a question or flag notification, check that routeToParticipant returned a specific handle …
- Distinctive: line 296
If the user's intent is ambiguous, ask one clarifying question, not three.
- Distinctive: line 298
Always print a short summary at the end of each subcommand so the user knows what actually happened.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Collaborating Skill
You are driving /forge:collaborate. The primitives live in
scripts/forge-collab.cjs (exported by require into a local Node script
or invoked via node -e). This skill translates user intent into calls
against those primitives, honoring the invariants from spec-collab:
- Session ID is derived from
git remote get-url origin; all participants in the same repo auto-join the same session. - During the
executingphase, AI decisions never block humans: they become flags that humans can review and override async. - Writes to shared coordination state (consolidated.md, categories.json)
are gated by a short-lived
consolidationlease to prevent concurrent overwrites. - All brainstorm + consolidated + categories + questions + flags
artifacts live under
.forge/collab/and are committed to git so late joiners get full context viagit pull.
Subcommand Dispatch
Read the first word of the user's arguments. Route to the matching phase
below. If no subcommand is given, default to status.
start -- initialize a session
- Derive the session ID by calling
sessionIdFromOrigin()via a small inline Node script:
If this throws because there is nonode -e "console.log(require('./scripts/forge-collab.cjs').sessionIdFromOrigin())"originremote, tell the user to add one and stop. - Resolve the participant handle: prefer
gh api user --jq .login, fall back togit config user.email, finally$USER. - Ensure
.forge/collab/exists (mkdir -p .forge/collab). - Write
.forge/collab/participant.jsonwith{handle, session_id, started: <iso>}. Write this FIRST; it is the heavy artifact that holds the session metadata. - Write
.forge/collab/.enabledas an empty marker file. This MUST be the final filesystem action; it is the atomic signal that collab mode is fully on. Use thewriteEnabledMarkerprimitive:
Invariant: ifnode -e "require('./scripts/forge-collab.cjs').writeEnabledMarker('.forge')"startcrashes between step 4 and step 5, crash recovery will classify the state asstale_participantand offer a reset. If it crashes before step 4 there is nothing to recover. Do not reorder. - Resolve the transport mode. Call
selectTransportModewithprocess.envand any--pollingflag the user passed. Report:ably: "Realtime transport will use Ably (ABLY_KEY detected)." Prerequisite (forge-self-fixes-2 R013): theablynpm package is declared an OPTIONAL peerDependency in the pluginpackage.jsonand must be installed beforecreateAblyTransportwill succeed. If it isn't,startthrows "forge:collab realtime mode requires theablypeer dependency." Surface this check BEFORE callingcreateTransport('ably', ...):
If the probe fails, print the install command and stop with a non-zero exit unless the user also passednode -e "require.resolve('ably')" 2>/dev/null \ || echo 'Run: npm install ably (or pass --polling to skip realtime)'--polling.polling: "Zero-setup mode via git polling on forge/collab-state branch every ~2.5s." No install needed. The pull target branch is auto-resolved per R011 (origin/HEAD → upstream → current branch →mainfallback); no hardcodedmainassumption.setup-required: print the setup guide returned byrenderSetupGuide()and exit (unless--pollingwas passed).
- Report the session code (the full 12-hex session ID) and tell the user to share it out-of-band with teammates (though strictly speaking any teammate with the repo will derive the same code automatically).
join -- sync with an existing session
Call lateJoinBootstrap with the transport and the current unblocked
task IDs (read from .forge/plans/*-frontier.md):
- Do a git pull on the current branch.
- Read the plan frontier to list task IDs.
- Call
lateJoinBootstrap({ transport, unblockedTaskIds: ids, cwd })to get the list of claimable task IDs. - Print a tidy status: how many tasks total, how many already claimed by others, how many available for this joiner.
brainstorm -- chat-mode brain-dump
This is the interactive loop that replaces the single-user brainstorm. Runs in place in the current session.
- Greet: "Starting a collaborative brain-dump. I'll ask questions to
help you structure your thoughts. When you're happy, say 'accept' and
I'll write your refined input to
.forge/collab/brainstorm/." - Ask 3-5 clarifying questions one at a time to draw out the user's
ideas, priorities, and constraints. Match the tone of
/forge:brainstormbut scope to the user's own section -- don't try to design the whole product; the AI-driven consolidation across users will merge everyone's ideas later. - After each answer, summarize what you've captured.
- When the user says
accept(or "looks good", "write it", etc.), call the primitive via an inline Node script:
(Or just usenode -e "const c = require('./scripts/forge-collab.cjs'); \ const p = c.brainstormDump('.forge/collab', process.env.FORGE_HANDLE, \ process.env.FORGE_BRAIN_DUMP); console.log(p);"Writeagainst.forge/collab/brainstorm/inputs-<handle>.mddirectly with the standard frontmatter -- either path is equivalent.) - Stage + commit + push the new file per the project's auto_push
setting (read via
readAutoPushConfig('.forge')). - If a consolidated.md already exists, tell the user "Your input has
joined the brainstorm. When all contributors are in, run
/forge:collaborate consolidateto merge everyone's input."
consolidate -- run consolidation + categorization under lease
Optional subcommand for whoever takes the consolidation step. Calls
writeConsolidatedUnderLease(transport, '.forge/collab', handle, inputs,
opts) where inputs is the result of readAllInputs('.forge/collab').
- If the call returns
{ held: true }: report the task count and categories breakdown (coding vs research vs decision). - If
{ held: false, holder }: tell the user "Consolidation in progress by<holder>. Try again in a moment."
status -- show session state
Call the primitives to build a status report:
listActiveTaskClaims(transport, {now: Date.now()})-> active claimslistFlags('.forge/collab', {status: 'open'})-> open flags- Read
.forge/collab/participant.json-> current handle - Read
.forge/collab/categories.jsonif it exists -> task count
Print a tidy summary:
Session: <sessionId>
Mode: ably | polling
You: <handle>
Claims:
T004 daniel (expires in 85s)
T007 lucas (expires in 43s)
Open flags (3):
F0123abc T005 "use redis pubsub" (daniel)
F0456def T008 "retry with backoff" (sarah)
Next claimable:
T009, T011, T012claim <taskId> -- explicit claim
Call claimTask(transport, taskId, handle, { ttlSeconds: 120 }).
Report the outcome:
{ acquired: true }: "Reserved T004 for you. Lease expires in 120s; heartbeats auto-refresh while you work."{ acquired: false, holder }: "T004 is already held by<holder>. Wait for them to finish or run/forge:collaborate statusto see what else is claimable."
flags -- list forward-motion flags
Call listFlags('.forge/collab', { status }) with an optional status
filter. Print a table.
override <flagId> <new-decision> -- override an AI decision
Call overrideFlag('.forge/collab', flagId, newDecision, { author: handle }).
{ overridden: true, previousDecision }: confirm, note previous decision, and tell the user that dependent tasks will be re-triggered on the next execute iteration.{ overridden: false, reason }: surface the reason (not_found,already_overridden,malformed) so the user can diagnose.
leave -- release claims and disconnect
- Read
.forge/collab/participant.jsonfor the handle. - Delete
.forge/collab/.enabledFIRST viaremoveEnabledMarker:
This is the atomic "collab mode is off" flip. Any crash after this point is harmless — the marker is gone, the executor guard returns single-user, andnode -e "require('./scripts/forge-collab.cjs').removeEnabledMarker('.forge')"participant.jsonlingering is classified asstale_participantby/forge:collaborate recover. - List all active claims via
listActiveTaskClaims(transport)and filter forclaimant === handle. - For each such claim, call
releaseTaskClaim(transport, taskId, handle). - If the transport has a
disconnect()method, call it. - Delete
.forge/collab/participant.json. - Report: "Released
<N>claims. Disconnected from session."
Invariant: the delete order is .enabled -> claims -> disconnect ->
participant.json. Never remove participant.json before .enabled,
and never skip the .enabled removal. A partial leave that only strips
.enabled still leaves the executor in single-user mode, which is the
safe fallback.
recover -- repair a stale collab session
Scan .forge/collab/ for inconsistent marker state and offer the right
remedy for each case. This is the recovery path for crashes during
start or leave.
- Run the classifier:
node -e "const c=require('./scripts/forge-collab.cjs');console.log(JSON.stringify(c.classifyCollabState('.forge',{cwd:process.cwd()})))" - Interpret the
statusfield:inactive: both markers absent. Nothing to do; report "No collab session found."healthy: both markers present and session id matches current origin. Report "Collab session is running normally; no recovery needed."stale_participant:participant.jsonpresent,.enabledmissing. Diagnosis: start crashed before the marker landed, or leave aborted partway through. Prompt the user: "Reset the stale session?" On confirmation, callrecoverCollabState('.forge', { apply: true })which deletesparticipant.json(and any.enabledremnant).stale_enabled:.enabledpresent,participant.jsonmissing. Diagnosis: leave crashed afterparticipant.jsonwas deleted. Prompt "Repair participant from git config?" On confirmation, callrecoverCollabState('.forge', { apply: true })which re-derives the participant and writes a freshparticipant.jsonwith the current session id.session_mismatch: both markers present butparticipant.session_iddiffers from the origin-derived id (repo was re-pointed). Prompt "Migrate participant to the new session?" On confirmation, callrecoverCollabState('.forge', { apply: true })which rewrites the session id and records themigrated_fromvalue.
- After any mutation, print a short summary of the
actionsarray so the user knows exactly what changed.
Never auto-apply without prompting. Recovery is destructive to session state; the skill must show the diagnosis and remedy first.
Invariants to Respect
- Never write flag files outside the executing phase. The primitive
enforces this, but the skill should not even try to call
writeForwardMotionFlagin brainstorm or plan contexts. - Never bypass the consolidation lease. Every write to
consolidated.mdorcategories.jsonmust go throughwriteConsolidatedUnderLease. - Always inherit push behavior from
.forge/config.json. UsegatedPushwhen pushing from this skill, never a rawgit push. - Never broadcast a targeted message. When routing a question or flag
notification, check that
routeToParticipantreturned a specific handle before callingsendTargeted. Fall back topublishonly when the routing explicitly returned"broadcast".
Key Principles
- One subcommand per invocation. Don't chain.
- If the user's intent is ambiguous, ask one clarifying question, not three.
- Always print a short summary at the end of each subcommand so the user knows what actually happened.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

