Use when managing tasks with the agkan CLI tool - creating, listing, updating tasks, managing tags, blocking relationships, or tracking project progress with the kanban board.

2026-06-170

agkan-planning

gendosu/agkan-skills

Use when reviewing backlog tasks to assess decomposition, implementation readiness, and priority ordering before development begins.

2026-06-150

agkan-run-direct

gendosu/agkan-skills

Use when starting a development session to pick the highest priority Todo task from agkan, implement it directly without PR/branch, and mark it done.

2026-06-150

agkan-subtask-direct

gendosu/agkan-skills

Use when a task has been selected and you need to implement it directly without PR/branch creation - handles in_progress update, implementation, and marking done.

2026-06-090

agkan-subtask

gendosu/agkan-skills

Use when a task has been selected and you need to implement it in an isolated (forked) context - handles in_progress update, branch creation, implementation, PR creation, and marking review.

2026-05-200

agkan-review

gendosu/agkan-skills

Use when checking review tasks against GitHub PR status to automatically move them to done or closed.

2026-05-170

name	agkan-run
description	Use when starting a development session to pick the highest priority Todo task from agkan, implement it, create a pull request, and mark it done.

agkan-run

Overview

Standard workflow to pick the highest priority ready task from agkan, implement it, create a pull request, and complete it.

CRITICAL: This is a loop. After each task completes (including handling any interruptions), ALWAYS re-fetch the task list and continue unless explicitly told to stop.

Workflow

0. Fetch Config

CONFIG=$(agkan config get --json 2>/dev/null || echo '{}')
RUN_MODEL=$(echo "$CONFIG" | jq -r '.config.models.run.model // "sonnet"')
RUN_EFFORT=$(echo "$CONFIG" | jq -r '.config.models.run.effort // "medium"')

1. Update branch to latest

Before switching to the default branch, check for uncommitted changes:

git status --porcelain

If there are uncommitted changes, stash them first:

git stash push -m "agkan-run: stash before switching to default branch"

Then get the default branch name dynamically and update to latest:

DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@') && \
  [ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name' 2>/dev/null) && \
  git checkout "$DEFAULT_BRANCH" && git pull -p

2. Get ready tasks

agkan task list --status ready --json

3. Select the highest priority task

Evaluate tasks in descending order using the following criteria and select the top one:

Skip tasks with will-do-later tag: Tasks with the will-do-later tag are intentionally postponed tasks. Skip them unless they are in ready status — a task promoted to ready is executable regardless of the tag.

Priority (read from metadata field in the list JSON response):

Critical > High > Medium > Low

Tags (refer to when priority is the same):

bug > security > improvement > test > performance > refactor > docs

If there are child tasks or blocker tasks Prioritize the target child tasks or blocker tasks (same importance and tag criteria apply)

4. Check for blockers

agkan task block list <id> --json

If there are incomplete tasks in blockedBy, do not select that task. Instead, select a different task or process the blocker task first.

5. Update task to in_progress

agkan task update <id> status in_progress

5a. Inspect task for existing Branch/PR

Before launching the sub-agent, retrieve the task to get the branch and check the body for a PR: label:

agkan task get <id> --json

Extract:

Branch: read from .task.branch (first-class column; null if not set)
PR: parse the task body for a PR: <URL> label

Pass these values to the sub-agent prompt (Step 6) so it can resume work on the existing branch/PR instead of creating new ones.

6. Implement, create PR, complete

Use the Task tool (general-purpose sub-agent) to implement. Do not use Skill("agkan-subtask"); instead, embed the workflow steps directly in the sub-agent prompt.

Why embed steps instead of referencing a file path? Sub-agents spawned via the Task tool start with a fresh context. When installed as a plugin, the skill files may reside at a path unknown to the sub-agent (e.g., under a plugin cache directory), so instructing the sub-agent to read a relative or installation-specific path is unreliable. Embedding the workflow steps directly in the prompt makes the instructions path-independent.

Before calling Task(), substitute the placeholders with the values fetched in Step 0:

Replace <RUN_MODEL> with the value of $RUN_MODEL
Replace <RUN_EFFORT> with the value of $RUN_EFFORT

