diff --git a/AGENTS.md b/AGENTS.md index 0f3a5c55..dba647c9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -240,6 +240,42 @@ When you create a PR or start work, leave a clear signal: - **PR title prefix**: Use a descriptive prefix like `[nostr-core]`, `[playback]`, `[ui]`, `[ci]` so the scope is visible at a glance. - **PR description**: Include a "Files Modified" section listing the key files touched, so other agents can quickly detect conflicts. +### Task Claiming Protocol (Draft PR Lock) + +To prevent multiple agents from working on the same task simultaneously, every agent must **check for and create a draft PR** before starting work. The draft PR acts as a distributed lock visible to all agents across all platforms (Claude Code, Codex, Jules). + +**Before starting any task:** + +1. **Check for existing claims.** Search for open or draft PRs matching the task: + ``` + gh pr list --state open --search "" + ``` + If a matching PR exists (open or draft), **skip the task** — another agent is already working on it. + +2. **Claim the task.** If no matching PR exists: + a. Create your working branch. + b. Make a minimal initial commit (e.g., update `CONTEXT.md` with the task scope). + c. Push the branch and immediately open a **draft PR**: + ``` + gh pr create --draft \ + --title "[] : " \ + --body "Claimed by at . Work in progress." + ``` + d. Only after the draft PR is successfully created, begin the actual work. + +3. **Handle race conditions.** After creating your draft PR, re-check for duplicates: + ``` + gh pr list --state open --search "" + ``` + If you find another agent's PR for the same task that was created **before** yours, close your PR with `gh pr close ` and skip the task. + +4. **Convert to ready when done.** When the task is complete and verified, mark the draft PR as ready for review: + ``` + gh pr ready + ``` + +**Scheduler agents:** Daily and weekly scheduler agents must follow this protocol in addition to their CSV-based rotation logic. The draft PR check happens _after_ determining the next task but _before_ executing it. See the scheduler prompts for the specific implementation steps. + ### Currently In-Flight Work diff --git a/docs/agents/prompts/daily-scheduler.md b/docs/agents/prompts/daily-scheduler.md index efee08e5..65dacad9 100644 --- a/docs/agents/prompts/daily-scheduler.md +++ b/docs/agents/prompts/daily-scheduler.md @@ -54,6 +54,43 @@ Read both `AGENTS.md` and `CLAUDE.md` before executing any task. --- +## Step 1.5 — Claim the Task (Prevent Duplicate Work) + +Before executing the selected task, verify that no other agent is already working on it. Multiple agents may be running simultaneously across different platforms (Claude Code, Codex, Jules), so this check is **mandatory**. + +1. **Check for existing claims.** Search for open or draft PRs matching this agent: + ``` + gh pr list --state open --search "" + ``` + For example, if the selected agent is `audit-agent`, run: + ``` + gh pr list --state open --search "audit-agent" + ``` + If any matching PR exists (open or draft), this task is **already claimed**. + +2. **If already claimed:** Skip to the **next agent** in the roster (following the same alphabetical wrap-around rule from Step 1). Repeat this claim check for the new agent. If you cycle through the entire roster and all agents are claimed, log as `failed` with summary `"All roster tasks currently claimed by other agents"` and stop. + +3. **If unclaimed:** Claim the task immediately by creating a draft PR: + a. Create your working branch. + b. Make a minimal initial commit (e.g., update `CONTEXT.md` with the task scope). + c. Push the branch and open a **draft PR**: + ``` + gh pr create --draft \ + --title "[daily] : " \ + --body "Claimed by daily scheduler at $(date -u +%Y-%m-%dT%H:%M:%SZ). Work in progress." + ``` + d. Verify the draft PR was created successfully before proceeding to Step 2. + +4. **Race condition check:** After creating the draft PR, re-check: + ``` + gh pr list --state open --search "" + ``` + If you see another PR for this agent that was created *before* yours (by a different agent instance), close your PR with `gh pr close ` and skip to the next agent. + +**Important:** The draft PR is your lock. Do not skip this step. It prevents other agents on different platforms from picking up the same task. + +--- + ## Step 2 — Execute the Task 1. Read the selected agent's prompt file from `/docs/agents/prompts/daily/`. diff --git a/docs/agents/prompts/weekly-scheduler.md b/docs/agents/prompts/weekly-scheduler.md index 9af0fefb..9ccce604 100644 --- a/docs/agents/prompts/weekly-scheduler.md +++ b/docs/agents/prompts/weekly-scheduler.md @@ -49,6 +49,43 @@ Read both `AGENTS.md` and `CLAUDE.md` before executing any task. --- +## Step 1.5 — Claim the Task (Prevent Duplicate Work) + +Before executing the selected task, verify that no other agent is already working on it. Multiple agents may be running simultaneously across different platforms (Claude Code, Codex, Jules), so this check is **mandatory**. + +1. **Check for existing claims.** Search for open or draft PRs matching this agent: + ``` + gh pr list --state open --search "" + ``` + For example, if the selected agent is `changelog-agent`, run: + ``` + gh pr list --state open --search "changelog-agent" + ``` + If any matching PR exists (open or draft), this task is **already claimed**. + +2. **If already claimed:** Skip to the **next agent** in the roster (following the same alphabetical wrap-around rule from Step 1). Repeat this claim check for the new agent. If you cycle through the entire roster and all agents are claimed, log as `failed` with summary `"All roster tasks currently claimed by other agents"` and stop. + +3. **If unclaimed:** Claim the task immediately by creating a draft PR: + a. Create your working branch. + b. Make a minimal initial commit (e.g., update `CONTEXT.md` with the task scope). + c. Push the branch and open a **draft PR**: + ``` + gh pr create --draft \ + --title "[weekly] : " \ + --body "Claimed by weekly scheduler at $(date -u +%Y-%m-%dT%H:%M:%SZ). Work in progress." + ``` + d. Verify the draft PR was created successfully before proceeding to Step 2. + +4. **Race condition check:** After creating the draft PR, re-check: + ``` + gh pr list --state open --search "" + ``` + If you see another PR for this agent that was created *before* yours (by a different agent instance), close your PR with `gh pr close ` and skip to the next agent. + +**Important:** The draft PR is your lock. Do not skip this step. It prevents other agents on different platforms from picking up the same task. + +--- + ## Step 2 — Execute the Task 1. Read the selected agent's prompt file from `/docs/agents/prompts/weekly/`.