junjo: Instructions file for Codex

Junjo Platform AGENTS.md

Junjo is a multi-component platform repository. Read this file first, then read the nearest scoped AGENTS.md before changing a component.

Developer philosophy

• Be grug brained: prefer simple, explicit code and contracts.
• Everything is greenfield. Intentional breaking changes are allowed, but they must be documented and coordinated across every affected component.
• Do complete, well-architected work. Do not add compatibility fallbacks or abstractions that hide ownership.
• Follow single responsibility and separation of concerns.
• Ground plans and reviews in current code and accepted ADRs.
• Avoid scope creep and preserve unrelated user work.
• Do not engage in scope creep. Do not take liberties to refactor or change things that do not need to change beyond the requested implementations and ideas. Keep existing user-interfaces, styles, contracts, integrations, system -> system mechanics as they are unless it's required to change them as part of new feature implementation. Keep changes necessary and required. As much as needed, as little as possible.
• Do not set arbitrary contraints, budgets, caps, limitations. Do not truncate content. Do not set timeouts. Do not make assumptions about how much we can handle. Allow us to run into the exceptions when resources, time lengths, or capacity are exceeded. We will only create constraints as we encounter real exceptions caused by a real repeatable documented problem or limit.

Low-resource performance is a product requirement

Junjo's throughput, latency, and ability to run on low-end, memory-constrained hardware are core product differentiators. Preserve them when reviewing and changing SDK execution, telemetry, ingestion, storage, and queries. Generic "enterprise readiness" is not authorization to add steady-state CPU, memory, I/O, or coordination costs to cover exceptional events.

• Read the owning ADRs and benchmark evidence before recommending changes to these paths. Establish the unchanged baseline before selecting a fix; correctness tests and unconstrained microbenchmarks are not performance proof.
• Compare actual completed work, latency, CPU, and memory on the existing supported resource profile, including concurrent ingestion and queries where affected. Do not hide regressions by increasing resources, reducing offered work, counting generated-but-undelivered spans, or changing acceptance gates.
• Real-world test every change to Studio's query path, backend, or ingestion: make the queries from the real frontend while ingestion is processing spans at load, against the unchanged build. Measurements of the API alone, or after ingestion has finished, are not acceptance evidence. apps/studio/ingestion/benchmarks/README.md owns the procedure.
• Describe the failure trigger, evidence of occurrence, affected data, recovery path, and prevention cost separately. A deterministic fault reproduction establishes consequences, not how frequently the event occurs in deployments.
• Durability and acceptable-loss guarantees are explicit product/ADR decisions. Do not assume rare-event loss is acceptable, silently weaken an accepted guarantee, or strengthen it into a more expensive guarantee without a decision. Present measured tradeoffs; do not select them on the user's behalf.