Task(
  subagent_type="general-purpose",
  model="<RUN_MODEL>",
  description="Implement task #<id>",
  prompt="""
Please implement the following task.

Invoke the key-guidelines skill using the Skill tool: Skill("key-guidelines")

## Task Information
- ID: <id>
- Title: <title>
- Body: <body>

## Existing Branch/PR (if any)
- Branch: <existing-branch-name or "none">
- PR: <existing-PR-URL or "none">

If Branch or PR values above are set (not "none"), use them to resume work on the
existing branch and PR rather than creating new ones (as described in Step 2 below).

## Steps

Follow these steps to implement the task:

### 1. Update Task to In Progress

```bash
agkan task update <id> status in_progress

2. Check for Existing Branch/PR

The "Existing Branch/PR" values above come from the task record. Use them as follows:

Case A — Branch is not "none":

Check out the existing branch:

git fetch origin
git checkout <existing-branch-name>

Then check for conflicts with the default branch:

DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
git merge-base --is-ancestor origin/$DEFAULT_BRANCH HEAD

If this check fails (exit code non-zero), the branch has diverged and there may be conflicts. Surface a clear error and stop:

ERROR: Branch '<existing-branch-name>' has conflicts with '$DEFAULT_BRANCH'.
Please resolve the conflicts manually before resuming this task.

If no conflicts are detected, continue from Step 4 (skip Step 3, as the branch is already recorded in the task).

Case B — Branch is "none" (null in the task record):

Generate a branch name from the task ID and title. Use the following naming convention:

If the task has a bug or security tag → prefix fix/
Otherwise → prefix feat/
Format: <prefix>/<id>-<title-slug> (e.g., feat/42-add-login-page)

DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
git fetch origin
git checkout -b <branch-name> origin/$DEFAULT_BRANCH

Then continue to Step 3.

3. Write Branch Name to Task

agkan task update <id> --branch <branch-name>

This stores the branch as a first-class column on the task record so subsequent skill executions can resume work on the correct branch.

4. Implementation

Implement according to the task content.

Refer to /key-guidelines during implementation to maintain code quality.

5. Commit and Push

Stage files by specifying them explicitly. Do not use git add -A as it risks including unintended files such as .env or credentials.

git add <file1> <file2> ...
git commit -m "<commit message>"
git push -u origin <branch-name>

Note: Do not use git add -A or git add .. Files containing .env, credentials.*, or secrets may be committed unintentionally.

After push, verify it succeeded before proceeding to Step 6:

git ls-remote --heads origin <branch-name>

If push failed (empty output or non-zero exit code), record the error in the task body and do NOT proceed to PR creation. Leave the task as in_progress.

Recovery: If interrupted during Steps 4–7

If an error, permission denial, or user interruption occurs during implementation (Step 4), commit/push (Step 5), or PR creation (Step 6):

Do NOT update the task status to review
Record what happened in the task body
Leave the task as in_progress — complete the remaining steps before re-evaluating

6. Create PR

MANDATORY: PR creation after a successful push is required and MUST NOT be skipped. This step must complete before advancing to Steps 7 and 8. Skipping PR creation for any reason other than an existing PR: label (Case A below) is forbidden — including when approaching context limits.

If a PR: label was found in the task body (Step 2, Case A), skip PR creation — the existing PR will be updated automatically when commits are pushed to the branch.

Otherwise, create a new PR:

gh pr create --title "<title>" --body "<body>"

7. Add PR Information to Task

If a PR: label was already present in the task body (Step 2, Case A), skip this step.

Otherwise, record the newly created PR URL:

# First, retrieve the existing body
agkan task get <id> --json
# Then update by concatenating existing body with PR URL
agkan task update <id> body "<existing body>\n\nPR: <PR URL>"
# Also store as metadata so the board detail panel can display it
agkan task meta set <id> pr <PR URL>

8. Update Task to Review

Only execute this step if implementation succeeded — specifically, if ALL of the following conditions are met:

Implementation succeeded means ALL of the following:

At least one git commit was executed in this session (verify with git log --oneline -1)
Actual code/file changes were committed (not just task management operations)
git push completed without errors
PR was created or already exists

Scope note: The interruption guard below applies only to this status transition decision — not to Steps 4–7. If a confirmation or interruption occurred during implementation and has since been resolved, complete Steps 5–6 before evaluating the guard below.

The following do NOT count as implementation:

agkan task comment add (comment additions only)
agkan task update --body / --file (body/metadata updates only)
Discussion or planning without code commits

Before updating to review, verify a commit was made:

git log --oneline -1

If no commits were made in this session, do NOT update the status to review. Leave the task as in_progress.

If a critical error occurred (e.g., git push failed, PR creation failed, permission denied), do NOT update the status to review. Leave the task as in_progress and record the error details in the task body:

# On error: record what went wrong in the task body (optional but recommended)
agkan task get <id> --json
agkan task update <id> body "<existing body>\n\nError: <error description>"
# Do NOT run: agkan task update <id> status review

If an unresolved interruption remains at this point (e.g., push or PR creation in Steps 5–6 could not complete, a tool use is still blocked, or the skill is still awaiting user clarification), do NOT update the status to review. Leave the task as in_progress:

# When an unresolved interruption prevents completion: do NOT advance to review
# Resolve the interruption, complete Steps 5–6, then re-evaluate
# Do NOT run: agkan task update <id> status review

review status means implementation is fully complete — a PR has been successfully created and is awaiting human review. It does not mean "paused waiting for user input".

If only task management operations were performed (comments, body updates, no commits), do NOT update the status to review. Leave the task as in_progress.

If implementation succeeded (commits were made and pushed, PR created, no unresolved interruptions), update to review:

agkan task update <id> status review

Confirm the update succeeded:

agkan task get <id> --json

Verify that the status is review. If it is still in_progress, retry the update command.

Important Notes

Do not mark task as done before PR is merged (mark as done after PR review and merge)
Step 8 (status → review) must only be executed when implementation succeeded — do not update to review if a critical error occurred
Step 8 (status → review) requires at least one git commit to have been made — task management operations alone (comments, body updates) do NOT qualify as implementation
If a critical error occurs (git push failure, PR creation failure, permission error), keep the task as in_progress and record the error
If only task management operations were performed (no commits), keep the task as in_progress

Effort

Thoroughness hint: <RUN_EFFORT> """ )


