Opinionated AGENTS.md Harness

A portable, strict agent harness for making AI coding agents behave: small diffs, clean layers, explicit guardrails, and honest validation.

Note

This is a template. Copy this file to your repo root as AGENTS.md, then rename this heading to your repo name.

🔍 Search for ✏️ to find all places you need to customize.

The top half (above the ^^^ boundary) is the Code Commander's doctrine — universal standards that apply to any codebase. Tweak sparingly. The bottom half (below the boundary) is your repo's context — fill it in with your stack, layout, conventions, and dev setup.

Works with: Pi, OpenCode, Codex, Cursor, Antigravity, Claude Code, and any agent that reads AGENTS.md.

Your work shall be judged by the Code Commander — a veteran engineer who has shipped systems older than most frameworks. He is ruthlessly strict about craft, but carries a young heart: he remembers what it felt like to push his first production deploy at 2 AM, and he respects anyone willing to learn. Mention him (directly or metaphorically) after code edits.

✏️ <one-line description: language/runtime, what it is, one owner or team>

Our Core Principles

Override: If the user's message contains I as code commander ask you to …, bypass guardrails for that single turn only.

Our way of thinking

Think step by step. Divide into atomic steps, then execute.
Read existing files for full context before editing.

Surface assumptions. State them before coding. Multiple interpretations? Name them.
Simplicity first. Minimum code that solves the problem. No speculative features.
Surgical changes. Touch only what the task requires. Match existing style. Remove only orphans your changes created.
Goal-driven execution. Transform tasks into verifiable criteria, then execute.

Our Core Values

Conciseness: 300-line files, small functions
Organization: layering, modularization, consistency
Clarity: quick human understanding
Standards: TYPE SAFETY, naming consistency, one way to lint
Spec & Wiki: check docs before starting work (see §Wiki & Specs)

Coding Standards (EXTREMELY IMPORTANT)

Applies to all languages & frameworks — even docs & AI rules.

PATTERN: Layering & Modularization (EXTREMELY IMPORTANT)

Everything has a place, and everything should be at its place

Layering & Modularization is the CRUX of software engineering.
Break complex functions. Hunt for patterns that make code wet & make it DRY.
Find opportunities to group common code into shared libraries & modules.
Push lower level functions into base/, core/ and similar pkgs/files/modules.
Always try to first find the lego blocks to compose higher level functions and reuse them.
Directory hygiene (≤ 7 files). Past 7 → introduce subdirectories by domain.

If you find something needing better modularization or layering, present findings to the user. e.g: We are converting datetime objects → timestamps everywhere... shall we create a shared utility?

Associate every function/file/module with a layer:

Layer 0: Depends on nothing.
Layer N: MAX(all things it depends on) <= N-1
Reduce the layer value of everything in day-to-day work.

PATTERN: Clean Code: Small Functions (EXTREMELY IMPORTANT)

Easiest rule to follow — readable, clean code as a side effect.

Function body ≤ 60 lines. Ideally 20–50.
One-liner single-use functions: inline them at the call-site. A named function that wraps a single expression and is called once adds indirection without value.
If you find a violation, put this in its docstring:
- ⚠️ I am a poorly written function... Please refactor me ⚠️
- Also surface it to the user towards the end of your turn.
The length metric alone is not enough — split on LOGICAL units of abstraction.

PATTERN: Clean Code: Miscellaneous (EXTREMELY IMPORTANT)

Avoid more than 2 nested levels of if-else / switch-case / try-catch in any function.
Avoid try-catch in general — put it at the top level. Let lower functions throw and bubble up.
- Corollary: No chains of fallbacks. Such code hides when primary paths fail.
Use functional patterns (match...case in Python, equivalent elsewhere).
Use declarative patterns as much as possible.
Type safety:
- All functions should define input-output types.
- Types should be precise — dict is a useless type.
- Applies to all languages; critical in Python.
- Reuse types by composing smaller types.
Naming: Consistency is key.
- Keep it concise and mildly abbreviated.
- See Codebase Conventions section for accepted shorthands.

File Docstrings

Every source file must have a top-level docstring (first line, or first after imports).
Format: /** <what this file contains/exposes> */ (TS) or """<what>""" (Python).
Keep to 1-2 lines. Skip for index.ts barrel files and generated code.

PATTERN: Clean Code: Comments (IMPORTANT)

NEVER delete existing comments unless asked. You may shorten or reword; preserve intent.
Keep comments minimal. Explain WHY, not WHAT.
Crisp docstrings on all exported classes & public functions.
No 1-liners inside functions/classes unless the name is too ambiguous.

Use comments as logical separators:

Type A: Top-level (dashes go till col 80):

# ------------------------------------------------------------------------------
# important section name
# ------------------------------------------------------------------------------

Type B: Nested:

# crisp-section-name -----------------------------------------------------------
  # helper functions -----------------------------------------------------------

Type C: Small markers (within functions): # background-tasks ----

After any banner: no blank line before next code.

META INSTRUCTIONS: Writing AGENTS & SKILL Files

These rules govern how AGENTS.md, SKILL.md, docs/specs/, and docs/wiki/ files are written.

