Add open-source maintainer toolkit example

examples/09-oss-maintainer-kit/README.md

@@ -0,0 +1,100 @@
+# 09 — Open-Source Maintainer Kit
+
+A drop-in toolkit of comment-triggered TaskSpawners that automate common
+open-source maintenance tasks: issue triage, auto-fix, code review, PR
+feedback loops, stale issue cleanup, and contributor onboarding.
+
+## Use Case
+
+Maintainers type `/bot triage`, `/bot fix`, `/bot review`, `/bot update`, or
+`/bot guide` on any issue or PR. Kelos picks up the comment and spawns an
+agent Task automatically. No label taxonomy required — just comments.
+
+This is a **multi-agent orchestration** example: six TaskSpawners coordinate
+the full issue-to-PR-to-review lifecycle.
+
+## Resources
+
+| File | Kind | Purpose |
+|------|------|---------|
+| `github-token-secret.yaml` | Secret | GitHub token for cloning, PR creation, and polling |
+| `credentials-secret.yaml` | Secret | Anthropic API key for the agent |
+| `workspace.yaml` | Workspace | Git repository to clone into each Task |
+| `agentconfig.yaml` | AgentConfig | Shared instructions for all agents |
+| `triage-spawner.yaml` | TaskSpawner | `/bot triage` — classify and prioritize issues |
+| `worker-spawner.yaml` | TaskSpawner | `/bot fix` — pick up issues and create PRs |
+| `code-review-spawner.yaml` | TaskSpawner | `/bot review` — automated code review on PRs |
+| `pr-responder-spawner.yaml` | TaskSpawner | `/bot update` — address PR review feedback |
+| `stale-issue-spawner.yaml` | TaskSpawner | Cron — weekly stale issue cleanup |
+| `contributor-guide-spawner.yaml` | TaskSpawner | `/bot guide` — onboarding help for contributors |
+
+## How It Works
+
+```
+Maintainer comments "/bot triage" on issue
+    └── triage-spawner → agent classifies, labels, and comments
+
+Maintainer comments "/bot fix" on issue
+    └── worker-spawner → agent creates branch, implements fix, opens PR
+
+Maintainer comments "/bot review" on PR
+    └── code-review-spawner → agent reviews the diff and posts review comments
+
+Reviewer comments "/bot update" on PR
+    └── pr-responder-spawner → agent addresses review feedback, pushes to branch
+
+Every Monday at 9am
+    └── stale-issue-spawner → agent reviews inactive issues, posts updates
+
+Maintainer comments "/bot guide" on good-first-issue
+    └── contributor-guide-spawner → agent posts a contributor guide comment
+```
+
+## Steps
+
+1. **Edit the secrets** — replace placeholders in `github-token-secret.yaml`
+   and `credentials-secret.yaml` with your real tokens.
+
+2. **Edit `workspace.yaml`** — set your repository URL.
+
+3. **Review `agentconfig.yaml`** — customize the instructions for your project.
+
+4. **Apply the resources:**
+
+```bash
+kubectl apply -f examples/09-oss-maintainer-kit/
+```
+
+5. **Verify the spawners are running:**
+
+```bash
+kubectl get taskspawners -w
+```
+
+6. **Test it** — comment `/bot triage` on an open issue in your repository.
+   The TaskSpawner picks it up on the next poll and creates a Task.
+
+7. **Watch spawned Tasks:**
+
+```bash
+kubectl get tasks -w
+```
+
+8. **Cleanup:**
+
+```bash
+kubectl delete -f examples/09-oss-maintainer-kit/
+```
+
+## Customization
+
+- **Swap agent type** — change `type` in any spawner's `taskTemplate` to use
+  `codex`, `gemini`, or another supported agent.
+- **Add label filters** — add `labels` or `excludeLabels` to any spawner to
+  narrow which issues/PRs it responds to.
+- **Adjust concurrency** — increase `maxConcurrency` for higher throughput or
+  decrease it to limit resource usage.
+- **Change the trigger comment** — replace `/bot triage` with any prefix your
+  team prefers (e.g., `/kelos triage`, `/ai triage`).
+- **Layer in label-based triggers** — for projects with an existing label
+  taxonomy, you can remove `triggerComment` and use `labels` instead.

