Extend code generation with blocks

The block directive adds custom code-generation steps to the build. When the compiler reaches the generate stage, it renders your templates and writes the output into the generated project alongside the archetype's own files. Use it when you need custom modules, configuration files, or extra dependencies that the standard archetype does not produce. For where this sits in the build, see The compilation pipeline.

Generate a file from a template

A block with a generates map writes new files into the generated project. Each key is an output path within that project, and each value is a Jinja2 template relative to the manifest:

block "build_info" {
  description = "Generates a Rust module with build-time constants."

  generates = {
    "src/build_info.rs" = "./codegen/build_info.jinja2"
  }
}

// Generated by agentc. Do not edit.
pub const AGENT_NAME: &str = "{{ agent_name }}";
pub const AGENT_VERSION: &str = "{{ agent.version }}";

The template context includes agent_name, agent, providers, tools, skills, locals, and the other resolved manifest values.

Contribute to an extension point

The contributes map renders a template into a named extension point that the archetype exposes, rather than writing a standalone file. Each key is an extension point name; each value is a template:

block "extra_routes" {
  contributes = {
    "http_routes" = "./codegen/extra_routes.jinja2"
  }
}

Which extension points exist depends on the archetype. Inspect the generated project or the archetype documentation to find their names.

Add dependencies

The dependencies map declares extra crates the generated code needs. Each entry is added to the generated project's Cargo.toml:

block "custom_module" {
  generates = {
    "src/custom.rs" = "./codegen/custom.jinja2"
  }

  dependencies = {
    "serde"       = "1"
    "my-internal" = { git = "https://github.com/example/my-internal" }
  }
}

Understand ordering

All blocks run during the generate stage, after the archetype has produced its base files. If a block writes to a path the archetype also writes, the block output wins. Multiple blocks render in declaration order.

The full field set is summarized below.

Where to go next

• The compilation pipeline: the generate stage that renders blocks.
• agentc generate: inspect the generated project before compiling.