Self-Development Orchestration Patterns

September 5, 2026 · View on GitHub

This directory contains real-world orchestration patterns used by the Kelos project itself for autonomous development.

The nested agora/ directory applies the same orchestration pattern to the sibling kelos-dev/agora repository while keeping the configuration in this repo.

The nested kanon/ directory does the same for the sibling kelos-dev/kanon repository.

The nested open-actions/ directory does the same for the sibling kelos-dev/open-actions repository.

cs creates persistent interactive Codex environments for developing Kelos with the same Workspace, credentials, model, effort, and Git identity as the kelos-workers SessionSpawner.

How It Works

kelos-self-development

Every self-development Task, TaskSpawner, Session, and SessionSpawner in this directory and its nested Agora, Kanon, and Open Actions directories references base-agent.yaml, which copies gjkim42/kanon-repo's instructions/AGENTS.md and installs all skills from that repository through spec.skills. Tasks and TaskSpawners add a second role-specific AgentConfig when they need local identity, conventions, or workflow instructions. The issue and PR pick-up SessionSpawners for Kelos, Agora, Kanon, and Open Actions, plus Sessions created with cs, use only base-agent.

Apply the shared AgentConfig before deploying any self-development resource:

kubectl apply -f self-development/base-agent.yaml

All other AgentConfigs provide only role- or repository-specific instructions; they do not duplicate the shared skills.

Autonomous discovery agents that publish GitHub issues maintain at most one open generated-by-kelos issue slot per TaskSpawner. Its title starts with the TaskSpawner name in brackets, and its body includes both a kelos-taskspawner=<name> marker and one replaceable Latest verdict section. Each run checks whether an unassigned slot is still valid against the current repository before retaining, replacing, or closing it. Assigned issues and PRs are treated as ongoing human or agent work and are not updated by autonomous discovery jobs.

Spawners

SpawnerTriggerAgentDescription
kelos-workersWebhook: issue comment /kelos pick-upCodexCreates a durable Session with the open issue URL and a dedicated issue branch
kelos-plannerWebhook: issue comment /kelos planCodexInvestigates an issue and posts a structured implementation plan — advisory only, no code changes
kelos-reviewerWebhook: PR comment /kelos reviewCodexReviews PRs on demand — analyzes code, checks conventions, and updates a sticky review comment
kelos-claude-reviewerWebhook: PR comment /kelos claude-reviewClaude FableRuns an additional code review path with Claude Code and updates a Claude-specific sticky review comment
kelos-api-reviewerWebhook: issue/PR comment /kelos api-reviewCodexReviews Kubernetes API design on issues or PRs — naming, compatibility, CRD validation
kelos-claude-api-reviewerWebhook: issue/PR comment /kelos claude-api-reviewClaude FableRuns an additional Kubernetes API design review path with Claude Code and updates Claude-specific sticky PR comments
kelos-pr-responderWebhook: PR comment/review /kelos pick-upCodexCreates a durable Session with the open PR URL on its existing branch
kelos-triageWebhook: issue opened/labeled/reopened (needs-actor)CodexClassifies issues by kind/priority, detects duplicates, and recommends an actor
kelos-fake-userCron (daily 09:00 UTC)CodexTests DX as a new user and maintains one unassigned issue slot for the highest-impact problem found
kelos-fake-strategistCron (every 12 hours)CodexExplores new use cases, integrations, and API ideas while maintaining one unassigned strategic issue slot
kelos-config-updateCron (daily 18:00 UTC)CodexReviews recent PR feedback and creates or updates unassigned configuration PRs accordingly
kelos-self-updateCron (daily 06:00 UTC)CodexReviews prompts, configs, and workflow files while maintaining one unassigned improvement issue slot
kelos-image-updateCron (daily 03:00 UTC)CodexChecks for newer agent image versions and creates or updates unassigned PRs for them
kelos-squash-commitsWebhook: PR comment /kelos squash-commitsCodexRebases and squashes PR branch commits into a single clean commit

kelos-workers.yaml

