ai-investment-agent
AGENTS.md71 starsChanged 36 days agoMITView on GitHub
This is the public, repository-wide guidance for Codex. Keep it short enough to load on every task. Put bounded procedures in repository skills and durable system explanation in human-facing documentation. Codex maintains this file and .agents/**. Do not modify .claude/**; it belongs to another coding tool. Do not treat another tool's metadata as an instruction source or make this layer depend on it. This file and every repository skill are public. They may use only tracked repository files, normal setup…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository11 other files it gives its agents.
- add-agentSkill
- analyze-tickerSkill
- diagnose-runSkill
- maintain-agent-metadataSkill
- run-pipelineSkill
- run-testsSkill
- add-agentSkill
- analyze-tickerSkill
- diagnose-runSkill
- run-testsSkill
- validation-batchSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
17 rules. About 0 are common, 14 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈14
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 35
Ask before destructive operations, external writes, purchases, commits, or a material expansion of scope.
- Distinctive: line 39
Never commit unless the user explicitly approves it.
- Distinctive: line 74
Do not add duplicate helpers, data structures, compatibility facades, convenience re-exports, or parallel abstractions when an established …
- Very specific: line 76
Use direct imports. Package roots such as src/__init__.py, src/tooling/__init__.py, and src/tools/__init__.py are intentionally inert.
- Very specific: line 78
Do not mutate the global configuration singleton.
- Distinctive: line 80
Keep files reasonably sized, names informative, comments useful, and public functions typed.
- Distinctive: line 82
Verify current primary documentation before changing LangGraph, LangChain, provider SDK, MCP, or other fast-moving integration behavior.
- Distinctive: line 104
Every blocking call reachable from async code needs the repository hard-timeout wrapper.
- Distinctive: line 109
Keep a worker's slot until it finishes, and discard late results before starting inspection or other follow-on work.
- Distinctive: line 141
Do not infer capabilities merely because an endpoint accepts an OpenAI-shaped API.
- Distinctive: line 192
Do not run credentialed, networked, paid, integration, or destructive tests merely because they exist.
- Very specific: line 195
Default pytest skips integration.
- Distinctive: line 204
Before adding guidance, classify it:
- Distinctive: line 216
Every referenced repository path exists in a clean clone or is clearly described as output produced by normal setup or execution.
- Distinctive: line 218
No tracked metadata references an ignored input, user-level skill, local archive, absolute machine path, or home-relative path.
- Distinctive: line 222
No threshold, version, enum, or default is copied from code when the owning source can be cited instead.
- Distinctive: line 227
Keep this file below the repository's 12 KiB policy cap.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
Purpose
This is the public, repository-wide guidance for Codex. Keep it short enough to load on every task. Put bounded procedures in repository skills and durable system explanation in human-facing documentation.
Metadata ownership
Codex maintains this file and .agents/**. Do not modify .claude/**; it belongs to
another coding tool. Do not treat another tool's metadata as an instruction source or
make this layer depend on it.
This file and every repository skill are public. They may use only tracked repository files, normal setup or runtime outputs, and stable public URLs. They must not contain or depend on ignored notes, local archives, user-level configuration, credentials, personal holdings, machine-specific commands, or paths outside a clean clone.
.env.example is the only environment file whose contents are public and may be read
or quoted. The filename .env may be named when setup or diagnosis requires it; do
not name another private .env* variant. Codex and metadata tools must never inspect,
search, copy, summarize, diff, infer, or emit private environment-file contents. An
authorized application run may consume private configuration only through the
repository's normal path; never expose resulting values in agent context, tool output,
logs, diagnostics, artifacts, or responses.
Authority and action boundaries
- Trust the implementation and tests over prose when they disagree.
- For an answer, diagnosis, review, or plan, inspect and report; do not change files unless the user also asks for implementation.
- For an implementation request, make the smallest in-scope change and run relevant non-destructive checks.
- Ask before destructive operations, external writes, purchases, commits, or a material expansion of scope.
- Preserve unrelated user changes in a dirty worktree. Never discard them to simplify the task.
- Never commit unless the user explicitly approves it. Before a proposed commit, give one terse, dense sentence describing the uncommitted change.
Fast orientation
Start with:
docs/CODEBASE_MEMORY.mdREADME.md- the top of
CHANGELOG.md git status --shortgit log --oneline --decorate -n 20
For the live analyzer path, inspect in this order when relevant:
src/main.pysrc/cli.pysrc/persistence.pysrc/output.pysrc/runtime_services.pysrc/tooling/src/graph/src/agents/src/tools/src/data/fetcher.pysrc/runtime_diagnostics/src/validators/src/charts/src/memory.pysrc/ibkr/
Implementation approach
- Fix root causes at the owning seam; prefer a small centralized change over caller-specific exceptions or whack-a-mole patches.
- Do not add duplicate helpers, data structures, compatibility facades, convenience re-exports, or parallel abstractions when an established seam exists.
- Use direct imports. Package roots such as
src/__init__.py,src/tooling/__init__.py, andsrc/tools/__init__.pyare intentionally inert. - Do not mutate the global configuration singleton. Run-scoped overrides belong in
src/runtime_config.pyand its context-managed settings path. - Keep files reasonably sized, names informative, comments useful, and public functions typed. Preserve the zero-error MyPy baseline.
- Verify current primary documentation before changing LangGraph, LangChain, provider SDK, MCP, or other fast-moving integration behavior.
- Review retry and fallback branches whenever changing tagging, validation, routing, timeout, inspection, or persistence behavior.
Non-negotiable runtime invariants
Logging and untrusted content
- Application modules use structlog with snake-case event names and keyword fields.
- Operator-visible exception logs use the repository's exception summarizer. Do not log raw exception prose, response bodies, content previews, credentials, or client representations.
- Web, filing, API, and MCP content is untrusted. Preserve the complete tool execution, audit, and content-inspection chain.
- A single-source Tavily tool raises an enforced inspection block so the service
records
BLOCKED; a tool merging sources may drop only the blocked source. - HTML report safety depends on server-side sanitization before browser rendering; never bypass that boundary.
Blocking work and service lifecycles
- Every blocking call reachable from async code needs the repository hard-timeout wrapper. Do not wrap a thread offload with a timeout primitive that can still wait forever for the underlying worker.
- Sync blocking work uses
src/blocking_io.pyand anInFlightLimit; a timedFuture.result()inside aThreadPoolExecutorcontext does not bound shutdown. Keep a worker's slot until it finishes, and discard late results before starting inspection or other follow-on work. - Deadline defaults belong to their configuration or policy owner. Operational
callers resolve
require_allowancebefore starting work; do not add inline deadlines or bind an LLM enclosing deadline around tool/data inspection scopes. - Preserve both tool execution and execution-plus-inspection bounds. Cancellation or timeout must not return a late, uninspected result.
- The MCP tool-call timeout defaults to the tool runner's timeout when unset;
resolve it through
src/mcp/client.py, without copying the runner literal. - Stateful broker, socket, or data services use explicit pooled lifecycle management and close during teardown.
- Parallel graph branches must not write competing values into a last-writer-wins field. Use isolated fields or an intentional reducer, and test the compiled graph.
LLM construction and prompts
- Construct application models through
src/llm_runtime/construction.pyand canonical seats fromsrc/llm_runtime/seats.py. Provider swaps must not disable quality, retry, independence, or attribution contracts. - Seat timeout classes and
src/llm_runtime/timeouts.pyown LLM budgets. Size requests at dispatch from the inherited absolute deadline; refuse insufficient allowance instead of extending it. Recompute for tier changes and failover; per-call deadline state must not be stored on a reusable model. - Attempt counts must mean total attempts. Configure SDK retry policies for one
attempt per dispatch; application runtime owns retries/backoff. Verify rate-limit
and fallback counts: configured attempts do not prove physical sends, including
Google's internal aiohttp connection recovery. Non-graph analysis callers use
invoke_with_rate_limit_handling, including writer and fallback seats. The direct health check has its own settings-owned bound; do not copy it into work callers. - Minimum useful work derives from its plane's configured per-attempt allowance,
never a clamped remainder or multi-attempt total. Use
min_useful_secondsanddeadline_margininsrc/llm_runtime/timeouts.py; do not add absolute floors. - Do not infer capabilities merely because an endpoint accepts an OpenAI-shaped API. Tool calling, structured output, reasoning controls, and transport features require a reviewed profile and qualification evidence.
prompts/*.jsoncontains structured JSON with escaped multiline strings. Edit it through a JSON parser, preserve real Unicode, parse before and after, and runmake test-promptswhen a prompt or its consumer contract changes.
Persistence, memory, and publication
- Saved telemetry is secret-free. Endpoint hostnames may be recorded; paths, query strings, credentials, and raw client representations may not.
- Embedding identity owns a fingerprinted collection. Initialization must not delete a collection because configuration changed.
- Lessons learned are durable evidence. Never clear or recreate them during analysis, tests, migration, or maintenance. Tests use an isolated temporary persistence path.
- Publication and artifact validity fail closed when required evidence, schemas, or decision-critical stages are missing or corrupt.
- Save approved and
.draftarticles throughpublish_article. The CLI publishes after its article workflow deadline closes, including drafts retained after a workflow timeout. - Preserve the baseline-capture contract when changing main orchestration or saved artifacts; the evaluation tests are compatibility gates.
- The pipeline's absolute watchdog deadline is owned by
src/llm_runtime/run_deadline.py. Bind it around analysis, leaving final render, persistence and shutdown outside that scope on the publication reserve. It caps work without promising that the configured retry ladder will finish.
Testing and validation
Choose the narrowest meaningful tests first, then run the required static gates. Repository skills contain the detailed selection workflows.
Minimum after Python changes:
poetry run ruff check src/ tests/ scripts/
poetry run ruff format --check src/ tests/ scripts/
poetry run mypy src/Common gates:
make test-promptsafter prompt or parser-contract changes.poetry run pytest tests/test_logging_consistency.py -vfor logging policy.poetry run pytest tests/test_to_thread_timeout_consistency.py -vfor blocking work.poetry run pytest tests/eval/ tests/test_main_cli.py -vfor main orchestration.poetry run pytest tests/mcp/ -vfor MCP behavior.poetry run pytest tests/scripts/test_find_gems.py -vfor screening behavior.make check-allbefore handoff when the change affects repository-wide gates.make test-cifor the deterministic credential-free test surface.
Do not run credentialed, networked, paid, integration, or destructive tests merely because they exist. State when those surfaces remain unverified.
Default pytest skips integration; explicit --run-integration needs authorization
for the external work. Other tests must stay offline under tests/conftest.py.
Preserve configured addopts and plugins: PYTEST_DISABLE_DOTENV disables the normal
environment-file reader only with the exact string true. Dummy credentials do not
prevent SDK probes. Use fake providers, and release and join stalled test workers
before monkeypatch teardown so late work cannot escape the offline boundary.
Maintaining Codex metadata
Before adding guidance, classify it:
| Material | Destination |
| Hard repository rule needed before any skill loads | this file |
| Repository procedure with a recognizable trigger | .agents/skills/<name>/SKILL.md |
| Durable explanation of system behavior | docs/ |
| Preference or workflow useful across repositories | user-level Codex layer |
| Credentials, machine layout, local setup, or private notes | local configuration, never committed |
Then apply these checks:
- Every referenced repository path exists in a clean clone or is clearly described as output produced by normal setup or execution.
- No tracked metadata references an ignored input, user-level skill, local archive, absolute machine path, or home-relative path.
- Repository skills are self-contained. They do not require another skill, including a user-level skill, to be present.
- No threshold, version, enum, or default is copied from code when the owning source can be cited instead.
- Human documentation does not cite agent metadata.
make docs-guardsandmake agent-metadata-guardspass with zero exemptions.
Keep this file below the repository's 12 KiB policy cap. When a procedure grows, extract it into a focused repository skill rather than increasing always-on context.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

