godmode-core
godmode-core is the library crate behind the godmode command. It owns the task graph and
session domain model, repository state files, plan and template ingestion, verification and review
engines, agent and workflow metadata, governance policy evaluation, and adapters for external
tools. godmode-cli is intentionally the presentation layer over these APIs.
The crate follows the workspace version and Rust 2024 edition. It is exposed as the Rust library
godmode_core; doctests are disabled. Most APIs are synchronous, while async dispatch support uses
Tokio.
Workspace Role
The workspace separates responsibilities as follows:
| Package | Role |
|---|---|
godmode-core |
Domain types, state transitions, persistence, integrations, and reports |
godmode-cli |
Clap command model, human/JSON/SARIF rendering, process exit behavior |
godmode-conformance |
Cross-module behavioral contracts, fixtures, properties, reports |
xtask |
Repository quality, distribution, and installation commands |
Consumers can use godmode-core without depending on Clap or CLI output formatting.
Core Task Model
The primary types are in model:
TaskGraphcontains orderedTaskvalues and private plan-ingestion provenance.Taskrecords its ID, title, status, dependencies, notes, external provenance, optional crate, run command, commit, dates, timings, priority, and tags.Statusserializes aspending,running,done, orblocked.Priorityserializes ashigh,normal, orlow;normalis the default and is omitted from YAML.TaskProvenancecurrently carries an optional structured Doob ID.
graph provides the low-level operations:
use ;
let mut tasks = default;
add?;
start?;
complete?;
assert!;
# Ok::
graph::add rejects duplicate IDs and dependency cycles. graph::start only accepts pending tasks
whose dependencies are done. graph::complete only accepts running tasks. Removal also deletes
references to the removed task, while clear can remove only done tasks or the complete graph.
to_petgraph and to_dot expose graph projections for analysis and visualization.
Session API
session::Session is the preferred stateful facade. It loads configuration and the task graph,
performs typed transitions, persists transition state, validates rx: run commands when enabled,
and emits Crux-compatible JSONL events when configured.
use ;
let root = new;
let mut session = open?;
session.add_task?;
session.save?;
session.start_task?;
session.complete_task?;
# Ok::
Important behavior:
Session::start_tasksetsstarted_at; directgraph::startdoes not.Session::complete_taskcalculates duration, records completion metadata, and auto-saves.Session::ingest_planrestores the in-memory graph if persistence fails.Session::summaryreturns status counts and per-task durations.handonandhandoffare compatibility helpers for session-start and session-end reporting.
Use Session::graph() for reads. graph_mut() is a hidden escape hatch; direct mutation bypasses
the auto-save and trace invariants maintained by typed session methods.
Plans, Templates, And Dispatch
plan::parse recognizes ### Task N: Title or ### N. Title headings and these optional
annotations:
**Crate**: `godmode-core`
**Run**: `cargo nextest run -p godmode-core`
**Depends-on**: `graph:existing-task`
Without **Depends-on**, parsed tasks form a sequential chain. plan::ingest keeps the first
available tN IDs, deterministically namespaces collisions from the source filename, rewrites
internal dependencies, preserves explicit graph: dependencies, and records source-to-ID mappings
for idempotent re-ingestion. IngestReport reports parsed, added, skipped, and assigned IDs.
templates loads task templates from repository templates/ before
$HOME/.config/godmode/templates/, substitutes declared {{variables}}, and applies resolved tasks
to a graph. Template parse and substitution failures use miette diagnostics.
dispatch provides:
independent_chainsfor bounded, crate-oriented task chains.critical_pathfor the longest active dependency chain.dispatch_with_configandasync_dispatch_with_configfor retry-aware execution.file_overlap_warningsfor chains that target the same crate.
Other Public Subsystems
| Modules | Responsibility and representative API |
|---|---|
config, detect |
Config precedence, project naming, repository discovery, root pinning |
pipeline |
YAML skill pipelines, persisted step history, optional and parallel steps |
workflow |
Agent workflow DAG parsing, runnable-step selection, resumable execution |
wave, worktree |
Parallel slot state, retry settings, and guarded Git worktree lifecycle |
verify |
Pluggable VerifyStep gates and aggregate VerifyReport values |
review |
Skill, agent, plugin manifest, naming, and shared-library conformance checks |
policy |
Layered governance policy resolution, tool checks, and JSONL audit events |
agent, agent_index |
Agent generation, discovery, filtering, and index generation |
skill, registry |
Local skill installation and the global artifact registry |
eval |
Bounded skill evaluations, run persistence, baselines, comparison, CI gates |
context, cache |
Hook/subagent context and a fast status cache for prompt integrations |
memory_banking, insights, report_index |
Persistent project context and reports |
hooks, integrations |
Built-in hooks and adapters for GitHub, Doob, Hj, Rx, and Crux |
release |
Version bumping, tags, changelog generation, and version validation |
sarif, scaffold, test_check |
Machine-readable findings and testing support commands |
External command integrations are adapters rather than hard runtime dependencies. Their callers generally degrade gracefully when an optional tool is unavailable; command-specific modules define the exact fallback behavior.
Persistence And Serialization Contracts
The crate uses Serde-backed YAML, JSON, TOML, and JSONL contracts. The main paths are:
| Path | Format | Owner |
|---|---|---|
.ctx/godmode/tasks.yaml |
YAML | model, graph, session |
.ctx/GODMODE.tasks.yaml |
legacy YAML fallback | graph |
.ctx/godmode/session.json |
JSON | root pinning and session hooks |
.ctx/godmode/sessions/*.jsonl |
JSONL | task steps and session summaries |
.ctx/godmode/pipeline.yaml |
YAML | active pipeline state |
.ctx/godmode/wave-status.json |
JSON | parallel wave slots |
.ctx/godmode/workflow-<name>.json |
JSON | workflow execution state |
.ctx/godmode/evaluations/<skill>/ |
JSON | evaluation runs and baseline |
$HOME/.config/godmode/registry.json |
JSON | installed skills and agents |
graph::load returns an empty graph when no task file exists. New writes use
.ctx/godmode/tasks.yaml; the legacy file is read only when the new path is absent. Optional and
defaulted task fields preserve compatibility with older task files. Internal done-task caches are
never serialized.
Configuration loads in this order:
<repo>/.godmode.toml$HOME/.config/godmode/config.toml- built-in defaults
The default integration settings enable Doob, Hj, Crux, and Rx, while Coursers validation is off. The handoff writer and Doob handoff synchronization are enabled with a ten-commit limit.
Features
| Feature | Effect |
|---|---|
| default | Runtime library only |
testing |
Enables testing::{audit,binary,conformance,env,prop,seed} helpers |
test-utils |
Alias that enables testing |
The workspace conformance package consumes the ordinary public runtime API. The feature-gated
testing module is reusable support for adapter suites, dependency/snapshot audits, isolated test
environments, property assertions, deterministic seeds, and binary lookup.
Development And Testing
From the workspace root:
cargo check -p godmode-core --all-features
cargo clippy -p godmode-core --all-targets --all-features -- -D warnings
cargo nextest run -p godmode-core --all-features
cargo run -p godmode-conformance --bin run-conformance -- --verbose
Use temporary directories in tests for all persisted state. When changing serialized types, add a
round-trip or compatibility test and update the conformance fixtures when the contract change is
intentional. When adding a public subsystem, export it from src/lib.rs and keep the CLI layer
focused on argument parsing and rendering.