Configuration

YAML definitions, environment variables, and project settings.

Repo-Scoped Config (.ark.yaml)

Place a .ark.yaml in your repo root to set defaults for sessions created from that repo:

flow: quick          # default flow
compute: ec2-dev     # default compute
group: my-project    # default group

Agent Definitions

Agents live in agents/<name>.yaml (built-in) or ~/.ark/agents/<name>.yaml (user).

Full agent schema:

name: implementer
description: "Implements features with tests"
model: opus              # opus | sonnet | haiku
max_turns: 200
system_prompt: |
  Working on {repo}. Task: {summary}. Ticket: {ticket}.
tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - WebSearch
permission_mode: bypassPermissions
mcp_servers: []          # MCP server names
skills: []               # Skill paths
memories: []             # Memory file paths
env:
  CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: "80"

Template variables available: {ticket}, {summary}, {workdir}, {repo}, {branch}.

Built-in agents: planner, implementer, reviewer, documenter, worker.

Flow Definitions

Flows live in flows/definitions/<name>.yaml (built-in) or ~/.ark/flows/<name>.yaml (user).

Full flow schema:

name: default
description: "Full SDLC pipeline"
stages:
  - name: plan
    agent: planner
    gate: manual         # auto | manual | review | condition
    autonomy: edit       # full | execute | edit | read-only
    task: |
      Plan the implementation for {summary}.
    on_failure: notify

  - name: implement
    agent: implementer
    gate: auto
    on_failure: "retry(3)"

  - name: review
    agent: reviewer
    gate: review         # waits for GitHub PR approval

Built-in flows: bare (single agent), quick (implement+review), default (full pipeline), parallel (fan-out).

Gate types:

• auto: advances if agent completes without error
• manual: waits for human to advance
• review: waits for GitHub PR approval webhook
• condition: evaluates an expression

Skill Definitions

Skills are reusable prompt fragments for agents. They live in three locations (highest priority first):

Attach skills to agents via the skills field in agent YAML. A skill is a markdown file containing instructions, patterns, or domain knowledge that gets injected into the agent context.

Recipe Definitions

Recipes are session templates with variables. They live in three locations (highest priority first):

Recipe schema:

name: quick-fix
description: "Fast bugfix with bare flow"
repo: .
flow: bare
summary: "Fix: {issue}"
variables:
  - name: issue
    prompt: "Describe the issue"

Built-in recipes: quick-fix, feature-build, code-review. Create a recipe from an existing session with sessionToRecipe.

Guardrails

Guardrails are pattern-based tool authorization rules defined in agent or flow configuration. They block dangerous commands before execution. Example patterns: rm -rf /, git push --force, DROP TABLE.

Environment Variables

Data Locations

Cron Schedules

ark schedule add --cron "0 2 * * *" --flow bare --repo /path --summary "Nightly tests"

Cron format: minute hour day-of-month month day-of-week. Supports wildcards (*), ranges (1-5), steps (*/5), and comma lists (1,3,5).