omniconductor 0.3.0

package/core/recipes/i18n.md

@@ -0,0 +1,118 @@
+---
+recipe_id: i18n
+recipe_name: "Multi-locale translation key sync"
+applies_when: "project supports 2+ locales for user-facing text"
+severity: ABSOLUTE (when installed)
+linked_rules:
+  - quality-gates
+  - spec-as-you-go
+---
+
+# Recipe — i18n Multi-Locale Sync
+
+> Opt-in recipe. Install when the project supports 2+ locales. The originating project supports 8 locales (en, ko, ja, zh, es, fr, de, pt); the rule generalizes to N.
+
+## 1. The N-locale rule
+
+When new user-facing text is added to ANY surface, translation keys for ALL supported locales MUST be added in the same PR. Partial coverage (e.g., en + ko added, others left empty) is treated as INCOMPLETE.
+
+### 1.1 Why all-locales-or-none
+
+Partial coverage produces UI fallback chaos: some locales render the new text, others render the key string or fall back to en, the user thinks the feature is broken in their language. The rule eliminates the partial state entirely.
+
+### 1.2 Locale list (project-specific)
+
+The project's rule index lists the supported locales explicitly. The originating project's list:
+
+```
+en, ko, ja, zh, es, fr, de, pt
+```
+
+The recipe is the rule; the locale list is the parameter.
+
+## 2. Source-of-truth + per-app copies
+
+The originating project's organization (used as a reference pattern):
+
+```
+packages/shared/src/i18n/translations.ts   ← source of truth
+<web-app>/lib/i18n/translations.ts          ← web local copy (always synced)
+<mobile-app>/...                            ← mobile imports from shared package directly
+```
+
+### 2.1 Why a web local copy
+
+Web build does not always resolve shared package imports at runtime in the same way as mobile. The local copy is the runtime artifact for web. The build process MAY automate the copy, but the copy still needs to land in source control and be auditable.
+
+### 2.2 Sync verification
+
+A pre-build script verifies the two files are byte-identical (or otherwise structurally consistent). Production project example: `scripts/check-i18n-sync.mjs` runs sha256 byte-diff on the source-of-truth and the local copy, blocking the build if they diverge.
+
+### 2.3 Why pre-build (not pre-commit)
+
+Pre-commit catches local divergence but not divergence introduced by an external PR or merge conflict resolution. Pre-build catches both. The cost is one fast file read on every build.
+
+## 3. The "empty key" anti-pattern
+
+Adding `helpFaq.q1: ""` (empty string) for some locales is NOT acceptable. The user sees a blank UI. Either:
+
+- Provide a real translation (preferred — use AI translation as draft, human-review later if needed).
+- Fall back to en explicitly via the i18n library's fallback chain (so the user sees English text, not blank).
+- Don't ship the key until all locales have content.
+
+## 4. Component contract
+
+Every user-facing string MUST go through the i18n hook (e.g., `useTranslation()`). Hardcoded strings are forbidden by `coding-conventions.md` (recipe). The pattern:
+
+```tsx
+// WRONG
+<Button>Save plan</Button>
+
+// RIGHT
+const { t } = useTranslation();
+<Button>{t("plan.save")}</Button>
+```
+
+This applies to every visible string, including:
+
+- Button labels.
+- Page titles.
+- Form placeholders.
+- Error messages (the i18n key, NOT the raw error from a service).
+- Toast messages.
+- ARIA labels (translated, not hardcoded).
+
+## 5. Adding a new translation key — checklist
+
+For every new key:
+
+- [ ] Added to source-of-truth file with all N locales populated.
+- [ ] Local copies (per-app) synced.
+- [ ] Sync-check script (if installed) passes.
+- [ ] Component uses the key via `t()`.
+- [ ] No hardcoded English string remains as a placeholder.
+
+## 6. Adding a new locale
+
+Adding a new locale (e.g., the project decides to support `it`):
+
+- [ ] Add the locale code to the locale list in the rule index.
+- [ ] Add `it` keys to every existing translation key in the source-of-truth.
+- [ ] Update fallback chain configuration.
+- [ ] Update language-picker UI (if user-selectable).
+- [ ] Update any locale-specific assets (date format, number format, RTL handling if applicable).
+
+## 7. Cross-tool enforcement
+
+| Mechanism | Where |
+|---|---|
+| Pre-build sync check | `scripts/check-i18n-sync.mjs` (or equivalent) — blocks build on divergence |
+| Pre-commit review | Reviewer checklist item: "all locales added?" |
+| TypeScript | Strongly-typed key set (translation hook returns errors for unknown keys) |
+| Rule text | This recipe text, loaded into the tool's rule context |
+
+## 8. Production failure example
+
+Documented failure: a PR added 96 keys to the source-of-truth for one locale, but the web local copy was missing those 96 keys. Pre-build sync check caught it before the PR merged. Without the sync check, the prod build would have failed at runtime in that locale only — likely undetected for hours.
+
+The pre-build sync check is the single most cost-effective i18n investment a multi-locale project can make.

