# Working with Coding Agents on GitHub — End-to-End Playbook A hands-on, bookmark-it walkthrough for getting the **most** out of iKanban's coding agents: turn any task into a **merged pull request** by handing it to `@claude`, `@copilot`, or `@gemini` — and drive the whole thing (kick off → watch → review → merge → iterate) **without leaving iKanban**. > New here? Start with [Coding Agents (GitHub PRs)](/docs/ai-chat/coding-agents) for the one-time repo setup, and [Agent Lifecycle (Issue → Merge)](/docs/ai-chat/agent-lifecycle) for the big-picture flow. **This page is the practical playbook** — what to type, what you'll see, and how to get a great result every time. --- ## What you can do with this - Assign a real code change to an AI agent from a task — it writes the code and opens a **pull request** back to your repo. - Track it on the **Agent Activity card** right on the task: `Queued → Working → Pull request opened → Merged`. - **Review, approve, and merge** from the card — no tab-switching to GitHub. - **Iterate** by replying with a follow-up — changes land on the _same_ PR. - When CI breaks, get an **automatic triage comment** telling you the likely cause. --- ## Before you start (one-time) You need this set up once per repo (details in [Coding Agents](/docs/ai-chat/coding-agents)): 1. **Connect GitHub** to your workspace and pick the repository for the team. 2. **Enable the agent** you want: - **Copilot** — nothing to install; it's GitHub-native. - **Claude / Gemini** — configure the provider's maintained workflow for the repository. Review its permissions and event handling; the iKanban guide does not ship copy-paste workflow YAML. 3. (Recommended) Install the **iKanban GitHub App** on the repo so status updates arrive in real time. Once that's done, you never touch it again — the rest is per-task. --- ## Step 1 — Kick off an agent On any task, do **either**: - **Mention it in a comment:** `@claude`, `@copilot`, or `@gemini` — followed by what you want. - **Use the Assign action** on the task and pick the agent. The moment you do, iKanban opens a GitHub issue for the work and the task shows an **Agent Activity card**. The board moves the task to **In Progress** automatically. **Which agent?** | Pick… | When | | ----------- | --------------------------------------------------------------------------------------- | | **Claude** | General implementation, refactors, multi-file changes, following detailed instructions. | | **Gemini** | Similar scope; its workflow also runs lint/build checks before opening the PR. | | **Copilot** | You want GitHub's native agent and its own PR flow. | You can use different agents on different tasks in parallel — each task tracks its own run. --- ## Step 2 — Write instructions that get a great result The agent only knows what the task tells it. A few minutes here saves a round-trip: - **Be specific about the outcome.** "Add a `Cancel` button to the invoice dialog that calls `POST /invoices/{id}/cancel` and shows a toast on success" beats "handle cancel". - **Name the files or patterns** to follow ("match the existing `AsyncButton` usage in `InvoiceActions`"). - **State the acceptance criteria** — what "done" looks like, and any edge cases. - **Keep the task focused.** One coherent change per task merges faster and reviews cleaner than a mega-task. - **Say what NOT to touch** if there's adjacent code you want left alone. --- ## Step 3 — Watch it work (the Agent Activity card) The card updates itself (it refreshes every few seconds while the agent is active). You'll see the chip and checklist move through: | Card shows | What it means | What you do | | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | **Queued** — _waiting for the agent to pick up_ | The issue is created; the agent hasn't started yet. | Nothing — just wait. | | **Working** — _agent is working on this issue_ | The agent is writing code. | Nothing yet. | | ✅ **Pull request opened** | A PR is up with the changes. | **Review it** (next step). | | **Done** — _agent finished its work_ | The agent finished. Its answer shows in the task's live activity. A PR with changes stays open for your review. | Read the answer; review and merge the PR if it has changes. | | **Merged** — _pull request merged_ | The change is in; the task moves to **Done**. | Done 🎉 | | **Failed** / _did not complete_ | The run ended without a PR, or its PR with changes was closed without merging. Closing an empty PR after the agent finished keeps the run **Done**. | Check the task comments, refine the instructions, and mention the agent again. | There's a **GitHub issue** link on the card if you ever want the raw thread. --- ## Step 4 — Review & merge (without leaving iKanban) When the card shows **Pull request opened**: 1. Open the PR from the card to see the diff and the agent's summary. 2. **Approve** it, or request changes. 3. **Merge** — from the card or GitHub. On merge, the PR's `Closes #…` reference **closes the GitHub issue and marks the iKanban task Done**, and the agent gets credit on **Insights → Agent Activity**. > **Tip — let the merge close the task.** If you click _Done_ by hand before the PR merges, that move is logged as **you**, not the agent. Let the merge do it and the agent earns the credit. --- ## Step 5 — Iterate on the same PR Not quite right? **Reply with another mention** on the task — `@claude also handle the empty-state case` — and the follow-up goes to the **existing PR**, not a new run. Keep iterating in the same thread until it's ready to merge. --- ## When CI fails If the checks on an agent's PR fail, iKanban posts an **automatic triage comment** — a short, plain-English root-cause hypothesis pulled from the failed job's log, plus the most useful next check. Read it, decide, and either fix-forward (a follow-up mention) or close the PR. You'll also get an **inbox notification** that CI failed. More in [CI Failure Triage](/docs/ai-chat/ci-failure-triage). --- ## Get the most out of it (power tips) - **Parallelize.** Fan several small tasks out to agents at once — each runs independently and tracks its own card. - **Right agent for the job.** Use Gemini when you want lint/build enforced pre-PR; Claude for detailed multi-file work; Copilot for native GitHub flow. - **Small, well-scoped tasks win.** They implement faster, review cleaner, and merge sooner than a sprawling one. - **Treat an agent PR like any contribution — review before merging.** Agents finish at _merge_; they don't verify the change in production for you. - **Measure it.** **Insights → Agent Activity** shows what share of your board moves agents are driving — a quick read on how much leverage you're getting. - **Follow-ups over restarts.** Refining via a reply keeps everything on one PR and one review thread. --- ## Troubleshooting | Symptom | What to do | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Card stuck on **Queued** for a while | The agent hasn't picked up yet, or the repo isn't fully set up — confirm GitHub is connected and the workflow/App is installed ([setup](/docs/ai-chat/coding-agents)). | | Card **Working**, no PR after a while | The agent may still be running, or its run ended without changes — check the task comments; refine and mention it again. | | PR opened but **won't auto-merge** | Merge it from the card — auto-merge needs an extra repo token; the change still closes the task correctly on merge. | | Agent shows **Failed** | The run didn't finish — read the task comments for why, tighten the instructions, and re-mention the agent. | | Merge counted as **you**, not the agent | You moved the task to Done manually before the PR merged. Let the merge do it next time. | --- ## Quick reference (bookmark this) - **Kick off:** mention `@claude` / `@copilot` / `@gemini` on a task, or use **Assign**. - **Card states:** `Queued → Working → Pull request opened → Merged` (or `Failed`). - **Review/merge:** from the Agent Activity card — approve, then merge. - **Iterate:** reply with another mention → same PR. - **Measure:** Insights → Agent Activity. - **Related:** [Setup & workflows](/docs/ai-chat/coding-agents) · [Lifecycle overview](/docs/ai-chat/agent-lifecycle) · [CI triage](/docs/ai-chat/ci-failure-triage)