Add weekly research heartbeat

.gitignore

@@ -1,4 +1,5 @@
 __pycache__/
+.tools/
 *.py[cod]
 .DS_Store
 Thumbs.db

AGENTS.md

@@ -0,0 +1,67 @@
+# Codex Flightdeck Agent Guide
+
+## Purpose
+
+This repository is a public, file-based operating kit for OpenAI Codex. Most
+changes are documentation, templates, reusable prompts, or validation rules.
+Keep recommendations reviewable and distinguish official product facts from
+local observations and community practices.
+
+## Start Here
+
+- Read `README.md` for the package map and adoption path.
+- Read `CODEX_SOURCE_MAP.md` before changing Codex facts or configuration.
+- Use `CODEX_WEEKLY_RESEARCH.md` for recurring research and maintenance.
+- Treat `.codex/config.toml.template` as a public shared template, not the
+  maintainer's personal configuration.
+
+## Repository Layout
+
+- Root `CODEX_*.md` files: operating policies and workflow guidance.
+- `skills/bootstrap-project/`: the installable automatic-bootstrap skill.
+- `.codex/config.toml.template`: conservative project configuration example.
+- `*/AGENTS.md.template`: scoped instruction examples.
+- `research/`: dated maintenance reports and adoption decisions.
+- `scripts/validate.py`: dependency-free package validation.
+- `.github/`: contribution templates and CI.
+
+## Commands
+
+- Validate: `python scripts/validate.py`
+- Review whitespace errors: `git diff --check`
+- Review scope: `git status --short --branch` and `git diff --stat`
+- Search guidance: `rg -n "<term>" -g "*.md" -g "*.template" .`
+
+No dependency installation or build step is required. CI uses Python 3.11 and
+runs the same validation command.
+
+## Research Rules
+
+- Refresh the current Codex manual before changing current product guidance.
+- Use official OpenAI documentation or reproducible current-client behavior
+  for supported models, configuration keys, permissions, and product behavior.
+- Use GitHub, X, blogs, papers, and community projects for discovery only.
+- Classify community candidates as `adopt`, `watch`, `test isolated`, or
+  `ignore`; do not turn a popular claim into a product fact.
+- Date drift-prone findings and link the source in the output artifact.
+
+## Editing And Safety
+
+- Keep changes small, public-safe, and free of personal paths or credentials.
+- Do not silently change the public defaults from `workspace-write` plus
+  `on-request`.
+- Present `danger-full-access` plus `never` only as an explicit operator choice
+  for trusted or isolated environments.
+- Do not add dependencies, hooks, write-capable integrations, or global config
+  mutations as incidental maintenance.
+- Preserve the distinction between personal defaults, repository guidance,
+  skills, plugins, MCP, hooks, and scheduled tasks.
+
+## Validation And Review
+
+- Run `python scripts/validate.py` after every change.
+- Run `git diff --check` and review the complete diff before publishing.
+- For configuration examples, verify every active key against the current
+  manual or current local behavior.
+- For research updates, record the decision and rationale, not only a link list.
+- Report validation performed and any unverified or deferred candidate.

CODEX_COST_AND_SAFETY_POLICY.md

@@ -46,9 +46,12 @@
 
 ## Thread Budget Policy
 
+- Start single-agent. For independent workstreams, begin with two to four workers and increase only after measuring a quality or wall-clock benefit.
 - Use one thread for scoped tasks.
 - Use subagents only for concrete, bounded work that can run independently.
 - Keep delegation depth shallow unless recursive fan-out is explicitly justified.
+- The current documented defaults are `agents.max_threads = 6` and `agents.max_depth = 1`; avoid pinning larger values without a benchmark.
+- Prefer Terra or another current lower-cost option for read-heavy workers when the surface supports model routing. Verify the actual routed model before relying on the saving.
 - Use ultra only when parallel work materially improves quality or wall-clock time.
 - Require a root synthesis and validation pass after parallel work.
 - Stop loops when findings stop improving.

CODEX_SOURCE_MAP.md