Creates a durable Session when the maintainer posts /kelos pick-up on an open issue. The initial prompt supplies the issue URL and asks the agent to find the best way to address it. Follow-ups continue through the Session's web or terminal clients after the initial turn.

TriggerGitHub issue_comment webhook with an exact /kelos pick-up command from gjkim42 on an open issue
AgentCodex
Storage10 GiB persistent volume per created Session

Key features:

  • Lets the agent choose how to address the linked issue
  • Uses kelos-task-<number> for the issue branch
  • Requires /kelos pick-up from the maintainer before starting work
  • Excludes comments from kelos-bot[bot] to prevent self-trigger loops
  • Keeps the Session available for later web or terminal follow-ups

Deploy:

kubectl apply -f self-development/base-agent.yaml
kubectl apply -f self-development/kelos-workers.yaml

kelos-planner.yaml

Reacts to /kelos plan comments on open issues. Investigates the issue, inspects the codebase, and posts a structured implementation plan — advisory only, no code changes.

TriggerGitHub issue_comment webhook with /kelos plan
AgentCodex
Concurrency2

Key features:

  • Reads the issue body, all comments, linked issues/PRs, and relevant source code
  • Posts a single planning comment with: plan assessment, implementation steps, acceptance criteria, and open questions/risks
  • If the issue already contains a solid plan, normalizes it into a canonical step list instead of inventing a new one
  • A later /kelos plan comment retriggers planning after more discussion or scope changes

Handoff flow:

  1. /kelos plan — requests or refreshes an implementation plan
  2. /kelos pick-up — maintainer hands off to workers when ready

Deploy:

kubectl apply -f self-development/kelos-planner.yaml

kelos-reviewer.yaml

Reviews open pull requests on demand when a maintainer or kelos-bot[bot] posts /kelos review.

TriggerGitHub PR comment webhook with /kelos review from a maintainer or kelos-bot[bot]
AgentCodex
Concurrency3

Key features:

  • Uses the review-all skill to reconcile two independent reviews of the same diff
  • Reads the full diff and surrounding context to understand changes
  • Checks correctness, tests, project conventions, security, and code quality
  • Reviews test adequacy without rerunning local validation
  • Creates or updates a single sticky PR comment with the structured review result
  • Summarizes specific file/line findings in the sticky comment without inline review comments
  • Read-only agent — does not push code or modify files

Handoff flow:

  1. /kelos review — a maintainer or kelos-bot[bot] requests a code review
  2. /kelos review — a maintainer can retrigger review after changes are pushed

Deploy:

kubectl apply -f self-development/kelos-reviewer.yaml

kelos-claude-reviewer.yaml

Runs a Claude Fable review when a maintainer posts /kelos claude-review, using the Claude Code runner. It uses a separate trigger from the Codex reviewer.

TriggerGitHub PR comment webhook with /kelos claude-review from a maintainer or kelos-bot[bot]
AgentClaude Fable via Claude Code
Concurrency3

Key features:

  • Uses the same code review checklist and structured sticky comment output as kelos-reviewer
  • Creates or updates a single Claude-specific sticky PR comment with the structured review result
  • Provides an independent model-family review without replacing the Codex reviewer
  • Read-only agent — does not push code or modify files

Deploy:

kubectl apply -f self-development/kelos-claude-reviewer.yaml

kelos-api-reviewer.yaml

Reviews issues and pull requests for Kubernetes API design conventions, compatibility, and best practices when a maintainer or kelos-bot[bot] posts /kelos api-review.

TriggerGitHub issue/PR comment webhook with /kelos api-review from a maintainer or kelos-bot[bot]
AgentCodex
Concurrency3

Key features:

  • Uses the api-review skill for API design analysis and verdicts
  • Works on both issues (API design proposals) and pull requests (API implementation review)
  • Focused on Kubernetes API design concerns (field naming, primitive types, compatibility, CRD validation, naming/docs, defaulting/conversion)
  • References upstream Kubernetes API conventions and API review process documentation
  • Checks for correct use of resource.Quantity, metav1.Time, metav1.Duration
  • Verifies additive-only changes and forwards compatibility
  • For PRs: creates or updates a single sticky PR comment with structured API review feedback
  • For issues: posts a structured comment with API design guidance
  • Read-only agent — does not push code or modify files

