Plan Reference

dgov authors plans as plan trees under .dgov/plans/<name>/. dgov compile turns that tree into _compiled.toml, and dgov run executes the compiled output.

Structure Overview

# .dgov/plans/refactor-api/_root.toml
[plan]
name = "refactor-api"
summary = "Refactor the API surface"
sections = ["tasks"]
 
# .dgov/plans/refactor-api/tasks/main.toml
[tasks.validate]
summary = "Validate current state"
prompt = "Review src/api.py and verify the current endpoint structure"
commit_message = "docs: add validation notes"
files.read = ["src/api.py"]
 
[tasks.migrate]
summary = "Migrate to new schema"
prompt = "Refactor src/api.py to use the new typed response schema"
depends_on = ["validate"]
commit_message = "refactor: migrate api to typed schema"
files.edit = ["src/api.py"]
files.create = ["src/api/types.py"]

`_root.toml` `[plan]` Section

The plan-tree root metadata.

Field	Type	Required	Default	Description
`name`	string	Yes	—	Unique identifier for this plan
`summary`	string	No	`""`	One-line summary of the plan
`sections`	array of strings	Yes	—	Top-level section directories to compile

`[tasks.<slug>]` Section

Individual task definitions live inside section TOMLs such as tasks/main.toml.

Field	Type	Required	Default	Description
`slug`	string	Yes (implicit)	—	Task identifier (from table key)
`summary`	string	Yes	—	Short description for logs and UI
`prompt`	string	Yes	—	Instructions sent to the worker agent
`agent`	string	No	project default	Model/router override for this task
`depends_on`	array of strings	No	`[]`	Slugs that must complete first
`commit_message`	string	Yes	—	Git commit message on success
`timeout_s`	integer	No	900	Seconds before task aborts

File Claims `[tasks.<slug>.files]`

File claims enforce isolation between concurrent tasks. The kernel validates that independent tasks (no dependency edge) never claim overlapping file paths.

Field	Type	Description
`create`	array of strings	Files the task will create
`edit`	array of strings	Files the task will modify
`delete`	array of strings	Files the task will remove
`read`	array of strings	Files the task reads (informational, not enforced)
`touch`	array of strings	Flat claim list used by compiled plans and shorthand authoring

Flat File Claims Shorthand

For simple cases where you only need to claim files without specifying the operation type, use the files shorthand. This is equivalent to touch—the files will be created if they don't exist, and the task claims ownership.

[tasks.generate_config]
summary = "Generate default config"
prompt = "Create a default config.json with basic settings"
files = ["config.json"]

This is equivalent to:

[tasks.generate_config]
summary = "Generate default config"
prompt = "Create a default config.json with basic settings"
files.touch = ["config.json"]

Use the shorthand for brevity when the operation is clear from context, or use explicit create/edit/delete/read when you need precise control.

agent only overrides the model/router name for a task. Provider selection stays repo-level through .dgov/project.toml (llm_base_url and llm_api_key_env).

File Claim Isolation

File claims are the foundation of deterministic concurrency:

Declaration: Every task must declare files it touches
Validation: Before execution, the kernel checks for conflicts
Enforcement: Independent tasks with overlapping paths fail validation

Conflict Example (Invalid)

[tasks.a]
summary = "Update config"
prompt = "Change port to 8080"
files.edit = ["config.yaml"]
 
[tasks.b]
summary = "Also update config"
prompt = "Change port to 9090"
files.edit = ["config.yaml"]  # ERROR: no dependency edge with task.a

Valid Dependency Chain

[tasks.a]
summary = "Update config"
files.edit = ["config.yaml"]
 
[tasks.b]
summary = "Read updated config"
files.read = ["config.yaml"]
depends_on = ["a"]  # OK: explicit ordering prevents conflict

Path Overlap Rules

Conflicts are detected when paths are identical or one is a parent of another:

src/main.py overlaps with src/main.py
src/ overlaps with src/main.py
config.yaml does NOT overlap with other.yaml

Full Example

[plan]
name = "payment-gateway-refactor"
summary = "Refactor payment integrations safely"
sections = ["tasks"]
 
# === Phase 1: Analysis ===
 
[tasks.audit]
summary = "Audit current payment code"
prompt = """
Review src/payments/ directory and identify:
1. All external API calls
2. Error handling gaps
3. Missing type annotations
 
Write findings to audit_report.md
"""
agent = "senior-reviewer"
commit_message = "docs: payment system audit report"
timeout_s = 1200
files.read = [
    "src/payments/",
    "src/payments/stripe.py",
    "src/payments/paypal.py",
]
files.create = ["audit_report.md"]
 
# === Phase 2: Design ===
 
[tasks.design_schema]
summary = "Design new payment schema"
prompt = "Based on audit_report.md, design typed models for PaymentMethod and PaymentResult"
depends_on = ["audit"]
commit_message = "design: payment type schema"
files.read = ["audit_report.md"]
files.create = ["src/payments/types.py"]
 
# === Phase 3: Implementation ===
 
[tasks.refactor_stripe]
summary = "Migrate Stripe integration"
prompt = "Refactor src/payments/stripe.py to use new types from src/payments/types.py"
depends_on = ["design_schema"]
commit_message = "refactor: migrate stripe to typed models"
files.edit = ["src/payments/stripe.py"]
files.read = ["src/payments/types.py"]
 
[tasks.refactor_paypal]
summary = "Migrate PayPal integration"
prompt = "Refactor src/payments/paypal.py to use new types from src/payments/types.py"
depends_on = ["design_schema"]
commit_message = "refactor: migrate paypal to typed models"
files.edit = ["src/payments/paypal.py"]
files.read = ["src/payments/types.py"]
 
# === Phase 4: Cleanup ===
 
[tasks.remove_legacy]
summary = "Remove legacy payment module"
prompt = "Delete src/payments/legacy.py after confirming no imports remain"
depends_on = ["refactor_stripe", "refactor_paypal"]
commit_message = "chore: remove legacy payment module"
files.read = ["src/payments/stripe.py", "src/payments/paypal.py"]
files.delete = ["src/payments/legacy.py"]

Validation

Validate a compiled plan without executing:

dgov validate .dgov/plans/payment-gateway-refactor/_compiled.toml

This checks:

TOML syntax and schema
All dependencies reference existing tasks
No file conflicts between independent tasks
All tasks have resolvable agents