Guidance files are project-level instruction files for LLM-enabled editors and coding agents. They teach the assistant how to read Tonto syntax, reason with UFO and OntoUML stereotypes, choose task-specific procedures, and keep generated changes reviewable.
The guidance files are generated by Tonto templates. Do not copy them manually unless you need to customize them.
Add guidance during project initialization
Run:
tonto-cli init
The initializer asks which editor or agentic IDE you use:
Cursor
VS Code
Codex
Claude Code
Google (Gemini / Antigravity)
All
It writes the guidance files into the folder expected by the selected environment.
Add guidance to an existing project from VS Code
Open the project folder in VS Code and run:
Tonto: Add Guidances to project (Work with LLMs)
This command writes the same guidance set without recreating the Tonto project.
Generated locations
| Target | Generated location | Format |
|---|---|---|
| Cursor | .cursor/rules/ | .mdc rule files |
| VS Code / GitHub Copilot | .github/instructions/ plus .github/copilot-instructions.md | .instructions.md files |
| Codex | .codex/ | Markdown files |
| Claude Code | .claude/ | Markdown files |
| Google Gemini / Antigravity | .agents/ | Markdown files |
| All | Every target above | Mixed |
Guidance file set
The filenames vary slightly by target extension, but the content follows this structure:
| Guidance | Purpose |
|---|---|
tonto-guidance | General Tonto grammar, project structure, stereotypes, syntax patterns, relations, generalization sets, reserved keywords, and recommended LLM workflow. |
tonto_llm_guidance | Router guidance. It maps the user request to the most relevant specialized guidance file. |
tonto-cardinality-guidance | Explains how to read and choose relation cardinalities such as [1], [0..1], [*], and [1..*]. |
tonto-llm-create-new-elements | Procedure for creating or extending ontologies with new classes, relations, attributes, packages, and generalization sets. |
tonto_llm_terminology_analysis_guide | Procedure for checking names, labels, attributes, relations, stereotype congruence, and terminology consistency. |
tonto_llm_understanding_and_summarization_guide | Procedure for summarizing a package or complete ontology in natural language. |
tonto_llm_documentation_guide | Procedure for writing labels, descriptions, JSDoc-style comments, and multilingual documentation. |
The VS Code target also creates .github/copilot-instructions.md, which points Copilot to the generated instruction files.
Router pattern
The guidance set uses a router-and-specialist pattern:
- The assistant reads the user request.
- It selects the relevant specialized guidance.
- It inspects the existing Tonto project before editing.
- It proposes a plan or change with stereotype rationale when the request affects the ontology.
- The modeler reviews the result and runs validation.
This keeps the general Tonto reference separate from task-specific modeling judgment.
Recommended prompt starter
When asking an assistant to work with a Tonto ontology, include the project context explicitly:
Use the Tonto guidance files in this project.
First inspect tonto.json, imports, package names, and existing declarations.
Then propose a short plan before editing.
After changes, explain the main UFO stereotype choices and tell me what to validate.
For a concrete task:
Extend this ontology with course offerings and course enrollment.
Use Tonto syntax, preserve the existing package structure, and model material relations
with relators when the relation has its own properties.
Validation after guidance-assisted edits
After accepting generated changes, run:
tonto-cli validate .
If you want the assistant to repair errors, paste the validation output or point it to the editor diagnostics and ask it to revise the smallest necessary part of the model.