docs(torch): add bitvid scheduler overlay prompt pack

2026-10-27 07:52:24 +00:00 · 2026-02-13 20:21:07 -05:00
1 parent 149bd0b49e
commit 3c600771e0
@@ -7,6 +7,7 @@ This folder is a repo-ready extraction of TORCH so you can move it into a standa
 - `src/nostr-lock.mjs` — Generic lock/check/list CLI
 - `src/docs/TORCH.md` — Protocol summary and usage
 - `src/prompts/` — Generic scheduler prompts and flow
+- `examples/bitvid/` — Bitvid-specific scheduler overlay examples

 ## Drop-in notes

@@ -20,6 +21,29 @@ This folder is a repo-ready extraction of TORCH so you can move it into a standa
 4. Optionally set a namespace per repo:
   - `NOSTR_LOCK_NAMESPACE=my-project`

+## Using the bitvid example overlay in a new host project
+
+The files in `examples/bitvid/` are intentionally preserved as a concrete, real-world overlay:
+
+- `daily-scheduler.md`
+- `weekly-scheduler.md`
+- `scheduler-flow.md`
+- `META_PROMPTS.md`
+
+They include the exact bitvid command paths and full roster mappings as examples.
+
+To adapt this for another host project:
+
+1. Copy `examples/bitvid/` into your project prompt area (or duplicate it as a new overlay directory like `examples/<your-project>/`).
+2. Replace path references to your host project's structure (for example, change:
+   - `docs/agents/prompts/...`
+   - `docs/agents/task-logs/...`
+   - `node scripts/agent/nostr-lock.mjs ...`
+   to your project-specific locations).
+3. Replace daily/weekly roster tables with your own agent names and prompt filenames.
+4. Update `AGENT_PLATFORM=...` defaults in `META_PROMPTS.md` if your runtime uses a different platform value.
+5. Keep `src/prompts/*` generic; store host-specific behavior in overlays so TORCH remains portable.
+
 ## Example

 ```bash
@@ -0,0 +1,73 @@
+# Bitvid Agent Scheduler Meta Prompts (Example Overlay)
+
+This file is an extracted **bitvid-specific overlay** for TORCH meta prompts.
+
+Copy one block below into the agent session.
+
+---
+
+## Daily Scheduler Meta Prompt
+
+```text
+You are the bitvid daily agent scheduler.
+
+Follow `docs/agents/prompts/scheduler-flow.md` exactly.
+
+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/
+
+MUST 2: Run preflight to get the exclusion set:
+
+node scripts/agent/nostr-lock.mjs check --cadence daily
+
+Use the `locked` array from the JSON output as the exclusion set.
+
+MUST 3: Run these commands in this order:
+1) cat AGENTS.md CLAUDE.md
+2) ls -1 docs/agents/task-logs/daily/ | sort | tail -n 1
+3) Select next roster agent not in exclusion set
+4) Claim via Nostr lock:
+   AGENT_PLATFORM=jules node scripts/agent/nostr-lock.mjs lock --agent <agent-name> --cadence daily
+   Exit 0 = lock acquired, proceed. Exit 3 = race lost, go back to step 2.
+5) Execute selected prompt from docs/agents/prompts/daily/
+6) npm run lint
+7) Create `_completed.md` or `_failed.md`, commit, push
+
+MUST 4: 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
+
+```text
+You are the bitvid weekly agent scheduler.
+
+Follow `docs/agents/prompts/scheduler-flow.md` exactly.
+
+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/
+
+MUST 2: Run preflight to get the exclusion set:
+
+node scripts/agent/nostr-lock.mjs check --cadence weekly
+
+Use the `locked` array from the JSON output as the exclusion set.
+
+MUST 3: Run these commands in this order:
+1) cat AGENTS.md CLAUDE.md
+2) ls -1 docs/agents/task-logs/weekly/ | sort | tail -n 1
+3) Select next roster agent not in exclusion set
+4) Claim via Nostr lock:
+   AGENT_PLATFORM=jules node scripts/agent/nostr-lock.mjs lock --agent <agent-name> --cadence weekly
+   Exit 0 = lock acquired, proceed. Exit 3 = race lost, go back to step 2.
+5) Execute selected prompt from docs/agents/prompts/weekly/
+6) npm run lint
+7) Create `_completed.md` or `_failed.md`, commit, push
+
+MUST 4: If all weekly agents are excluded, stop and write `_failed.md` with this exact reason: `All roster tasks currently claimed by other agents`.
+```
@@ -0,0 +1,38 @@
+# Daily Agent Scheduler Prompt (Bitvid Example Overlay)
+
+This file is an extracted **bitvid-specific overlay** for TORCH scheduler prompts.
+
+Use `docs/agents/prompts/scheduler-flow.md` as the authoritative scheduler procedure.
+
+## Daily Cadence Configuration (Bitvid Example)
+
+- `cadence`: `daily`
+- `log_dir`: `docs/agents/task-logs/daily/`
+- `branch_prefix`: `agents/daily/`
+- `prompt_dir`: `docs/agents/prompts/daily/`
+
+## Daily Agent Roster (alphabetical order)
+
+| # | Agent Name | Prompt File |
+|---|-----------|-------------|
+| 1 | audit-agent | `bitvid-audit-agent.md` |
+| 2 | ci-health-agent | `bitvid-ci-health-agent.md` |
+| 3 | const-refactor-agent | `bitvid-const-refactor-agent.md` |
+| 4 | content-audit-agent | `bitvid-content-audit-agent.md` |
+| 5 | decompose-agent | `bitvid-decompose-agent.md` |
+| 6 | deps-security-agent | `bitvid-deps-security-agent.md` |
+| 7 | design-system-audit-agent | `bitvid-design-system-audit-agent.md` |
+| 8 | docs-agent | `bitvid-docs-agent.md` |
+| 9 | docs-alignment-agent | `bitvid-docs-alignment-agent.md` |
+| 10 | docs-code-investigator | `bitvid-docs-code-investigator.md` |
+| 11 | innerhtml-migration-agent | `bitvid-innerhtml-migration-agent.md` |
+| 12 | known-issues-agent | `bitvid-known-issues-agent.md` |
+| 13 | load-test-agent | `bitvid-load-test-agent.md` |
+| 14 | nip-research-agent | `bitvid-nip-research-agent.md` |
+| 15 | onboarding-audit-agent | `bitvid-onboarding-audit-agent.md` |
+| 16 | perf-agent | `bitvid-perf-agent.md` |
+| 17 | prompt-curator-agent | `bitvid-prompt-curator-agent.md` |
+| 18 | scheduler-update-agent | `bitvid-scheduler-update-agent.md` |
+| 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` |
@@ -0,0 +1,71 @@
+# Scheduler Flow (Bitvid Example Overlay)
+
+This file is an extracted **bitvid-specific overlay** for TORCH scheduler flow.
+
+Use this document for **all scheduler runs**. Task locking uses the **TORCH** protocol (see `docs/agents/TORCH.md`).
+
+## Scheduler Override (Top-Line Rule)
+
+During scheduler execution, the scheduler-specific instructions in this document and the cadence prompt (`daily-scheduler.md` or `weekly-scheduler.md`) **supersede generic AGENTS workflow details** when they conflict.
+
+### Global rules that still apply
+
+- Follow core safety and policy constraints (no harmful behavior, no secret exfiltration, no policy violations).
+- Do not perform destructive or irreversible actions unless explicitly required by the scheduler task definition.
+- Keep repository integrity checks (e.g., required lint/test commands in the scheduler flow) and leave an auditable log trail.
+- Respect non-interactive execution constraints and do not pause for manual approvals.
+
+### Generic AGENTS workflow details intentionally ignored for scheduler runs
+
+- The normal "one subsystem per PR" restriction, because scheduler operations are orchestration/meta-work that may touch scheduler logs, prompts, and coordination docs together.
+- The standard task-claim sequence described for general agents when it conflicts with the stricter, numbered MUST sequence below.
+- Generic start-of-task bookkeeping patterns not referenced by scheduler prompts (for example, creating extra context/todo artifacts) when they would add noise to automated scheduler runs.
+
+## Numbered MUST Procedure
+
+1. **MUST** set cadence variables before any command:
+   - `cadence` = `daily` or `weekly`
+   - `log_dir` = `docs/agents/task-logs/<cadence>/`
+   - `branch_prefix` = `agents/<cadence>/`
+   - `prompt_dir` = `docs/agents/prompts/<cadence>/`
+
+2. **MUST** run the preflight check to build the exclusion set:
+
+   ```bash
+   node scripts/agent/nostr-lock.mjs check --cadence <cadence>
+   ```
+
+   This queries Nostr relays for active lock events and returns JSON with `locked` and `available` agent lists. Use the `locked` array as the exclusion set.
+
+3. **MUST** read both policy files before selecting an agent:
+
+   ```bash
+   cat AGENTS.md CLAUDE.md
+   ```
+
+4. **MUST** run this command to identify the latest cadence log file, then choose the next roster agent not in the exclusion set:
+
+   ```bash
+   ls -1 <log_dir> | sort | tail -n 1
+   ```
+
+5. **MUST** stop and write a `_failed.md` log with `All roster tasks currently claimed by other agents` when every roster agent is excluded.
+
+6. **MUST** claim the selected agent:
+
+   ```bash
+   AGENT_PLATFORM=<jules|claude-code|codex> \
+   node scripts/agent/nostr-lock.mjs lock \
+     --agent <agent-name> \
+     --cadence <cadence>
+   ```
+
+   The script generates an ephemeral keypair, publishes a NIP-78 lock event to Nostr relays with NIP-40 auto-expiration (2 hours), and performs a built-in race check. No tokens or secrets needed.
+
+   - **Exit code 0** = lock acquired, proceed to Step 7.
+   - **Exit code 3** = race lost (another agent claimed first). Return to Step 2.
+   - **Exit code 2** = relay error. Write a `_failed.md` log with reason `Nostr relay error` and stop.
+
+7. **MUST** execute `<prompt_dir>/<prompt-file>` end-to-end.
+
+8. **MUST** create exactly one final status file (`_completed.md` or `_failed.md`), run `npm run lint`, then commit and push.
@@ -0,0 +1,33 @@
+# Weekly Agent Scheduler Prompt (Bitvid Example Overlay)
+
+This file is an extracted **bitvid-specific overlay** for TORCH scheduler prompts.
+
+Use `docs/agents/prompts/scheduler-flow.md` as the authoritative scheduler procedure.
+
+## Weekly Cadence Configuration (Bitvid Example)
+
+- `cadence`: `weekly`
+- `log_dir`: `docs/agents/task-logs/weekly/`
+- `branch_prefix`: `agents/weekly/`
+- `prompt_dir`: `docs/agents/prompts/weekly/`
+
+## Weekly 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` |