/opportunity-factory

Runtime Modes

The factory should keep working even when OpenClaw-specific features are unavailable. Treat the periodic prompts as the portable core, then choose an execution adapter.

Portable Core

Use three recurring prompt roles:

The same prompt text can run in OpenClaw, VS Code Chat, Copilot CLI, another agent runner, or a human-operated checklist.

Mode Selection

State Files

Use a workspace-local state folder such as factory-state/ or any user-provided equivalent. Avoid hardcoded absolute paths.

Suggested files:

• factory-state.json: frame, counters, learning, thresholds
• tasks-pending.json: executable queue
• tasks-done.json: completed/skipped/failed history
• artifacts/*.md: one artifact per task
• outcome-log.json: observed/estimated/assumed metrics
• pipeline-log.jsonl: append-only audit log

If the user already has a state layout, adapt to it instead of renaming everything.

Single-Cycle Automation

When the queue is small and tasks are safe/local, prefer one scheduled automation that performs commander -> one worker task -> reducer in a single run instead of separate commander and worker automations. This reduces state drift and halves scheduled runs, but only works when the cycle can safely update state.

Rules:

• Pick at most one auto-eligible task per run.
• Auto-skip tasks that require manual play, GUI-only judgment, legal/risk acceptance, publishing, payment, account creation, secrets, personal data, or long-running work.
• Before rewriting JSON array state files, create backups, parse the original, rewrite the full array, parse the result, and restore backup on failure.
• Use an append-only JSONL pipeline log for audit records.
• Acquire a short-lived lock atomically with create-new/O_EXCL semantics, or use a transactional equivalent lease; never test-then-create. If the lock is still valid, skip and log a no-op.
• Refresh lock heartbeat during long work and remove the lock in a finally/guaranteed-cleanup path when the adapter supports it.
• If the heartbeat is expired beyond the recovery threshold, reconcile the selected task, expected artifact, target files, done history, and pipeline log before the next run. A stale in_progress string is not proof that a worker is still alive.
• When target files changed but the required artifact/verification is missing, preserve the partial files, return the task to pending (or a dedicated recovery state), and require bounded re-verification; never mark it done from side effects alone.
• Mark a task done only when its artifact contains evidence that the success metric was met; otherwise leave it pending or blocked.

Cadence Defaults

Start conservative and tune after the first few cycles:

• commander: every 15-60 minutes
• worker: every 15-120 minutes, depending on task cost
• reporter-learner: every 6-24 hours
• workflow-review: weekly, or after 10-20 artifacts if the factory is moving quickly

For manual operation, run one commander, one worker, then one reporter-learner after a few artifacts exist.

Scheduler Presets

Use these as starting points when the environment can run scheduled prompts or jobs. Replace command placeholders with the local agent runner.

For surface-specific setup across GitHub Copilot App, GitHub Copilot CLI, Microsoft Scout, VS Code GitHub Copilot Chat, OpenClaw, and GitHub Actions, first use references/workspace-setup.md to verify capabilities and state persistence.

Registration and Migration

Applies to every preset below.

• Register disabled, verify, then enable. Re-read each job back from the scheduler and compare name, cadence, scope, and prompt path against the intended values. Enable outside the window where a job is about to fire, so the first run does not start mid-setup.
• Make durable state true before enabling, not after. The first scheduled run reads that state, and a post-enable edit races with it.
• Job IDs are host-bound. Record host, registration time, and enabled/disabled status beside each job in dashboard state. On a new host, re-register and re-verify instead of trusting recorded IDs, and confirm the scheduler entry actually exists rather than believing the dashboard's claim.
• A scheduler may keep its own copy of the prompt even when configured to point at a prompt file. Editing the file then leaves the scheduled copy stale, so update the job too whenever the prompt's invoked commands or contract change.
• Expect optimistic concurrency. A create/update can be rejected because another window changed the task list. That rejection means nothing was written, so reload and retry once instead of assuming a partial apply.
• Verify runtime dependencies by executing them on this host before enabling anything unattended: interpreter version, required libraries, browser/driver binaries, and the timezone database when day-boundary logic uses IANA zone names. A missing dependency turns every unattended run into a silent failure.

Conservative Default

Use this first for a new factory or expensive model/tool stack.

OpenClaw / Cron

Best for unattended operation with isolated sessions and shared state.

Rules:

• Run worker prompts in isolated sessions when possible.
• Give each specialist worker a narrow capability or task kind.
• Keep external publish, paid actions, account creation, and secret access behind human approval.

Hosted Agent Scheduler

Use this for scheduler-capable hosted agent environments. Examples might include Copilot Scheduler, GitHub Copilot App, Microsoft Scout, or similar products when the current product version actually supports recurring prompts/jobs.

Rules:

• Treat the hosted platform as an execution adapter, not as the factory design itself.
• Verify where state persists: repo files, platform memory, issue/discussion, database, artifact storage, or external workspace.
• Prefer platform-native approvals for publish, payment, account, secret, personal-data, and policy-risk actions.
• If the platform cannot write durable artifacts, have workers return artifact text and let commander persist or propose persistence.
• Do not assume product-specific feature names; map whatever the platform offers to commander, worker, and reporter-learner.
• For small queues, a single-cycle hosted automation can replace separate commander/worker jobs if JSON state updates are backed up, validated, and locked.

Copilot Scheduler (VS Code Extension)

Use this when the VS Code Copilot Scheduler extension is installed and the factory should run as scheduled Copilot Chat prompts in a workspace.

Settings and task options to verify:

• Task scope is workspace, not global, unless intentionally shared.
• Prompt templates point to local .github/prompts/*.md, the configured global prompts folder, or inline prompt text.
• Do not assume per-task model selection exists. Verify the task schema. In at least one observed extension version it is absent, so scheduled runs resolve the model from the editor's current default and model choice has to happen inside the prompt by launching subagents with an explicit model. Record the adapter version and the observed model-resolution behavior in the setup output rather than trusting this note.
• Max Runs/Day, allowed time window, jitter, and minimum interval warnings are configured.
• Notification mode and execution history are configured for low noise.
• auto-mode or autonomous-execution hints are enabled only after preflight passes.
• Copilot usage and acceptable-use limits are respected; avoid excessive automated bulk activity.

Treat Copilot Scheduler as a VS Code adapter. It schedules prompt execution; the factory still needs durable state, artifacts, approval boundaries, and validation.

An editor-hosted scheduler only fires while the editor is running. For unattended cadences, add an OS-level pre-stage job that opens the workspace before the first scheduled prompt, and make its "already open" detection fail-open: a false positive silently kills every downstream run, while a false negative only reopens a window the editor already reuses. Duplicate work from reopening is absorbed by the worker singleton lock, not by the detection heuristic (see lifecycle-and-health.md ## Lock Scopes).

Generic Cron / CLI Scheduler

Use when any command-line agent can be invoked from cron, systemd timer, launchd, or another scheduler.

# placeholders only; replace <run-prompt> with the local runner
0 * * * * <run-prompt> assets/prompts/commander.md
15 */2 * * * <run-prompt> assets/prompts/worker.md
0 9,17 * * * <run-prompt> assets/prompts/reporter-learner.md

