Add open-source maintainer toolkit example (examples/08-oss-maintainer-kit)

[gjkim42]

Summary

Create a reusable, drop-in toolkit that lets any open-source project adopt Kelos for maintainer automation with minimal setup. The goal is to make Kelos the standard platform for AI-assisted open-source maintenance and drive adoption.

Related: #568 (original proposal), #291 (overlapping use case patterns)

Problem

1. No multi-agent orchestration example — The existing 7 examples demonstrate individual patterns (single task, cron, pipeline, etc.), but none show how multiple TaskSpawners coordinate a real maintainer workflow end-to-end.
2. Self-development configs are Kelos-specific — self-development/ is a production deployment referencing Kelos-specific labels, conventions, and identity. New users must reverse-engineer what's generalizable.
3. Label-heavy triggers create adoption friction — Many automation patterns assume projects have dedicated labels (needs-triage, auto-fix, etc.). Most projects don't, and setting up a label taxonomy is a barrier.

Proposed Solution

A new examples/08-oss-maintainer-kit/ directory with comment-triggered TaskSpawners that work on any GitHub repository out of the box.

Design principles

• Comment-based triggers by default — Maintainers type /bot triage, /bot fix, /bot update on any issue or PR. No label setup required.
• Zero-config start — Only a Workspace (repo URL + token) and agent credentials are needed. Everything else has sensible defaults.
• Labels as optional enhancement — Projects that want more automation can layer in label filters, but they're not a prerequisite.
• Familiar UX — Mirrors /lgtm, /approve, /hold patterns from Prow and similar bots that contributors already know.

Directory structure

examples/08-oss-maintainer-kit/
├── README.md                       # Setup guide + customization instructions
├── workspace.yaml                  # Template Workspace (user fills in their repo)
├── agentconfig.yaml                # Shared AgentConfig with project-agnostic defaults
├── triage-spawner.yaml             # /bot triage — classify and prioritize issues
├── worker-spawner.yaml             # /bot fix — pick up issues and create PRs
├── pr-responder-spawner.yaml       # /bot update — address PR review feedback
├── stale-issue-spawner.yaml        # Cron — weekly stale issue cleanup
└── contributor-guide-spawner.yaml  # /bot guide — onboarding help for good-first-issue items

1. triage-spawner.yaml — Issue triage (/bot triage)

apiVersion: kelos.dev/v1alpha1
kind: TaskSpawner
metadata:
  name: oss-triage
spec:
  when:
    githubIssues:
      state: open
      triggerComment: /bot triage
      excludeComments:
        - /bot done
  maxConcurrency: 4
  taskTemplate:
    type: claude-code
    model: sonnet
    workspaceRef:
      name: my-project
    credentials:
      type: api-key
      secretRef:
        name: agent-credentials
    agentConfigRef:
      name: oss-maintainer-agent
    promptTemplate: |
      You are an issue triage agent for an open-source project.

      Analyze issue #{{.Number}}: {{.Title}}

      {{.Body}}
      {{if .Comments}}
      Comments:
      {{.Comments}}
      {{end}}

      Tasks:
      1. Classify the issue (bug, feature request, question, documentation)
      2. Check if this is a duplicate of any open issue
      3. Assess severity and priority
      4. If it's a question, provide a helpful answer directly
      5. Post a triage comment with your analysis
      6. Apply appropriate labels if the project uses them

      Rules:
      - Be welcoming — this may be someone's first open-source interaction
      - For duplicates, link to the original issue and suggest closing
      - For questions answered in docs, link to the relevant documentation
      - Do NOT close issues — only comment and label

2. worker-spawner.yaml — Auto-fix (/bot fix)

apiVersion: kelos.dev/v1alpha1
kind: TaskSpawner
metadata:
  name: oss-worker
