Tool Architecture¶

This page explains how Dokugent CLI is structured under the hood. It covers the folder layout, key file relationships, and how agent workflows are organized for traceability and runtime use.

Project Folder Layout¶

.dokugent/
├── data/
│   ├── agents/               # Per-agent configuration files
│   ├── byo/                  # Bring Your Own (BYO) JSON files
│   ├── compliance/           # Governance rules: contact,
│   │                         #   data sensitivity, retention, legal basis
│   ├── conventions/          # LLM behavior documentation
│   ├── criteria/             # Evaluation rules per agent
│   ├── io/                   # I/O rules: file types, access flags,
│   │                         #   denylist, approval policies
│   ├── owners/               # Identity definitions
│   ├── plans/                # Workflow steps
│   └── tool-list/            # Tools and capabilities listing
│
├── ops/
│   ├── certified/            # Signed agent certs
│   ├── compiled/             # Final compiled bundles
│   ├── logs/                 # CLI run logs
│   ├── previews/             # Agent preview results
│   └── reports/              # Audit reports, trace summaries
│
└── index/                    # Plan index, links, trace references

How Certs, Keys, and Plans Interact¶

AgentID: Every folder starts with an agentId, timestamped to mark identity and version.
Plans: Authored using dokugent plan, these define step-by-step workflows in .md format.
Criteria: Defined using dokugent criteria, describing what good outputs look like.
Conventions: Optional per-LLM behavior guides using dokugent conventions.
Keys: Created via dokugent keygen, used to sign and verify agent certs.
Certs: Generated using dokugent certify, capturing validated agent behavior and structure.
Compile: Combines certs, BYO data, and metadata into a deployable .compiled.cert.json file.

File Relationship Overview (ASCII Diagram)¶

[dokugent init]
      ↓
[dokugent agent] + [dokugent owner]
      ↓
[plan.md] + [criteria.md] + [conventions.md]
      ↓
[dokugent tool-list]
      ↓
[dokugent compliance] + [dokugent io]
      ↓
[dokugent preview] + [dokugent security]
      ↓
[dokugent certify] → .cert.json (signed)
      ↓
[dokugent compile] + byo.json
      ↓
.compiled.cert.json + .sha256 + logs + reports

This architecture ensures that every agent is:

Scaffolded with intent
Validated with criteria
Signed for trust
Traceable for audits

Next Up in Architecture¶

The following components are in active development and will be added here soon:

.dokugent/data/compliance/ — governance metadata: contact info, sensitivity, retention, user roles, log/audit refs
.dokugent/data/io/ — I/O rules for allowed outputs, denylists, approval policies
.dokugent/data/tool-list/ — LLM-visible tools and capability declarations