Keep state paths configurable. Do not embed machine-specific absolute paths in prompt files.

Windows Task Scheduler

Use for a Windows workstation or always-on desktop.

Prefer a small PowerShell wrapper that calls the local agent runner with a prompt file. If Task Scheduler cannot be registered, use a user-level startup/keepalive mechanism only after confirming it will not spawn duplicate loops.

GitHub Actions

Use only for low-frequency, repo-safe automation.

Rules:

• Treat runners as ephemeral; persist state as repository files, artifacts, issues, or external storage.
• Avoid external publishing, payments, account creation, and secret-dependent actions unless explicitly approved.
• Keep GitHub-hosted runner minutes and API rate limits in the runtime limits.

Manual Supervised Loop

Use when no scheduler is available or when testing a new factory.

commander -> worker -> worker -> reporter-learner

Run the reporter after two or more artifacts exist, or when a blocker appears.

Operating Profiles

Do not use burst mode without daily run limits and a clear stop condition.

AI-Autonomous Preset (ai-autonomous)

ai-autonomous preset は Autonomy Mode 別に skill 全体を自律運用するための SSOT preset。既定は AUTO、setup で mode 未指定なら Phase 1 で必ず user に確認する。

既定値 (all reference default, tunable)

Adapter 例示 (実選択は環境依存)

