agkan-planning-subtask

Overview

A sub-workflow that reviews a single Backlog task in agkan, makes decisions on decomposition, Ready status movement, and deferral.

Agent Compatibility

Use the executing environment's available tools; these procedures apply across agents. Delegate(...) below is pseudocode, not a tool name: map it to the available sub-agent tool and supported arguments, using the indicated role and prompt. Wait for completion before continuing. If delegation is unavailable or disallowed, execute the same procedure in the current agent, preserving its scope and status checks. An empty model means inherit the current model (omit the model override). Honor an explicit model only when the environment supports it; never silently substitute a different model. Check this before changing task status; if unsupported, report the limitation and stop unless a later step defines a skip/recovery procedure. Pass effort through a supported setting, or retain it as prompt-level thoroughness guidance without claiming the runtime effort was changed. Resolve referenced skills from the environment's skill catalog or this installation's sibling directories. Pass a resolved accessible path or embed their instructions in the sub-agent prompt; do not assume a .claude/skills installation.

Workflow

0. Fetch Config

CONFIG=$(agkan config get --json 2>/dev/null || echo '{}')
PLANNING_MODEL=$(echo "$CONFIG" | jq -r '.config.models.planning.model // empty')
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 the environment's user-question tool, or ask directly in conversation, before proceeding
- Do NOT move to Ready until the question is resolved
- Record the question and the user's answer in the task body
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 a codebase-investigation sub-agent based on scope: for a single targeted lookup (e.g. finding one file or symbol), search directly; only delegate to a codebase-investigation sub-agent when the investigation spans multiple files, unfamiliar naming conventions, or broad codebase areas. Create the task list once investigation is complete, using a planning facility if available. Apply the config values fetched in Step 0 to the investigation:

Delegate(
  role="codebase investigation",
  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 investigation'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>

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-planning skill)

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