agkan-run-direct

Overview

A workflow to select the highest priority ready task from agkan, implement it directly without creating a branch or PR, and mark it as done.

Workflow

0. Fetch Config

Retrieve the agkan configuration and extract model/effort settings for the sub-agent:

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 // "high"')

These values are passed to the sub-agent in Step 6.

1. Update Branch

This skill is designed to commit directly to the current branch (default branch or topic branch). Therefore, only execute git pull -p (unlike agkan-run, there is no need to create a new branch from the default branch).

• When running on a topic branch: implement directly on the current branch
• When starting from the default branch: get the default branch name dynamically and execute checkout + pull beforehand if necessary

# Get the default branch name dynamically
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)
# Then pull
git pull -p

2. Get Ready Tasks

agkan task list --status ready --json

3. Select One High-Priority Task

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

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

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

Critical > High > Medium > Low

Tags (used when priority is the same):

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

When there are subtasks or blocker tasks Prioritize the target subtasks or blocker tasks (using the same importance and tag criteria)

4. Check for Blockers

agkan task block list <id> --json

If incomplete tasks exist in blockedBy, do not select that task; instead, select a different task or process the blocker tasks first.

5. Update Task Status to in_progress

agkan task update <id> status in_progress

6. Implementation and Completion

Use the Task tool (general-purpose sub-agent) to implement.

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>

## Procedure
Invoke the agkan-subtask-direct skill using the Skill tool: Skill("agkan-subtask-direct")

## Error Handling
If a critical error occurs during implementation (git push failure, commit failure,
permission denied, etc.), do NOT update the task status to done. Leave the task as
`in_progress` and record the error in the task body:

agkan task get <id> --json agkan task update <id> body "<existing body>\n\nError: <error description>"

Only update to done if implementation and all commits/pushes succeeded.

## Effort
Thoroughness level for this session: <RUN_EFFORT>
- low: Implement quickly with minimal exploration; prefer direct solutions
- medium: Balance thoroughness with speed; standard implementation quality
- high: Be thorough; explore edge cases, add tests, review carefully
- xhigh: Recommended default for coding/agentic work; maximize correctness and edge-case coverage
- max: Reserve for the highest-stakes or most complex tasks
"""
)

7. Verify Task Status After Sub-Agent Completes

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

agkan task get <id> --json

Scope note: The interruption guard below applies **only to this status
transition decision** — not to the sub-agent's implementation steps. If the
sub-agent was interrupted during implementation and the interruption has since
been resolved, ensure the sub-agent completes its implementation steps (commit,
push) before evaluating the guard below.

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

• If a critical error occurred: Do NOT update to done. 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 done. Leave the task as in_progress.
• If the task body contains an error about no commit being made (silent failure surfaced by the sub-agent): Do NOT update to done. Leave the task as in_progress.
• If implementation succeeded (at least one git commit was made and pushed) but the sub-agent forgot to update the status, verify with git log --oneline -1 and update manually only if a commit exists:

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

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. Re-fetch Task List and Continue or End Session

After the sub-agent completes, re-fetch the task list to pick up any newly added ready tasks:

agkan task list --status ready --json

If there is no instruction to end from the user and ready tasks exist (including newly added ones), select the next task and repeat from step 3 of the same workflow.

If no ready tasks remain, end the session.

Priority Determination Flow

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

Tag Priority List

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

Important Notes

• Always select only one task (do not work on multiple tasks simultaneously)
• If no tasks exist, end the session
• Do not create branches or PRs (commit directly to the current branch)
• Task status update to done and static analysis checks are handled inside the sub-agent (agkan-subtask-direct), not in the main thread