Saturngod-Inspired Repository Guide

Saturngod-Inspired Repository Guide

A reusable pattern for a project-level AGENTS.md. Adapt it to facts in the repository and delete irrelevant sections. Precision matters more than length.

Principles

1. Declare the source of truth for product scope and acceptance.
2. Explain architecture and dependency direction concisely.
3. Name trust boundaries and non-negotiable invariants.
4. Provide exact setup, focused-check, full-check, and release commands.
5. Separate handwritten, generated, migrated, and vendored code.
6. State where tests belong and which contracts need regression coverage.
7. Keep subsystem traps in scoped guides near their code.
8. Require evidence before declaring completion.

Template

# Repository Guide

## Product and source of truth
- Purpose and users:
- Scope/plan:
- Definition of done:
- Progress tracker rule:

## Architecture
- Runtime/application shell:
- Modules and responsibilities:
- Dependency direction:
- Public API:
- Authoritative data/contracts:

## Trust boundaries and invariants
- Untrusted inputs:
- Authentication/authorization:
- Tenant/workspace isolation:
- Cross-process schemas:
- Secret/redaction policy:
- Forbidden generic capabilities:
- Values mirrored across services:

## Project structure
- Production code:
- UI/application shell:
- Tests:
- Resources:
- Generated code—do not hand-edit:
- Migrations/data:

## Commands
- Setup:
- Development:
- Focused test:
- Full tests:
- Format/lint/typecheck:
- Complete verification:
- Package/release:

## Coding conventions
- Language/framework idioms:
- Naming/formatting:
- Error handling:
- Concurrency/isolation:
- Reuse existing components and services before adding new ones.

## Testing
- Framework/location:
- Name tests after behavior.
- Add regression coverage for contracts, parsers/codecs, state transitions, controllers, and security changes.
- Visual behavior requires browser/device evidence.

## Generated code and migrations
- Regeneration command:
- Never hand-edit generated paths.
- Never modify an applied migration; append a forward migration.

## Operations
- Long-running processes:
- Configuration precedence:
- Retry/cleanup/observability:
- Deployment and rollback:

## Things an agent might get wrong
- [Non-obvious invariant and why]
- [Historical regression to avoid]
- [Plan statement differing from executable behavior]

## Completion report
Return the user-visible outcome, changed files, exact verification, boundary confirmation, generation/migration actions, compatibility impact, and remaining risks. Never commit, push, release, weaken permissions, or expose credentials unless explicitly authorized.

Preferred dependency shape

Do not create these layers for a small script without real change pressure.

Verification ladder

1. Smallest relevant test while iterating
2. Formatter/linter/typecheck for touched languages
3. Repository combined check
4. Platform, E2E, or package check when crossing that boundary
5. Browser/device/screenshot evidence for visual behavior

Scoped instruction files

Add a nested guide when a subsystem has an independent runtime, language, deployment, generated surface, security boundary, or dangerous gotchas. Link to root guidance and document only narrower facts.

Related

• Saturngod Repository Engineering Study
• Spec Map Build Prove Learn
• Agent Rules
• Definition of Done

Knowledge connections

• Vault Knowledge Graph
• AI Engineering Map