diff --git a/torch/README.md b/torch/README.md index a9552a92..5eef5174 100644 --- a/torch/README.md +++ b/torch/README.md @@ -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//`). +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 diff --git a/torch/examples/bitvid/META_PROMPTS.md b/torch/examples/bitvid/META_PROMPTS.md new file mode 100644 index 00000000..99804435 --- /dev/null +++ b/torch/examples/bitvid/META_PROMPTS.md @@ -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 --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 --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`. +``` diff --git a/torch/examples/bitvid/daily-scheduler.md b/torch/examples/bitvid/daily-scheduler.md new file mode 100644 index 00000000..f1627d89 --- /dev/null +++ b/torch/examples/bitvid/daily-scheduler.md @@ -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` | diff --git a/torch/examples/bitvid/scheduler-flow.md b/torch/examples/bitvid/scheduler-flow.md new file mode 100644 index 00000000..dae05892 --- /dev/null +++ b/torch/examples/bitvid/scheduler-flow.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//` + - `branch_prefix` = `agents//` + - `prompt_dir` = `docs/agents/prompts//` + +2. **MUST** run the preflight check to build the exclusion set: + + ```bash + node scripts/agent/nostr-lock.mjs check --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 | 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= \ + node scripts/agent/nostr-lock.mjs lock \ + --agent \ + --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 `/` end-to-end. + +8. **MUST** create exactly one final status file (`_completed.md` or `_failed.md`), run `npm run lint`, then commit and push. diff --git a/torch/examples/bitvid/weekly-scheduler.md b/torch/examples/bitvid/weekly-scheduler.md new file mode 100644 index 00000000..e867e63f --- /dev/null +++ b/torch/examples/bitvid/weekly-scheduler.md @@ -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` |