Advanced Artifact Configuration

This page is for operators who want to change the typed outputs Ralph Workflow expects and records. Use it when you need to edit contracts, decision vocabularies, or summary paths without guessing how those outputs connect back to the workflow. The core loop stays simple, but the artifact layer is where you make the workflow reviewable and predictable for your team.

Treat artifacts as operator-facing contracts, not generic notes. If your question is about workflow routing, use Advanced Pipeline Configuration. If your question is about MCP servers, use Advanced MCP Configuration.

Which file am I editing?

  • project-local artifact policy → .agent/artifacts.toml

  • user-global default artifact policy → ~/.config/ralph-workflow-artifacts.toml

  • bundled default / example → ralph/policy/defaults/artifacts.toml

In most real repos, start with .agent/artifacts.toml.

After editing, run:

ralph --check-policy
ralph --diagnose

What artifacts.toml controls

artifacts.toml declares the artifact contracts for each drain.

It owns:

  • which artifact each drain must submit

  • artifact types

  • decision vocabularies for analysis artifacts

  • summary markdown output paths

  • which prompt template is responsible for producing that artifact

The major fields

Each [artifacts.<name>] block usually contains:

  • drain

  • artifact_type

  • decision_vocabulary

  • prompt_template

  • markdown_summary_path

Example:

[artifacts.development_analysis_decision]
drain = "development_analysis"
artifact_type = "development_analysis_decision"
decision_vocabulary = ["completed", "request_changes", "failed"]
prompt_template = "development_analysis.jinja"
markdown_summary_path = ".agent/DEVELOPMENT_ANALYSIS_DECISION.md"

Decision vocabulary vs routing

This is an important distinction:

  • artifacts.toml defines the allowed decision strings

  • pipeline.toml defines where those decisions route

If you add or rename a decision in artifacts.toml, you must update the matching analysis-phase decision routing in pipeline.toml too.

Common advanced user stories

I want to add a new analysis decision

  1. update decision_vocabulary in artifacts.toml

  2. update the matching [phases.<name>.decisions.*] routing in pipeline.toml

  3. run ralph --check-policy

I want human-readable summaries written to different files

Edit markdown_summary_path.

I want to add a new drain artifact

Add a new [artifacts.<name>] block and ensure the matching drain/phase expects it.

What usually goes wrong

  • changing decision vocabulary without updating policy routing

  • renaming an artifact block without updating the phase/drain that expects it

  • treating artifacts.toml like generic docs instead of a strict contract file

Markdown artifact conventions

Each artifact type has a short, closed markdown format. Agents read its bundled format document, author the complete markdown document, and submit it through ralph_submit_md_artifact. Ralph Workflow validates the same document before storing it at .agent/artifacts/<artifact_type>.md.

Keep custom prompt guidance aligned with the bundled format document. Do not introduce a second schema or instruct agents to write artifact files directly.