> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clawcontrol.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace Agent Generator

This page documents the workspace-level generator that produces `agents/` scaffolding from templates in this repository.

This is **not** the same as the in-product **Agent Templates** feature. If you are authoring templates for import into ClawControl via the UI/API, see [Agent Templates](/reference/agent-templates).

## What It Generates

* Role prompts: `agents/<role>.md`
* Per-agent SOUL/HEARTBEAT: `agents/<role>/SOUL.md`, `agents/<role>/HEARTBEAT.md`
* Global files: `AGENTS.md`, `SOUL.md`, `HEARTBEAT.md`, `agents/SOUL.md`, `agents/HEARTBEAT.md`
* Runtime config: `clawcontrol.config.yaml`

## Template Sources

* `templates/roles/*.template.md`
* `templates/agent/SOUL.template.md`
* `templates/agent/HEARTBEAT.template.md`
* `templates/config/clawcontrol.config.template.yaml`
* `templates/config/agent-entry.template.yaml`
* `templates/global/*.template.md`

## Variables

Supported placeholders in templates:

* `{{PREFIX}}`
* `{{PREFIX_CAPITALIZED}}`
* `{{ROLE}}`
* `{{ROLE_CAPITALIZED}}`
* `{{AGENT_ID}}`
* `{{AGENT_NAME}}`
* `{{EMOJI}}`

## Usage

CLI (prefix argument):

```bash theme={null}
./scripts/init-agents.sh acme --force
```

CLI (manifest):

```bash theme={null}
./scripts/init-agents.sh --manifest agents-manifest.example.yaml --force
```

npm script:

```bash theme={null}
npm run init:agents -- --manifest agents-manifest.example.yaml --force
```

## Prefix Behavior

Prefix is optional:

* With prefix `acme`: IDs like `acmebuild`, names like `AcmeBuild`
* Without prefix: IDs like `build`, names like `Build`

Default is no prefix unless `--prefix` or a manifest prefix is provided.

## Manifest Options

* `prefix`: lowercase prefix (optional)
* `owner`: owner string for config
* `roles.<role>.enabled`: boolean to include/exclude a role
* `roles.<role>.emoji`: override default emoji
* `roles.<role>.model_tier`: override model tier
* `roles.<role>.permissions`: merge permission overrides
* `heartbeat.global`: extra global heartbeat checks

## Safety and Validation

The generator validates:

* required templates exist
* manifest YAML syntax
* unresolved template placeholders
* existing output files (`--force` required to overwrite)

Use `--dry-run` to preview writes.

## Last updated

2026-02-13

## Related pages

* [Agents, Teams, and Templates](/features/agents-hierarchy-templates)
* [Repository Layout](/developers/repo-layout)
* [Agent Templates](/reference/agent-templates)