Hierarchical reveal — summary first, details in subsections.
Telegram density — one idea per line; no filler.
Imperatives over prose — "Run uv sync" not "You should run…"
Refer, don't duplicate — point to source files.
MD tables ≤ 4 columns — wider tables are unreadable in raw markdown; use nested bullets or split.
Shell examples: prefer one fenced block with related commands separated by # comments.
TL;DR at top (implicit or explicit). Key Files last, as bullet markdown links.
Line caps — wiki/readme/skills ≤ 300 lines; top-level AGENTS.md ≤ 400 lines.

Guardrails (EXTREMELY IMPORTANT)

GUARDRAILS ARE NOT NEGOTIABLE. CAN ONLY BE BYPASSED WITH THE SPECIAL CODE-COMMANDER OVERRIDE PHRASE.

✏️ Type Checking

Run after significant code changes — or when asked. Ask user permission first.

<runtime>: <typecheck command>

After editing typed code across multiple files, offer: "Want me to run type checks?"

Shell & Tooling

To filter/exclude lines in a pipe, use grep -v (not rg -v). rg -v without explicit input recurses the entire tree + inverts = output explosion.
ripgrep globs (--glob): avoid nested ** patterns (e.g. **foo/.bar**). Complex glob composition can hang due to catastrophic backtracking in globset.
While editing .gitignore file(s), make sure to have ripgrep friendly patterns.

Git Operations

Allowed (RO & LOCAL commands): git diff, git log, git branch, git status.
NOT ALLOWED (RW & REMOTE commands): git push, git commit, git merge, git reset, git rebase.

Secrets & Environment

Never echo $SECRET_VAR or printenv SECRET_VAR — leaks into terminal history.
To check existence: [[ -n "$VAR" ]] && echo set || echo unset — value never printed.
Never hardcode credentials, API keys, or tokens in code or scripts.
Never log secrets via console.log, print, or logger.*.

Destructive Operations

Confirm with user before:

rm -rf on any path outside scratch directories or /tmp/
Dropping or truncating database collections or tables
Installing packages globally (npm install -g, pip install --user, etc)
Destructive git operations which can damage local or remote state ARE NOT ALLOWED.

Hands-Off Directories

Do NOT create or edit files in these directories unless explicitly asked:

.cursor/ — Cursor rules/settings only
.claude/ — Claude Code settings/MCP
.vscode/ — VS Code workspace settings

Key Sections in This File (Quick Reference)

These sections are owned by the AI (below the boundary). Know where they are:

## About The Repo — skills catalog, wiki & specs system
## Monorepo Layout — directory tree
## Stack — runtimes, tooling, CI
## Guardrails — non-negotiable safety rules
## Codebase Conventions — naming, shorthands, env files, generated code, scratch
## Local Development — dev server URLs, sync setup, commit hygiene
## Key Files — quick-reference markdown links (always last)

AGENTS.local.md — Machine-Specific Additive Rules

AGENTS.local.md is a gitignored file at repo root. It layers on top of this file — additive by default, but may override any section when it says so explicitly. Use it for: local port overrides, SSH tunnel URLs, shell quirks, MCP safety rules, alternate credentials, custom tooling paths.

^^^ ANYTHING ABOVE THIS SHOULD NOT BE MODIFIED BY AI ^^^ Code Commander

About The Repo

✏️ Agent Skills

~/.agents/skills/ (global)
.agents/skills/ (repo-level)
Never create .cursor/skills/ or .cursor/commands/. Prefer .agents/ for portability.
Layout: SKILL.md required; README.md optional; *-reference.md for heavy reference.
Keep SKILL.md under 300 lines. Heavy reference → sibling .md, one level deep.

Skill	Purpose
`<skill>`

✏️ Wiki & Specs System

docs/wiki/ — permanent knowledge
docs/specs/ — designs to build

Full rules: docs/AGENTS.md.

✏️ Monorepo Layout

src/       → Application source code
tests/     → Test suites
docs/      → Documentation
config/    → Configuration files

Stack

✏️ <Runtime 1>

<setup / install commands>
<build / lint / test commands>

✏️ <Runtime 2>

<setup / install commands>
<build / lint / test commands>

✏️ CI Pipeline

<job 1>
<job 2>

Codebase Conventions

✏️ Naming & Shorthands

Timestamps use consistent suffixes: start_ts, end_ts, created_ts, updated_ts, scheduled_ts, expiry_ts.

Short	Meaning	Notes
`ctx`	Context
`db`	Database

Generated Code

Machine output is gitignored. Never commit.

Environment Files

Template suffix: *.env.example. Gitignore all .env* and *.env.
Use FIXME placeholders — never real credentials.

✏️ Scratch Directory

<scratch-dir>/ — <purpose, e.g. gitignored scratch + runtime artifacts>

✏️ Local Development

Service	URL	Source
`<name>`	http://localhost:``	`<source>/`

✏️ Key Files

AGENTS.md — this file, repo-wide agent rules
<path> —

dsculptor/AGENTS.template.md

Select an option

No results found