sjames / sjames/syscribe

feat(planning): claim/ownership markers on PlanningItem for concurrent multi-agent work

Open
#115 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
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

  • claim sets claimedBy/claimedAt; fails clearly if the item is already claimed by someone else
  • release clears both fields regardless of current status
  • A new warning fires when two claimed/in_progress PlanningItems overlap by achieves: or evidence.path:
  • claimedBy is visible in list PlanningItem --json and in show <id>
  • Claiming an already-done PlanningItem is rejected (nothing to claim)

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.