examples/09-oss-maintainer-kit/agentconfig.yaml

@@ -0,0 +1,20 @@
+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
+    - 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.)

examples/09-oss-maintainer-kit/code-review-spawner.yaml

@@ -0,0 +1,58 @@
+apiVersion: kelos.dev/v1alpha1
+kind: TaskSpawner
+metadata:
+  name: oss-code-reviewer
+spec:
+  when:
+    githubPullRequests:
+      state: open
+      draft: false
+      triggerComment: /bot review
+      excludeComments:
+        - /bot needs-input
+        - /bot done
+  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 a code reviewer for an open-source project.
+
+      PR #{{.Number}}: {{.Title}}
+      Branch: {{.Branch}}
+
+      {{if .Comments}}
+      PR conversation:
+      {{.Comments}}
+      {{end}}
+
+      Steps:
+      1. Check out the PR branch and read the full diff against the base branch
+      2. Understand the intent of the changes from the PR description and comments
+      3. Review the code for:
+         - Correctness — does the code do what it claims?
+         - Bugs — potential nil dereferences, race conditions, off-by-one errors
+         - Security — injection, leaked credentials, unsafe operations
+         - Tests — are changes adequately tested?
+         - Style — does the code follow the project's existing conventions?
+      4. Post a review comment summarizing your findings
+      5. If there are specific issues, use inline review comments on the relevant lines
+      6. After posting the review, post "/bot done" as a separate comment on
+         the PR so the spawner does not re-trigger
+
+      Rules:
+      - Focus on substantive issues — do not nitpick formatting or style preferences
+        that are not part of the project's established conventions
+      - Acknowledge what the PR does well before listing issues
+      - If the code looks good, say so — not every review needs to request changes
+      - Be constructive — suggest fixes, not just problems
+      - If you need more context, post "/bot needs-input" and explain what you need

examples/09-oss-maintainer-kit/contributor-guide-spawner.yaml

@@ -0,0 +1,45 @@
+apiVersion: kelos.dev/v1alpha1
+kind: TaskSpawner
+metadata:
+  name: oss-contributor-guide
+spec:
+  when:
+    githubIssues:
+      state: open
+      triggerComment: /bot guide
+      excludeComments:
+        - /bot needs-input
+        - /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
+      - After posting the guide, post "/bot done" as a separate comment on
+        the issue so the spawner does not re-trigger

examples/09-oss-maintainer-kit/credentials-secret.yaml

@@ -0,0 +1,7 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: agent-credentials
+type: Opaque
+stringData:
+  ANTHROPIC_API_KEY: "" # TODO: paste your Anthropic API key

examples/09-oss-maintainer-kit/github-token-secret.yaml

@@ -0,0 +1,7 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: github-token
+type: Opaque
+stringData:
+  GITHUB_TOKEN: "" # TODO: paste a GitHub PAT with repo permissions

examples/09-oss-maintainer-kit/pr-responder-spawner.yaml

@@ -0,0 +1,54 @@
+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
+        - /bot done
+  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
+      - After completing the update, post "/bot done" as a separate comment on
+        the PR so the spawner does not re-trigger

examples/09-oss-maintainer-kit/stale-issue-spawner.yaml

@@ -0,0 +1,36 @@
+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

examples/09-oss-maintainer-kit/triage-spawner.yaml

@@ -0,0 +1,50 @@
+apiVersion: kelos.dev/v1alpha1
+kind: TaskSpawner
+metadata:
+  name: oss-triage
+spec:
+  when:
+    githubIssues:
+      state: open
+      triggerComment: /bot triage
+      excludeComments:
+        - /bot needs-input
+        - /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
+      - After completing triage, post "/bot done" as a separate comment on
+        the issue so the spawner does not re-trigger