diff --git a/examples/09-oss-maintainer-kit/README.md b/examples/09-oss-maintainer-kit/README.md new file mode 100644 index 0000000..d0f88dd --- /dev/null +++ b/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. diff --git a/examples/09-oss-maintainer-kit/agentconfig.yaml b/examples/09-oss-maintainer-kit/agentconfig.yaml new file mode 100644 index 0000000..e210236 --- /dev/null +++ b/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.) diff --git a/examples/09-oss-maintainer-kit/code-review-spawner.yaml b/examples/09-oss-maintainer-kit/code-review-spawner.yaml new file mode 100644 index 0000000..09347c4 --- /dev/null +++ b/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 diff --git a/examples/09-oss-maintainer-kit/contributor-guide-spawner.yaml b/examples/09-oss-maintainer-kit/contributor-guide-spawner.yaml new file mode 100644 index 0000000..037b79d --- /dev/null +++ b/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 diff --git a/examples/09-oss-maintainer-kit/credentials-secret.yaml b/examples/09-oss-maintainer-kit/credentials-secret.yaml new file mode 100644 index 0000000..51e2cd3 --- /dev/null +++ b/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 diff --git a/examples/09-oss-maintainer-kit/github-token-secret.yaml b/examples/09-oss-maintainer-kit/github-token-secret.yaml new file mode 100644 index 0000000..138c5c2 --- /dev/null +++ b/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 diff --git a/examples/09-oss-maintainer-kit/pr-responder-spawner.yaml b/examples/09-oss-maintainer-kit/pr-responder-spawner.yaml new file mode 100644 index 0000000..974beb3 --- /dev/null +++ b/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 diff --git a/examples/09-oss-maintainer-kit/stale-issue-spawner.yaml b/examples/09-oss-maintainer-kit/stale-issue-spawner.yaml new file mode 100644 index 0000000..e676a97 --- /dev/null +++ b/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 diff --git a/examples/09-oss-maintainer-kit/triage-spawner.yaml b/examples/09-oss-maintainer-kit/triage-spawner.yaml new file mode 100644 index 0000000..0d24b53 --- /dev/null +++ b/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 diff --git a/examples/09-oss-maintainer-kit/worker-spawner.yaml b/examples/09-oss-maintainer-kit/worker-spawner.yaml new file mode 100644 index 0000000..9b2fd01 --- /dev/null +++ b/examples/09-oss-maintainer-kit/worker-spawner.yaml @@ -0,0 +1,48 @@ +apiVersion: kelos.dev/v1alpha1 +kind: TaskSpawner +metadata: + name: oss-worker +spec: + when: + githubIssues: + state: open + triggerComment: /bot fix + 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: "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" + - After successfully creating the PR, post "/bot done" as a separate + comment on the issue so the spawner does not re-trigger diff --git a/examples/09-oss-maintainer-kit/workspace.yaml b/examples/09-oss-maintainer-kit/workspace.yaml new file mode 100644 index 0000000..5e15e16 --- /dev/null +++ b/examples/09-oss-maintainer-kit/workspace.yaml @@ -0,0 +1,9 @@ +apiVersion: kelos.dev/v1alpha1 +kind: Workspace +metadata: + name: my-project +spec: + repo: https://github.com/owner/repo.git # TODO: replace with your repository URL + ref: main + secretRef: + name: github-token diff --git a/examples/README.md b/examples/README.md index 405a43a..a3a39f1 100644 --- a/examples/README.md +++ b/examples/README.md @@ -19,6 +19,7 @@ Ready-to-use patterns and YAML manifests for orchestrating AI agents with Kelos. | [06-fork-workflow](06-fork-workflow/) | Discover upstream issues and work in a fork | | [07-task-pipeline](07-task-pipeline/) | Chain Tasks with `dependsOn` and pass results between stages | | [08-task-with-kelos-skill](08-task-with-kelos-skill/) | Give an agent the Kelos skill for authoring and debugging resources | +| [09-oss-maintainer-kit](09-oss-maintainer-kit/) | Drop-in toolkit for AI-assisted open-source maintenance with comment-triggered agents | ## How to Use