spec:
  when:
    githubIssues:
      state: open
      triggerComment: /bot fix
      excludeComments:
        - /bot needs-input
  maxConcurrency: 2
  taskTemplate:
    type: claude-code
    model: opus
    workspaceRef:
      name: my-project
    credentials:
      type: api-key
      secretRef:
        name: agent-credentials
    agentConfigRef:
      name: oss-maintainer-agent
    branch: "bot/fix-{{.Number}}"
    promptTemplate: |
      Fix issue #{{.Number}}: {{.Title}}

      {{.Body}}
      {{if .Comments}}
      Comments:
      {{.Comments}}
      {{end}}

      Steps:
      1. Understand the issue from the description and comments
      2. Explore the codebase to find the relevant code
      3. Implement a minimal, focused fix
      4. Run tests if a test command is documented
      5. Create a PR referencing the issue

      Rules:
      - Keep changes minimal — fix only what the issue asks for
      - Do not refactor surrounding code
      - If you cannot fix it confidently, comment on the issue explaining why
        and post "/bot needs-input"

3. pr-responder-spawner.yaml — PR feedback loop (/bot update)

This is the critical piece that closes the automation loop. Uses githubPullRequests trigger with PR-specific fields ({{.Branch}}, {{.ReviewState}}, {{.ReviewComments}}).

apiVersion: kelos.dev/v1alpha1
kind: TaskSpawner
metadata:
  name: oss-pr-responder
spec:
  when:
    githubPullRequests:
      state: open
      draft: false
      triggerComment: /bot update
      excludeComments:
        - /bot needs-input
  maxConcurrency: 2
  taskTemplate:
    type: claude-code
    model: opus
    workspaceRef:
      name: my-project
    credentials:
      type: api-key
      secretRef:
        name: agent-credentials
    agentConfigRef:
      name: oss-maintainer-agent
    branch: "{{.Branch}}"
    promptTemplate: |
      You are updating an existing PR in response to review feedback.

      PR #{{.Number}}: {{.Title}}
      Branch: {{.Branch}}
      Review state: {{.ReviewState}}

      {{if .ReviewComments}}
      Inline review comments:
      {{.ReviewComments}}
      {{end}}
      {{if .Comments}}
      PR conversation:
      {{.Comments}}
      {{end}}

      Steps:
      1. Check out the existing branch and read the current diff
      2. Address each review comment with minimal, focused changes
      3. Run tests to verify your changes
      4. Commit and push to the same branch
      5. Post a comment summarizing what you changed

      Rules:
      - Make incremental changes — do NOT rewrite from scratch
      - If you need maintainer input, post "/bot needs-input" and explain why

4. stale-issue-spawner.yaml — Weekly stale cleanup (cron)

apiVersion: kelos.dev/v1alpha1
kind: TaskSpawner
metadata:
  name: oss-stale-cleanup
spec:
  when:
    cron:
      schedule: "0 9 * * 1"    # Every Monday at 9am
  maxConcurrency: 1
  taskTemplate:
    type: claude-code
    model: sonnet
    workspaceRef:
      name: my-project
    credentials:
      type: api-key
      secretRef:
        name: agent-credentials
    agentConfigRef:
      name: oss-maintainer-agent
    promptTemplate: |
      Review open issues with no activity in 90+ days.

      Steps:
      1. List issues with no recent activity using gh CLI
      2. For each stale issue:
         - Check if the issue is still relevant
         - Check if a PR already addresses it
         - If clearly outdated, comment explaining why and suggest closing
         - If unclear, ask the reporter for an update
      3. Process at most 5 issues per run to avoid noise

      Rules:
      - Never close issues directly — only comment
      - Be respectful — someone may still care about the issue
      - Skip issues with "pinned" or "keep-open" labels

5. contributor-guide-spawner.yaml — Contributor help (/bot guide)

apiVersion: kelos.dev/v1alpha1
kind: TaskSpawner
metadata:
  name: oss-contributor-guide
