Menu
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.
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.
Use when reviewing backlog tasks to assess decomposition, implementation readiness, and priority ordering before development begins.
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.
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.
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.
Use when checking review tasks against GitHub PR status to automatically move them to done or closed.
| name | agkan-subtask |
| description | 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. |
| user-invokable | false |
| metadata | {"context":"fork"} |
Workflow to implement a selected task on a new branch, create a PR, and move to review.
agkan task update <id> status in_progress
Read the branch from the task's first-class branch column:
TASK_JSON=$(agkan task get <id> --json)
BRANCH=$(echo "$TASK_JSON" | jq -r '.task.branch // empty')
Also parse the task body for a PR: label:
PR: <URL>
Case A — Branch is non-null:
Check out the existing branch:
git fetch origin
git checkout "$BRANCH"
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 null:
Generate a branch name from the task ID and title. Use the following naming convention:
bug or security tag → prefix fix/feat/<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.
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.
Implement according to the task content.
Refer to /key-guidelines during implementation to maintain code quality.
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 -Aorgit 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):
reviewin_progress — complete the remaining steps before re-evaluatingMANDATORY: PR creation after a successful push is required and MUST NOT be skipped. This step must complete before advancing to Steps 7 and 9. 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>"
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>
If the task body contains - [ ] checklist items, update items completed during this implementation.
TASK_JSON=$(agkan task get <id> --json)
CURRENT_BODY=$(echo "$TASK_JSON" | jq -r '.task.body // empty')
echo "$CURRENT_BODY" | grep -q -- '- \[ \]' || echo "No unchecked items — skipping"
- [ ] with - [x]. Write the updated body to a temp file and apply:cat > /tmp/agkan_checkbox_$$.md << 'BODY'
<updated body with completed items marked as - [x]>
BODY
agkan task update <id> --file /tmp/agkan_checkbox_$$.md
Only mark items that were actually completed in this session. Leave pending items as
- [ ].
Before updating the task status, perform a self-review of the implementation using the superpowers:code-reviewer sub-agent:
Agent(
subagent_type="superpowers:code-reviewer",
description="Self-review task #<id> implementation",
prompt="""Review the implementation of the following task.
Task #<id>: <title>
Task body:
<body>
Review the git changes (run `git diff origin/<default-branch>...HEAD` to see them) against the original plan and coding standards. Check for correctness, security issues, and code quality. Report critical issues that must be fixed before completing the task.
"""
)
If the code reviewer identifies critical issues, fix them, commit and push the fixes, before proceeding.
Only execute this step if implementation succeeded — specifically, if ALL of the following conditions are met:
Implementation succeeded means ALL of the following:
git commit was executed in this sessiongit push completed without errorsScope note: The interruption guard below applies only to this status transition decision — not to Steps 4–8. If a confirmation or interruption occurred during implementation and has since been resolved, complete Steps 5–7 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)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–7 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–7, 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 implementation succeeded, 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.
git commit to have been made — task management operations alone (comments, body updates) do NOT qualify as implementationin_progress and record the errorin_progress — do NOT advance to reviewreview status is exclusively for tasks where implementation is fully complete and a PR is awaiting human reviewagkan-run skill)