• Copilot Scheduler (VS Code Extension)
• Microsoft Scout Automation
• OpenClaw
• GitHub Copilot App
• GitHub Actions
• Windows Task Scheduler
• cron / Generic CLI Scheduler
• Manual Supervised Loop

各 adapter の設定例は本ファイル ## Scheduler Presets セクション参照。

Tune Apply by Autonomy Mode (SSOT)

この table が Autonomy Mode 別の tune apply 動作の SSOT。references/tunable-defaults.md はこの table を参照する。

Rule:

• どの mode でも hard rule 変更疑いは security-approve に escalate、user 明示承認まで proceed 不可
• Reference default 変更は tunable-defaults.md の一覧項目のみ、hard rule 侵食禁止
• 3 サイクル追跡の baseline / 悪化閾値は tunable-defaults.md 参照

Workflow-review Dispatch

• 通常: weekly cadence
• Ad-hoc: 以下 trigger で hourly cycle 内でも dispatch (詳細: references/tunable-defaults.md "Workflow-review Dispatch" 節)
  • Blocker Test 4/4 escalation が 24h で 3 件以上
  • Anti-pattern registry の同一 fingerprint count が K=3 到達
  • Discovery Floor trigger が 3 サイクル連続でも新規 candidate 流入ゼロ
  • criticLog の Layer 3 reject が 24h で 2 件以上

Invariant Check (Hard Rule 誤変更抑止)

Workflow-review が weekly + ad-hoc で以下 invariant を check、違反検出時は dashboard-state.hardRuleViolationLog に append + user notify + revert 提案:

1. references/approval-policy.md に auto / security-approve 見出し両方 present か
2. references/rubber-duck-review.md の "Layer 3 Blocking Critic" 節に 5 gate 全部 present か
3. references/fallback-lane.md の Auto-Refill 契約節 present か
4. references/persistence-profile.md の 3 profile 全部定義 present か
5. SKILL.md の "Tunable vs Hard Rules" 節 present か
6. references/rubber-duck-review.md に "Repair -> Re-review Contract" と blocked-independence があり、reviewRepairRounds が 3〜20、independenceBlockLimit が 1〜5 を維持しているか

詳細と対処: references/tunable-defaults.md "Hard Rule 誤変更抑止 (Invariant Check)" 節。

See Also

• references/tunable-defaults.md: reference default 一覧 + hard rules + Autonomy Mode 別動作
• references/approval-policy.md: 2 バケット詳細
• references/rubber-duck-review.md: Layer 3 gate SSOT
• references/fallback-lane.md: fallback lane / Discovery Floor / Auto-Refill
• references/persistence-profile.md: 3 profile / class mapping
• references/dashboard-state.md: tuningLog / hardRuleViolationLog schema

Runaway Controls

Every scheduled setup should define these controls in state or scheduler configuration:

Commander must not add work when limits are exceeded. Reporter-learner should surface limit hits and recommend lowering cadence, increasing budget, or pruning stale work.

OpenClaw-Specific Behavior

OpenClaw can run this as unattended cron pulses, but the skill must not require OpenClaw.

When OpenClaw is present:

• map commander to the orchestrator agent
• map worker to one or more specialist agents
• map reporter-learner to the reporting/orchestrator agent
• keep worker outputs artifact-only
• keep shared state updates single-writer

When OpenClaw is absent, preserve the same contracts and run the prompts through whatever execution mechanism is available.

Stop and Ask

Stop unattended execution and ask the user when:

• external publishing, payment, account creation, or secret write/issue/delete/external send is required
• repeated blockers pass the configured threshold
• the factory cannot persist state or artifacts
• the next step could create legal, safety, privacy, or platform policy risk
• the success metric cannot be observed or estimated honestly

Do not stop merely because local/private work needs review. Inside a durable user-approved autonomy envelope, reviewer PASS plus an explicit queue item may advance the next task. On review reject/ambiguity, revise, narrow, re-review, or use a fallback lane before asking; escalate only after bounded retries fail or a security-approve boundary is reached.