### 7. Verify task status after sub-agent completes

After the sub-agent completes, check whether the task has been moved out of `in_progress`:

```bash
agkan task get <id> --json

If the status is still in_progress, determine whether the sub-agent encountered a critical error (git push failure, PR creation failure, permission error). Check the task body for any recorded error messages.

If a critical error occurred: Do NOT update to review. Leave the task as in_progress so the issue can be resolved manually.
If only task management operations were performed (comment additions, body updates, discussion — no actual commits): Do NOT update to review. Leave the task as in_progress.
If implementation succeeded (at least one git commit was made and pushed, PR created) but the sub-agent forgot to update the status, verify with git log --oneline -1 on the task's branch and update manually only if a commit exists:

# Verify a commit was actually made before marking review
git log --oneline -1
# Only if a commit is confirmed:
agkan task update <id> status review

The following do NOT qualify as implementation success:

agkan task comment add (comment additions only)
agkan task update --body / --file (body/metadata updates only)
Discussion or planning without code commits

8. Handle interruptions, then ALWAYS re-fetch and continue

After confirming the task status, there may be interruptions before you can proceed:

Interruption types and how to handle them

Interruption	How to handle	Then...
IDE diagnostic (linter, type error, etc.)	Fix the issue immediately	Resume step 8
User question about the current task	Answer, then fix if needed	Resume step 8
User explicitly says "stop" / "exit"	Stop the workflow	End session

IDE diagnostics (e.g., <new-diagnostics> in system-reminder) are part of the current task's implementation — not a reason to end the workflow. Fix them and continue.

After handling any interruption, always ask yourself:

"Am I in the middle of an agkan-run workflow? If yes, go back to step 8."

Re-fetch the task list to pick up any newly added ready tasks:

agkan task list --status ready --json

If there are no termination instructions from the user and ready tasks exist (including newly added ones), select the next task and repeat from step 3 of the workflow.

If no ready tasks remain, end the session.

Loop Structure

START
  ↓
git pull (default branch) & get ready tasks
  ↓
No tasks? → END SESSION
  ↓
Select highest priority task (skip will-do-later)
  ↓
Check blockers → blocked? → select different task
  ↓
Update status: in_progress
  ↓
Launch sub-agent to implement & create PR
  ↓
Sub-agent done?
  ↓
Interruption occurred? (diagnostic, user question)
  Yes → Handle it → RETURN HERE
  No  ↓
Re-fetch task list  ←──────────────────────────┐
  ↓                                              │
Ready tasks exist AND no stop instruction? ─Yes─┘
  ↓ No
END SESSION

Red flags — you are breaking the loop:

Sub-agent completed, you fixed a diagnostic, then stopped
Sub-agent completed, user asked a question, you answered, then stopped
You forgot to re-fetch the task list after any action

All of these mean: Go back to step 7. Re-fetch the task list.

Priority Determination Flow

Todo task list
    ↓
Sort by priority (Critical → High → Medium → Low)
    ↓
Multiple tasks with same priority?
   Yes → Sort by tag priority (bug → security → ... → docs)
   No  → Select top task
    ↓
Select 1 task and start work

Tag Priority List

See the canonical definition in agkan/SKILL.md (Tag Priority section).

Notes

Always select only 1 task (do not start multiple tasks simultaneously)
If no tasks exist, end the session
Do not mark task as done before PR merge (mark as done after PR review and merge)
Never stop mid-workflow due to interruptions — handle them and resume
review status is exclusively for tasks where implementation is fully complete and a PR is awaiting human review — never set review when waiting for user input or when execution was interrupted mid-task