Handoff flow:

  1. /kelos api-review — a maintainer or kelos-bot[bot] requests an API design review
  2. /kelos api-review — a maintainer can retrigger review after changes or further discussion

Deploy:

kubectl apply -f self-development/kelos-api-reviewer.yaml

kelos-claude-api-reviewer.yaml

Runs a Claude Fable API design review when a maintainer posts /kelos claude-api-review, using the Claude Code runner. It uses a separate trigger from the Codex API reviewer.

TriggerGitHub issue/PR comment webhook with /kelos claude-api-review from a maintainer or kelos-bot[bot]
AgentClaude Fable via Claude Code
Concurrency3

Key features:

  • Uses the api-review skill for API design analysis and verdicts
  • Uses the same Kubernetes API design checklist and structured output as kelos-api-reviewer
  • Works on both issues and pull requests
  • Creates or updates a Claude-specific sticky PR comment for pull requests
  • Posts a structured API design comment for issues
  • Provides an independent model-family review without replacing the Codex API reviewer
  • Read-only agent — does not push code or modify files

Deploy:

kubectl apply -f self-development/kelos-claude-api-reviewer.yaml

kelos-pr-responder.yaml

Creates a durable Session when the maintainer posts an exact /kelos pick-up PR comment or review on an open pull request. The initial prompt supplies the PR URL and asks the agent to find the best way to address it.

TriggerGitHub PR comment or review webhook with an exact /kelos pick-up command from gjkim42 on an open PR; review events also exclude drafts
AgentCodex
Storage10 GiB persistent volume per created Session

Key features:

  • Starts the Session on the existing PR branch
  • Lets the agent choose how to address the linked PR
  • Keeps the Session available for later web or terminal follow-ups
  • Requires /kelos pick-up PR comment or review body to be picked up

Deploy:

kubectl apply -f self-development/base-agent.yaml
kubectl apply -f self-development/kelos-pr-responder.yaml

kelos-triage.yaml

Picks up open GitHub issues labeled needs-actor and performs automated triage.

TriggerGitHub issue opened/labeled/reopened webhooks with needs-actor
AgentCodex
Concurrency8

For each issue, the agent:

  1. Classifies with exactly one kind/* label (kind/bug, kind/feature, kind/api, kind/docs). kind/api covers any change that introduces or modifies a user-facing API surface — CRD fields, CLI commands or flags, webhooks, etc.
  2. Checks if the issue has already been fixed by a merged PR or recent commit
  3. Checks if the issue references outdated APIs, flags, or features
  4. Detects duplicate issues
  5. Assesses priority (priority/important-soon, priority/important-longterm, priority/backlog)
  6. Recommends an actor — assigns actor/kelos if the issue has clear scope and verifiable criteria, otherwise assigns actor/human. kind/api issues always get actor/human and are not marked triage-accepted, because new user-facing APIs must be reviewed and discussed with a maintainer before any PR is opened.

Posts a single triage comment with its findings and adds the kelos/needs-input label to prevent re-triage.

Deploy:

kubectl apply -f self-development/kelos-triage.yaml

kelos-fake-user.yaml

Runs daily to test the developer experience as if you were a new user.

TriggerCron 0 9 * * * (daily at 09:00 UTC)
AgentCodex
Concurrency1

Each run picks one focus area:

  • Documentation & Onboarding — follow getting-started instructions, test CLI help text
  • Developer Experience — review error messages, test common workflows
  • Examples & Use Cases — verify manifests, identify missing examples

Creates or updates the single unassigned kelos-fake-user issue slot for the highest-impact problem found. If that issue is assigned, the run treats it as ongoing and exits without editing it or creating another issue.

Deploy:

kubectl apply -f self-development/kelos-fake-user.yaml

kelos-fake-strategist.yaml

Runs every 12 hours to strategically explore new ways to use and improve Kelos.

TriggerCron 0 */12 * * * (every 12 hours)
AgentCodex
Concurrency1

