agkan-review

agkan-review

Overview

Workflow to retrieve tasks with Review status in agkan, check the merge/close status of GitHub PRs, and automatically update their status.

---

Workflow

Primary: Run the bundled script

Run the bundled review.sh script to process all review tasks in one command. Resolve this skill's directory from its loaded SKILL.md path or the environment's skill catalog. Set BASE_DIR to that directory and use it to resolve the script path:

bash "$BASE_DIR/review.sh"

BASE_DIR is the directory containing this skill's SKILL.md and review.sh, regardless of the agent or installation location.

The script:

1. Fetches all tasks with --status review
2. Extracts the PR URL from each task body (PR: <URL>) or metadata (pr key)
3. Calls gh pr view <URL> --json state,mergedAt for each PR
4. Updates task status to done (MERGED) or closed (CLOSED without merge), skips OPEN
5. Adds a comment recording the reason and timestamp
6. Prints a summary: done: X, closed: X, skipped (OPEN): X, no PR: X

If repeated execution needs an allowlist, use the executing environment's supported permission settings for this script, following its approval rules.

---

Fallback: Manual step-by-step workflow

Use the manual steps below if the script is unavailable or you need to process tasks individually.

1. Retrieve Review tasks

agkan task list --status review --json

2. Initialize summary counters

Before processing tasks, initialize the following counters to track results:

• done_count = 0
• closed_count = 0
• skipped_open_count = 0
• no_pr_count = 0

3. Confirm PR URL for each task

First, extract the PR URL from the task body in the format PR: <URL>.

If no URL is found in the body, check the task metadata as a fallback:

agkan task meta list <id>

Use the value of the pr key if present.

If no URL is found in either the body or metadata, increment no_pr_count, skip the task and output a message indicating manual verification is needed.

4. Check PR status on GitHub

gh pr view <PR URL> --json state,mergedAt

Field	Meaning
state	OPEN / CLOSED / MERGED
mergedAt	Merge date/time (null if not merged)

5. Move status based on PR status

PR State	agkan Status	Command	Counter
MERGED	done	agkan task update <id> status done	Increment done_count
CLOSED (mergedAt is null)	closed	agkan task update <id> status closed	Increment closed_count
OPEN	No change	Skip (still under review)	Increment skipped_open_count

6. Add comment recording the reason for status change

After updating status to done or closed, record the merge date/time and reason:

agkan task comment add <id> "<comment>"

Comment format by status:

Status	Comment Example
done	Merged at <mergedAt>. PR was merged and task is complete.
closed	PR was closed without merging. Task moved to closed.

7. Display summary after all tasks are processed

done: <done_count>, closed: <closed_count>, skipped (OPEN): <skipped_open_count>, no PR: <no_pr_count>

---

Decision Flow

Retrieve all Review tasks
    ↓
Initialize counters (done=0, closed=0, skipped_open=0, no_pr=0)
    ↓
Repeat for each task
    ↓
Does the body contain "PR: <URL>"?
   Yes → Use that URL
   No  → Check metadata: agkan task meta list <id>
            Does metadata contain "pr" key?
               Yes → Use that URL
               No  → Increment no_pr_count → Skip (output message prompting manual verification)
    ↓
Check PR status
    ↓
What is the PR state?
   MERGED  → Move to done → Increment done_count → Add comment with mergedAt timestamp
   CLOSED  → Move to closed → Increment closed_count → Add comment noting PR closed without merge
   OPEN    → Skip (waiting for review) → Increment skipped_open_count
    ↓
Move to next task (repeat until all tasks are processed)
    ↓
Display summary: done: X, closed: X, skipped (OPEN): X, no PR: X

---

Notes

• PR URL is first looked up in the task body in the format PR: <URL>
• If not found in the body, the pr key from agkan task meta list <id> is used as a fallback
• If PR URL is not found in either location, prompt for manual verification (skip task)
• done means successful completion, closed means suspended or withdrawn
• The gh command is required and will not work in environments where it is unavailable

---

Troubleshooting

grep: invalid option -- P on macOS

BSD grep (shipped with macOS) does not support the -P (Perl-compatible regex) flag. If you see this error, you are likely running an older version of review.sh that used grep -oP.

Symptom: PR URLs are not extracted from task bodies, and the script silently falls back to metadata lookup (which may also be empty), resulting in PR未設定 for tasks that do have a PR: <URL> line.

Fix: The current review.sh uses sed instead of grep -oP:

# Compatible with macOS (BSD) and Linux (GNU)
pr_url=$(echo "$body" | sed -n 's/.*PR: \(https:\/\/[^[:space:]]*\).*/\1/p' | head -1 || true)

If you are still seeing the error after updating, confirm you are running the latest version of the skill.