kelos

name: kelos description: Author, debug, and operate Kelos resources (Task, Workspace, AgentConfig, TaskSpawner) on Kubernetes. Use when working with Kelos CRDs or the kelos CLI. compatibility: Requires kubectl and access to a Kubernetes cluster

Kelos Skill

Use this skill when you need to author, debug, or operate Kelos resources (Task, Workspace, AgentConfig, TaskSpawner) on a Kubernetes cluster.

Installing Kelos

Install the controller and CRDs into a Kubernetes cluster:

kelos install

Uninstall:

kelos uninstall

Initialize a local config file at ~/.kelos/config.yaml:

kelos init

Core Resources

Kelos defines four custom resources:

Task

A Task runs an AI agent with a prompt. Key fields:

• spec.type (required): claude-code, codex, gemini, opencode, or cursor
• spec.prompt (required): The task prompt
• spec.credentials (required): type (api-key or oauth) and secretRef.name
• spec.workspaceRef.name: Reference to a Workspace
• spec.agentConfigRef.name: Reference to an AgentConfig
• spec.branch: Git branch mutex — only one Task with the same branch runs at a time
• spec.dependsOn: Task names that must succeed first
• spec.ttlSecondsAfterFinished: Auto-delete after completion (seconds)
• spec.model: Model override
• spec.effort: Agent reasoning effort
• spec.podOverrides: Resource limits, timeout, env vars, node selector

Task status phases: Pending -> Running -> Succeeded or Failed. Tasks with unmet dependencies enter Waiting.

Workspace

A Workspace defines a git repository for the agent:

