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). 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:

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

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