Project structure¶

my-project/
├── pyproject.toml / uv.lock      # Python dependencies (uv)
├── tuvl.lock                     # pinned model ids, artifact hashes, MCP schemas (tuvl lock)
├── .env / .env.example           # secrets and connection settings — never in YAML
├── specs/
│   ├── triage-ticket.md          # intent: flows, policies, acceptance examples
│   └── triage-ticket.tasks.yaml  # task list, written by the coding agent — statuses are derived
├── workflows/                    # kind: Workflow (version: tuvl/v2)
├── agents/                       # code agents: one @agent function per file
│   └── _generated/schemas.py     # typed In/Out models (tuvl codegen) — never hand-edited
├── models/                       # kind: ModelDefinition, EmbeddingRegistry, CollectionRegistry
├── llms/                         # kind: AgentModel — type llm or decision
├── datasources/                  # kind: DataSource
├── federation/                   # kind: FederationProvider
├── artifacts/                    # prompts, steering, skills (.md); guardrail, hook, mcp, judge, rules (YAML)
├── tests/
│   ├── triage_ticket/*.yaml      # kind: Test (generated from the spec, or hand-written)
│   └── fixtures/                 # pinned run journals for replay
├── fixtures/judge/               # labelled judge calibration subjects
├── .agents/                      # AGENTS.md + skills for coding agents (tuvl skills update)
└── .tuvl/                        # system.yaml, layout, breakpoints, judge cache, dev session

Folder names are conventions: tuvl discovers documents recursively and dispatches them by kind:.

Generated vs written¶

Document kinds¶

Workflow, Test, TaskPlan (all version: tuvl/v2), ModelDefinition, AgentModel, DataSource, RedisConfig, EmbeddingRegistry/EmbeddingConfig, CollectionRegistry/ CollectionConfig, FederationProvider, Artifact, ProjectConfig, TelemetryConfig, SystemConfig. Every document is kind: + metadata: + spec:. See the Agentic Manual.