Each run picks one focus area:

  • New Use Cases — explore what types of projects/teams could benefit from Kelos
  • Integration Opportunities — identify tools/platforms Kelos could integrate with
  • New CRDs & API Extensions — propose new CRDs or extensions to existing ones

Creates or updates the single unassigned kelos-fake-strategist issue slot for the highest-impact actionable insight. If that issue is assigned, the run treats it as ongoing and exits without editing it or creating another issue.

Deploy:

kubectl apply -f self-development/kelos-fake-strategist.yaml

kelos-config-update.yaml

Runs daily to update agent configuration based on patterns found in PR reviews.

TriggerCron 0 18 * * * (daily at 18:00 UTC)
AgentCodex
Concurrency1

Reviews recent PRs and their review comments to identify recurring feedback patterns, then updates agent configuration accordingly:

  • Project-level changes — updates AGENTS.md or the applicable role-specific AgentConfig
  • Task-specific changes — updates TaskSpawner prompts in self-development/*.yaml or creates/updates AgentConfig for specific agents

Creates PRs with changes for maintainer review. Skips uncertain or contradictory feedback, and skips an existing configuration PR when it has assignees.

Deploy:

kubectl apply -f self-development/kelos-config-update.yaml

kelos-self-update.yaml

Runs daily to review and update the self-development workflow files themselves.

TriggerCron 0 6 * * * (daily at 06:00 UTC)
AgentCodex
Concurrency1

Each run picks one focus area:

  • Prompt Tuning — review and improve prompts based on actual agent output quality
  • Configuration Alignment — ensure resource settings, labels, and AgentConfig stay consistent
  • Workflow Completeness — check that agent prompts reflect current project conventions and Makefile targets
  • Task Template Maintenance — keep one-off task definitions in sync with their TaskSpawner counterparts

Creates or updates the single unassigned kelos-self-update issue slot for the highest-impact actionable improvement. If that issue is assigned, the run treats it as ongoing and exits without editing it or creating another issue.

Deploy:

kubectl apply -f self-development/kelos-self-update.yaml

kelos-image-update.yaml

Runs daily to check for newer versions of coding agent images and creates PRs to update them.

TriggerCron 0 3 * * * (daily at 03:00 UTC)
AgentCodex
Concurrency1

Checks the following coding agents for updates:

  • claude-code — @anthropic-ai/claude-code npm package
  • codex — @openai/codex npm package
  • gemini — @google/gemini-cli npm package
  • opencode — opencode-ai npm package
  • cursor — binary download, version discovered from https://cursor.com/install

Creates at most one PR per agent. Skips agents that are already up to date or already have an assigned open update PR.

Deploy:

kubectl apply -f self-development/kelos-image-update.yaml

kelos-squash-commits.yaml

Rebases and squashes PR branch commits into a single clean commit when a maintainer posts /kelos squash-commits.

TriggerGitHub PR comment webhook with /kelos squash-commits
AgentCodex
Concurrency1

Key features:

  • Rebases the PR branch on origin/main and squashes all commits after the merge base into one
  • Amends the squashed commit message based on the linked issue and PR description when needed
  • Force-pushes with --force-with-lease
  • Updates the PR description to match the squashed change, preserving the Closes #N reference
  • Adds kelos/needs-input to the linked issue to signal the PR is ready for re-review
  • Does not start new development work or modify source code

Deploy:

kubectl apply -f self-development/kelos-squash-commits.yaml

Interactive Development Session

cs NAME creates a persistent Codex Session with the same Workspace, credentials, model, effort, Git identity, and base-agent AgentConfig as kelos-workers. It does not use the worker's resource requests and limits, allowing namespace resource defaults to apply.

The Session requires the base-agent AgentConfig, kelos-session-agent Workspace, personal-github-token Secret, and kelos-credentials Secret described below. Its 10Gi workspace persists across Pod replacement and is deleted with the Session.

Add this directory to your PATH and run the script from any directory:

export PATH="$PWD/self-development:$PATH"
cs my-session

cs embeds the Session manifest and uses the current kubectl context and namespace. It fails if that name already exists and prints the kelos session connect command after creation.

Prerequisites

Before deploying these examples, you need to create the following resources:

1. Workspace Resources

workspaces.yaml defines the kelos-agent, agora-agent, kanon-agent, and open-actions-agent Workspaces used by Tasks and TaskSpawners. They reference the kelos-agent-credentials Secret described below so GitHub operations use the Kelos bot identity.

Sessions use dedicated Workspaces so they can authenticate with a personal token without changing Task credentials. The checked-in manifest includes Session Workspaces for Kelos, Agora, Kanon, and kelos-dev/open-actions. Apply both manifests after creating their Secrets below:

kubectl apply -f self-development/workspaces.yaml
kubectl apply -f self-development/session-workspaces.yaml

The Kelos Session Workspace is equivalent to:

apiVersion: kelos.dev/v1alpha2
kind: Workspace
metadata:
  name: kelos-session-agent
spec:
  repo: https://github.com/kelos-dev/kelos.git
  ref: main
  secretRef:
    name: personal-github-token

2. Project GitHub App Secret

Create the GitHub App Secret referenced by workspaces.yaml:

kubectl create secret generic kelos-agent-credentials \
  --from-literal=appID=<your-github-app-id> \
  --from-literal=installationID=<your-github-app-installation-id> \
  --from-file=privateKey=<path-to-private-key.pem>

The GitHub App installation must have access to the repositories used by the project Workspaces.

3. Session GitHub Token Secret

Create the personal token Secret referenced only by the Session Workspaces:

kubectl create secret generic personal-github-token \
  --from-literal=GITHUB_TOKEN="$(gh auth token)" \
  --dry-run=client -o yaml | kubectl apply -f -

The token needs these permissions:

  • repo (full control of private repositories)
  • workflow (if your repo uses GitHub Actions)

4. WebhookGateway, Secret, and Delivery

The issue and pull request TaskSpawners in this directory are webhook-driven and routed through a WebhookGateway (webhookgateway.yaml) that each spawner references via githubWebhook.gatewayRef. The gateway authenticates inbound deliveries against its own secret and resolves outbound GitHub API credentials per gateway.

Create the github-webhook-secret Secret (in the same namespace as the TaskSpawners) and apply the gateway. The gateway reads two things from it: the inbound HMAC secret under a webhook-secret key, and outbound GitHub API credentials for PR-file enrichment and status reporting — a GITHUB_TOKEN PAT or GitHub App keys; the credential needs repo and checks:write.

kubectl create secret generic github-webhook-secret \
  --from-literal=webhook-secret=<your-github-webhook-secret> \
  --from-literal=GITHUB_TOKEN=<token-with-repo-and-checks:write>
# Or use GitHub App credentials instead of GITHUB_TOKEN:
#   --from-literal=appID=... --from-literal=installationID=... \
#   --from-file=privateKey=app.private-key.pem

kubectl apply -f webhookgateway.yaml

Then:

  • Enable the gateway webhook server in your Kelos deployment — webhookServer.gatewayServer.enabled: true plus Gateway-API or Ingress routing (see examples/webhook-gateway-values.yaml).
  • Find the gateway's inbound path: kubectl get webhookgateway kelos -o jsonpath='{.status.path}' (it is /webhook/<namespace>/kelos).
  • Expose https://<your-domain>/webhook/<namespace>/kelos over HTTPS and configure the repository webhook to POST there using the same secret.
  • Subscribe the repository webhook to issues, issue_comment, and pull_request_review.

Spawners with a gatewayRef are served only by the gateway server. The gateway server and referenced WebhookGateway must both be available for their webhook deliveries to be processed.

Webhook spawners only react to new events after deployment. If an issue or PR was already in a matching state before the webhook server went live, retrigger it with a fresh comment or relabel after deployment.

5. Agent Credentials Secret

Create a secret with your agent credentials. Most checked-in spawners use Codex OAuth, and the Claude reviewer spawners use Claude Code with OAuth from the same Secret:

kubectl create secret generic kelos-credentials \
  --from-file=CODEX_AUTH_JSON=$HOME/.codex/auth.json \
  --from-literal=CLAUDE_CODE_OAUTH_TOKEN=<your-claude-code-oauth-token>
kubectl label secret kelos-credentials kelos.dev/codex-oauth-refresh=true

Labeling the OAuth Secret opts it into controller-managed Codex OAuth refresh. Kelos creates one CronJob per labeled Secret with a non-empty CODEX_AUTH_JSON key, skips unlabeled Secrets and API-key credentials, and preserves other keys such as CLAUDE_CODE_OAUTH_TOKEN.

For API-key auth, change the task template credential type to api-key and create the secret without the OAuth refresh label:

kubectl create secret generic kelos-credentials \
  --from-literal=CODEX_API_KEY=<your-openai-api-key>

Customizing for Your Repository

To adapt these examples for your own repository:

  1. Update the Workspace reference:

    • Change spec.taskTemplate.worker.workspaceRef.name to match your Workspace resource
    • Or update the Workspace to point to your repository

  2. Update the webhook repository and filters:

    spec:
  when:
    githubWebhook:
      repository: your-org/your-repo
      excludeAuthors:
        - your-bot[bot]            # avoid self-trigger loops
      events: [issue_comment]
      filters:
        - event: issue_comment
          action: created
          bodyPattern: '(?m)^/kelos pick-up[ \t]*\r?$'
          commentOn: Issue          # or PullRequest, depending on spawner
          author: your-maintainer   # maintainer-approval gate
          labels: [your-label]
          state: open

    Webhook filter fields the shipped self-development spawners rely on. The same githubWebhook fields are available under TaskSpawner.spec.when and SessionSpawner.spec.when:

    FieldWhere it livesPurpose
    excludeAuthorsTaskSpawner.spec.when.githubWebhook (top-level)Drop events sent by listed usernames before filter evaluation; use this to exclude your own bot account and prevent self-trigger loops.
    bodyPatternTaskSpawner.spec.when.githubWebhook.filters[]Go re2 regex match against the comment/review body — the modern replacement for substring-only matching.
    excludeBodyPatternsTaskSpawner.spec.when.githubWebhook.filters[]Companion to bodyPattern: a list of regexes that, if any match, drop the event. Use to carve out bot-echo replies that would otherwise match bodyPattern.
    commentOnTaskSpawner.spec.when.githubWebhook.filters[]Scopes issue_comment events to Issue or PullRequest. GitHub fires issue_comment for both, so set this to keep issue-only spawners off PRs (and vice versa).
    authorTaskSpawner.spec.when.githubWebhook.filters[]Restrict matches to a single sender's username. Omit it to accept every sender not listed in top-level excludeAuthors; kelos-workers sets it to the maintainer as an approval gate.
    draftTaskSpawner.spec.when.githubWebhook.filters[]Match by PR draft status. Set false to skip drafts; omit to match both.

    See docs/reference.md for the full TaskSpawner.spec.when.githubWebhook field reference.

  3. Customize the prompt:

    • Edit spec.taskTemplate.promptTemplate for a TaskSpawner or spec.sessionTemplate.initialPrompt for a SessionSpawner
    • Available template variables (Go text/template syntax):
    VariableDescriptionGitHub WebhookCron
    {{.ID}}Unique identifier for the work itemIssue/PR number as string (e.g., "42")Date-time string (e.g., "20260207-0900")
    {{.Number}}Issue or PR numberIssue/PR number (e.g., 42)0
    {{.Title}}Title of the work itemIssue/PR titleTrigger time (RFC3339)
    {{.Body}}Body text of the work itemIssue/PR bodyEmpty
    {{.URL}}URL to the source itemGitHub HTML URLEmpty
    {{.Event}}GitHub webhook event typeissue_comment, issues, pull_request_review, etc.Empty
    {{.Action}}GitHub webhook actioncreated, labeled, submitted, etc.Empty
    {{.Sender}}GitHub username that triggered the webhookGitHub loginEmpty
    {{.Branch}}Branch name when present in the webhook payloadPR head branch or pushed branch; empty for issue eventsEmpty
    {{.CommentBody}}Triggering comment or review bodyAvailable for comment and review eventsEmpty
    {{.CommentURL}}Triggering comment or review URLAvailable for comment and review eventsEmpty
    {{.Kind}}Type of work item"webhook""Issue"
    {{.Time}}Trigger time (RFC3339)EmptyCron tick time (e.g., "2026-02-07T09:00:00Z")
    {{.Schedule}}Cron schedule expressionEmptySchedule string (e.g., "0 * * * *")

    The webhook-based self-development agents re-read the latest issue or PR state with gh before acting, so they do not depend on aggregated {{.Comments}}, {{.ReviewComments}}, or {{.ReviewState}} variables.

  4. Remember the trigger is event-driven:

    • Webhook spawners do not poll or backfill old work items
    • Retrigger an existing issue or PR with a fresh comment or relabel after deployment
    • Duplicate a filter if you need to allow multiple specific GitHub usernames

  5. Adjust the Codex model and effort:

    spec:
  taskTemplate:
    worker:
      model: gpt-6-astra
      effort: xhigh

    The checked-in spawners use gpt-6-astra for high-capability tasks and gpt-5.4-mini for lower-cost routine tasks. They set effort by role: xhigh for complex planning, coding, strategy, review, PR update, and configuration update workflows; high for triage; and medium for routine image, fake-user, and squash workflows.

Feedback Loop Pattern

The key pattern in these examples is webhook-triggered handoff with durable, agent-directed Sessions:

  1. GitHub delivers an issue_comment, issues, or pull_request_review webhook
  2. The matching TaskSpawner creates a Task, while the issue and PR pick-up spawners for Kelos, Agora, Kanon, and Open Actions create Sessions
  3. A pick-up Session receives the issue or PR URL and asks the agent to choose the best way to address it
  4. Issue Sessions start on a dedicated issue branch, while PR Sessions start on the existing PR branch
  5. An exact /kelos pick-up command creates a Session for an open issue or PR; explicit commands or relabel events retrigger the other matching automation

Each matching webhook delivery creates a discrete Task or Session. A created Session remains available for interactive follow-ups through Session clients. Bot status and review replies should not include trigger commands accidentally. Explicit bot comments can trigger reviewer spawners when those spawners include a matching bot-author filter.

Troubleshooting

TaskSpawner not creating tasks:

  • Check the TaskSpawner status: kubectl get taskspawner <name> -o yaml
  • Verify the Workspace exists: kubectl get workspace
  • Ensure credentials are correctly configured: kubectl get secret kelos-credentials
  • Ensure the gateway webhook server is enabled (webhookServer.gatewayServer.enabled), the WebhookGateway is Authenticated (kubectl get webhookgateway kelos), and the github-webhook-secret exists with a webhook-secret key
  • Check webhook server logs: kubectl logs -l app.kubernetes.io/component=webhook-gateway-server
  • Review the repository webhook's recent deliveries in GitHub
  • If the issue or PR matched before you deployed the webhook server, retrigger it with a new comment or relabel

SessionSpawner not creating a Session:

  • Check the SessionSpawner status: kubectl get sessionspawner <name> -o yaml
  • Check created Sessions: SPAWNER_UID=$(kubectl get sessionspawner <name> -o jsonpath='{.metadata.uid}'); kubectl get sessions -l kelos.dev/sessionspawner="$SPAWNER_UID"
  • Check the same Workspace, credentials, webhook server, and recent-delivery details listed above

Tasks failing immediately:

  • Verify the agent credentials are valid
  • Check if the Workspace repository is accessible
  • Review task logs: kubectl logs -l job-name=<job-name>

Agent not creating PRs:

  • For Sessions, ensure personal-github-token exists and the corresponding *-session-agent Workspace references it
  • For Tasks, check the credentials referenced by the regular project Workspace
  • Verify the token has repo permissions
  • Check if the SessionSpawner configures the Git identity in worker.podOverrides.env

Next Steps

  • Read the main README for more details on Tasks and Workspaces
  • Review the agent image interface to create custom agents
  • Check existing TaskSpawners: kubectl get taskspawners
  • Monitor task execution: kelos get tasks or kubectl get tasks