@@ -11,9 +11,12 @@ This project separates product facts, reproducible local behavior, and community
 - [Model Context Protocol](https://developers.openai.com/codex/mcp)
 - [Skills](https://developers.openai.com/codex/skills)
 - [Latest model guidance](https://developers.openai.com/api/docs/guides/latest-model)
+- [What's new](https://learn.chatgpt.com/docs/whats-new)
+- [Scheduled tasks](https://learn.chatgpt.com/docs/automations)
 - [Subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents)
 - [Models and reasoning](https://learn.chatgpt.com/docs/models)
 - [Permissions](https://learn.chatgpt.com/docs/permissions)
+- [OpenAI Codex releases](https://github.com/openai/codex/releases)
 
 ## Evidence Hierarchy
 
@@ -45,6 +48,7 @@ For each candidate, prefer a decision such as `ignore`, `watch`, `test isolated`
 - Re-fetch the current Codex manual and configuration reference.
 - Check model and reasoning support.
 - Review changes to skills, plugins, MCP, hooks, and automation behavior.
+- Check the latest dated report in `research/` and run one catch-up if the scheduled heartbeat was missed.
 - Compare recommendations with actual local failures and successes.
 - Remove stale examples and redundant flags.
 - Run `python scripts/validate.py` before publishing.

CODEX_TASK_PROMPT_LIBRARY.md

@@ -143,3 +143,10 @@ Goal: Implement the approved plan for [task].
 Context: Approved plan: [link/paste]. Relevant updates since approval: [notes].
 Constraints: Stay inside approved scope unless you find a blocker.
 Done when: Implementation, validation, and diff review are complete.
+
+## Weekly Codex Research
+
+Goal: Run the repository's `CODEX_WEEKLY_RESEARCH.md` workflow and keep current guidance useful.
+Context: Start from the latest dated report in `research/`, current git state, the fresh Codex manual, maintained GitHub projects, and current public technical discussion.
+Constraints: Separate official facts from community signals. Classify candidates as adopt, watch, test isolated, or ignore. Do not add dependencies, change global config, or publish without authorization. If the scheduled run was missed, perform one catch-up and do not create duplicate reports.
+Done when: A dated report records sources and decisions, adopted changes are minimal and verified, `python scripts/validate.py` passes, and the diff has been reviewed.

CODEX_WEEKLY_RESEARCH.md

@@ -0,0 +1,88 @@
+# Codex Weekly Research And Maintenance
+
+This workflow keeps Flightdeck current without turning every new repository,
+post, or feature announcement into configuration churn.
+
+## Cadence
+
+- **Weekly heartbeat:** a focused 30–60 minute scan for documentation drift,
+  breaking changes, recurring user pain, and one small useful improvement.
+- **Monthly refresh:** a deeper comparison of models, configuration, plugins,
+  skills, MCP, hooks, scheduled tasks, and representative community projects.
+- **Missed run:** trigger one manual catch-up when the project is next available.
+  Do not backdate it or start multiple replacement runs.
+
+Local scheduled tasks require the computer to be on, the desktop app to be
+running, and the project to remain available. Prefer a dedicated worktree so a
+background run cannot collide with unfinished local changes.
+
+## Source Lanes
+
+1. **Official facts:** current Codex manual, What's New, changelog, configuration
+   reference, model guidance, and the official `openai/codex` repository.
+2. **Reproducible behavior:** current client behavior, validation output, logs,
+   and small controlled experiments.
+3. **Community discovery:** maintained GitHub repositories, issues,
+   discussions, X posts, engineering blogs, benchmarks, and papers.
+
+Community sources can suggest a test. They do not prove a Codex capability,
+configuration key, limit, or pricing rule.
+
+## Weekly Workflow
+
+1. Read the latest dated report in `research/` and the current git status.
+2. Fetch a fresh Codex manual and check What's New plus the Codex changelog.
+3. Compare current guidance for models, reasoning, permissions, subagents,
+   scheduled tasks, skills, plugins, MCP, hooks, and memories with this repo.
+4. Scan recent GitHub projects and discussions for maintained, licensed, and
+   reproducible ideas. Sample current X discussion for friction and workflows.
+5. Classify every material candidate:
+   - `adopt`: verified, useful, and low-overlap;
+   - `watch`: interesting but immature or insufficiently verified;
+   - `test isolated`: worth a bounded experiment before recommendation;
+   - `ignore`: stale, redundant, unsafe, or too costly for the value.
+6. Implement the smallest improvement that removes real drift or adds a
+   reusable workflow. A no-change result is valid when nothing clears the bar.
+7. Create `research/YYYY-MM-DD.md` with sources, decisions, changes, validation,
+   and deferred work.
+8. Run `python scripts/validate.py`, `git diff --check`, and review the full diff.
+9. Publish through a reviewable branch or pull request when practical.
+
+## Cost Guardrails
+
+- Start with one agent. Use subagents only for independent, bounded lanes.
+- Start parallel work with two to four workers; increase only after measuring a
+  real speed or quality benefit.
+- Keep nesting shallow. The current documented default `agents.max_depth = 1`
+  is a good general boundary.
+- Do not pin a larger `agents.max_threads` merely because the client permits it.
+- Prefer faster/lower-cost workers for read-heavy scans when the current surface
+  supports model routing, and verify that routing instead of assuming it.
+- Stop expanding research when new sources repeat existing findings.
+
+## Durable Scheduled Prompt
+
+Use this as the task prompt, adapting paths and publication rules to the repo:
+
+```text
+Run the repository's weekly Codex research workflow in
+CODEX_WEEKLY_RESEARCH.md.
+
+Start from the latest report in research/ and the current git state. Refresh
+official Codex sources, scan maintained GitHub projects and current public
+technical discussion, then classify candidates as adopt, watch, test isolated,
+or ignore. Implement only verified, useful, low-risk improvements. Create a
+dated research report, run the repository validation, review the diff, and
+return a concise summary with sources and deferred items.
+
+If the previous scheduled run was missed, perform one catch-up run now. Do not
+create duplicate reports for the same date. Do not publish, merge, install
+third-party dependencies, or change global configuration unless the task has
+explicit authorization for that action.
+```
+
+## Completion Criteria
+
+A run is complete when it leaves a dated decision trail, the package validates,
+the diff is reviewable, and every adopted recommendation is backed by an
+official source or a reproducible experiment.

README.md

@@ -47,6 +47,7 @@ flowchart LR
 | Automatic setup | [`skills/bootstrap-project/`](skills/bootstrap-project/) | Inspect, prepare, validate, then continue the original task |
 | Model strategy | [`CODEX_COST_AND_SAFETY_POLICY.md`](CODEX_COST_AND_SAFETY_POLICY.md) | Match capability and reasoning to task value |
 | Task workflows | [`CODEX_TASK_PROMPT_LIBRARY.md`](CODEX_TASK_PROMPT_LIBRARY.md) | Reusable implementation, debugging, research, and review prompts |
+| Weekly maintenance | [`CODEX_WEEKLY_RESEARCH.md`](CODEX_WEEKLY_RESEARCH.md) | Current-source research, catch-up, adoption decisions, and validation |
 | Quality gates | [`CODEX_PR_REVIEW_GUIDELINES.md`](CODEX_PR_REVIEW_GUIDELINES.md) | Review behavior and evidence requirements |
 | Integrations | [`CODEX_MCP_PLAN.md`](CODEX_MCP_PLAN.md) | Scope MCP servers and write permissions deliberately |
 
@@ -104,6 +105,22 @@ Model names and supported reasoning levels evolve. Verify current options in the
 
 The goal is not minimum tokens at any cost. It is maximum useful work per unit of capacity. Subagents can protect the main context and reduce wall-clock time, but each agent performs its own model and tool work. Use them when parallelism materially improves quality or speed—not as a default ceremony.
 
+Start with one agent. For clearly independent lanes, two to four workers are a
+practical starting range; expand only after measuring a real benefit. Keep
+nesting shallow and let the root agent own synthesis and validation.
+
+## Weekly maintenance
+
+Flightdeck includes a source-driven [weekly research workflow](CODEX_WEEKLY_RESEARCH.md)
+and dated [research reports](research/). The workflow refreshes official Codex
+facts, samples maintained GitHub projects and public technical discussion, and
+turns candidates into explicit `adopt`, `watch`, `test isolated`, or `ignore`
+decisions.
+
+If a scheduled run is missed, run one manual catch-up when the project is next
+available. Local scheduled tasks require the desktop app and computer to be
+running; a dedicated worktree keeps background edits separate from active work.
+
 ## Safety model
 
 Flightdeck ships with conservative shared defaults:
@@ -129,6 +146,8 @@ High-autonomy profiles such as `danger-full-access` plus `never` can be appropri
 - [`CODEX_REVIEW_PROMPTS.md`](CODEX_REVIEW_PROMPTS.md): focused review prompts.
 - [`CODEX_SKILL_LIBRARY_PLAN.md`](CODEX_SKILL_LIBRARY_PLAN.md): when a workflow should become a skill.
 - [`CODEX_SOURCE_MAP.md`](CODEX_SOURCE_MAP.md): evidence and source hierarchy.
+- [`CODEX_WEEKLY_RESEARCH.md`](CODEX_WEEKLY_RESEARCH.md): recurring maintenance and catch-up workflow.
+- [`research/`](research/): dated findings, decisions, validation, and deferred experiments.
 
 ## Design principles
 

research/2026-07-14.md

@@ -0,0 +1,65 @@
+# Weekly Research Report — 2026-07-14
+
+## Outcome
+
+Adopt a repeatable weekly maintenance workflow, document manual catch-up for
+missed scheduled runs, and tighten the subagent cost guidance. Do not install a
+large agent pack or a third-party linter in this run.
+
+## Official Findings
+
+- Scheduled tasks can run against a local project or an isolated worktree. A
+  local-project run requires the computer to be on, the desktop app to be
+  running, and the project to remain available.
+- Scheduled tasks can explicitly invoke skills and should be tested manually
+  before relying on a recurring schedule.
+- Subagents consume more tokens than comparable single-agent runs. Current
+  local clients can delegate after a direct request or applicable project/skill
+  instructions.
+- Current documented subagent defaults are six open threads and depth one.
+  Depth one permits direct children but prevents recursive fan-out.
+- Current model guidance recommends Sol for demanding work, Terra for faster
+  and lower-cost support work, and selective use of Max or Ultra. Most tasks do
+  not need Max or Ultra.
+
+## Community Scan
+
+| Candidate or signal | Decision | Rationale |
+| --- | --- | --- |
+| [`harness/harness-skills`](https://github.com/harness/harness-skills) | `adopt pattern` | Its small skill entrypoints plus shared references/templates reinforce keeping recurring workflows explicit and reviewable. |
+| [`agent-sh/agnix`](https://github.com/agent-sh/agnix) | `test isolated` | Agent-guidance linting is promising, but Flightdeck already has a dependency-free validator and should not add a dependency without a measured gap. |
+| Large packs with hundreds of agents and skills, such as [`sehoon787/my-codex`](https://github.com/sehoon787/my-codex) | `ignore for now` | Breadth increases trigger ambiguity, maintenance, and context/tool surface. Flightdeck should stay composable and minimal. |
+| X reports of intentionally running 14 subagents to consume available quota ([example](https://x.com/da_green_hermit/status/2076963615106613316)) | `counter-pattern` | It demonstrates throughput, not efficiency. Add a two-to-four-worker starting range and require measured benefit before expansion. |
+| X report that model-specific delegation did not behave as expected ([example](https://x.com/daengbo/status/2076988430186430473)) | `watch` | Treat routing as surface-dependent and verify it locally before durable model pins. A single report is not product evidence. |
+
+## Changes Adopted
+
+- Added a repo-specific `AGENTS.md` with verified commands and research rules.
+- Added `CODEX_WEEKLY_RESEARCH.md` with cadence, source lanes, catch-up behavior,
+  decision classes, a durable scheduled prompt, and completion criteria.
+- Added explicit subagent starting limits and documented official defaults in
+  `CODEX_COST_AND_SAFETY_POLICY.md`.
+- Added weekly research to the README, prompt library, source map, and package
+  validation.
+
+## Sources
+
+- [Codex manual](https://developers.openai.com/codex/codex-manual.md)
+- [Scheduled tasks](https://learn.chatgpt.com/docs/automations)
+- [Subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents)
+- [Models](https://learn.chatgpt.com/docs/models)
+- [What's new](https://learn.chatgpt.com/docs/whats-new)
+- [OpenAI Codex releases](https://github.com/openai/codex/releases)
+
+## Validation
+
+- Baseline before edits: `python scripts/validate.py` passed with 39 text files.
+- After edits: `python scripts/validate.py` passed with 42 text files and
+  `git diff --check` reported no whitespace errors.
+
+## Deferred
+
+- Evaluate `agnix` against a copy of the repository and compare findings with
+  `scripts/validate.py` before considering any dependency or CI integration.
+- Benchmark one-agent versus two-to-four-agent research on the same source set.
+- Review the first three scheduled outputs before changing cadence or model.

scripts/validate.py

@@ -13,10 +13,12 @@
 ROOT = Path(__file__).resolve().parents[1]
 
 REQUIRED = (
+    "AGENTS.md",
     "README.md",
     "LICENSE",
     "CONTRIBUTING.md",
     "SECURITY.md",
+    "CODEX_WEEKLY_RESEARCH.md",
     "GLOBAL_AGENTS.md.template",
     "REPO_AGENTS.md.template",
     ".codex/config.toml.template",
@@ -31,6 +33,7 @@
     "GitHub token": re.compile(r"\b(?:ghp|github_pat)_[A-Za-z0-9_]{20,}\b"),
     "OpenAI-style secret": re.compile(r"\bsk-[A-Za-z0-9_-]{20,}\b"),
 }
+EXCLUDED_DIRS = {".git", ".tools", "__pycache__"}
 
 MARKDOWN_LINK = re.compile(r"!?\[[^\]]*\]\(([^)]+)\)")
 
@@ -39,7 +42,9 @@ def text_files() -> list[Path]:
     return [
         path
         for path in ROOT.rglob("*")
-        if path.is_file() and ".git" not in path.parts and path.name != "LICENSE"
+        if path.is_file()
+        and not EXCLUDED_DIRS.intersection(path.parts)
+        and path.name != "LICENSE"
     ]