Coding Guidelines

This repo is intended to be a guide primarily read by agents to understand preferences and guidelines for coding, research, or any other task.

This repo should be accessible for reference over the internet or placed into context accessible by agents for work on a project.

Guideline substance lives under content/:

• content/shared/: Portable guidelines that can be imported into projects and shared with others (primarily agent-readable).
• content/personal/: Operator- and host-specific guidelines (shell config, host paths, personal skills). Stays in this repo; load when that context applies (still shaped for agents on those hosts).
• content/operator/: Human operator guidance for designing and running host controls around agents (sandboxing, PATH layout, loud bypasses). Not default agent session context.
• content/templates/: Opinionated stacks (specifications, not generators).

See the shared glossary for definition of specific terms and concepts as they are used throughout these documents.

Shared guideline groups

• Generic Agent Guidelines: Generic advice for any agent-assisted work.
• Project Management and Tooling: Config-file style, layered tooling, bootstrap/preload, and how automation invokes tools.
• Software: Authorship, maintenance, and documentation of software projects (guidelines, documentation, CLI UX, CLI applications).
• Blob Management: Large or opaque files managed alongside repository history (prefer DVC over git-lfs for new projects).
• Markdown style guide: GFM dialect, wrapping, fences, tables, and related formatting rules.
• Writing for humans: How agents should write to operators (chat, plans for review, plain-text-first output, abbreviations and initialisms).
• Technical Writing: Guidelines for technical writing meant for a non-personal audience.
• Writing Contributor Documentation: Contributor-facing docs, style-guide exceptions, and avoiding upstream restatement.
• Research: Guidelines for research.

Operator guideline groups

For humans who install and supervise agents on a host (not agent bootloaders):

• Operator hub: audience split and how to use this tree.
• Sandboxing agents: why default-on sandboxing, principles, threat model, escape hatches.
• Implementing a sandboxed agent CLI: reproduce the landrun + opt + PATH wrapper pattern on your own machine.

Templates

Opinionated, concrete stacks (not a cookiecutter/copier generator):

• Templates hub
• Generic project template: git, mise, hk, EditorConfig, PRJX, RFC 22 agent layout, blob defaults

Getting Started

• Projects: shared/getting-started.md (drop-in project AGENTS.md).
• Hosts (personal): personal/getting-started.md (drop-in ~/.agents/AGENTS.md, plus harness pointers such as ~/.config/goose/AGENTS.md for goose).
• Host hardening (operators): operator/README.md (sandboxing patterns distilled from bimker design decisions).

Maintaining this repo

See contributing/ for roles and workflows used to maintain this repository (not part of the portable shared set).

Developing this checkout (bootstrap, mise, hooks, checks): contributing/development.md.

Design / ADRs: design/.