intent driven development

Agent Protocol

Overview

How chant invokes AI agents and exchanges information.

Invocation

# Primary: CLI with environment context
CHANT_SPEC_ID=2026-01-22-001-x7m \
CHANT_PROJECT=auth \
CHANT_PROMPT=standard \
claude --print "$(cat .chant/prompts/standard.md)" < spec.md

Environment Variables

Chant sets these before invoking the agent:

Variable	Description
`CHANT_SPEC_ID`	Current spec ID
`CHANT_SPEC_FILE`	Absolute path to spec markdown
`CHANT_PROJECT`	Project prefix (if any)
`CHANT_PROMPT`	Prompt name being used
`CHANT_PROMPT_FILE`	Absolute path to prompt markdown
`CHANT_WORKTREE`	Worktree path (if isolated)
`CHANT_ATTEMPT`	Attempt number (1, 2, 3…)
`CHANT_TIMEOUT`	Remaining timeout in seconds

Input

Agent receives:

System prompt - The prompt markdown (agent behavior)
User prompt - The spec markdown (what to do)

# Conceptual
claude \
  --system-prompt .chant/prompts/standard.md \
  --user-prompt .chant/specs/2026-01-22-001-x7m.md

Output

Agent writes directly to:

Working directory - Code changes
Spec file - Progress updates (output section)
Git - Commits (if prompt instructs)

Exit Handling

Agent Exit	Chant Action
0	Mark spec `completed`
Non-zero	Mark spec `failed`, capture error
Timeout	Kill agent, mark `failed`
Signal	Mark `failed`, note signal

MCP Server

Chant exposes an MCP server (chant-mcp) for tool integration with agents.

Required for: Some agents (only way to provide tools) Optional for: CLI-based agents (enhancement for structured tool access)

See mcp.md for full design.

Invocation Example

# Non-interactive execution (provider-specific)
CHANT_SPEC_ID=2026-01-22-001-x7m \
CHANT_SPEC_FILE=/path/to/spec.md \
CHANT_PROMPT_FILE=/path/to/prompt.md \
agent-cli --autonomous --spec $CHANT_SPEC_FILE

Each provider has its own CLI flags. Chant abstracts this through the provider interface.

Providers

Chant supports multiple AI providers via adapters:

Built-in Providers

Chant supports multiple AI providers via adapters. Providers are pluggable - see the protocol specification for details on adding new ones.

# config.md
agent:
  provider: default       # Built-in provider

Provider Configuration

# config.md
agent:
  provider: my-provider
  model: model-name
  api_key: ${PROVIDER_API_KEY}

Custom Providers (Plugins)

For unsupported agents, define custom command:

# config.md
agent:
  provider: custom
  command: "my-agent --execute"
  # Chant sets env vars, pipes spec to stdin

Provider Interface

Any provider must:

Accept spec content (stdin or file)
Accept prompt/system instruction (env var or flag)
Write changes to working directory
Exit 0 on success, non-zero on failure

# Provider receives:
CHANT_SPEC_ID=2026-01-22-001-x7m
CHANT_SPEC_FILE=/path/to/spec.md
CHANT_PROMPT_FILE=/path/to/prompt.md
CHANT_WORKTREE=/path/to/worktree

# Provider must:
# 1. Read spec and prompt
# 2. Execute changes
# 3. Exit with status

Provider Plugins

Plugins live in .chant/providers/:

.chant/providers/
  my-provider.md       # Plugin definition

# .chant/providers/my-provider.md
---
name: my-provider
command: my-agent
args:
  - "--autonomous"
  - "--spec-file"
  - "{{spec_file}}"
env:
  MY_AGENT_KEY: ${MY_AGENT_KEY}
---

# My Provider

Custom agent for specialized work.

## Setup

1. Install my-agent: `brew install my-agent`
2. Set MY_AGENT_KEY environment variable

## Capabilities

- Supports TypeScript
- Runs tests automatically

Per-Spec Provider Override

# spec frontmatter
---
status: pending
agent:
  provider: alternate-provider
  model: model-name
---

Provider Selection Logic

Spec frontmatter agent.provider (highest)
Config agent.provider
Environment CHANT_PROVIDER
Built-in default

Custom Command (Legacy)

Simple command override (deprecated, use providers):

# config.md
agent:
  command: "my-agent --autonomous"

Spec and prompt are passed via stdin/env. Agent writes to filesystem.

Keyboard shortcuts

Chant Documentation