spec:
  when:
    githubIssues:
      state: open
      triggerComment: /bot guide
      excludeComments:
        - /bot done
  maxConcurrency: 2
  taskTemplate:
    type: claude-code
    model: sonnet
    workspaceRef:
      name: my-project
    credentials:
      type: api-key
      secretRef:
        name: agent-credentials
    agentConfigRef:
      name: oss-maintainer-agent
    promptTemplate: |
      Help potential contributors get started with issue #{{.Number}}.

      Issue: {{.Title}}
      {{.Body}}

      Steps:
      1. Understand what needs to be done
      2. Explore the codebase to find relevant files and code paths
      3. Post a contributor guide comment that includes:
         - Which files to look at (with line references)
         - The expected approach (high-level steps)
         - How to test the changes locally
         - Links to relevant documentation or similar past PRs

      Rules:
      - Write for someone who may have never contributed to this project
      - Include concrete file paths and function names
      - If the issue is too complex for a first-time contributor, say so

6. Shared agentconfig.yaml

apiVersion: kelos.dev/v1alpha1
kind: AgentConfig
metadata:
  name: oss-maintainer-agent
spec:
  agentsMD: |
    # Open Source Maintainer Agent

    You are running in an ephemeral container. Persist work through
    PRs, issues, or comments — file system changes disappear after completion.

    ## Communication
    - Be welcoming and respectful to all contributors
    - Start comments with "🤖 **Bot** (automated)\n\n" so humans can tell
    - Use clear, concise language
    - Link to relevant documentation when possible

    ## Standards
    - Check for existing issues/PRs before creating new ones
    - Keep changes minimal and focused
    - Follow the project's existing conventions (check CONTRIBUTING.md, Makefile, etc.)

Why this matters for Kelos adoption

• Immediate value — Open-source maintainers are the most likely early adopters. They have real pain (burnout, issue backlog) and the technical background to deploy on Kubernetes.
• Proof by example — Kelos's own self-development pipeline (6 TaskSpawners including githubPullRequests-based PR responder) proves this works in production.
• Low barrier — Comment-based triggers mean zero label setup. A project can go from install to working automation in minutes.
• Network effects — Contributors to projects using Kelos see it in action, creating organic awareness.
• Showcases key differentiators — Multi-agent orchestration, githubPullRequests triggers, comment-based feedback loops, and the full issue→PR→review→update cycle.

Scope

This is a docs/examples-only change — no code modifications needed. All proposed configs use existing API features.

/kind docs

[kelos-bot]

🤖 Kelos Agent @gjkim42

Kelos Triage Report

Kind: kind/docs (already applied)
Priority: priority/important-longterm — Valuable for driving adoption and showcasing multi-agent orchestration, but not blocking any users or fixing broken behavior
Actor: actor/kelos — Well-scoped docs/examples change with concrete YAML provided; all proposed API fields verified as valid

Status: STILL VALID

Evidence:

• No merged PRs reference this issue (gh pr list --state merged --search "627" returned empty)
• No commits on main reference this issue or related keywords
• examples/08-oss-maintainer-kit/ does not exist in the codebase — only examples 01-07 are present
• All proposed YAML fields are valid in the current API:
  • triggerComment — exists in api/v1alpha1/taskspawner_types.go
  • excludeComments — exists in api/v1alpha1/taskspawner_types.go
  • githubPullRequests — fully implemented as a trigger type
  • {{.Branch}}, {{.ReviewState}}, {{.ReviewComments}} — implemented in internal/source/prompt.go
  • model — exists in both TaskTemplate and TaskSpec
• The self-development directory (self-development/) confirms these patterns work in production (e.g., kelos-pr-responder.yaml, kelos-workers.yaml)
• Referenced issue New use case: Reusable open-source maintainer automation kit with example TaskSpawner configs #568 (original proposal) is closed, making this the active successor

Duplicates found: None exact. Related issues:

• Orchestrator pattern #328 ("Orchestrator pattern") — vague request that Add open-source maintainer toolkit example (examples/08-oss-maintainer-kit) #627 would partially or fully satisfy
• New use cases: PR review, fleet migration, security audit, and beyond #291 ("New use cases: PR review, fleet migration, security audit, and beyond") — overlapping vision but proposes different example directories (05/06/07 vs 08); already cross-referenced by the author
• comment based workflow should work with review comments and others as well #615 ("Comment-based workflow should work with review comments") — the PR responder spawner in Add open-source maintainer toolkit example (examples/08-oss-maintainer-kit) #627 depends on this capability working for review comments

Recommendation: KEEP OPEN