Core Concepts

Core Terminology¶

agentId¶

A unique timestamped identity assigned to an agent folder (e.g., happybot@2025-05-24_19-15-55-492). Used to track, sign, and version every plan, cert, and compiled file.

cert¶

A signed JSON document generated by dokugent certify. Contains validated agent data, criteria, conventions, metadata, and optionally a BYO bundle.

criteria¶

Standards that define what “good output” looks like. Used by agents and humans to evaluate LLM responses.

plan index¶

A list of steps an agent is expected to follow. Created with dokugent plan. Traced by dryrun and simulate commands.

BYO bundle¶

Supplemental JSON files provided by the developer to customize or constrain agent behavior. Loaded during compile from .dokugent/data/byo.

traceability¶

The ability to follow the origin, version, and validation trail of every agent file. Powered by SHA256 hashes, signed certs, and structured folder layout.

Why Structure-First Matters¶

Most LLM-based workflows start with a prompt. Dokugent flips that: it starts with documentation and scaffolding.

By using structure-first development: - You reduce unpredictable agent behavior - You make expectations clear for humans and machines - You enable reproducibility across environments and models

Docs-as-Contract Philosophy¶

Dokugent treats Markdown files not as passive notes but as active contracts. Each file describes behavior, constraints, or evaluation rules that the agent must comply with.

This: - Encourages transparency - Supports human-in-the-loop review - Makes AI workflows safer and easier to audit

📦 What is BYO?¶

BYO (Bring Your Own) refers to external JSON files that you manually provide to enrich agent behavior, context, or validation logic.

Dokugent uses the .dokugent/data/byo/ folder to gather these supplemental files during compile. They get bundled into the final agent context under a secure, signed certificate.

Use BYO files for: - Domain-specific memory - Safety policies and filters - Role definitions or restrictions - Shared JSON specs across agents

Each BYO file should be in valid JSON format. Dokugent will scan and include them into the compiled agent’s runtime footprint, enabling modular and secure customization.