thePR0M3TH3AN/bitvid
1
0 Fork 0
mirror of https://github.com/PR0M3TH3AN/bitvid.git synced 2026-10-27 07:52:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(agents): centralize scheduler flow steps

Browse Source
This commit is contained in:
thePR0M3TH3AN committed 2026-02-13 14:18:17 -05:00
1 parent 8cee2c0f31
commit 56d7b8488b
3 files changed
+74 -602
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/agents/prompts/daily-scheduler.md
+7 -300
View File
@@ -1,142 +1,15 @@
# Daily Agent Scheduler Prompt
Use this prompt to run the next daily agent task in the rotation.
Use `docs/agents/prompts/scheduler-flow.md` as the authoritative scheduler procedure.
---
## Daily Cadence Configuration
You are the **bitvid daily agent scheduler**. Your job is to determine which daily agent task to run next, execute it, and log the run.
- `cadence`: `daily`
- `log_dir`: `docs/agents/task-logs/daily/`
- `branch_prefix`: `agents/daily/`
- `prompt_dir`: `docs/agents/prompts/daily/`
## Authority Hierarchy
1. **AGENTS.md** — repository-wide policy (overrides everything)
2. **CLAUDE.md** — repository conventions and development guidance
3. **This prompt** — scheduler logic
4. **Individual agent prompt** — the task you will execute
Read both `AGENTS.md` and `CLAUDE.md` before executing any task.
---
## Task Log Format
Task logs use a **directory-based format** where each log entry is a separate file. This prevents git merge conflicts when multiple agents run concurrently.
### Directory
```
docs/agents/task-logs/daily/
```
### File Naming Convention
```
YYYY-MM-DD_HH-MM-SS_<agent-name>_<status>.md
```
Examples:
- `2026-02-13_14-30-00_docs-agent_started.md`
- `2026-02-13_15-45-22_docs-agent_completed.md`
### File Content Template
Each log file contains:
```markdown
# Agent Task Log Entry
- **Date:** YYYY-MM-DD
- **Agent:** <agent-name>
- **Prompt:** <prompt-file>
- **Status:** started | completed | failed
- **Branch:** <branch-name>
- **Summary:** <one-line summary>
```
### Reading the Log
To find the most recent entry:
```bash
ls docs/agents/task-logs/daily/ | sort | tail -n 1
```
To find all entries for a specific agent:
```bash
ls docs/agents/task-logs/daily/ | grep "<agent-name>"
```
---
## PRE-FLIGHT GATE — Run These Commands NOW
> **This gate is NOT optional. You MUST run both commands below and paste their raw output before doing anything else. If you skip this, you will duplicate another agent's work and waste the entire run. This has happened repeatedly.**
If you arrived here from the meta prompt and already ran these commands and pasted the output, you may skip ahead to Step 1. Otherwise:
### COMMAND 1 — Check for open daily agent PRs
Run this command:
```bash
curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, prs: [.[] | {number, created_at, draft, head: {ref: .head.ref}, agent: ((.head.ref | capture("^agents/daily/(?<agent>[^/]+)/")?.agent) // (.title | capture("(?<agent>[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}'
```
**Paste the complete raw output.** If the command returns nothing or errors, write: `OUTPUT: (empty — no results)`
Normalize each PR to an agent name using this deterministic rule:
1. **Preferred:** parse the branch name from `head.ref` with the convention `agents/daily/<agent-name>/...`.
2. **Fallback:** only if branch parsing fails, parse `<agent-name>` from the PR title.
3. If an agent cannot be derived from PR metadata, treat that PR as a **global lock warning** and do not schedule any daily agent until manually resolved.
Examples of valid daily claim branch names (all parseable):
- `agents/daily/docs-agent/2026-02-13-claim`
- `agents/daily/test-audit-agent/run-2026-02-13`
- `agents/daily/prompt-curator-agent/task-rotation-fix`
**OFF LIMITS rule:** any PR that maps to an agent in the **daily cadence** is excluded, regardless of title tag format.
### COMMAND 2 — Check the task log for incomplete runs
Run this command:
```bash
ls docs/agents/task-logs/daily/ | sort
```
**Paste the complete raw output.**
Look for any `_started.md` files that do NOT have a corresponding `_completed.md` or `_failed.md` file from the same agent at a later timestamp. Those agents are **OFF LIMITS** (unless the started file is more than 24 hours old — check the date in the filename).
### COMMAND 3 — Run claim audit (authoritative exclusion source)
Run this command:
```bash
node scripts/agents/claim-audit.mjs --cadence daily
```
**Paste the complete raw output.** This script is now the authoritative source for exclusions.
Use the script output exactly:
- `excludedAgents` (JSON field) is the only valid exclusion list.
- If `globalLockWarning` is `true`, treat cadence as locked.
- If `exclusionListResolved` is `false`, stop immediately (fail-closed).
Do not manually rebuild or edit the exclusion list after the script runs.
**Fail-closed fallback:** If Command 3 fails for any reason (non-zero exit, missing script, malformed JSON, network error), do not execute any daily task. Create a `failed` scheduler log entry with summary: `Claim audit unavailable; exclusion list unresolved`.
**Do not proceed to Step 1 until you have pasted outputs for Commands 1, 2, and 3 and confirmed exclusion resolution.**
---
## Step 1 — Determine the Next Task
1. List the task log directory: `ls docs/agents/task-logs/daily/ | sort`
2. Find the **most recent entry** (last file alphabetically — filenames sort chronologically).
3. Identify the `agent-name` from the filename (the third segment, between the second `_` and the status).
4. Look up that agent in the alphabetical roster below and select the **next agent** in the list.
5. If the most recent agent is the **last** in the roster, wrap around to the **first**.
6. If the directory is empty, start with the **first** agent in the roster.
7. **CHECK YOUR EXCLUSION LIST.** If the selected agent is on the exclusion list, skip to the next agent in the roster. Repeat until you find an agent that is NOT excluded. If you cycle through the entire roster and ALL agents are excluded, log as `failed` with summary `"All roster tasks currently claimed by other agents"` and stop.
### Agent Roster (alphabetical order)
## Daily Agent Roster (alphabetical order)
| # | Agent Name | Prompt File |
|---|-----------|-------------|
@@ -161,169 +34,3 @@ Do not manually rebuild or edit the exclusion list after the script runs.
| 19 | style-agent | `bitvid-style-agent.md` |
| 20 | test-audit-agent | `bitvid-test-audit-agent.md` |
| 21 | todo-triage-agent | `bitvid-todo-triage-agent.md` |
---
## Step 2 — Claim the Task (Prevent Duplicate Work)
> **This step is MANDATORY. Do not proceed to execution without completing it.**
You must create a visible claim before doing any work. This claim is a **distributed lock** that prevents agents on other platforms (Claude Code, Codex, Jules) from picking up the same task.
### 2a. Mandatory claim sequence (exact order)
Complete the following in this exact order. Do not reorder or skip steps:
1. Create your working branch.
2. Create a minimal claim commit (for example, a new `context/CONTEXT_<timestamp>.md` with task scope).
3. Push the branch immediately.
4. Open a **draft PR immediately** after the push.
5. Create and push the `_started.md` log file.
6. Re-run the claim check command.
7. Only then proceed to Step 3 (task execution).
### 2b. Draft PR requirement (soft fail)
Try to open a draft PR immediately after the push.
- If successful: Record the PR number.
- If failed (e.g., missing `GH_TOKEN`): **Do not abort.** Log the failure in the `started` file summary (e.g., "Task claimed (PR creation skipped) — execution beginning") and proceed. The pushed branch and `started` log file serve as the primary distributed lock.
### 2c. Create and push `_started.md` log file
> **Create a `started` log file NOW, before executing the task. This ensures the rotation advances even if you crash during execution.**
Create a new file in `docs/agents/task-logs/daily/` with this naming pattern:
```
YYYY-MM-DD_HH-MM-SS_<agent-name>_started.md
```
Use the current UTC timestamp. The file content should be:
```markdown
# Agent Task Log Entry
- **Date:** <YYYY-MM-DD>
- **Agent:** <agent-name>
- **Prompt:** <prompt-file>
- **Status:** started
- **Branch:** <branch-name>
- **Summary:** Task claimed — execution beginning
```
Commit and push this log file to your branch. This `started` entry serves as a secondary lock: other scheduler instances will see it and skip this agent.
### 2d. Final pre-execution claim check (race condition check)
After pushing the started log, re-check for competing claims:
```bash
curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, prs: [.[] | {number, created_at, draft, head: {ref: .head.ref}, agent: ((.head.ref | capture("^agents/daily/(?<agent>[^/]+)/")?.agent) // (.title | capture("(?<agent>[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}'
```
Decision logic (must be explicit):
1. Compare only open/draft PRs whose derived `agent` matches the agent you just claimed.
2. If another matching PR has an earlier `created_at`, abort this run and pick the next agent.
3. If `created_at` values are equal or ambiguous, use the lower `number` as the tie-breaker (lower number wins).
Before proceeding, print exactly one race verdict line:
- `RACE CHECK: won`
- `RACE CHECK: lost (agent already claimed by PR #<number>)`
If the verdict is lost, abandon your branch and go back to Step 1 to select the next agent.
### 2e. Required output checklist (must be filled before Step 3)
```text
Branch pushed: yes/no
Draft PR #: ... (or "FAILED/SKIPPED")
Started log filename: ...
Final pre-execution claim check passed: yes/no
```
Do not begin Step 3 until all checklist fields are filled.
---
## Step 3 — Execute the Task
1. Read the selected agent's prompt file from `docs/agents/prompts/daily/<filename>`.
2. Adopt that prompt as your operating instructions for this session.
3. Follow the agent prompt's workflow end-to-end, including:
- Updating the persistent state files (in `context/`, `todo/`, `decisions/`, `test_logs/`) per AGENTS.md Section 15.
- Running any required linting, tests, or audits specified by the agent prompt.
- Creating artifacts, reports, or PRs as the agent prompt directs.
---
## Step 4 — Update the Task Log (Final Status)
After completing the task (or if the task fails), create a **new** log file with the final status. Do NOT modify the `started` file.
Create a new file in `docs/agents/task-logs/daily/`:
For completed tasks:
```
YYYY-MM-DD_HH-MM-SS_<agent-name>_completed.md
```
For failed tasks:
```
YYYY-MM-DD_HH-MM-SS_<agent-name>_failed.md
```
Use the current UTC timestamp (which will be later than the `started` file). The file content should be:
```markdown
# Agent Task Log Entry
- **Date:** <YYYY-MM-DD>
- **Agent:** <agent-name>
- **Prompt:** <prompt-file>
- **Status:** completed (or failed)
- **Branch:** <branch-name>
- **Summary:** <one-line summary of what was done or why it failed>
```
### Rules for the Log
- **Never modify existing files** — always create new files. This eliminates merge conflicts.
- **One `started` + one final file per run** — each scheduler invocation creates exactly two files (started, then completed/failed).
- **Use UTC timestamps** — ensures consistent chronological sorting across time zones.
- **Files sort chronologically** — the filename format ensures `ls | sort` produces a timeline.
---
## Step 5 — Verify and Submit
1. **Verify the log**: List `docs/agents/task-logs/daily/` and confirm your entries were created correctly (proper filename format, valid content).
2. **Run a final check**: Execute `npm run lint` to confirm no lint regressions were introduced.
3. **Commit your changes** with a descriptive message following this pattern:
```
chore(agents): run <agent-name> daily task — <brief summary>
```
4. **Push** to the appropriate branch.
---
## Error Handling
- If the agent prompt file is **empty or missing**, skip it, log the run as `failed` with summary `"Prompt file empty or missing"`, and proceed to the **next agent** in the roster.
- If a task **fails mid-execution** (test failures, build errors), log the run as `failed` with a summary describing the failure. Still commit the log file and any partial artifacts.
- If the task log directory is **missing**, create it: `mkdir -p docs/agents/task-logs/daily/`.
- If **Draft PR creation fails**, fall back to log-file-only claiming (the branch + `started` file).
- If `curl` or `jq` is **unavailable or errors**, fall back to log-file-only claiming (the `started` file). Log a warning in your summary that PR-based claim checking was degraded.
---
## Quick Reference: What Prevents Duplicate Work
| Layer | Mechanism | Catches |
|-------|-----------|---------|
| **Pre-flight gate** | Scan ALL open PR metadata via `curl` + deterministic agent mapping | Agents claimed by any platform |
| **Pre-flight gate** | Check task log dir for `started` files | Agents in progress (even without PR) |
| **Step 2a** | Branch + claim commit + push + draft PR | Cross-platform visibility and explicit lock |
| **Step 2c** | Create `started` log file immediately | Crash recovery — rotation advances |
| **Step 2d** | Final race condition re-check | Simultaneous claims |
All five layers must be executed. No single layer is sufficient on its own.
**Why directories instead of CSV?** Each agent creates its own uniquely-named file, so concurrent agents never touch the same file. This eliminates the git merge conflicts and race conditions that occurred when multiple agents appended to a shared CSV.
docs/agents/prompts/scheduler-flow.md
+60
View File
@@ -0,0 +1,60 @@
# Scheduler Flow (Single Source of Truth)
Use this document for **all scheduler runs**. Do not redefine preflight or claim logic in other scheduler prompts.
## Required Steps (Strict Order)
1. **Load policy files first**
- Read `AGENTS.md` and `CLAUDE.md`.
2. **Set cadence config**
- `cadence`: `daily` or `weekly`
- `log_dir`: `docs/agents/task-logs/<cadence>/`
- `branch_prefix`: `agents/<cadence>/`
- `prompt_dir`: `docs/agents/prompts/<cadence>/`
3. **Run preflight claim audit (required, fail-closed)**
- `curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, prs: [.[] | {number, created_at, draft, head: {ref: .head.ref}, agent: ((.head.ref | capture("^agents/<cadence>/(?<agent>[^/]+)/")?.agent) // (.title | capture("(?<agent>[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}'`
- `ls <log_dir> | sort`
- `node scripts/agents/claim-audit.mjs --cadence <cadence>`
- Use `excludedAgents` from claim-audit output as the only exclusion list.
- If claim-audit fails, `globalLockWarning=true`, or `exclusionListResolved=false`, stop and log `failed`.
4. **Select next agent from cadence roster**
- Read latest file in `<log_dir>` (alphabetical sort).
- Advance to next agent in that cadence's roster.
- Skip excluded agents.
- If all are excluded, log `failed` with `All roster tasks currently claimed by other agents` and stop.
5. **Claim task before execution (required sequence)**
1. Create branch.
2. Create minimal claim commit.
3. Push branch.
4. Attempt draft PR.
5. Create and push `<timestamp>_<agent>_started.md` in `<log_dir>`.
6. Re-run open PR check.
7. Race decision:
- If earlier matching PR exists: `RACE CHECK: lost (agent already claimed by PR #<number>)`, abandon branch, go back to Step 4.
- Otherwise: `RACE CHECK: won`, continue.
6. **Execute selected agent prompt**
- Open `<prompt_dir>/<prompt-file>`.
- Run required workflow end-to-end.
7. **Write final status log**
- Create `<timestamp>_<agent>_completed.md` or `_failed.md` in `<log_dir>`.
- Never edit existing log files.
8. **Validate and submit**
- Verify log files exist and are correctly named.
- Run required checks (default: `npm run lint`).
- Commit and push changes.
## Reference (Optional / Explanatory)
- File format for each log entry:
- `YYYY-MM-DD_HH-MM-SS_<agent-name>_<status>.md`
- Include: Date, Agent, Prompt, Status, Branch, Summary.
- Draft PR creation is recommended for visibility; if unavailable, branch + started log still act as lock.
- `started` + final status files provide crash recovery and clean chronological rotation.
- Directory-based logs avoid CSV merge conflicts during concurrent scheduler runs.
docs/agents/prompts/weekly-scheduler.md
+7 -302
View File
@@ -1,142 +1,15 @@
# Weekly Agent Scheduler Prompt
Use this prompt to run the next weekly agent task in the rotation.
Use `docs/agents/prompts/scheduler-flow.md` as the authoritative scheduler procedure.
---
## Weekly Cadence Configuration
You are the **bitvid weekly agent scheduler**. Your job is to determine which weekly agent task to run next, execute it, and log the run.
- `cadence`: `weekly`
- `log_dir`: `docs/agents/task-logs/weekly/`
- `branch_prefix`: `agents/weekly/`
- `prompt_dir`: `docs/agents/prompts/weekly/`
## Authority Hierarchy
1. **AGENTS.md** — repository-wide policy (overrides everything)
2. **CLAUDE.md** — repository conventions and development guidance
3. **This prompt** — scheduler logic
4. **Individual agent prompt** — the task you will execute
Read both `AGENTS.md` and `CLAUDE.md` before executing any task.
---
## Task Log Format
Task logs use a **directory-based format** where each log entry is a separate file. This prevents git merge conflicts when multiple agents run concurrently.
### Directory
```
docs/agents/task-logs/weekly/
```
### File Naming Convention
```
YYYY-MM-DD_HH-MM-SS_<agent-name>_<status>.md
```
Examples:
- `2026-02-13_14-30-00_changelog-agent_started.md`
- `2026-02-13_15-45-22_changelog-agent_completed.md`
### File Content Template
Each log file contains:
```markdown
# Agent Task Log Entry
- **Date:** YYYY-MM-DD
- **Agent:** <agent-name>
- **Prompt:** <prompt-file>
- **Status:** started | completed | failed
- **Branch:** <branch-name>
- **Summary:** <one-line summary>
```
### Reading the Log
To find the most recent entry:
```bash
ls docs/agents/task-logs/weekly/ | sort | tail -n 1
```
To find all entries for a specific agent:
```bash
ls docs/agents/task-logs/weekly/ | grep "<agent-name>"
```
---
## PRE-FLIGHT GATE — Run These Commands NOW
> **This gate is NOT optional. You MUST run both commands below and paste their raw output before doing anything else. If you skip this, you will duplicate another agent's work and waste the entire run. This has happened repeatedly.**
If you arrived here from the meta prompt and already ran these commands and pasted the output, you may skip ahead to Step 1. Otherwise:
### COMMAND 1 — Check for open weekly agent PRs
Run this command:
```bash
curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, prs: [.[] | {number, created_at, draft, head: {ref: .head.ref}, agent: ((.head.ref | capture("^agents/weekly/(?<agent>[^/]+)/")?.agent) // (.title | capture("(?<agent>[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}'
```
**Paste the complete raw output.** If the command returns nothing or errors, write: `OUTPUT: (empty — no results)`
Normalize each PR to an agent name using this deterministic rule:
1. **Preferred:** parse the branch name from `head.ref` with the convention `agents/weekly/<agent-name>/...`.
2. **Fallback:** only if branch parsing fails, parse `<agent-name>` from the PR title.
3. If an agent cannot be derived from PR metadata, treat that PR as a **global lock warning** and do not schedule any weekly agent until manually resolved.
Examples of valid weekly claim branch names (all parseable):
- `agents/weekly/ci-health-agent/2026-02-weekly-run`
- `agents/weekly/telemetry-agent/report-refresh`
- `agents/weekly/weekly-synthesis-agent/sprint-07`
**OFF LIMITS rule:** any PR that maps to an agent in the **weekly cadence** is excluded, regardless of title tag format.
### COMMAND 2 — Check the task log for incomplete runs
Run this command:
```bash
ls docs/agents/task-logs/weekly/ | sort
```
**Paste the complete raw output.**
Look for any `_started.md` files that do NOT have a corresponding `_completed.md` or `_failed.md` file from the same agent at a later timestamp. Those agents are **OFF LIMITS** (unless the started file is more than 24 hours old — check the date in the filename).
### COMMAND 3 — Run claim audit (authoritative exclusion source)
Run this command:
```bash
node scripts/agents/claim-audit.mjs --cadence weekly
```
**Paste the complete raw output.** This script is now the authoritative source for exclusions.
Use the script output exactly:
- `excludedAgents` (JSON field) is the only valid exclusion list.
- If `globalLockWarning` is `true`, treat cadence as locked.
- If `exclusionListResolved` is `false`, stop immediately (fail-closed).
Do not manually rebuild or edit the exclusion list after the script runs.
**Fail-closed fallback:** If Command 3 fails for any reason (non-zero exit, missing script, malformed JSON, network error), do not execute any weekly task. Create a `failed` scheduler log entry with summary: `Claim audit unavailable; exclusion list unresolved`.
**Do not proceed to Step 1 until you have pasted outputs for Commands 1, 2, and 3 and confirmed exclusion resolution.**
---
## Step 1 — Determine the Next Task
1. List the task log directory: `ls docs/agents/task-logs/weekly/ | sort`
2. Find the **most recent entry** (last file alphabetically — filenames sort chronologically).
3. Identify the `agent-name` from the filename (the third segment, between the second `_` and the status).
4. Look up that agent in the alphabetical roster below and select the **next agent** in the list.
5. If the most recent agent is the **last** in the roster, wrap around to the **first**.
6. If the directory is empty, start with the **first** agent in the roster.
7. **CHECK YOUR EXCLUSION LIST.** If the selected agent is on the exclusion list, skip to the next agent in the roster. Repeat until you find an agent that is NOT excluded. If you cycle through the entire roster and ALL agents are excluded, log as `failed` with summary `"All roster tasks currently claimed by other agents"` and stop.
### Agent Roster (alphabetical order)
## Weekly Agent Roster (alphabetical order)
| # | Agent Name | Prompt File |
|---|-----------|-------------|
@@ -156,171 +29,3 @@ Do not manually rebuild or edit the exclusion list after the script runs.
| 14 | telemetry-agent | `bitvid-telemetry-agent.md` |
| 15 | test-coverage-agent | `bitvid-test-coverage-agent.md` |
| 16 | weekly-synthesis-agent | `bitvid-weekly-synthesis-agent.md` |
---
## Step 2 — Claim the Task (Prevent Duplicate Work)
> **This step is MANDATORY. Do not proceed to execution without completing it.**
You must create a visible claim before doing any work. This claim is a **distributed lock** that prevents agents on other platforms (Claude Code, Codex, Jules) from picking up the same task.
### 2a. Mandatory claim sequence (exact order)
Complete the following in this exact order. Do not reorder or skip steps:
1. Create your working branch.
2. Create a minimal claim commit (for example, a new `context/CONTEXT_<timestamp>.md` with task scope).
3. Push the branch immediately.
4. Open a **draft PR immediately** after the push.
5. Create and push the `_started.md` log file.
6. Re-run the claim check command.
7. Only then proceed to Step 3 (task execution).
### 2b. Draft PR requirement (soft fail)
Try to open a draft PR immediately after the push.
- If successful: Record the PR number.
- If failed (e.g., missing `GH_TOKEN`): **Do not abort.** Log the failure in the `started` file summary (e.g., "Task claimed (PR creation skipped) — execution beginning") and proceed. The pushed branch and `started` log file serve as the primary distributed lock.
### 2c. Create and push `_started.md` log file
> **Create a `started` log file NOW, before executing the task. This ensures the rotation advances even if you crash during execution.**
Create a new file in `docs/agents/task-logs/weekly/` with this naming pattern:
```
YYYY-MM-DD_HH-MM-SS_<agent-name>_started.md
```
Use the current UTC timestamp. The file content should be:
```markdown
# Agent Task Log Entry
- **Date:** <YYYY-MM-DD>
- **Agent:** <agent-name>
- **Prompt:** <prompt-file>
- **Status:** started
- **Branch:** <branch-name>
- **Summary:** Task claimed — execution beginning
```
Commit and push this log file to your branch. This `started` entry serves as a secondary lock: other scheduler instances will see it and skip this agent.
### 2d. Final pre-execution claim check (race condition check)
After pushing the started log, re-check for competing claims:
```bash
curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, prs: [.[] | {number, created_at, draft, head: {ref: .head.ref}, agent: ((.head.ref | capture("^agents/weekly/(?<agent>[^/]+)/")?.agent) // (.title | capture("(?<agent>[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}'
```
Decision logic (must be explicit):
1. Compare only open/draft PRs whose derived `agent` matches the agent you just claimed.
2. If another matching PR has an earlier `created_at`, abort this run and pick the next agent.
3. If `created_at` values are equal or ambiguous, use the lower `number` as the tie-breaker (lower number wins).
Before proceeding, print exactly one race verdict line:
- `RACE CHECK: won`
- `RACE CHECK: lost (agent already claimed by PR #<number>)`
If the verdict is lost, abandon your branch and go back to Step 1 to select the next agent.
### 2e. Required output checklist (must be filled before Step 3)
```text
Branch pushed: yes/no
Draft PR #: ... (or "FAILED/SKIPPED")
Started log filename: ...
Final pre-execution claim check passed: yes/no
```
Do not begin Step 3 until all checklist fields are filled.
---
## Step 3 — Execute the Task
1. Read the selected agent's prompt file from `docs/agents/prompts/weekly/<filename>`.
2. Adopt that prompt as your operating instructions for this session.
3. Follow the agent prompt's workflow end-to-end, including:
- Updating the persistent state files (in `context/`, `todo/`, `decisions/`, `test_logs/`) per AGENTS.md Section 15.
- Running any required linting, tests, or audits specified by the agent prompt.
- Creating artifacts, reports, or PRs as the agent prompt directs.
---
## Step 4 — Update the Task Log (Final Status)
After completing the task (or if the task fails), create a **new** log file with the final status. Do NOT modify the `started` file.
Create a new file in `docs/agents/task-logs/weekly/`:
For completed tasks:
```
YYYY-MM-DD_HH-MM-SS_<agent-name>_completed.md
```
For failed tasks:
```
YYYY-MM-DD_HH-MM-SS_<agent-name>_failed.md
```
Use the current UTC timestamp (which will be later than the `started` file). The file content should be:
```markdown
# Agent Task Log Entry
- **Date:** <YYYY-MM-DD>
- **Agent:** <agent-name>
- **Prompt:** <prompt-file>
- **Status:** completed (or failed)
- **Branch:** <branch-name>
- **Summary:** <one-line summary of what was done or why it failed>
```
### Rules for the Log
- **Never modify existing files** — always create new files. This eliminates merge conflicts.
- **One `started` + one final file per run** — each scheduler invocation creates exactly two files (started, then completed/failed).
- **Use UTC timestamps** — ensures consistent chronological sorting across time zones.
- **Files sort chronologically** — the filename format ensures `ls | sort` produces a timeline.
**Important:** Weekly agents use their own log directory (`docs/agents/task-logs/weekly/`), separate from the daily log (`docs/agents/task-logs/daily/`). This keeps weekly and daily rotations independent and avoids one cadence interfering with the other's position tracking.
---
## Step 5 — Verify and Submit
1. **Verify the log**: List `docs/agents/task-logs/weekly/` and confirm your entries were created correctly (proper filename format, valid content).
2. **Run a final check**: Execute `npm run lint` to confirm no lint regressions were introduced.
3. **Commit your changes** with a descriptive message following this pattern:
```
chore(agents): run <agent-name> weekly task — <brief summary>
```
4. **Push** to the appropriate branch.
---
## Error Handling
- If the agent prompt file is **empty or missing**, skip it, log the run as `failed` with summary `"Prompt file empty or missing"`, and proceed to the **next agent** in the roster.
- If a task **fails mid-execution** (test failures, build errors), log the run as `failed` with a summary describing the failure. Still commit the log file and any partial artifacts.
- If the task log directory is **missing**, create it: `mkdir -p docs/agents/task-logs/weekly/`.
- If **Draft PR creation fails**, fall back to log-file-only claiming (the branch + `started` file).
- If `curl` or `jq` is **unavailable or errors**, fall back to log-file-only claiming (the `started` file). Log a warning in your summary that PR-based claim checking was degraded.
---
## Quick Reference: What Prevents Duplicate Work
| Layer | Mechanism | Catches |
|-------|-----------|---------|
| **Pre-flight gate** | Scan ALL open PR metadata via `curl` + deterministic agent mapping | Agents claimed by any platform |
| **Pre-flight gate** | Check task log dir for `started` files | Agents in progress (even without PR) |
| **Step 2a** | Branch + claim commit + push + draft PR | Cross-platform visibility and explicit lock |
| **Step 2c** | Create `started` log file immediately | Crash recovery — rotation advances |
| **Step 2d** | Final race condition re-check | Simultaneous claims |
All five layers must be executed. No single layer is sufficient on its own.
**Why directories instead of CSV?** Each agent creates its own uniquely-named file, so concurrent agents never touch the same file. This eliminates the git merge conflicts and race conditions that occurred when multiple agents appended to a shared CSV.