package/core/recipes/monorepo.md

@@ -0,0 +1,101 @@
+---
+recipe_id: monorepo
+recipe_name: "Monorepo structure with shared package"
+applies_when: "project uses npm workspaces (or equivalent) with shared code between apps"
+severity: STRONG (when installed)
+linked_rules:
+  - workflow
+---
+
+# Recipe — Monorepo Structure
+
+> Opt-in recipe. Install when the project uses npm workspaces (or pnpm / yarn workspaces / turborepo) with shared code between multiple deployable apps. Do NOT install on single-app projects.
+
+## 1. The frozen folder structure rule
+
+Once the monorepo's top-level structure is set (apps + packages + root config), DO NOT change it without explicit authorization.
+
+### 1.1 Why "frozen"
+
+Folder restructures invalidate every cached path: TypeScript paths, IDE workspaces, deploy pipelines, test selectors, documentation references. The cost of a restructure is high enough that "let's clean this up" is not a sufficient justification.
+
+The originating project recorded this as an explicit user instruction: "do not change current monorepo folder structure". The rule generalizes.
+
+## 2. Reference structure (originating project)
+
+```
+project-root/
+├── apps/
+│   ├── web/             ← Next.js app (or equivalent)
+│   └── mobile/          ← React Native / Expo app (or equivalent)
+├── packages/
+│   └── shared/          ← Shared business logic, types, constants, i18n source-of-truth
+├── docs/                ← All project documentation
+├── .claude/ (or .cursor/ / .github/instructions/ / .windsurf/)
+├── package.json         ← root with `workspaces` config
+└── ...
+```
+
+This is the reference, not the mandate. Adopters with different conventions (e.g., turborepo with `packages/web`, `packages/mobile`) follow the same principle: freeze the top-level layout once decided.
+
+## 3. Shared package contract
+
+Code that goes in `packages/shared`:
+
+- Business logic that runs identically on both surfaces.
+- Type definitions consumed by both surfaces.
+- Constants (rate limits, feature names, error codes).
+- i18n source-of-truth (per `recipes/i18n.md`).
+
+Code that does NOT go in `packages/shared`:
+
+- Surface-specific UI components (web: `<web-app>/components/`; mobile: `<mobile-app>/src/components/`).
+- Surface-specific hooks that depend on platform APIs.
+- Build / deploy configuration.
+
+## 4. Import direction
+
+```
+<web-app>/        →  imports from packages/shared  (one-way)
+<mobile-app>/     →  imports from packages/shared  (one-way)
+packages/shared/  →  imports nothing from apps/    (HARD RULE)
+```
+
+Reverse imports (shared importing from apps/) create build-order cycles and defeat the purpose of the shared package.
+
+### 4.1 Web's "imports from shared" caveat
+
+On some build setups, the web app does NOT import from `packages/shared` directly at runtime — instead it consumes a local copy (this is the i18n recipe's pattern). Whether direct import or local copy is the right pattern depends on the deploy target's module resolution semantics. The recipe documents the convention; the project's own tooling makes it work.
+
+## 5. Code duplication between apps
+
+Duplicated business logic between the web and mobile surfaces is FORBIDDEN. If two surfaces have the same logic, it belongs in `packages/shared`.
+
+The reviewer role's checklist (`roles/reviewer.md`) includes a "no duplicated business logic" check. The check is performed by reading the diffs for both surfaces and looking for parallel logic.
+
+## 6. Test organization
+
+```
+<web-app>/e2e/
+├── functional/      ← E2E functional specs
+├── visual/          ← Visual smoke specs
+└── pages.ts         ← Page catalog for visual smoke
+
+<mobile-app>/__tests__/   ← Mobile-specific
+packages/shared/__tests__/  ← Unit tests for shared logic
+```
+
+Test execution is per-app (each `package.json` has its own test script). Root `package.json` has aggregate scripts that run all apps.
+
+## 7. Deploy pipeline implications
+
+Each app deploys independently. Changes to `packages/shared` trigger redeploys of every app that imports it. CI configuration MUST handle this — typically by running every app's build when shared changes.
+
+## 8. Cross-tool enforcement
+
+| Mechanism | Where |
+|---|---|
+| Folder structure freeze | Rule text + reviewer checklist |
+| Import direction | TypeScript compiler (with `paths` config) + lint rule (e.g., `import/no-internal-modules`) |
+| Duplication check | Reviewer role manual check |
+| Build coupling | CI configuration (per-app build matrix) |

package/core/recipes/self-improvement.md

@@ -0,0 +1,61 @@
+---
+recipe_id: self-improvement
+recipe_name: "Self-Improvement (Reflector, propose-only)"
+applies_when: "a project wants periodic, human-approved distillation of session lessons into its memory/rules"
+severity: STRONG (when installed)
+linked_rules:
+  - meta-discipline
+  - operations
+---
+
+# Recipe — Self-Improvement (Reflector)
+
+> Opt-in recipe. Install when you want CONDUCTOR to periodically read your recent sessions and PROPOSE lessons for your memory/rules. It never applies anything automatically. Do NOT install if you do not want a retrospective step — there is no silent learning here by design.
+
+## The loop
+
+```
+Observe → Reflect → Propose → (human GO) → Apply
+```
+
+- **Observe** — a stop-hook logs a trajectory pointer each session (Claude adapter); git history and `docs/CURRENT_WORK.md` are always-available fallbacks.
+- **Reflect** — the `reflector` role reads the period's trajectories (success AND failure) and distils atomic lessons.
+- **Propose** — the reflector appends `ADD/UPDATE/STALE` deltas to `docs/REFLECTION-PROPOSALS.md`. This is the ONLY output. Nothing is written to memory or rules.
+- **Apply** — a human reviews the proposals like a diff and accepts/edits/rejects. On acceptance, the lesson becomes a `feedback_lesson-*.md` memory entry (see `core/memory-pattern/README.md`).
+
+## Safety contract (read first)
+
+- **Propose-only.** The reflector must never edit rules, memory, or code. Applying is a human decision.
+- **Grounded-or-dropped.** Every proposed lesson cites a trajectory; un-cited lessons are discarded.
+- **Delta, never rewrite.** Lessons are atomic items merged/pruned by a deterministic script, never by rewriting a whole file. This prevents "context collapse" (accumulated detail eroded by repeated full rewrites).
+
+## Cadence
+
+Run weekly (batch), or on demand via `/reflect`. To automate the weekly run, register the emitted `.conductor/reflect/run-weekly.sh` with a scheduler — see `.conductor/reflect/SCHEDULING.md` for per-tool instructions (OS cron/launchd is the universal local path). Reflection must not exceed the rule-file-edit budget in `core/anti-patterns/frequent-rule-file-edit.md` (more than 3 rule-file commits/week is itself a smell) — batch proposals, do not drip per-session edits.
+
+## Trajectory sources (precedence)
+
+1. Session transcript (richest) — via `.conductor/trajectories/index.jsonl`.
+2. git history — universal.
+3. Retro artifact — `docs/CURRENT_WORK.md`, `docs/sessions/*`.
+
+## Per-tool automation
+
+- **Claude**: the `stop-trajectory-log` hook records pointers; a scheduled run (Routines / Desktop Scheduled Task / cron → `claude -p`) invokes the reflector weekly; `.conductor/reflect/prune-lessons.sh` keeps the store bounded; `/reflect` runs it on demand.
+- **Other tools**: the WHAT above is identical. Each adapter emits the trajectory hook, the native `/reflect` command, the reflector agent/rule, `.conductor/reflect/prune-lessons.sh`, and `.conductor/reflect/run-weekly.sh` + `reflect-brief.md` + `SCHEDULING.md`. Register `run-weekly.sh` with OS cron/launchd (or a native local scheduler where available) per `SCHEDULING.md`; the universal floor is running `/reflect` manually.
+
+## Bounded store (deterministic prune)
+
+`.conductor/reflect/prune-lessons.sh` (non-LLM) decays lessons unused for K weeks to `status: stale`, and marks-stale lessons whose provenance path no longer exists. It never deletes a lesson — only exact byte-duplicate files are removed (no information is lost). It is idempotent. This is the anti-collapse guarantee. (Non-destructive marking matches the propose-only philosophy: an unattended script must not destroy user memory.)
+
+## Conductor Integration
+
+**meta-discipline (M1 originality / M2 token economy)**: the reflector reads with ranges and map-then-reduce; proposals are original, grounded distillations, not copied text.
+
+**operations (O1 real-time docs sync)**: accepted lessons and the proposals file are part of the project's documentation state.
+
+## Cross-References
+
+- `core/roles/reflector.md` — the actor this recipe drives.
+- `core/memory-pattern/README.md` — the `feedback_lesson-*` file format proposals target.
+- `core/anti-patterns/frequent-rule-file-edit.md` — the edit-budget guardrail.

package/core/recipes/tdd.md

@@ -0,0 +1,128 @@
+---
+recipe_id: tdd
+recipe_name: "Test-Driven Development (Red-Green-Refactor)"
+applies_when: "project has a test framework (vitest / jest / pytest / etc.) and wants TDD methodology enforced across feature work, bug fixes, and refactors"
+severity: STRONG (when installed)
+linked_rules:
+  - spec-as-you-go
+  - quality-gates
+---
+
+# Recipe — Test-Driven Development
+
+> Opt-in recipe. Install on projects with an established test framework where TDD discipline is a team standard. Do NOT install on throwaway prototypes or projects with no testing infrastructure — adopt the test framework first.
+
+## When to Apply
+
+Every development activity that changes behavior:
+
+- **New feature** — write the test before writing production code
+- **Bug fix** — write a failing test that reproduces the bug; then fix it
+- **Refactor** — green test suite is the safety net; refactor to keep it green
+- **Behavior change** — update the test first to reflect the new expected behavior
+
+Exceptions (discuss with your human partner before skipping):
+
+- Throwaway exploration / spike — throw away the spike code; start fresh with TDD
+- Generated / scaffolded code — add behavior tests before modifying generated output
+- Configuration files with no testable behavior
+
+## Pattern — Red-Green-Refactor
+
+The TDD cycle has three phases. Each phase has an explicit STOP-AND-VERIFY step that cannot be skipped.
+
+### RED — Write One Failing Test
+
+Write the smallest test that describes a single desired behavior. Run the suite and confirm the test fails for the right reason (missing feature, not a syntax error).
+
+```bash
+# vitest
+npx vitest run path/to/file.test.ts
+
+# jest
+npx jest path/to/file.test.ts
+
+# pytest
+pytest tests/test_feature.py::test_specific_case -v
+```
+
+A test that passes immediately proves nothing — it was either testing existing behavior or testing the wrong thing. If it passes on first run, fix the test.
+
+### GREEN — Minimal Implementation
+
+Write the simplest code that makes the failing test pass. "Simplest" means: no speculative features, no generalization the test does not require, no YAGNI extensions. If the test passes with three lines, ship three lines.
+
+Do not refactor during Green. Refactoring while Red is still on the board is how the cycle breaks.
+
+```bash
+# Watch mode for rapid Red → Green iteration
+npx vitest --watch path/to/file.test.ts
+pytest-watch tests/
+```
+
+After the test passes, run the full suite to confirm no regression.
+
+### REFACTOR — Clean Up, Stay Green
+
+With Green confirmed, remove duplication, improve names, extract helpers. Every refactor step must keep the suite green. Refactoring does not mean adding new behavior — that starts a new Red phase.
+
+Commit discipline: keep Red, Green, and Refactor as separate commits when the history is audited. This is an option, not a hard requirement — but it makes rollback and review significantly cleaner.
+
+## Canonical Cycle for a Bug Fix
+
+1. Reproduce the bug with a deterministic, minimal failing test
+2. Confirm the test fails with the exact error message the bug produces
+3. Write the minimal fix
+4. Confirm the test passes; run the full suite
+5. Refactor the fix if the implementation is rough
+
+Never fix a bug without a test. A fix without a test is a guess that happened to work today.
+
+## Sub-Agent Dispatch Ordering
+
+When delegating implementation via sub-agents, the brief MUST specify this sequence:
+
+1. Write the failing test(s) first
+2. Implement until the tests pass
+3. Run the full suite and confirm green
+4. Report test output as proof of completion
+
+A sub-agent that returns "implemented X" without test output has not completed the task.
+
+## Conductor Integration
+
+**spec-as-you-go (W3)**: Tests are executable specs. When a feature's behavior changes, the test changes first. The spec doc and the test should describe the same invariants.
+
+**quality-gates (Q1 pre-commit)**: Test passage is a pre-commit gate. The gate is not "tests exist" — it is "tests run green." Both conditions are required.
+
+**workflow.md W2 (build phase)**: Every W2 implementation task applies this recipe's Red-Green-Refactor cycle. The plan should include an explicit "write failing tests first" step in the W2 brief.
+
+## Anti-Patterns
+
+| Anti-pattern | Why it breaks TDD |
+|---|---|
+| Write implementation first, tests after | Tests-after answer "what does this do?" Tests-first answer "what should this do?" Tests-after are biased by the implementation you just wrote. |
+| Write 10+ failing tests in one Red phase | Massive Red phases extend the feedback loop and make root cause diagnosis harder when Green fails. Write one test at a time. |
+| Mock-heavy tests that never touch real code | Tests that exercise only mock return values give false confidence. Use real code paths; mock only unavoidable I/O boundaries (network, filesystem, clock). |
+| "Too simple to test" rationalization | Simple code breaks in context. The test costs 30 seconds. |
+| Refactoring during the Red phase | You cannot safely refactor against a failing test. Always refactor from Green. |
+| Keeping unverified "reference" implementation | Once you have reference code, you will adapt it instead of deriving from the test. Delete it. Start from the test. |
+
+## Verification Checklist
+
+Before marking any task complete:
+
+- [ ] Every new function or method has a test that was written first
+- [ ] Watched each test fail before implementing
+- [ ] Each test failed for the expected reason (feature absent, not typo)
+- [ ] Wrote minimal code to pass each test
+- [ ] All tests pass
+- [ ] No warnings or errors in test output
+- [ ] Tests cover edge cases and error paths (not just happy path)
+
+## Cross-References
+
+- `core/universal-rules/spec-as-you-go.md` — tests as executable specs; same-turn update rule
+- `core/universal-rules/quality-gates.md` — Q1 pre-commit: test green is a hard gate
+- `core/recipes/debugging.md` — when a test fails during investigation, this recipe owns the fix cycle
+- Red-Green-Refactor is Kent Beck's method; this recipe is independently written. Its structure was informed in part by the **Superpowers** project (idea-level; no text reproduced) — see `THIRD_PARTY_NOTICES.md`.

package/core/recipes/web-mobile-parity.md

@@ -0,0 +1,87 @@
+---
+recipe_id: web-mobile-parity
+recipe_name: "Web ↔ Mobile feature and bug parity"
+applies_when: "project has both web and mobile surfaces sharing user-facing features or business logic"
+severity: ABSOLUTE (when installed)
+linked_rules:
+  - workflow
+  - quality-gates
+---
+
+# Recipe — Web ↔ Mobile Parity
+
+> Opt-in recipe. Install when the project has both web and mobile surfaces. Do NOT install on web-only or mobile-only projects.
+
+## 1. Feature parity (P1)
+
+Every user-facing feature MUST be developed for both web and mobile in the same iteration. Pair-development is the default; one-surface-only is an explicit exception that requires a written justification (a one-line note in CURRENT_WORK.md is sufficient).
+
+### 1.1 Why pair-development
+
+If web ships first, mobile parity gets deprioritized indefinitely. The originating project tracked this and found that "mobile follow-up" tasks aged out at a 60% rate within 3 months. Pairing eliminates the queue entirely.
+
+### 1.2 Acceptable single-surface exceptions
+
+- Admin features (web-only by policy — admins don't operate from mobile).
+- Experimental features behind a feature flag (mobile waits for the flag to flip).
+- Surface-specific hardware integrations (camera, biometrics — mobile only).
+- Marketing pages (web only).
+
+### 1.3 Pair-development workflow
+
+For a feature touching user-facing flow:
+
+1. Planner produces design with explicit web + mobile section.
+2. Builder dispatch implements both surfaces in same logical task. (Mechanically may be 2 sub-tasks, but they share a single task ID.)
+3. Tests cover both surfaces (web E2E + mobile E2E or equivalent).
+4. Pre-commit review covers both diffs.
+5. Spec update mentions both surfaces.
+
+## 2. Bug-fix parity (P2 — ABSOLUTE)
+
+When a bug is found on one surface, the orchestrator MUST verify whether the same bug exists on the other surface and fix BOTH in the same PR.
+
+### 2.1 The half-fix anti-pattern
+
+The single most-violated rule in the originating project's history. A bug was reported on web; the orchestrator fixed web; the user found the same bug on mobile two days later. This pattern repeated until the rule was promoted to ABSOLUTE.
+
+### 2.2 Verification protocol
+
+When a bug is reported:
+
+1. Reproduce on the reported surface.
+2. **Before fixing**: check whether the same bug exists on the other surface. (`grep` for the same logic, run the same scenario.)
+3. If yes: fix both in the same PR.
+4. If no: state explicitly in the commit message that the other surface was checked and found unaffected.
+
+### 2.3 Why "before fixing"
+
+Fixing on one surface first means the orchestrator's mental model is loaded with that surface's code. Switching contexts to the other surface afterward is harder; the rule treats both surfaces as the same diagnostic context.
+
+## 3. Code organization to support parity
+
+| Pattern | Rationale |
+|---|---|
+| Shared business logic in a shared package (e.g., `packages/shared`) | Single source of truth → no drift. |
+| Shared types and constants in shared package | Type drift between surfaces is the worst kind. |
+| Surface-specific UI in `<web-app>/` and `<mobile-app>/` | Surfaces have different UI primitives; that's correct. |
+| Translation source-of-truth in shared package, with per-app local copies kept in sync | Web build doesn't depend on shared package import resolution at runtime; the local copy is the runtime artifact. |
+
+The `recipes/monorepo.md` recipe describes the npm-workspaces structure that makes this organization practical.
+
+## 4. Test coverage parity
+
+If a flow has a web E2E test, the mobile equivalent flow MUST have a mobile E2E test (or documented reason why not — typically "mobile uses native components that web E2E doesn't exercise").
+
+The `recipes/i18n.md` recipe handles the translation-key parity concern (8-locale or N-locale sync between web and mobile).
+
+## 5. Cross-tool enforcement
+
+| Mechanism | Enforcement |
+|---|---|
+| Shared package import structure | TypeScript compiler at build time |
+| E2E test coverage | CI test runner |
+| Bug-fix parity | Rule text + pre-commit review (Q1) prompts |
+| Pair-development | Planner gate + reviewer checklist |
+
+This recipe has no automated cross-surface check beyond rule text. The reviewer role is the final gate that catches single-surface PRs that should have been pair-developed.

package/core/reflector/SCHEDULING.md

@@ -0,0 +1,83 @@
+# Scheduling the weekly Reflector
+
+The Reflector is **propose-only** — a scheduled run reads `.conductor/trajectories/index.jsonl`
++ git history and appends proposals to `docs/REFLECTION-PROPOSALS.md`. It applies nothing.
+Nothing here auto-registers a schedule (that is a machine/user-level action a repo installer
+cannot do for you); this documents how to register the runner CONDUCTOR emitted:
+
+    .conductor/reflect/run-weekly.sh
+
+It auto-detects the first supported CLI on `PATH`
+(`claude` → `codex` → `gemini` → `cursor-agent` → `copilot` → `devin`).
+Force one with `CONDUCTOR_REFLECT_CLI=<cli>`; preview with `CONDUCTOR_REFLECT_DRYRUN=1`.
+
+> **Local vs cloud — the one rule that matters.** The trajectory log lives locally under
+> `.conductor/` (typically git-ignored). A **cloud** scheduler runs on a fresh clone and
+> **cannot see it**. So for local-trajectory reflection, use a **local** scheduler:
+> OS cron / launchd, Claude Desktop scheduled tasks, or Codex app automations.
+> Cloud schedulers (Cursor Automations, Copilot cloud automations, Devin Scheduled Sessions)
+> only work if you commit `.conductor/trajectories/` — not recommended.
+
+## Universal: OS cron / launchd (works on every tool, local files)
+
+`cron` — weekly, Mondays 09:00 (edit `crontab -e`), using an absolute project path:
+
+    0 9 * * 1  cd /abs/path/to/project && ./.conductor/reflect/run-weekly.sh >> .conductor/reflect-weekly.log 2>&1
+
+macOS `launchd` — a `~/Library/LaunchAgents/conductor-reflect.plist` `StartCalendarInterval`
+entry (Weekday 1, Hour 9) invoking the same script. Dry-run first:
+
+    CONDUCTOR_REFLECT_DRYRUN=1 ./.conductor/reflect/run-weekly.sh
+
+## Native local schedulers (best where available)
+
+- **Claude Code — Desktop Scheduled Tasks** (local; sees uncommitted files; weekly picker).
+  Create a task whose prompt is `/reflect` (Desktop app must be open, machine awake). The
+  cloud "Routines" run on a fresh clone → they will NOT see local trajectories.
+- **Codex — app Automations** (local project, `cron` syntax, invokes saved skills). Create a
+  weekly automation running the `$reflect` skill against the local project (Codex app must be
+  running, project present on disk).
+
+## Cloud schedulers — trajectory-blind (avoid for local reflection)
+
+Cursor **Automations**, Copilot **cloud** automations, and Devin **Scheduled Sessions** run in a
+cloud clone and cannot read un-committed `.conductor/`. Use OS cron locally instead. (Copilot's
+desktop app also has *local* automations, which can work like the OS-cron path.)
+
+## CI: GitHub Actions (cron) — only if trajectories are committed
+
+A workflow runs on a fresh checkout, so `.conductor/trajectories/index.jsonl` must be committed
+(or restored from an artifact), and the resulting `docs/REFLECTION-PROPOSALS.md` committed/PR'd
+back. Per-tool official actions + `on: schedule`:
+
+    # Claude
+    - uses: actions/checkout@v4
+    - uses: anthropics/claude-code-action@v1
+      with: { prompt: "/reflect", anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} }
+
+    # Gemini
+    - uses: google-github-actions/run-gemini-cli@v0
+      with: { prompt: "/reflect", gemini_api_key: ${{ secrets.GEMINI_API_KEY }} }
+
+    # Codex
+    - uses: openai/codex-action@v1
+      with: { prompt: "Run the $reflect skill", openai-api-key: ${{ secrets.OPENAI_API_KEY }} }
+
+    # Copilot
+    - run: npm i -g @github/copilot && copilot -p "$(cat .conductor/reflect/reflect-brief.md)" --allow-tool=write --no-ask-user
+      env: { COPILOT_GITHUB_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }} }
+
+(Trigger with `on: { schedule: [{ cron: "0 9 * * 1" }] }`.)
+
+## After a run
+
+Review `docs/REFLECTION-PROPOSALS.md`; for accepted deltas, add them as `feedback_lesson-*.md`
+memory entries, then run `.conductor/reflect/prune-lessons.sh <memory-dir>` to keep the set bounded.
+
+---
+
+*Headless flags + scheduler local/cloud behavior verified against first-party docs 2026-07-05.
+Some details (Cursor custom-command in `-p`, exact approval-flag names, Copilot-app local file
+scope, the Copilot CI token env var `COPILOT_GITHUB_TOKEN`) were not first-party-confirmable —
+the runner inlines the brief text rather than relying on unverified `/reflect` resolution, and
+you may need to add your tool's write-approval flag / confirm its CI secret name.*