agkan-subtask
agkan-subtask
Overview
Workflow to implement a selected task on a new branch, create a PR, and move to review.
Workflow
1. Update Task to In Progress
agkan task update <id> --status in_progress
2. Check for Existing Branch/PR
Before creating a new branch, check for an existing branch in two places:
- Task metadata (primary source):
BRANCH=$(agkan task meta get <id> branch 2>/dev/null)
- Task body (fallback — only if metadata is empty):
agkan task get <id> --json
Parse the task body for the following labels:
Branch: <branch-name>
PR: <URL>
If $BRANCH from metadata is empty, parse the body for Branch: <branch-name> and use that value.
Case A — Branch found (via metadata or body label):
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 name is already recorded).
Case B — No branch label found:
Create a new branch. Branch name is generated from task ID and title (example: 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
# First, retrieve the existing body
agkan task get <id> --json
# Write body to tmp file and update using --file to preserve newlines
cat > /tmp/agkan_body_$$.md << 'BODY'
<existing body>
Branch: <branch-name>
BODY
agkan task update <id> --file /tmp/agkan_body_$$.md
# Also store as metadata so the board detail panel can display it
agkan task meta set <id> branch <branch-name>
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 -Aorgit add .. Files containing.env,credentials.*, or secrets may be committed unintentionally.
6. Create PR
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
# Write body to tmp file and update using --file to preserve newlines
cat > /tmp/agkan_body_$$.md << 'BODY'
<existing body>
PR: <PR URL>
BODY
agkan task update <id> --file /tmp/agkan_body_$$.md
# 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 git push (Step 5) and PR creation (Step 6) both completed without critical errors (permission errors, push failures, etc.).
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
# Write body to tmp file and update using --file to preserve newlines
cat > /tmp/agkan_body_$$.md << 'BODY'
<existing body>
Error: <error description>
BODY
agkan task update <id> --file /tmp/agkan_body_$$.md
# Do NOT run: agkan task update <id> --status review
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.
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
- If a critical error occurs (git push failure, PR creation failure, permission error), keep the task as
in_progressand record the error - This skill is used after task selection (task selection is done with
agkan-runskill)
More from gendosu/agkan-skills
agkan-planning-subtask
Use when reviewing a single backlog task to assess decomposition, implementation readiness, and priority ordering.
7agkan
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.
6agkan-review
Use when checking review tasks against GitHub PR status to automatically move them to done or closed.
6execute-subtask
[DEPRECATED] Use agkan-subtask instead. 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 done.
6execute-add
[DEPRECATED] Use agkan-add instead. Use when adding a new task to the backlog — collects title, body, tags, priority, and parent task, then creates it with agkan.
6agkan-run-direct
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.
6