bitvid/docs/agents/prompts/weekly-scheduler.md

Weekly Agent Scheduler Prompt

Use this prompt to run the next weekly agent task in the rotation.

---

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.

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.

---

Step 0 — Pre-Flight: Scan ALL In-Flight Work (MANDATORY)

DO NOT SKIP THIS STEP. This is the single most important step in the entire scheduler. If you skip this, you will cause duplicate work and waste an entire agent run.

Before determining which agent to run, you MUST build situational awareness of what is already in progress. Run these commands and record the results:

0a. List ALL open weekly agent PRs

curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq -c '.[] | select(.title | contains("[weekly]")) | {number: .number, title: .title, created_at: .created_at, author: .user.login}'

Record every open PR. These represent active claims by other agents. Any agent whose name appears in these PR titles is OFF LIMITS.

0b. Check the task log for incomplete runs

cat docs/agents/WEEKLY_AGENT_TASK_LOG.csv

Look for any rows with status started — these represent agents that began work but haven't finished. Treat them the same as open PRs: those agents are OFF LIMITS unless the started entry is older than 24 hours (stale/abandoned).

0c. Build your exclusion list

Combine the results from 0a and 0b into an explicit exclusion list:

• Agents with open/draft PRs → EXCLUDED
• Agents with started status less than 24 hours old → EXCLUDED

Write this exclusion list down before proceeding. You will reference it in Step 1.

If the curl command fails (e.g., network error, API limit): You MUST still check the CSV for started entries. Log a warning in your summary that PR-based claim checking was unavailable.

---

Step 1 — Determine the Next Task

1. Read the weekly task log at docs/agents/WEEKLY_AGENT_TASK_LOG.csv.
2. Find the most recent entry (last non-header row).
3. Identify the agent_name from that entry.
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 log file is empty (no entries beyond the header), start with the first agent in the roster.
7. CHECK YOUR EXCLUSION LIST FROM STEP 0. 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)

#	Agent Name	Prompt File
1	bug-reproducer-agent	bitvid-bug-reproducer-agent.md
2	changelog-agent	bitvid-changelog-agent.md
3	dead-code-agent	bitvid-dead-code-agent.md
4	event-schema-agent	bitvid-event-schema-agent.md
5	frontend-console-debug-agent	bitvid-frontend-console-debug-agent.md
6	fuzz-agent	bitvid-fuzz-agent.md
7	interop-agent	bitvid-interop-agent.md
8	perf-deepdive-agent	bitvid-perf-deepdive-agent.md
9	perf-optimization-agent	bitvid-perf-optimization-agent.md
10	pr-review-agent	bitvid-pr-review-agent.md
11	race-condition-agent	bitvid-race-condition-agent.md
12	refactor-agent	bitvid-refactor-agent.md
13	smoke-agent	bitvid-smoke-agent.md
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. Create your working branch and claim via draft PR

1. Create your working branch.
2. Make a minimal initial commit (e.g., update CONTEXT.md with the task scope).
3. Push the branch and open a draft PR:

   gh pr create --draft \
     --title "[weekly] <agent-name>: <brief task description>" \
     --body "Claimed by weekly scheduler at $(date -u +%Y-%m-%dT%H:%M:%SZ). Work in progress."
   

4. Verify the draft PR was created successfully before proceeding.

2b. Race condition check

After creating the draft PR, immediately re-check:

curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq -c '.[] | select(.title | contains("[weekly] <agent-name>")) | {number: .number, title: .title, created_at: .created_at}'

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 <your-pr-number> (if gh works) and go back to Step 1 to select the next agent.

2c. Log "started" in the CSV immediately

This is critical. Append a started row to the CSV NOW, before executing the task. This ensures the rotation advances even if you crash during execution.

Append this row to docs/agents/WEEKLY_AGENT_TASK_LOG.csv:

<date>,<agent-name>,<prompt-file>,started,<branch>,"Task claimed — execution beginning"

Commit and push this CSV update to your branch. This started entry serves as a secondary lock: other scheduler instances that cannot reach gh will still see it and skip this agent.

If gh is unavailable: You MUST still log the started entry and push it. The CSV started row is your minimum viable claim.

---

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 (CONTEXT.md, TODO.md, DECISIONS.md, TEST_LOG.md) 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), update the CSV entry you wrote in Step 2c. Find the started row you appended and add a new row with the final status:

Append a new row to docs/agents/WEEKLY_AGENT_TASK_LOG.csv:

<date>,<agent-name>,<prompt-file>,completed,<branch>,"<summary of what was done>"

Or if the task failed:

<date>,<agent-name>,<prompt-file>,failed,<branch>,"<summary of why it failed>"

CSV Format

date,agent_name,prompt_file,status,branch,summary

Column	Format	Description
date	YYYY-MM-DD	Date the task was executed
agent_name	string	Agent name from the roster (e.g., changelog-agent)
prompt_file	string	Filename executed (e.g., bitvid-changelog-agent.md)
status	started, completed, or failed	Current status of the task
branch	string	Git branch where work was committed
summary	quoted string	One-line summary of what was done or why it failed

Rules for the Log

• Always append — never delete or modify existing rows.
• One started + one final row per run — each scheduler invocation adds exactly two rows (started, then completed/failed).
• Quote the summary — use double quotes around the summary field since it may contain commas.
• Keep it sorted — rows are naturally in chronological order by append time.

Important: Weekly agents use their own log file (WEEKLY_AGENT_TASK_LOG.csv), separate from the daily log (AGENT_TASK_LOG.csv). 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: Re-read docs/agents/WEEKLY_AGENT_TASK_LOG.csv and confirm your entries were appended correctly (proper CSV format, no corruption of previous rows).
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 update and any partial artifacts.
• If the CSV file itself is missing or corrupt, recreate it with the header row before appending.
• If gh or curl is unavailable or errors, fall back to CSV-only claiming (the started row). Log a warning in your summary that PR-based claim checking was degraded.

---

Quick Reference: What Prevents Duplicate Work

Layer	Mechanism	Catches
Step 0	Scan ALL open [weekly] PRs	Agents claimed by any platform
Step 0	Check CSV for started rows	Agents in progress (even without PR)
Step 2a	Create draft PR as lock	Cross-platform visibility
Step 2b	Race condition re-check	Simultaneous claims
Step 2c	Log started to CSV immediately	Crash recovery — rotation advances

All five layers must be executed. No single layer is sufficient on its own.