# Agent Lifecycle (Issue → Merge)

What happens, step by step, from the moment you assign a coding agent to a task until the issue closes — and how each move is **attributed** (Agent vs Human) on the **Insights → Agent Activity** dashboard.

> This is the _behind-the-scenes flow_. For prerequisites, task assignment, and review steps, see [Coding Agents (GitHub PRs)](/docs/ai-chat/coding-agents). Workflow files are repository-specific; that guide intentionally does not publish copy-paste YAML.

## The flow at a glance

```
1. Issue created (todo)                          ── you, in iKanban
        │
        ▼
2. Assign an agent — @claude / @copilot / @gemini
        │   • iKanban opens a GitHub issue + an Agent Activity card
        │   • board move: todo → In Progress      ✅ attributed AGENT
        ▼
3. Agent runs                                    ── on GitHub
        │   • reads the issue, writes the code, commits, PUSHES A BRANCH
        ▼
4. Pull request opened
        │   • Copilot opens its own PR
        │   • Claude / Gemini: a workflow step opens it (with "Closes #N")
        ▼
5. Reconciler sees the PR (polls GitHub ~30–60s)
        │   • board move: In Progress → In Review ✅ attributed AGENT
        ▼
6. Review → Merge
        │   • approve + merge from the card (or auto-merge)
        ▼
7. PR merged
        │   • board move: → Done                  ✅ attributed AGENT
        │   • "Closes #N" closes the GitHub issue + the iKanban task
        ▼
8. Insights → Agent Activity shows each move,
   and the agent % goes up.
```

Steps **2, 5, 7** are where the agent earns credit on the dashboard. If **you** move a status by hand instead (e.g. click Done before the PR merges), that move is logged as **Human**, not Agent.

## How each agent maps to the flow

Every step works for all three, but the upstream half differs:

| Step                  | **Claude**                              | **Gemini**                                | **Copilot**         |
| --------------------- | --------------------------------------- | ----------------------------------------- | ------------------- |
| Branch                | ✅ `claude-code-action`                 | ✅ prompt: `git checkout -b`              | ✅ GitHub           |
| Implement             | ✅                                      | ✅                                        | ✅                  |
| Validate (lint/build) | ⚠️ not enforced in the workflow         | ✅ prompt runs `pnpm lint`, `cargo check` | ✅ (its own)        |
| **Open PR**           | ✅ workflow step (after the agent)      | ✅ same step                              | ✅ opens its own PR |
| Review                | approve from the card (or auto-approve) | same                                      | same                |
| Merge                 | ✅ from the card / auto-merge           | ✅                                        | ✅                  |
| Close on merge        | ✅ `Closes #N`                          | ✅                                        | ✅                  |

**Why Copilot differs:** Copilot is GitHub's _native_ coding agent — it runs on github.com and opens its own PR, so there's no workflow file for it. **Claude** (`claude.yml`) and **Gemini** (`gemini.yml`) run as GitHub Actions in your repo.

## Where each step actually happens

| Move                      | Driven by                                                                                                                        |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| todo → In Progress        | The assign action (the moment you mention the agent)                                                                             |
| Push branch → **open PR** | Copilot natively; Claude/Gemini via an **"Open PR from agent branch"** step in their workflow that opens the PR with `Closes #N` |
| In Progress → In Review   | iKanban's reconciler, when it detects the open PR                                                                                |
| → Done + close issue/task | The PR merge — `Closes #N` closes the issue, and the reconciler moves the task to Done                                           |

## Attribution: Agent vs Human

Every board move above is recorded with **who made it**:

- **Agent** — the move was caused by the agent's lifecycle (assignment, PR opened, PR merged). Attributed to the team's AI-agent identity.
- **Human** — a real person moved the status (in the browser or via the API/CLI).

Open **Insights → Agent Activity** to see the split: a headline _"X% of board moves were by agents"_, an Agent / Human / System breakdown, and a recent-transitions feed.

> **Tip:** to see an agent get credit for _closing_ a task, let the agent's **PR merge** drive it to Done — don't click Done by hand first. A manual close is (correctly) logged as Human.

## Notes & current limits

- **Auto-merge needs a token.** Claude/Gemini open the PR with the workflow's built-in token, which (by GitHub's loop-prevention) does **not** auto-trigger the auto-merge workflow. So the PR **opens** automatically but is **merged from the card / manually** unless your repo adds a Personal Access Token secret for the open-PR step. The board still attributes and closes correctly on merge.
- **No "verify in prod" step.** Agents close on merge; they don't run the post-deploy "is it actually working in production?" check that a human would. Treat an agent PR like an external contribution and **review before merging**.
- **One agent per task at a time.** A new mention on a task that already has an active agent is forwarded to the existing PR, not started as a second run.

## Troubleshooting

| Symptom                            | Likely cause                                                                                                                           |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Card stuck on "In Progress", no PR | Claude/Gemini pushed a branch but the PR step hasn't run/opened it yet — check the workflow run, or open the branch's "Create PR" link |
| Agent close shows as **Human**     | The task was moved to Done by hand (or via API/CLI) before the PR merged                                                               |
| Agent bar stays 0%                 | No agent has _moved a status_ in the window yet — historical agent merges before the feature shipped aren't counted                    |
| PR opened but never merges         | The auto-merge token caveat above — merge it from the Agent Activity card                                                              |