agkan-subtask-direct

Overview

A workflow to directly implement a selected task without creating a branch or PR and mark it as complete.

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 '{}')
REVIEW_MODEL=$(echo "$CONFIG" | jq -r '.config.models.review.model // empty')
REVIEW_EFFORT=$(echo "$CONFIG" | jq -r '.config.models.review.effort // "high"')

1. Update Task to In Progress

agkan task update <id> status in_progress

2. Check for Existing Branch

Read the branch from the task's first-class branch column:

BRANCH=$(agkan task get <id> --json | jq -r '.task.branch // empty')

Case A — Branch is non-null:

Check out the existing branch:

git fetch origin
git checkout "$BRANCH"

All subsequent commits and pushes must target this branch.

Case B — Branch is null:

Generate a branch name from the task ID and title. Use the following naming convention:

If the task has a bug or security tag → prefix fix/
Otherwise → prefix feat/
Format: <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

Persist the generated branch name to the task:

agkan task update <id> --branch <branch-name>

3. Implementation

Implement according to the task requirements.

Refer to /key-guidelines during implementation to maintain code quality.

4. Static Analysis / Lint Check (if applicable)

If the project has a static analysis or lint tool configured, run it before committing:

TypeScript: npx tsc --noEmit
ESLint: npx eslint .
RuboCop: bundle exec rubocop
Ruff (Python): ruff check .
Other: run the appropriate tool for the project language

Fix any errors before proceeding.

5. Commit

Committing and pushing the implementation is required and must not be skipped. This step must complete before advancing to Steps 7 and 8. Do not skip the commit for any reason, including approaching context limits or after running tests/lint.

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>"
# If a branch was checked out from the task's branch column, push to it; otherwise push to current branch
git push -u origin <branch-name-or-current>

Note: Do not use git add -A or git add .. Files containing .env, credentials.*, or secrets may be committed unintentionally.

After push, verify it succeeded before proceeding to Step 7:

git ls-remote --heads origin <branch-name-or-current>

If push failed (empty output or non-zero exit code), record the error in the task body and do NOT proceed to Step 7. Leave the task as in_progress.

Recovery: If interrupted during Steps 3–5

If an error, permission denial, or user interruption occurs during implementation (Step 3), lint check (Step 4), or commit/push (Step 5):

Do NOT update the task status to done
Record what happened in the task body
Leave the task as in_progress — complete the remaining steps before re-evaluating

6. Update Checkboxes

If the task body contains - [ ] checklist items, update items completed during this implementation.

Retrieve the current body:

TASK_JSON=$(agkan task get <id> --json)
CURRENT_BODY=$(echo "$TASK_JSON" | jq -r '.task.body // empty')

Check whether the body contains unchecked items. If none found, skip this step:

echo "$CURRENT_BODY" | grep -q -- '- \[ \]' || echo "No unchecked items — skipping"

For each item completed in this implementation, replace its - [ ] 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 - [ ].

7. Self-Review

Avoid duplicating a review already completed with equivalent scope. Otherwise, use an independent review when available, or perform the same checks directly.

Before updating the task status, perform a self-review of the implementation using a general-purpose sub-agent. Substitute <REVIEW_MODEL> and <REVIEW_EFFORT> with the values fetched in Step 0:

Delegate(
  role="general-purpose",
  model="<REVIEW_MODEL>",
  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 HEAD~1 HEAD` to see them) against the original plan and coding standards. Check for correctness, security issues, and code quality.

Report all issues found, each annotated with a severity (critical/major/minor) and a
confidence level. Do not filter by severity in this report — filtering, if needed, is
the responsibility of the caller reading this review, not this step.

## Effort / Thoroughness
Thoroughness/effort level: <REVIEW_EFFORT>
- low: Quick pass. Focus on obvious correctness and security issues.
- medium: Standard review. Check correctness, security, and code quality.
- high: Deep review. Additionally examine edge cases, test coverage, and architectural fit.
- xhigh: Recommended default for coding/agentic work; maximize correctness and edge-case coverage.
- max: Reserve for the highest-stakes or most complex tasks.
"""
)

If the code reviewer identifies critical issues, fix them and commit the fixes before proceeding.

8. Update task to done

Only execute this step if implementation succeeded — specifically, if ALL of the following conditions are met:

Scope note: The interruption guard below applies only to this status transition decision — not to Steps 3–6. If a confirmation or interruption occurred during implementation and has since been resolved, complete Steps 3–6 before evaluating the guard below.

Implementation succeeded means ALL of the following:

At least one git commit was executed in this session (verify with git log --oneline -1)
Actual code/file changes were committed (not just task management operations)
git push completed without errors

The following do NOT count as implementation:

agkan task comment add (comment additions only)
agkan task update --body / --file (body/metadata updates only)
Discussion or planning without code changes

Before updating to done, verify a commit was made:

git log --oneline -1

If no commits were made in this session (output is empty or only shows pre-existing commits), do NOT update the status to done. Surface the failure by appending an error line to the task body, then leave the task as in_progress:

# Surface silent failure: no commit was made
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: Skill reached end without a commit. Implementation was not completed — files may remain uncommitted in the working tree. Manual intervention required.
BODY
agkan task update <id> --file /tmp/agkan_body_$$.md
# Do NOT run: agkan task update <id> status done

If a critical error occurred (e.g., git push failed, permission denied, commit failed), do NOT update the status to done. 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 done

If only task management operations were performed (comments, body updates, no commits), do NOT update the status to done. Leave the task as in_progress.

If implementation succeeded (commits were made and pushed), update to done:

agkan task update <id> status done

Important Notes

Branch creation: check out an existing branch if .task.branch is non-null; otherwise auto-generate a name and create the branch, then persist it via agkan task update <id> --branch <name>
Do not create a PR
The condition for moving a task to done (commit made, no critical error) is defined in full in Step 8 above — see that step for the exact rule; it is not repeated here
This skill is used after task selection (task selection is done with the agkan-run-direct skill)