gendosu agkan-planning-subtask
Overview
A sub-workflow that reviews a single Backlog task in agkan, makes decisions on decomposition, Ready status movement, and deferral.
Workflow
0. Fetch Config
CONFIG=$(agkan config get --json 2>/dev/null || echo '{}')
PLANNING_MODEL=$(echo "$CONFIG" | jq -r '.config.models.planning.model // "sonnet"')
PLANNING_EFFORT=$(echo "$CONFIG" | jq -r '.config.models.planning.effort // "high"')
1. Content Review, Supplementation, and Task List Creation
- If task content is unclear, investigate and confirm details by examining the code
- If questions arise that cannot be resolved through code investigation alone:
- Use
AskUserQuestionto ask the user before proceeding - Do NOT move to Ready until the question is resolved
- Record the question and the user's answer in the task body
- Use
- Append the investigated content to the task description:
# First, retrieve the existing body
agkan task get <id> --json
# Then update by concatenating existing body with new content
agkan task update <id> --file /dev/stdin << 'EOF'
<existing body>
<additional content>
EOF
- If the task contains multiple pieces of work, organize the content and append it to the description in task list format:
When creating a task list, decide whether to investigate directly or delegate to the Explore subagent based on scope: for a single targeted lookup (e.g. finding one file or symbol), search directly; only delegate to the Explore subagent when the investigation spans multiple files, unfamiliar naming conventions, or broad codebase areas. Use Plan mode to create the task list once investigation is complete. Apply the config values fetched in Step 0 to the Explore call:
Model differences: Opus 5 = tends to over-delegate to subagents (the opposite of Opus 4.8), so handle simple investigation directly and reserve Explore delegation for broad, multi-file investigation only. Fable 5 = benefits from eager delegation, so when in doubt, delegate to Explore.
Agent(
subagent_type="Explore",
model="<PLANNING_MODEL>",
description="Investigate task #<id>",
prompt="""
Investigate the codebase to understand the following task before creating the task list.
## Task Information
- ID: <id>
- Title: <title>
- Body: <body>
## Search Breadth
Effort level: <PLANNING_EFFORT> (maps to the Explore agent's search breadth, not implementation thoroughness)
- low: quick — a single targeted lookup
- medium: medium — moderate exploration
- high: very thorough — search across multiple locations and naming conventions
- xhigh: very thorough, recommended default — search across multiple locations, naming conventions, and related files
- max: exhaustive — reserve for the highest-stakes or most complex investigations
"""
)
- [ ] Work item 1
- [ ] Work item 2
- [ ] Work item 3
After completing content review and creating the task list, write the planning results back to the task body. This step is required and must not be skipped.
# REQUIRED: Write planning results to task body
# Always execute this step regardless of whether content was changed
agkan task get <id> --json
# Then update with the full body including planning results
agkan task update <id> --file /dev/stdin << 'EOF'
<full updated body with planning results, scope, implementation approach, and task list>
EOF
2. Blocking Relationship Setup
During planning, identify dependencies between this task and other tasks, and register them formally.
# List tasks to find related tasks
agkan task list --json
# Check existing blocking relationships for this task
agkan task block list <id> --json
# Register: another task blocks this task (this task is blocked by <blocker-id>)
agkan task block add <blocker-id> <id>
# Register: this task blocks another task (this task blocks <other-id>)
agkan task block add <id> <other-id>
Register blocking relationships when:
- This task depends on another task that is not yet done (register as blocked)
- Another task cannot start until this task is done (register as blocker)
3. Task Decomposition Decision
Decomposition Granularity Standard: 1 Task = 1 PR = 1 Feature (Modification)
- Decompose so that when a PR is merged, that feature or modification is complete
- Do not divide tasks such that a PR merge results in an incomplete state
- Only split when multiple independent features or modifications are mixed in a single task
If a task contains scope exceeding the above standard, split it into sub-tasks:
# Create new tasks after splitting
# Use --parent to maintain the parent-child relationship with the original task
# This makes the task hierarchy visible in `agkan task list --tree`
agkan task add "<sub-task name>" "<details>" --parent <original-id>
# Close the original task as split (or update it)
agkan task update <id> --status closed
4. Ready/Deferral Decision (Decision Only — Do NOT Execute Yet)
Decide the outcome for this task. Do NOT run any agkan task update command yet.
Ready if all of the following conditions are met:
- Scope that can be implemented as a single PR
- Implementation approach is clear
- No unresolved questions that require user input
Blockers do not prevent moving to Ready. If planning is complete and the task would be executable once blockers are resolved, move it to Ready. The blocking relationships registered in Step 2 already capture the dependency — when the blocker task is done, this task can be picked up immediately.
Deferral if any of the following apply:
- Low impact on current priorities
- Resources or information are insufficient
- The task itself is not yet well-defined enough to implement
Record your decision (Ready or Deferral) and the reasoning. Proceed to Step 5.
5. Self-Review
Before executing any status change, verify all previous steps are complete:
- Step 1: Task body is updated with content review and task list
- Step 2: Blocking relationships are registered (or confirmed none exist)
- Step 3: Decomposition decision is made (split or keep as-is)
- Step 4: Decision is recorded (Ready or Deferral) with reasoning
- No unresolved questions remain
- Task scope matches 1 PR = 1 feature standard
If any item is unchecked, return to that step and complete it before proceeding.
6. Execute Status Change
Only after all self-review items are checked, execute the status change.
If Ready:
Determine priority and run:
agkan task update <id> --status ready --priority <value>
Priority values: critical / high / medium / low
Priority determination criteria:
| Value | Criteria |
|---|---|
critical |
Production failures, security issues, blockers for other tasks |
high |
Important features with near deadlines, bugs with significant user impact |
medium |
Normal feature additions, improvements (default) |
low |
Nice-to-have, work on if time permits |
If Deferral:
# Create the tag if it does not exist
agkan tag add "will-do-later"
# Attach the tag to the task
agkan tag attach <task-id> <tag-id-or-name>
Tag Priority
See the canonical definition in agkan/SKILL.md (Tag Priority section).
Tag attachment command:
# Create the tag if it does not exist
agkan tag add "<tag>"
# Attach the tag to the task
agkan tag attach <task-id> <tag-id-or-name>
Notes
- When decomposing tasks, inherit the content of the original task
- Move to Ready only for tasks that can be "started immediately"
- This skill is used after task selection (task selection is done by the
agkan-planningskill)
Scope Boundary
This skill does not implement tasks. Its sole responsibility is to review tasks and update their status in agkan. Do not do any of the following:
- Edit source code files
- Create or modify any files in the codebase (other than agkan task updates via CLI)
- Implement features, fixes, or any code changes described in the task
If a task is ready for implementation, move it to Ready status and stop. Implementation is handled by a separate workflow (agkan-run).