AGENTS.md — Operating Contract for AI and Coding Agents¶

This file is the primary, tool-agnostic operating contract for any AI or coding agent working in this repository — Claude Code, Codex, Gemini CLI, GitHub Copilot, or any future agent. Tool-specific entry points (CLAUDE.md, GEMINI.md) exist and must defer to this file; they do not replace it.

Repository purpose¶

This repository is the governance and documentation source of truth for Devonshire Digital LLC and its ventures. It is documentation-first: most work here is writing, revising, or validating documentation, specifications, and small validation scripts — not shipping product features. Treat every change as something a human will read and rely on.

Required reading sequence¶

Before doing any substantive work, read in this order:

This file (AGENTS.md).
docs/ai/repository-context.md — what this repository is, its structure, and its conventions in more depth.
The applicable venture's ventures/<slug>/AGENTS.md, if the task touches a specific venture (e.g., ventures/shelfery/AGENTS.md).
Applicable standards (docs/standards/) and any related ADRs (docs/decisions/) for the area you are changing.

Full detail on load order and precedence is in docs/ai/context-loading-order.md.

Authority and inheritance¶

Company-level documents (docs/company/, docs/governance/, docs/standards/) set the floor. Venture-level documents (ventures/<slug>/) may add constraints specific to that venture but cannot weaken or override company-level policy. If a venture document appears to contradict a company document, treat the company document as controlling and flag the contradiction — do not silently pick one. Full rules: docs/governance/authority-and-inheritance.md.

Planning requirements¶

Nontrivial tasks (anything touching more than one file, anything that changes a policy's meaning, anything that will take multiple steps) require a written work plan in work/active/ before you start making changes. See docs/ai/planning-and-work-logs.md for the required plan structure and lifecycle (active → completed/archived).

Trivial tasks (a single typo fix, a single broken link fix) do not require a formal plan, but still warrant a one-line explanation of what you did and why.

Work-log expectations¶

For any nontrivial task, keep a running work log alongside the plan (see docs/ai/planning-and-work-logs.md). The log should let a human reconstruct what you did and why without re-reading the full diff.

Editing discipline¶

Make targeted edits. Change only what the task requires.
Do not perform unrelated rewrites, reformatting, or "drive-by" cleanups in the same change, even if you notice something else that looks wrong — note it instead (in the work log, or as a new entry in docs/governance/open-questions.md) and leave it for a separate, scoped task.
Preserve existing document metadata front matter unless the task is specifically to update it. If you update a document's substance, update last_reviewed and bump version appropriately.

File ownership boundaries¶

Documents are owned by roles (e.g., "Founder", "Repository Maintainer"), never by personal names. Do not add named individuals as owners.
Do not edit another venture's directory when working on a task scoped to one venture, unless the task explicitly requires a cross-venture change.
Do not restructure the top-level directory layout without an ADR.

Venture-specific context loading¶

When a task is scoped to a venture (e.g., Shelfery or Digital Products), load that venture's AGENTS.md and any product specifications under ventures/<slug>/ in addition to company-level context. Venture brand and naming details (e.g., Shelfery's color palette, Digital Products' working name) are provisional unless marked otherwise — do not present them as final in any generated content.

Product specification gates¶

Do not generate or scaffold product implementation code for a product that lacks a required specification, unless a human has explicitly authorized starting without one. What "required" means for a given product type is defined at the venture level; when in doubt, stop and ask rather than assume the gate is satisfied.

ADR requirements¶

Material architecture or policy decisions (anything that would be expensive to reverse, or that changes a company-wide rule) require an Architecture Decision Record under docs/decisions/, using the template in templates/. If you make such a decision as part of a task, write the ADR as part of that same task — do not defer it.

Evidence requirements¶

Do not present assumptions, estimates, or generated content as verified fact. Follow docs/company/research-and-evidence-principles.md: label claims as verified fact, observed evidence, customer statement, hypothesis, assumption, inference, or recommendation. Fabricated market data, fabricated test results, and fabricated customer quotes are prohibited outright — not just discouraged.

Validation requirements¶

Before considering any task complete, run:

python scripts/check.py

and, where applicable, the test suite:

python -m unittest discover tests

A task is not done if validation fails and the failure was not addressed or explicitly called out as a pre-existing, unrelated issue.

Human-review requirements for high-risk domains¶

Content or code touching legal claims, financial claims, privacy, security, medical/health information, nutrition, or food safety requires explicit human review before being treated as final. Flag such content clearly in your work log and do not mark it as approved.

Handoff expectations¶

When you stop work on a task — whether finished or not — leave the work plan and work log in a state that lets another agent or a human pick it up without reconstructing context from the diff alone. State what is done, what is pending, and any open questions you surfaced.

Definition of complete¶

A task is complete only when:

The requested change is made with targeted edits.
Required metadata front matter is present and accurate on any new or substantively changed document.
Validation (scripts/check.py, and tests where applicable) passes or failures are explicitly explained.
Any material decisions are recorded as ADRs.
The work log reflects what was actually done.
Nothing is marked status: approved unless a human has actually approved it.

Prohibited behavior¶

See docs/ai/prohibited-behaviors.md for the full list. At minimum: do not fabricate evidence or test results, do not introduce secrets or real customer data, do not mark draft policy as approved, do not silently override company-level policy with venture-level content, and do not perform large unrequested rewrites.

Report an issue about this page