Modes

Mode manifests, tool filtering, scope escalation, session lifecycle, and artifacts.

Modes are activatable overlays that temporarily modify an agent's behavior, tool access, and platform permissions. When a mode is active, it layers its configuration on top of the role's existing setup.

Mode Manifest

Every mode has a manifest (stored as JSONB) that defines its behavior:

{
  "schema_version": 1,
  "mode_type": "authoring",
  "prompt": {
    "system_addon": "You are now in PRD authoring mode...",
    "guidelines": [
      "Ask clarifying questions before each section",
      "Focus on user problems, not solutions"
    ],
    "entry_message": "Let's create a PRD. What problem are you solving?",
    "exit_message": "Your PRD has been saved."
  },
  "tools": {
    "allow": ["file_read", "file_write", "web_search_tool"],
    "deny": ["shell"],
    "additional_scopes": ["tickets:write"],
    "activate_mcp": ["github"]
  },
  "artifact": {
    "type": "document",
    "format": "markdown",
    "filename_template": "prd-{{slugify(title)}}.md",
    "output_template": "# {{title}}\n\n{{content}}"
  },
  "session": {
    "max_turns": 50,
    "auto_save_interval": 5,
    "exit_commands": ["/exit", "/done", "/finish"]
  }
}

Mode Types

The mode_type field classifies the mode's purpose:

Type	Description
`authoring`	Creating structured documents (PRDs, specs, reports)
`investigation`	Research and analysis tasks
`review`	Reviewing code, documents, or work output
`custom`	User-defined purpose

Prompt Configuration

The prompt block is additive to the role's existing system prompt:

Field	Type	Description
`system_addon`	string or null	Text appended to the system prompt while the mode is active
`guidelines`	string[]	Additional behavioral guidelines
`entry_message`	string or null	Message shown when the mode is activated
`exit_message`	string or null	Message shown when the mode is exited

Tool Configuration

The tools block controls which tools are available during the mode:

Allow / Deny Lists

{
  "allow": ["file_read", "file_write", "shell"],
  "deny": ["http_request"]
}

allow -- If non-empty, only these tools are available (whitelist). Tools not in the list are excluded.
deny -- These tools are explicitly excluded (blacklist). Applied after the allow list.

If both are empty, the role's default tool set is used unchanged.

Scope Escalation

The additional_scopes field temporarily grants the agent additional platform scopes for the duration of the mode:

{
  "additional_scopes": ["tickets:write", "pipelines:write"]
}

This is how modes like /the-creator can grant write access to platform resources that the role normally only has read access to. The escalated scopes are merged with the role's base platform_scopes when fetching MCP tools.

MCP Server Activation

The activate_mcp field enables external MCP servers by name for the duration of the mode:

{
  "activate_mcp": ["github", "linear"]
}

These servers must be configured in the platform. The mode activation adds them to the agent's tool set alongside any MCP servers already assigned to the role.

Artifact Configuration

Modes can produce structured output artifacts:

Field	Type	Description
`type`	string	Artifact type (default: `"document"`)
`format`	string	Output format: `markdown`, `json`, `yaml`, or `html`
`filename_template`	string or null	Template for the output filename
`schema`	object or null	JSON Schema for structured artifact data
`output_template`	string or null	Handlebars-style template for rendering the final artifact

Filename templates support {{key}} and {{slugify(key)}} placeholders that are resolved from the artifact draft data.

Session Configuration

Field	Type	Default	Description
`max_turns`	number	`50`	Maximum conversation turns (1--200)
`auto_save_interval`	number	`5`	Save draft every N turns
`exit_commands`	string[]	`["/exit", "/done", "/finish"]`	Commands that end the session

Exit commands must start with /.

Session Lifecycle

Mode sessions track the state of a mode activation:

Create -- A session is created when a mode is activated for a project + role
Active -- The agent operates with the mode's overlay; artifact drafts are saved periodically
Complete -- The session ends, artifact drafts are finalized and uploaded to S3
Cancel -- The session is abandoned without finalizing artifacts

When a session completes with an artifact draft, the system:

Renders the draft through the output_template (if configured)
Generates the filename from filename_template
Uploads the rendered content to object storage
Creates a project_documents record
Creates a mode_artifacts record linking the session to the document

API Endpoints

Mode CRUD

# List all modes
curl -H "Authorization: Bearer $TOKEN" \
  https://your-instance.com/api/v1/modes

# Create a mode
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "prd", "display_name": "PRD Authoring", "command": "/prd"}' \
  https://your-instance.com/api/v1/modes

# Upload a mode from file
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -F "file=@prd-mode.md" \
  https://your-instance.com/api/v1/modes/upload

# Reset a system-derived mode to the default template
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://your-instance.com/api/v1/modes/:id/reset

Role-Mode Assignments

# List modes assigned to a role
curl -H "Authorization: Bearer $TOKEN" \
  https://your-instance.com/api/v1/agent-roles/:id/modes

# Assign a mode to a role
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://your-instance.com/api/v1/agent-roles/:id/modes/:mode_id

# Remove a mode from a role
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://your-instance.com/api/v1/agent-roles/:id/modes/:mode_id

# Toggle or update a mode assignment
curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}' \
  https://your-instance.com/api/v1/agent-roles/:id/modes/:mode_id

Sessions

# Create a mode session
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "...", "role_id": "..."}' \
  https://your-instance.com/api/v1/modes/:id/sessions

# Get active session for a project + role
curl -H "Authorization: Bearer $TOKEN" \
  "https://your-instance.com/api/v1/modes/sessions/active?project_id=...&role_id=..."

# Update session draft
curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"artifact_draft": {"title": "My PRD", "content": "..."}}' \
  https://your-instance.com/api/v1/modes/sessions/:sid

# Complete session (finalizes artifact)
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://your-instance.com/api/v1/modes/sessions/:sid/complete

# Cancel session
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://your-instance.com/api/v1/modes/sessions/:sid/cancel

Artifacts

# List artifacts for a project
curl -H "Authorization: Bearer $TOKEN" \
  https://your-instance.com/api/v1/projects/:project_id/mode-artifacts

Upload Formats

Modes can be uploaded as .md, .json, or .yaml files (5 MB limit). The markdown format uses YAML frontmatter with the body becoming prompt.system_addon:

---
name: prd
display_name: PRD Authoring
command: /prd
description: Create product requirement documents
mode_type: authoring
tools:
  allow: ["file_read", "file_write"]
artifact:
  type: document
  format: markdown
  filename_template: "prd-{{slugify(title)}}.md"
---

You are now in PRD authoring mode. Help the user create a comprehensive product requirements document.

## Guidelines
- Ask clarifying questions before each section
- Focus on user problems, not solutions

Modes

On this page