feat(planning): claim/ownership markers on PlanningItem for concurrent multi-agent work
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 7
- Forks
- 1
- Avg merge
- 21m
- Merged PRs (30d)
- 2
Description
Summary
Add an optional claim/ownership mechanism for PlanningItem: a claimedBy:/claimedAt: field pair, a syscribe claim <PI-id> --by <agent-id> / syscribe release <PI-id> command, and a validation warning when two simultaneously-claimed in_progress PlanningItems have overlapping scope (shared achieves: requirement, or overlapping evidence.path: entries pointing at the same source file).
Motivation
Running several LLM agents concurrently against one spec+repo (each independently implementing a different PlanningItem in the background), the only thing preventing two agents from editing the same files at once was a rule I held in my own head and re-applied by hand every time: "never start a new agent whose file scope overlaps a currently-running one." That's a real, recurring coordination problem the moment more than one agent works the same model at once, and right now syscribe has no visibility into "is anything already being worked" — an orchestrating process has to infer it from git status, running-process lists, or its own memory of what it dispatched.
Proposed shape
# PlanningItem frontmatter
status: in_progress
claimedBy: agent-session-01VRUS...
claimedAt: 2026-09-12T08:00:00Z
syscribe claim <PI-id> --by <agent-id> # sets claimedBy/claimedAt, errors if already claimed
syscribe release <PI-id> # clears claimedBy/claimedAt (e.g. on completion or handoff)
syscribe list PlanningItem --status in_progress --json # already exposes status; would also expose claimedBy
Validation addition: a warning when two in_progress (or explicitly claimed) PlanningItems share a member of achieves:, or have evidence.path: entries resolving to the same repo file — the two concrete shapes of "these two agents are about to step on each other" that came up in practice.
This is advisory, not a lock in the filesystem sense — the value is making the question answerable ("is anyone already on this?") without an orchestrator having to reconstruct it from side channels every time.
Acceptance criteria
-
claimsetsclaimedBy/claimedAt; fails clearly if the item is already claimed by someone else -
releaseclears both fields regardless of currentstatus - A new warning fires when two claimed/
in_progressPlanningItems overlap byachieves:orevidence.path: -
claimedByis visible inlist PlanningItem --jsonand inshow <id> - Claiming an already-
donePlanningItem is rejected (nothing to claim)
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the PlanningItem representation and the existing command handlers for claim-like mutations, list/show output, and validation. Trace how frontmatter fields are parsed and serialized, then add tests covering claim, release, rejection of done or already-claimed items, overlap warnings, and JSON visibility. Done means all listed acceptance criteria pass.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- cli, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100