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 workflow, its authors, input, and output.
● 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

Every project has a package-level main workflow and main subroutine whose identifiers cannot be renamed. The root workflow must select that subroutine as its entry. 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 workflow	main, with the full ID demo.countdown.main
Root subroutine	main, with the full ID demo.countdown.main in the subroutine namespace
Definition modules	demo.countdown.workflows.main and demo.countdown.subroutines.main