Workspace guidance

AGENTS.md and Agent Skills

Use AGENTS.md for repository instructions that should apply automatically by location. Use Agent Skills for reusable guidance that should be searched and loaded only when a task makes it relevant.

The workspace-root AGENTS.md applies to the whole q workspace. A nested file applies to its directory and descendants.

Loading and precedence

q loads <workspace>/AGENTS.md when a session starts. The root guidance is available to ordinary chat, ACP sessions, and subagent model requests.

When a structured tool call identifies a path, q checks directories from the workspace root toward that target. Newly applicable nested files are inserted root-to-leaf, so the deeper AGENTS.md wins when repository instructions conflict inside its subtree.

If a new nested file is discovered immediately before a tool batch, q pauses that batch, adds the instruction, and returns a tool error asking the model to review it. The model can then retry only the calls that are still appropriate. Loaded instructions remain in the leading instruction block through context compaction.

Repository guidance remains subordinate to the system contract, q’s built-in developer instructions, and the user’s explicit request.

Path detection

q recognizes structured JSON fields such as path, paths, file, directory, source, destination, root, workdir, and working_directory.

It deliberately does not parse shell command strings for paths. If a nested directory is reached only through an opaque shell command, its AGENTS.md is not discovered automatically before that command runs.

Instruction safety

Each AGENTS.md is limited to 64 KiB and must be UTF-8 text without NUL bytes. Oversized valid text is truncated with a marker. Unreadable files, non-regular files, invalid text, and symlinks that resolve outside the workspace are ignored so repository-controlled prompt input remains bounded.

These checks constrain instruction loading. They do not sandbox shell commands or make repository instructions trusted above user and system policy.

Discovery with .qignore

The workspace-root .qignore filters directory discovery and root listings. It supports comments, negation, root anchoring, directory suffixes, and *, **, and ? wildcards. q’s own .q/ metadata is always excluded from discovery.

.qignore is not an access-control boundary. A model tool can still read an explicitly requested path when that path remains inside the workspace. Use operating-system permissions or isolation when a path must not be accessible at all.