dokugent conventions¶

How to Use¶

Interactive Wizard¶

Launches an interactive setup to scaffold a convention folder under a specific type (e.g., dev, editorial, qa, etc.). You can include agent files by typing their filenames manually.

Instant Scaffold (--t)¶

Quickly creates a versioned folder and drops a README.md file. If used with a type argument (e.g. --t editorial), it will:

Create the type folder if it doesn’t exist
Create a versioned folder named after the active agent
Create a symlink named latest
Write a blank README.md in the version folder
Generate a conventions.meta.json file containing convention metadata

Flags and Parameters¶

Flag	Description
`--t`	Create a blank `README.md` in the resolved convention folder. Accepts an optional type argument.
`--edit`	Reserved. (Not implemented yet.)
`--show`	Alias of `--trace`. Recursively prints contents of all `.md` files with token counts.
`--trace`	Same as `--show`, prints token counts and content per file.
`--check`	Validates the convention structure. Lists all markdown files with estimated token usage.

Convention Commands¶

Trace¶

Recursively lists .md files in the latest folder of each convention type, displaying filename, token count, and content.

Show¶

Alias of --trace. Same behavior.

Check¶

Scans all convention types with a latest symlink. Lists all .md files per type and displays estimated token counts per file and per folder. Flags missing or empty folders.

Instant Scaffold (--t)¶

Summarizes --t behavior:

Uses current agent ID in version slug
Fails gracefully under dev
Autogenerates folder, versioned folder, symlink, README.md, and conventions.meta.json file if needed

Folder Layout¶

.dokugent/data/conventions/
├── dev/
│   ├── happybot@2025-05-24_19-15-55-492/
│   │   ├── GPT4.md
│   │   └── conventions.meta.json
│   └── latest → happybot@2025-05-24_19-15-55-492
└── editorial/
    ├── happybot@2025-05-26T23-46-08-275Z/
    │   ├── README.md
    │   └── conventions.meta.json
    └── latest → happybot@2025-05-26T23-46-08-275Z

Best Practices¶

Only use --t for non-dev types (e.g., qa, editorial, etc.)
Maintain a single active latest symlink per convention type
Use agent-specific filenames (e.g., GPT4.md, LLM-CORE.md)
Convention files should reflect what the agent needs to know, not serve as full system prompts