stallhunt: Instructions file for Codex

AGENTS.md

This repository is the source of truth for the Stallhunt project.

Mission

Build a Linux-first command-line tool that automatically identifies active system performance bottlenecks and explains:

1. whether meaningful contention exists,
2. which resource is constraining progress,
3. which processes/services are being delayed,
4. which processes/services are likely causing the contention,
5. how much time is being lost,
6. what evidence supports the diagnosis,
7. how confident the tool is in each causal claim.

The project is not another top clone. Traditional monitors report resource consumption. Stallhunt should report lost progress and likely causes.

Product name: Stallhunt. Crate, package, and binary: stallhunt. See ADR-0012.

Operating principle

Treat Git as project memory.

A fresh clone on another computer must contain enough information for a competent coding agent or engineer to understand:

• what the project is,
• what has already been implemented,
• what decisions have been made,
• what remains,
• what is currently broken,
• what should be done next,
• why the architecture looks the way it does.

Do not rely on chat history as durable project context.

Required reading order

Before making non-trivial changes, read:

1. README.md
2. docs/README.md
3. docs/product.md
4. docs/architecture.md
5. docs/status.md
6. relevant files under docs/decisions/
7. any domain-specific document relevant to the requested work

For implementation work, also read:

• docs/data-model.md
• docs/telemetry.md
• docs/inference-engine.md
• docs/testing.md

Project constraints

Platform

• Linux first.
• Native Linux kernel interfaces are preferred over portability abstractions when they materially improve diagnosis.
• Other operating systems are explicitly out of scope until the Linux implementation is useful and stable.

Language

• Rust is the implementation language.
• Prefer stable Rust unless an ADR explicitly approves nightly-only functionality.