Imported from dhaval-joshi/ts-app (AGENTS.md). Install upstream with npx skills add dhaval-joshi/ts-app. Copyright stays with the author.

AGENTS.md — Codex / Shared Coding-Agent Instructions

This repository is actively developed by both Claude Code and Codex. AGENTS.md is the Codex/generic coding-agent operating contract. It is not the sole source of project knowledge.

Read before working

Start with:

1. README.md
2. docs/INDEX.md
3. docs/SAFETY.md
4. docs/ARCHITECTURE.md
5. docs/TESTING.md
6. docs/DEVELOPMENT.md
7. docs/DECISIONS.md when the task touches established design decisions
8. relevant files under agent-actions/

Then inspect the actual current source code. Never rely on chat history or memory when the current code can answer the question.

This is live trading software

A bug can cause real financial loss.

Non-negotiable rules:

• Never intentionally read, print, copy, expose, commit, or modify .env, .env.* (except .env.example), secrets/, private keys/certificates, credential files, or other secret-bearing local artifacts.
• Never dump environment variables as part of diagnosis.
• Never place, modify, cancel, or close a real broker order as ordinary verification. Live-broker actions require explicit human authorization in the current task.
• Prefer Paper mode, fake brokers, simulations, compilation, static checks, and other non-live verification.
• Never silently switch Live/Paper behavior.
• Never silently increase quantity, exposure, or trading scope.
• Never bypass, weaken, or remove safety checks merely to make a test pass.
• Never reintroduce broker-side OCO/conditional exits. The application-watched market-exit mechanism is the current design.
• Never introduce automatic flattening on a safeguard halt without explicit human approval.
• Preserve atomic persistence and recovery behavior.

The repository instructions are behavioral safeguards, not a substitute for OS-level access control. The project includes conservative Codex sandbox and approval defaults in .codex/config.toml, but .env must still remain outside any execution/workspace boundary you do not trust. Never intentionally inspect it.

Shared project truth

Do not duplicate project-specific truth in AGENTS.md when it belongs in README.md or docs/.

• README.md — detailed current product behavior and architecture.
• docs/ — focused shared engineering knowledge.
• CLAUDE.md — Claude Code-specific workflow.
• .claude/ — Claude-only commands/rules/skills/settings.
• .codex/ — Codex project configuration and command rules.
• .agents/skills/ — repository-scoped portable skills discovered by current Codex.
• agent-actions/ — durable planning and implementation handovers.

Multi-agent workflow

Claude Code and Codex share the same repository and may leave uncommitted work for each other.

Before changing anything:

git status
git diff
git log -5 --oneline

Never reset, stash, checkout, overwrite, or discard another agent's uncommitted changes without explicit human authorization.

Inspect agent-actions/planned/ and agent-actions/coded/ before starting. If a matching artifact already exists, continue it rather than creating a duplicate.

Mandatory planning handover

For every non-trivial task that may change code, the agent must create a planning artifact without being asked.

Location:

agent-actions/planned/

Filename:

plan_<epoch>_<short-slug>.md

The plan must include:

• objective/problem;
• verified current behavior;
• proposed design;
• files/components likely affected;
• safety implications;
• alternatives/trade-offs where relevant;
• verification plan;
• open questions/assumptions;
• explicit scope and non-scope.

A plan in planned/ is an action item, not approval. Present it to the human and obtain confirmation before implementation. If it remains in planned/, do not assume permission to code it.

Mandatory code-change handover

After implementing code changes, the agent must create a code-change artifact without being asked.

Location:

agent-actions/coded/

Filename:

code_<epoch>_<short-slug>.md

The code-change artifact must include:

• associated plan_... filename;
• objective;
• files changed;
• behavior changed;
• important implementation decisions;
• tests/simulations actually run and their results;
• what was not verified;
• known risks/follow-ups;
• whether another agent can safely continue.

The agent must not move anything into agent-actions/done/. The human owns acceptance and moves approved artifacts to done/.

Live progress logging for every spawned sub-agent

Added 2026-09-04, after a real incident: a long-running escalation hit repeated Anthropic-side API failures (a rate limit, then several consecutive capacity errors) mid-task, and the orchestrating session had no reliable way to know how much of the sub-agent's work was actually safe — whether resuming it would pick up cleanly or silently redo already-finished analysis. The underlying cause (a quota limit, an outage, a crash, anything) is not the point; not knowing what a stopped agent had actually established is the problem this section exists to prevent, permanently, not just for that one incident.

Whenever an agent (Claude Code, Codex, or either one's own sub-agents/subprocesses) spawns another agent for research, design, or verification work, the spawning prompt must explicitly instruct the spawned agent to maintain a LIVE, incrementally-updated progress document of its own work — not a summary written only at the end. Concretely:

• The document is updated as the agent goes (after each real step or finding), the same discipline already used for PHASE1_EXECUTION_ LOG.md / PHASE2_EXECUTION_LOG.md in this repository — not reconstructed retroactively once the task finishes or is interrupted.
• It must contain enough for either the same agent resumed, or a different agent starting fresh to continue without re-deriving already-completed work: what has been read/checked, what has been concluded (and on what evidence), what is still open, and the exact next step.
• It lives in the repository (under agent-actions/, alongside the plan or report it belongs to), not only in the agent's own transcript — a transcript can be lost or unavailable to whoever resumes the work; a committed-to-disk file cannot.
• This is required IN ADDITION TO, not instead of, the existing planning/code-change handover artifacts above — those describe finished work; this is what makes UNFINISHED work resumable.

The orchestrating agent must state this requirement explicitly in every spawn prompt. Do not assume a spawned agent will do this on its own initiative — it must be told, every time, the same way the planning and code-change handover requirements above must actually be followed, not just known about.

Development standards

• Inspect before modifying.
• Prefer the smallest coherent change.
• Read backend/models.py before changing persisted/config schemas.
• Route backend time through backend/clock.py.
• Preserve broker abstraction; do not duplicate Live/Paper order-management paths.
• For renames/removals, sweep backend, frontend, documentation, and relevant configuration for stale references.
• Comments should explain why, especially around safety-critical behavior.
• Report exactly what was tested and what remains uncertain.
• Distinguish verified, inferred, and live-unverified behavior.

Handover quality

Another agent must be able to continue from the repository alone. Do not rely on "I explained this in the chat" for important decisions.

Mandatory daily discussion notes

Added 2026-08-31 (re-added 2026-09-04 after this section was found missing from the file despite being cited from CLAUDE.md and recorded in Claude Code's own persistent memory as already present — flagging the gap rather than silently assuming which version was authoritative).

For every chat turn on this project (ts-app) — both the human's message and the agent's own reply — append a summarized entry to agent-actions/daily-discussion-notes/note_<yyyyMMdd>.md (create the file if it doesn't exist yet for today's date). Entry format, exactly:

-------------------------------
**<yyyy-MM-dd> <hh:mm> <AM/PM>**
**<Sender>:**
<concise summary, no thought process>

<Sender> is the human's name for their message, or the agent's own name (Claude, Codex, Gemini, ...) for an agent message. Always append, never overwrite or reorder existing entries.

Why: a durable, cross-agent-readable running log of what was discussed each day, independent of any one chat session's own history — so a different agent (or a resumed session) can reconstruct the recent conversation without access to the original transcript.

How to apply: at the end of handling each human message (append their entry) and at the end of each of the agent's own responses (append its own entry), in every session on this project — not just once, and not only for especially important turns. Applies going forward from 2026-08-31; not retroactively backfilled for turns before that date.