Project structure

A Verdog project contains one Python package, its workflow graphs, and its dependency pins. Git records project revisions; published releases refer to commits in a GitHub repository.

Files

A project combines repository-level metadata with a Python package that implements its workflows. ◆ project.json records the graph, while the package contains its subroutines, domain types, and generated declarations.

General project structure

◆ project.json
◆ pyproject.toml
◆ verdog.lock                 only when the project has pinned dependencies
● .gitignore
● AGENTS.md
src/<package>/
├── ◆ __init__.py
├── ● README.md
├── ● impl.py
├── ◆ workflows/__init__.py
├── workflows/<workflow>/
│   ├── ◆ __init__.py
│   ├── ◆ profiles/__init__.py
│   ├── profiles/<profile>/
│   │   └── ◆ __init__.py
│   ├── ◆ sessions/__init__.py
│   ├── sessions/<session>/
│   │   └── ◆ __init__.py
│   ├── ◆ bindings/__init__.py
│   └── ● requirements.txt
├── ◆ subroutines/__init__.py
└── subroutines/<subroutine>/
    ├── ◆ __init__.py
    ├── ● impl.py
    ├── ◆ workflows/__init__.py
    ├── ◆ subroutines/__init__.py
    ├── ◆ profiles/__init__.py
    ├── profiles/<profile-or-parameter>/
    │   └── ◆ __init__.py
    ├── ◆ sessions/__init__.py
    ├── sessions/<session-or-parameter>/
    │   └── ◆ __init__.py
    ├── ◆ features/__init__.py
    ├── features/<feature>/
    │   └── ◆ __init__.py
    ├── ◆ nodes/__init__.py
    ├── nodes/<node>/
    │   ├── ◆ __init__.py
    │   ├── ● impl.py        non-Feature executable nodes only
    │   └── visit/<incoming-edge>/
    │       ├── ◆ __init__.py
    │       └── ● impl.py
    └── edges/
        ├── ◆ __init__.py
        └── <edge>/
            └── ◆ __init__.py

Nested definitions repeat this layout below their parent subroutine. The tree shows compiler-created files; authored helpers, prompts, and tests may add paths according to the project's placement rules.

File	Role
◆ project.json	Canonical graph, editor layout, source manifest, and graph identity. Graph operations change this file.
◆ pyproject.toml	Shared Python package metadata, runtime dependency, and source paths. Workflow-specific packages remain in each workflow's ● requirements.txt.
◆ verdog.lock	Resolved pinned projects. It exists only while the project has external dependencies.
◆ src/<package>/__init__.py	Reexports the project Payload and records the generated ABI version.
Other ◆ __init__.py files	Declare entities, collect graph components, or mark Python packages. The workflows/ and subroutines/ collection files are empty package markers.
● src/<package>/impl.py	Declares the initial Payload type and its associated domain types.
● src/<package>/README.md	Public description of the project's workflows, their authors, inputs, and outputs.
● AGENTS.md	Authored rules for state, code, and prompt placement.

New projects include ● .gitignore if the repository does not already contain one.

Shared values

The compiler initially aliases each subroutine's Input and Output to the package Payload. Authors may replace those aliases with domain types in the subroutine's ● impl.py; Verdog does not require a universal payload type.

Place a shared type in the narrowest scope containing its consumers. The scaffolded AGENTS.md reserves package-root impl.py for Payload and types used in its annotations.

Package namespace

A project declares any number of root workflows and root subroutines, including none. A root definition's ID is its name, and its module lies directly under src/<package>/workflows/<id>/ or src/<package>/subroutines/<id>/. A root workflow wraps the root subroutine with the same name. Root definitions may be renamed and deleted like nested ones. project.json lists the root definitions in its top-level workflows and subroutines arrays.

Generated calls identify a target by its definition ID and concrete Python module path; the enclosing workflows/ and subroutines/ packages contain no discovery registry.

Pinned projects are Git submodules under external/<alias>/ and retain their own manifests. Their authored files remain ordinary Git working-tree files. The editor protects generated files according to each project's manifest. Compiling the consuming project checks supplied dependency files and their generated ABI but does not regenerate dependency files.

Countdown example

The Countdown project uses these paths and identifiers:

Project element	Countdown
Package	demo.countdown, stored under src/demo/countdown/
Domain value	Count(value: int) in ● subroutines/main/impl.py
Root workflows	main, with the full ID demo.countdown.main
Root subroutines	main, with the full ID demo.countdown.main in the subroutine namespace
Definition modules	demo.countdown.workflows.main and demo.countdown.subroutines.main