• spec.repo (required): Git URL (HTTPS, git://, or SSH)
• spec.ref: Branch, tag, or commit to checkout
• spec.secretRef.name: Secret with GITHUB_TOKEN (PAT) or GitHub App credentials (appID, installationID, privateKey)
• spec.remotes: Additional git remotes (name must not be origin)
• spec.files: Files to inject into the repo before the agent starts (e.g., CLAUDE.md, skills)

AgentConfig

An AgentConfig injects reusable instructions and tools into Tasks:

• spec.agentsMD: Instructions written to the agent's config (e.g., ~/.claude/CLAUDE.md). Additive — does not overwrite repo files
• spec.plugins: Plugin bundles with skills and sub-agents
  • plugins[].name: Plugin name (directory namespace)
  • plugins[].skills[].name / .content: Skill definitions (become SKILL.md)
  • plugins[].agents[].name / .content: Agent definitions (become <name>.md)
• spec.skills: skills.sh ecosystem packages
  • skills[].source: Package in owner/repo format
  • skills[].skill: Optional specific skill name
• spec.mcpServers: MCP server configurations
  • Supports stdio, http, and sse transport types
  • Use headersFrom / envFrom with a secretRef for sensitive values

TaskSpawner

A TaskSpawner auto-creates Tasks from external sources:

• spec.when.githubIssues: Discover from GitHub issues (labels, state, assignee, author, commentPolicy, priority labels)
• spec.when.githubPullRequests: Discover from GitHub PRs (labels, state, reviewState, author, draft, commentPolicy, priority labels)
• spec.when.cron: Trigger on a cron schedule
• spec.when.jira: Discover from Jira (project, JQL filter, secret with JIRA_TOKEN)
• spec.when.githubIssues.commentPolicy / spec.when.githubPullRequests.commentPolicy: Comment-based workflow control with authorization
  • triggerComment: Command that must appear for the item to be included (e.g., "/kelos pick-up")
  • excludeComments: Commands that exclude items; when combined with triggerComment, the most recent authorized command wins
  • allowedUsers: Restrict comment control to specific GitHub usernames
  • allowedTeams: Restrict to GitHub teams in org/team-slug format
  • minimumPermission: Require at least this repo permission (read, triage, write, maintain, admin)
• spec.taskTemplate: Template for spawned Tasks (same fields as Task spec)
  • promptTemplate and branch support Go text/template variables: {{.ID}}, {{.Number}}, {{.Title}}, {{.Body}}, {{.URL}}, {{.Labels}}, {{.Comments}}, {{.Kind}}, {{.Time}}, {{.Schedule}}
• spec.pollInterval: Polling frequency (default 5m)
• spec.maxConcurrency: Limit concurrent running Tasks
• spec.maxTotalTasks: Lifetime task creation limit
• spec.suspend: Pause/resume without deleting

CLI Quick Reference

Running Tasks

# Simple task
kelos run -p "Fix the login bug" --type claude-code

# With workspace and agent config
kelos run -p "Add tests" --workspace my-ws --agent-config my-ac

# With model override and branch
kelos run -p "Refactor auth" --model opus --effort high --branch feature/auth

# Watch task progress
kelos run -p "Fix bug" -w

Creating Resources

# Create a workspace
kelos create workspace my-ws \
  --repo https://github.com/org/repo.git \
  --ref main \
  --secret github-token

# Create an agent config with inline skill
kelos create agentconfig my-ac \
  --skill review="Review the PR for correctness and security" \
  --agents-md @instructions.md

# Create an agent config with skills.sh package
kelos create agentconfig my-ac \
  --skills-sh anthropics/skills:skill-creator

# Create an agent config with MCP server
kelos create agentconfig my-ac \
  --mcp github='{"type":"http","url":"https://api.githubcopilot.com/mcp/"}'

# Dry-run to preview YAML
kelos create agentconfig my-ac --skill review=@review.md --dry-run

Managing Resources

# List resources
kelos get tasks
kelos get taskspawners
kelos get workspaces

# View details
kelos get task my-task -d
kelos get task my-task -o yaml

# Stream logs
kelos logs my-task -f

# Suspend / resume a spawner
kelos suspend taskspawner my-spawner
kelos resume taskspawner my-spawner

# Delete
kelos delete task my-task

Configuration

Config file at ~/.kelos/config.yaml:

oauthToken: <token>       # or apiKey: <key>
model: sonnet                   # or a versioned ID like 'claude-sonnet-4-6' — value is passed to the agent as KELOS_MODEL
effort: high
namespace: default
workspace:
  repo: https://github.com/org/repo.git
  ref: main
  token: <github-token>

CLI flags always override config file values.

Dependency Chains

Tasks can depend on other Tasks using dependsOn. Dependent tasks access upstream results via Go template syntax in the prompt:

dependsOn: [scaffold]
prompt: |
  Code is on branch {{index .Deps "scaffold" "Results" "branch"}}.
  PR: {{index .Deps "scaffold" "Results" "pr"}}

Available result keys: branch, commit, base-branch, pr, input-tokens, output-tokens, cost-usd.

Troubleshooting

Task stuck in Pending

• Check if the credentials secret exists: kubectl get secret <name>
• Check controller logs: kubectl logs deployment/kelos-controller-manager -n kelos-system

Task stuck in Waiting

• Check if a dependency in dependsOn has not yet succeeded
• Check if another Task holds the branch lock (same spec.branch)

Task fails immediately

• Verify agent credentials are valid
• Check the workspace repository is accessible
• Review pod logs: kelos logs <task-name> or kubectl logs -l job-name=<job-name>

TaskSpawner not creating Tasks

• Check spawner status: kubectl get taskspawner <name> -o yaml
• Verify the Workspace exists: kubectl get workspace
• Check if maxConcurrency is reached (active tasks at limit)
• Check if maxTotalTasks limit is reached
• Check if suspend: true is set

AgentConfig not taking effect

• Verify the Task references it: spec.agentConfigRef.name must match
• Check plugin structure: skills become <plugin>/skills/<skill>/SKILL.md
• For skills.sh: ensure the package source is valid owner/repo format

Agent cannot push or create PRs

• Ensure the workspace secret has a valid GITHUB_TOKEN
• Verify the token has repo (and workflow if needed) permissions
• For GitHub Apps, check that appID, installationID, and privateKey are correct

Supported Agent Types

References

See the references/ directory next to this file for complete YAML examples:

• task.yaml — Task patterns
• workspace.yaml — Workspace patterns
• agentconfig.yaml — AgentConfig patterns
• taskspawner.yaml — TaskSpawner patterns