agentleFS
rgoerwitrgoerwit/ai-investment-agent/AGENTS.md

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

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
  1. Distinctive:

    Ask before destructive operations, external writes, purchases, commits, or a material expansion of scope.

    line 35
  2. Distinctive:

    Never commit unless the user explicitly approves it.

    line 39
  3. Distinctive:

    Do not add duplicate helpers, data structures, compatibility facades, convenience re-exports, or parallel abstractions when an established …

    line 74
  4. Very specific:

    Use direct imports. Package roots such as src/__init__.py, src/tooling/__init__.py, and src/tools/__init__.py are intentionally inert.

    line 76
  5. Very specific:

    Do not mutate the global configuration singleton.

    line 78
  6. Distinctive:

    Keep files reasonably sized, names informative, comments useful, and public functions typed.

    line 80
  7. Distinctive:

    Verify current primary documentation before changing LangGraph, LangChain, provider SDK, MCP, or other fast-moving integration behavior.

    line 82
  8. Distinctive:

    Every blocking call reachable from async code needs the repository hard-timeout wrapper.

    line 104
  9. Distinctive:

    Keep a worker's slot until it finishes, and discard late results before starting inspection or other follow-on work.

    line 109
  10. Distinctive:

    Do not infer capabilities merely because an endpoint accepts an OpenAI-shaped API.

    line 141
  11. Distinctive:

    Do not run credentialed, networked, paid, integration, or destructive tests merely because they exist.

    line 192
  12. Very specific:

    Default pytest skips integration.

    line 195
  13. Distinctive:

    Before adding guidance, classify it:

    line 204
  14. Distinctive:

    Every referenced repository path exists in a clean clone or is clearly described as output produced by normal setup or execution.

    line 216
  15. Distinctive:

    No tracked metadata references an ignored input, user-level skill, local archive, absolute machine path, or home-relative path.

    line 218
  16. Distinctive:

    No threshold, version, enum, or default is copied from code when the owning source can be cited instead.

    line 222
  17. Distinctive:

    Keep this file below the repository's 12 KiB policy cap.

    line 227

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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:

  1. docs/CODEBASE_MEMORY.md
  2. README.md
  3. the top of CHANGELOG.md
  4. git status --short
  5. git log --oneline --decorate -n 20

For the live analyzer path, inspect in this order when relevant:

  1. src/main.py
  2. src/cli.py
  3. src/persistence.py
  4. src/output.py
  5. src/runtime_services.py
  6. src/tooling/
  7. src/graph/
  8. src/agents/
  9. src/tools/
  10. src/data/fetcher.py
  11. src/runtime_diagnostics/
  12. src/validators/
  13. src/charts/
  14. src/memory.py
  15. src/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, and src/tools/__init__.py are intentionally inert.
  • Do not mutate the global configuration singleton. Run-scoped overrides belong in src/runtime_config.py and 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.py and an InFlightLimit; a timed Future.result() inside a ThreadPoolExecutor context 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_allowance before 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.py and canonical seats from src/llm_runtime/seats.py. Provider swaps must not disable quality, retry, independence, or attribution contracts.
  • Seat timeout classes and src/llm_runtime/timeouts.py own 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_seconds and deadline_margin in src/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/*.json contains structured JSON with escaped multiline strings. Edit it through a JSON parser, preserve real Unicode, parse before and after, and run make test-prompts when 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 .draft articles through publish_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-prompts after prompt or parser-contract changes.
  • poetry run pytest tests/test_logging_consistency.py -v for logging policy.
  • poetry run pytest tests/test_to_thread_timeout_consistency.py -v for blocking work.
  • poetry run pytest tests/eval/ tests/test_main_cli.py -v for main orchestration.
  • poetry run pytest tests/mcp/ -v for MCP behavior.
  • poetry run pytest tests/scripts/test_find_gems.py -v for screening behavior.
  • make check-all before handoff when the change affects repository-wide gates.
  • make test-ci for 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:

MaterialDestination
Hard repository rule needed before any skill loadsthis file
Repository procedure with a recognizable trigger.agents/skills/<name>/SKILL.md
Durable explanation of system behaviordocs/
Preference or workflow useful across repositoriesuser-level Codex layer
Credentials, machine layout, local setup, or private noteslocal configuration, never committed

Then apply these checks:

  1. Every referenced repository path exists in a clean clone or is clearly described as output produced by normal setup or execution.
  2. No tracked metadata references an ignored input, user-level skill, local archive, absolute machine path, or home-relative path.
  3. Repository skills are self-contained. They do not require another skill, including a user-level skill, to be present.
  4. No threshold, version, enum, or default is copied from code when the owning source can be cited instead.
  5. Human documentation does not cite agent metadata.
  6. make docs-guards and make agent-metadata-guards pass 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.