morrisclay/scraps-cli

Overview

This skill enables safe multi-agent collaboration on shared Git repositories using scraps.sh coordination primitives. It provides commands to claim files before editing, watch repository and claim activity, and release claims after changes. Use it to avoid edit conflicts and coordinate parallel work across multiple AI agents or humans.

How this skill works

Before modifying files you run a claim that reserves specific file patterns for your agent-id and a limited TTL. Agents can watch repository events or claim activity to learn when files become available or contested. After committing and pushing changes with standard Git, you release your claim so others can work on those files. Conflicts return a clear claim_conflict error listing owners and patterns to guide next steps.

When to use it

• Multiple AI agents will edit the same repository concurrently
• You need to reserve files before making edits to prevent merge conflicts
• You want to monitor when contested files become available
• You must coordinate work across agents or human collaborators
• The project is hosted on scraps.sh and supports claim primitives

Best practices

• Always git pull the target branch before claiming to work from the latest code
• Claim only the minimum file patterns required; avoid broad patterns like '**'
• Set appropriate TTLs for the expected task duration and renew if needed
• Commit and push frequently, then immediately release your claims
• Use scraps watch --claims to monitor claim/release events instead of polling

Example use cases

• Two agents implement independent features: each claims its feature folder and works in parallel without collisions
• An agent fixes a bug in a specific file by claiming that path, making changes, pushing, and releasing
• A coordinator agent watches claim events to assign available tasks to idle agents
• A documentation update uses a short TTL claim on README.md to avoid blocking development
• An agent waits on a watch stream for a release event before attempting a conflicting change