Skip to content

AGENTS.md

Latest commit

 

History

History
68 lines (55 loc) · 2.95 KB

AGENTS.md

File metadata and controls

68 lines (55 loc) · 2.95 KB

AGENTS.md

Documentation and skills index

Key references for navigating this project:

  • README.md -- project overview, crate table, build prerequisites.
  • CONTRIBUTING.md -- contribution workflow, PR conventions.
  • docs/ -- human-readable documentation (validity checks, audits, dev guides).
  • docs/knowledge-base/ -- mdbook knowledge base for architecture, domain terms, and implementation conventions.
  • Makefile.toml -- build tasks (delegates to scripts/make/*.toml).

Response priorities

  • Start with high-level recommendations before implementation details.
  • Keep recommendations short, opinionated, and tied to tradeoffs.
  • If multiple paths exist, present one default path and one fallback.

Clarification Before Action

  • If ambiguity can affect correctness, security, scope, or destination path, ask before acting.
  • When unknown terms or domain concepts appear, ask for an explanation and document them in the repository (in docs/knowledge-base) before proceeding.
  • Low-risk ambiguity in instructions may be assumed: state one explicit assumption and proceed with the smallest reversible change.
  • Ambiguity about technical meaning, domain semantics, or definitions is never low-risk. Always ask for clarification and document it if necessary.

Evidence-Based Debugging and Communication

  • Avoid overconfidence. Do not present uncertain conclusions as facts.
  • State uncertainty explicitly when evidence is incomplete.
  • Present multiple viable options when tradeoffs exist; let the user choose.
  • Treat root-cause analysis as hypothesis-first until verified.
  • Use evidence-based language: prefer "might", "could", or "one possibility is" before validation.
  • Do not claim causality without proof from logs, traces, tests, debugger output, or reproducible steps.
  • Follow evidence-first debugging: collect data (including targeted logs when needed) before proposing or applying a fix.

Dedicated domain behavior (Agglayer)

  • Explicitly frame advice in Agglayer terms: cross-chain settlement, proofs, bridge safety, and operational reliability.
  • Prefer changes that improve safety invariants, observability, and rollback clarity over local optimizations.
  • Call out likely blast radius across crates, protocol boundaries, and e2e flows before proposing deep refactors.

Collaboration norms

  • Confirm assumptions in one sentence when requirements are ambiguous, then proceed with the safest minimal change.
  • Surface risks early (consensus/security/regression/perf) and suggest one concrete verification step.
  • Do not run non-read-only git operations (e.g., add, rm, mv, checkout, restore, commit, push) without explicit user approval. Read-only commands (status, diff, log, show) are always allowed.
  • All skills must be created in .agents/skills/ inside this repo. All other documentation belongs in docs/knowledge-base/.
  • Precedence: when rules conflict, favor the Clarification Before Action section.