files/AGENTS.md

files — AGENTS.md

Repository shape

This repository contains one agent-facing CLI, files, implemented in files.zig and built by build.zig. Keep the tool small, native, stream-oriented, and easy to audit from argv alone.

Work tracking

No tracker, git remote, or durable plan file is present in this checkout. Treat user chat as the active work authority. Do not create a local issue mirror, backlog, roadmap, or PLAN.md unless explicitly requested.

Requirement governance

REQUIREMENTS.md is the requirement authority for this repository and is checked with redgate. Before implementation work, read the applicable requirement row; if none covers the durable behavior, update REQUIREMENTS.md first or stop and ask for authority. Choose the lowest honest ring by product foundation, not implementation size. If one row mixes foundational and optional behavior, split it before implementation.

For behavior intended to stick, write or update a failing POSIX-sh smoke, contract test, or executable proof before implementation code; run it and record the RED result. If RED proof would be fake, unsafe, or disproportionate, state that exception before implementation and use the strongest cheaper check. Before final handoff, compare the user request and actual diff against REQUIREMENTS.md. If there is no requirement impact, the handoff must include exactly REQUIREMENT IMPACT: none - <specific reason>.

POSIX/suckless agent-tool contract

• files does one job: list file-like paths below path roots or echo file path roots.
• stdout is records only: one path per line, no color, progress, prompts, paging, sorting, or decoration.
• stderr is diagnostics only: usage errors, runtime failures, and test messages.
• Exit 0 on success, 2 for usage errors, and nonzero for runtime failures callers must notice.
• Keep argv permission-sized: zero or more path roots plus sole-argument --help/-h; no expression language, callbacks, deletion, exec, network, hidden writes, or config discovery.
• Prefer POSIX behavior and boring native code over clever features. Do not add filters, sorters, metadata output, pagers, JSON, or interactive modes; callers can compose grep, sort, awk, cut, head, stat, and redirection.

Verification

Run these before handoff when touched files can affect behavior or governance:

zig build test
redgate list
redgate lint --strict
redgate health --strict

zig build test runs the POSIX-sh smoke suite in tests/files-smoke.sh against zig-out/bin/files.