diff --git a/docs/agents/prompts/META_PROMPTS.md b/docs/agents/prompts/META_PROMPTS.md index a020e3c9..07f7c875 100644 --- a/docs/agents/prompts/META_PROMPTS.md +++ b/docs/agents/prompts/META_PROMPTS.md @@ -1,6 +1,6 @@ # Bitvid Agent Scheduler Meta Prompts -This file contains the authoritative "Meta Prompts" to be used when triggering the daily and weekly agent schedulers. Copy-paste the relevant prompt below into the agent session. +Copy one block below into the agent session. --- @@ -9,58 +9,30 @@ This file contains the authoritative "Meta Prompts" to be used when triggering t ```text You are the bitvid daily agent scheduler. -YOUR VERY FIRST ACTION — before reading any file, before planning anything, -before choosing a task — is to run this command. Not later. NOW. +Follow `docs/agents/prompts/scheduler-flow.md` exactly. -COMMAND 1 — Check for open daily agent PRs: +MUST 1: Set cadence config to: +- cadence = daily +- log_dir = docs/agents/task-logs/daily/ +- branch_prefix = agents/daily/ +- prompt_dir = docs/agents/prompts/daily/ - 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) // (.title | capture("(?[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}' +MUST 2: Run this exact preflight command first: - Normalize each PR to an agent name using this deterministic rule: - 1) Preferred: parse `head.ref` as `agents/daily//...` - 2) Fallback: parse agent name from title only if branch parsing fails - 3) If agent cannot be derived from metadata, treat as GLOBAL LOCK warning and do not schedule daily tasks until manually resolved +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) // (.title | capture("(?[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}' - OFF LIMITS rule: any PR that maps to a daily-cadence agent is excluded, regardless of title tag format. +MUST 3: Run the exact command list in this order: +1) cat AGENTS.md CLAUDE.md +2) ls -1 docs/agents/task-logs/daily/ | sort | tail -n 1 +3) [claim] create branch, create+commit `_started.md`, push +4) rerun preflight command from MUST 2 +5) execute selected prompt from docs/agents/prompts/daily/ +6) npm run lint +7) create `_completed.md` or `_failed.md`, commit, push - Valid daily claim branch examples: - - agents/daily/docs-agent/2026-02-13-claim - - agents/daily/test-audit-agent/run-2026-02-13 +MUST 4: Race rule: after step 3, compare only matching derived `agent` claims from the rerun. Earlier `created_at` wins; if tied, lower PR number wins. Print exactly one line: `RACE CHECK: won` or `RACE CHECK: lost (agent already claimed by PR #)`. -Use this PR-list output as the only preflight exclusion source. -Do not block execution on any other preflight command. - -Now proceed with the scheduler: - -1. Read `AGENTS.md` and `CLAUDE.md` for project rules. -2. Read `docs/agents/prompts/daily-scheduler.md` and follow its instructions - starting from "Step 1 — Determine the Next Task." You already completed - the pre-flight gate above — use the PR-list exclusion set when selecting an agent. -3. Complete this claim sequence in exact order: - - create branch - - optionally create minimal claim commit - - push - - optionally open draft PR for visibility - - create and push `_started.md` log - - re-run claim check - - only then execute task -4. Before Step 3 execution, fill this required checklist block exactly: - - ```text - Branch pushed: yes/no - Draft PR #: ... - Started log filename: ... - Final pre-execution claim check passed: yes/no - ``` - -5. After execution: create a "completed" or "failed" log file (new file, never - modify the "started" file). Commit and push. - -Race check rule (must be applied after pushing `_started.md` log): -- Re-run the sortable PR metadata command and compare only PRs with matching derived `agent`. -- If another open/draft claim for the same agent has earlier `created_at`, you lose the race and must abort this run and pick the next agent. -- If timestamps are equal or ambiguous, lower PR `number` wins. -- Print one line before proceeding: `RACE CHECK: won` or `RACE CHECK: lost (agent already claimed by PR #)`. +MUST 5: If all daily agents are excluded, stop and write `_failed.md` with this exact reason: `All roster tasks currently claimed by other agents`. ``` ## Weekly Scheduler Meta Prompt @@ -68,56 +40,28 @@ Race check rule (must be applied after pushing `_started.md` log): ```text You are the bitvid weekly agent scheduler. -YOUR VERY FIRST ACTION — before reading any file, before planning anything, -before choosing a task — is to run this command. Not later. NOW. +Follow `docs/agents/prompts/scheduler-flow.md` exactly. -COMMAND 1 — Check for open weekly agent PRs: +MUST 1: Set cadence config to: +- cadence = weekly +- log_dir = docs/agents/task-logs/weekly/ +- branch_prefix = agents/weekly/ +- prompt_dir = docs/agents/prompts/weekly/ - 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) // (.title | capture("(?[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}' +MUST 2: Run this exact preflight command first: - Normalize each PR to an agent name using this deterministic rule: - 1) Preferred: parse `head.ref` as `agents/weekly//...` - 2) Fallback: parse agent name from title only if branch parsing fails - 3) If agent cannot be derived from metadata, treat as GLOBAL LOCK warning and do not schedule weekly tasks until manually resolved +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) // (.title | capture("(?[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}' - OFF LIMITS rule: any PR that maps to a weekly-cadence agent is excluded, regardless of title tag format. +MUST 3: Run the exact command list in this order: +1) cat AGENTS.md CLAUDE.md +2) ls -1 docs/agents/task-logs/weekly/ | sort | tail -n 1 +3) [claim] create branch, create+commit `_started.md`, push +4) rerun preflight command from MUST 2 +5) execute selected prompt from docs/agents/prompts/weekly/ +6) npm run lint +7) create `_completed.md` or `_failed.md`, commit, push - Valid weekly claim branch examples: - - agents/weekly/ci-health-agent/2026-02-weekly-run - - agents/weekly/weekly-synthesis-agent/sprint-07 +MUST 4: Race rule: after step 3, compare only matching derived `agent` claims from the rerun. Earlier `created_at` wins; if tied, lower PR number wins. Print exactly one line: `RACE CHECK: won` or `RACE CHECK: lost (agent already claimed by PR #)`. -Use this PR-list output as the only preflight exclusion source. -Do not block execution on any other preflight command. - -Now proceed with the scheduler: - -1. Read `AGENTS.md` and `CLAUDE.md` for project rules. -2. Read `docs/agents/prompts/weekly-scheduler.md` and follow its instructions - starting from "Step 1 — Determine the Next Task." You already completed - the pre-flight gate above — use the PR-list exclusion set when selecting an agent. -3. Complete this claim sequence in exact order: - - create branch - - optionally create minimal claim commit - - push - - optionally open draft PR for visibility - - create and push `_started.md` log - - re-run claim check - - only then execute task -4. Before Step 3 execution, fill this required checklist block exactly: - - ```text - Branch pushed: yes/no - Draft PR #: ... - Started log filename: ... - Final pre-execution claim check passed: yes/no - ``` - -5. After execution: create a "completed" or "failed" log file (new file, never - modify the "started" file). Commit and push. - -Race check rule (must be applied after pushing `_started.md` log): -- Re-run the sortable PR metadata command and compare only PRs with matching derived `agent`. -- If another open/draft claim for the same agent has earlier `created_at`, you lose the race and must abort this run and pick the next agent. -- If timestamps are equal or ambiguous, lower PR `number` wins. -- Print one line before proceeding: `RACE CHECK: won` or `RACE CHECK: lost (agent already claimed by PR #)`. +MUST 5: If all weekly agents are excluded, stop and write `_failed.md` with this exact reason: `All roster tasks currently claimed by other agents`. ``` diff --git a/docs/agents/prompts/scheduler-flow.md b/docs/agents/prompts/scheduler-flow.md index be113eec..bda0bb6e 100644 --- a/docs/agents/prompts/scheduler-flow.md +++ b/docs/agents/prompts/scheduler-flow.md @@ -1,58 +1,72 @@ # Scheduler Flow (Single Source of Truth) -Use this document for **all scheduler runs**. Do not redefine preflight or claim logic in other scheduler prompts. +Use this document for **all scheduler runs**. -## Required Steps (Strict Order) +## Numbered MUST Procedure -1. **Load policy files first** - - Read `AGENTS.md` and `CLAUDE.md`. +1. **MUST** set cadence variables before any command: + - `cadence` = `daily` or `weekly` + - `log_dir` = `docs/agents/task-logs//` + - `branch_prefix` = `agents//` + - `prompt_dir` = `docs/agents/prompts//` -2. **Set cadence config** - - `cadence`: `daily` or `weekly` - - `log_dir`: `docs/agents/task-logs//` - - `branch_prefix`: `agents//` - - `prompt_dir`: `docs/agents/prompts//` +2. **MUST** run this command first and save the JSON output as the preflight exclusion set: -3. **Run preflight PR-list check (required)** - - `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//(?[^/]+)/")?.agent) // (.title | capture("(?[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}'` - - Use this PR list output as the preflight exclusion source for already-claimed agents. - - **Do not block execution on any other preflight 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//(?[^/]+)/")?.agent) // (.title | capture("(?[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}' + ``` -4. **Select next agent from cadence roster** - - Read latest file in `` (alphabetical sort). - - Advance to next agent in that cadence's roster. - - Skip agents already claimed in the preflight PR-list output. - - If all are excluded, log `failed` with `All roster tasks currently claimed by other agents` and stop. +3. **MUST** derive excluded agents from command output using this order only: + 1) parse `head.ref` as `agents///...`; 2) fallback to title regex; 3) if still unknown, stop with a global lock message. -5. **Claim task before execution (recommended sequence)** - 1. Create branch. - 2. Optionally create a minimal claim commit. - 3. Push branch. - 4. Optionally open a draft PR for visibility. - 5. Create and push `__started.md` in ``. - 6. Re-run open PR check. - 7. Race decision: - - If earlier matching PR exists: `RACE CHECK: lost (agent already claimed by PR #)`, abandon branch, go back to Step 4. - - Otherwise: `RACE CHECK: won`, continue. +4. **MUST** run this command and read both policy files before selecting an agent: -6. **Execute selected agent prompt** - - Open `/`. - - Run required workflow end-to-end. + ```bash + cat AGENTS.md CLAUDE.md + ``` -7. **Write final status log** - - Create `__completed.md` or `_failed.md` in ``. - - Never edit existing log files. +5. **MUST** run this command to identify the latest cadence log file, then choose the next roster agent not excluded by Step 2: -8. **Validate and submit** - - Verify log files exist and are correctly named. - - Run required checks (default: `npm run lint`). - - Commit and push changes. + ```bash + ls -1 | sort | tail -n 1 + ``` -## Reference (Optional / Explanatory) +6. **MUST** stop and write a `_failed.md` log with `All roster tasks currently claimed by other agents` when every roster agent is excluded. -- File format for each log entry: - - `YYYY-MM-DD_HH-MM-SS__.md` - - Include: Date, Agent, Prompt, Status, Branch, Summary. -- Draft PR creation is optional and recommended for visibility; 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. +7. **MUST** claim the selected agent in this exact order: + 1) create branch, + 2) create and commit `__started.md` in ``, + 3) push branch and commit. + +8. **MUST** re-run the same PR preflight command from Step 2 immediately after push. If an earlier claim exists for the same derived agent, print `RACE CHECK: lost (agent already claimed by PR #)`, abandon the run, and return to Step 5. Otherwise print `RACE CHECK: won`. + +9. **MUST** execute `/` end-to-end. + +10. **MUST** create exactly one final status file (`_completed.md` or `_failed.md`), run `npm run lint`, then commit and push. + +## Canonical Example Run Output + +```text +$ 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) // (.title | capture("(?[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}' +{ "count": 12, "prs": [ ... ] } + +$ cat AGENTS.md CLAUDE.md +# bitvid — AI Agent Guide +... + +$ ls -1 docs/agents/task-logs/daily/ | sort | tail -n 1 +2026-02-13_18-40-00_load-test-agent_completed.md + +Selected agent: nip-research-agent +Created: docs/agents/task-logs/daily/2026-02-14_00-00-00_nip-research-agent_started.md +Pushed branch: agents/daily/nip-research-agent/2026-02-14-run + +$ 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) // (.title | capture("(?[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}' +{ "count": 13, "prs": [ ... ] } +RACE CHECK: won + +$ npm run lint +> lint passed + +Wrote: docs/agents/task-logs/daily/2026-02-14_00-12-00_nip-research-agent_completed.md +```