feat(workflow): extract reusable dev-workflow commands

tools/dev-workflow-v2/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "dev-workflow-v2",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "Event-sourced workflow state machine for structured task lifecycle"
 }

tools/dev-workflow-v2/README.md

@@ -30,7 +30,31 @@ Analyzes parallel work streams across active PRDs, recommends a task from an idl
 
 Renames the worktree branch to match the issue, reads the issue details, initializes the workflow state machine, and begins the IMPLEMENTING state.
 
-### 3. Workflow (internal)
+### 3. Code review
+
+```bash
+/dev-workflow-v2:code-review
+```
+
+Runs the reusable automated review bundle for the current branch and writes reports under `reviews/<branch-name>/`.
+
+### 4. List review threads
+
+```bash
+/dev-workflow-v2:list-review-threads
+```
+
+Lists unresolved review threads for the current PR in a structured, human-friendly format.
+
+### 5. Create PR
+
+```bash
+/dev-workflow-v2:create-pr
+```
+
+Pushes the current branch and creates a PR using the repo's standard title/body structure.
+
+### 6. Workflow (internal)
 
 ```bash
 /dev-workflow-v2:workflow <command>

tools/dev-workflow-v2/commands/code-review.md

@@ -0,0 +1,45 @@
+# code-review
+
+Run the reusable automated review bundle for the current branch.
+
+## Usage
+
+```bash
+/dev-workflow-v2:code-review
+```
+
+## Instructions
+
+1. Determine the current branch name: `git branch --show-current`
+1. Determine changed files against the merge base with `main`: `git diff --name-only $(git merge-base HEAD main)..HEAD`
+1. If no files changed, report that no review is needed and stop.
+1. Create the review report directory: `reviews/<branch-name>/`
+1. Build prompts for these three agents, each with the changed files list and its report path:
+   - `architecture-review` → `reviews/<branch-name>/architecture-review.md`
+   - `code-review` → `reviews/<branch-name>/code-review.md`
+   - `bug-scanner` → `reviews/<branch-name>/bug-scanner.md`
+1. Spawn those three agents in parallel.
+1. Wait for all agents to finish, parse each JSON verdict, and return a concise summary containing:
+   - changed files reviewed
+   - report directory
+   - each agent verdict
+   - overall PASS/FAIL
+
+## Prompt Format
+
+Each agent prompt must use this structure:
+
+```text
+Files to Review:
+- path/to/file.ts
+- path/to/other-file.ts
+
+Report Path: reviews/<branch-name>/<agent-name>.md
+```
+
+## Scope
+
+- This command only runs the reusable review bundle.
+- Do not run `task-check` here.
+- Do not record workflow state here.
+- Do not transition workflow state here.

tools/dev-workflow-v2/commands/create-pr.md

@@ -0,0 +1,65 @@
+# create-pr
+
+Push the current branch and create a PR using the standard repo format.
+
+## Usage
+
+```bash
+/dev-workflow-v2:create-pr
+```
+
+## Instructions
+
+1. Read the current branch name: `git branch --show-current`
+1. Fail if the current branch is `main`.
+1. Extract the GitHub issue number from the branch name pattern `issue-<N>-...`
+   - If no issue number can be inferred, stop and tell the user the command requires an issue-based branch name.
+1. Get a GitHub token: `gh auth token`
+1. Check whether a PR already exists for the current branch with `gh pr view --json number,url`
+   - Run the command as `GITHUB_TOKEN=<token> gh pr view ...`
+   - If a PR already exists, report the PR number and URL, then stop without updating it.
+1. Read the issue title and body with `GITHUB_TOKEN=<token> gh issue view <issue-number> --json title,body`
+1. Inspect the actual branch changes before drafting the PR:
+   - `git log --oneline $(git merge-base HEAD main)..HEAD`
+   - `git diff --stat $(git merge-base HEAD main)..HEAD`
+1. Draft the PR title in this format:
+
+```text
+<type>(<scope>): <implemented summary> (#<issue-number>)
+```
+
+1. Draft the PR body using the issue as source context and the branch diff as source truth. Do **not** copy the full issue body verbatim. Rewrite it into this structure:
+
+```md
+Closes #<issue-number>
+
+## Summary
+- <2-4 bullets describing the actual implemented changes>
+
+## Context
+<1 short paragraph explaining the problem and why this PR exists>
+
+## Traceability
+- PRD: <path or —>
+- PRD Section: <section refs or —>
+- Dependencies: <dependencies or omit if none>
+
+## Verification
+~~~bash
+<verification commands from the issue, preserved when present>
+~~~
+```
+
+1. Push the branch: `git push -u origin <branch-name>`
+1. Create the PR with `GITHUB_TOKEN=<token> gh pr create --title "<title>" --body "$(cat <<'EOF'
+<body>
+EOF
+)"`
+1. Return the created PR number and URL.
+
+## Scope
+
+- This command owns the push + PR creation flow.
+- Use the issue for intent, but summarize the actual diff in `## Summary`.
+- Do not copy the full issue body into the PR description.
+- Do not record workflow state here.

tools/dev-workflow-v2/commands/list-review-threads.md

@@ -0,0 +1,44 @@
+# list-review-threads
+
+List unresolved review threads for the current PR in a structured format.
+
+## Usage
+
+```bash
+/dev-workflow-v2:list-review-threads
+```
+
+## Instructions
+
+1. Read the current branch name: `git branch --show-current`
+2. Get a GitHub token: `gh auth token`
+3. Resolve the PR for the current branch with `gh pr view --json number,url,reviewThreads`
+   - Run the command as `GITHUB_TOKEN=<token> gh pr view ...`
+   - If no PR exists for the current branch, report that and stop.
+4. Filter to unresolved review threads only.
+5. Group the unresolved threads by file path. Use `no file` for threads without a path.
+6. For each unresolved thread, report:
+   - thread id
+   - file path
+   - line number if present
+   - comment authors in order
+   - the latest comment body as the primary summary
+7. Return a concise structured report with this order:
+
+```text
+PR: #<number> <url>
+Unresolved threads: <count>
+
+## <file path or "no file">
+- Thread: <id>
+  Line: <line or —>
+  Authors: <author1>, <author2>
+  Latest comment: <summary>
+```
+
+## Scope
+
+- This command only lists current unresolved review threads.
+- Do not reply to threads.
+- Do not resolve threads.
+- Do not record workflow state here.

tools/dev-workflow-v2/states/checking_feedback.md

@@ -2,11 +2,12 @@
 
 You are checking the PR for review feedback from humans and bots.
 
-Feedback is **automatically fetched** on entry to this state. The workflow queries `gh pr view --json reviewThreads`, filters unresolved threads, and records the result as either feedback-clean or feedback-exists with an unresolved count.
+Feedback is **automatically fetched** on entry to this state. The workflow records either feedback-clean or feedback-exists with an unresolved count. Run `/dev-workflow-v2:list-review-threads` to inspect the current unresolved threads in a structured format before deciding what to do next.
 
 ## TODO
 
 - [ ] Review the auto-fetched feedback result (check workflow state for feedbackClean / feedbackUnresolvedCount)
+- [ ] Run `/dev-workflow-v2:list-review-threads` if feedback exists or a structured review summary is needed
 - [ ] If clean — transition to REFLECTING: `/dev-workflow-v2:workflow transition REFLECTING`
 - [ ] If feedback exists — transition to ADDRESSING_FEEDBACK: `/dev-workflow-v2:workflow transition ADDRESSING_FEEDBACK`
 

tools/dev-workflow-v2/states/reviewing.md

@@ -4,12 +4,9 @@ You are running automated code review by spawning review agents in parallel.
 
 ## TODO
 
-- [ ] Determine changed files: `git diff --name-only $(git merge-base HEAD main)..HEAD`
-- [ ] Create report directory: `reviews/<branch-name>/`
-- [ ] Build agent prompts (see Prompt Construction below)
-- [ ] Spawn `architecture-review`, `code-review`, and `bug-scanner` agents in parallel using the Agent tool
+- [ ] Run `/dev-workflow-v2:code-review` to review the current branch and write reports to `reviews/<branch-name>/`
 - [ ] If `taskCheckPassed` is false AND a GitHub issue is recorded: also spawn `task-check` agent (see Conditional Task Check below)
-- [ ] Wait for all agents to complete and parse each agent's JSON verdict
+- [ ] Parse the `/dev-workflow-v2:code-review` verdicts for `architecture-review`, `code-review`, and `bug-scanner`
 - [ ] If task-check returned PASS: `/dev-workflow-v2:workflow record-task-check-passed`
 - [ ] Record each agent's verdict individually:
   - `/dev-workflow-v2:workflow record-architecture-review-passed` or `record-architecture-review-failed`
@@ -18,30 +15,13 @@ You are running automated code review by spawning review agents in parallel.
 - [ ] If all passed: `/dev-workflow-v2:workflow transition SUBMITTING_PR`
 - [ ] If any failed: fix the issues found in the reports, commit, then `/dev-workflow-v2:workflow transition IMPLEMENTING`
 
-## Prompt Construction
-
-Each review agent prompt must include:
-
-1. **Files to Review** — the changed files list from step 1
-2. **Report Path** — `reviews/<branch-name>/<agent-name>.md`
-
-Example prompt for spawning via the Agent tool with `subagent_type: "code-review"`:
-
-```text
-Files to Review:
-- src/foo.ts
-- src/bar.ts
-
-Report Path: reviews/feat-my-feature/code-review.md
-```
-
 ## Conditional Task Check
 
 Check the workflow state's `taskCheckPassed` flag. If it is already `true`, skip the task-check agent (it passed in a previous review cycle).
 
 If `taskCheckPassed` is `false` and a GitHub issue is recorded, spawn the task-check agent with `subagent_type: "task-check"`. Its prompt must include:
 
-1. **Files to Review** — same changed files list
+1. **Files to Review** — the current branch's changed files
 2. **Report Path** — `reviews/<branch-name>/task-check.md`
 3. **Task Details** — the GitHub issue body (fetch via `gh issue view <number>`)
 

tools/dev-workflow-v2/states/submitting_pr.md

@@ -4,8 +4,7 @@ You are creating or updating the pull request.
 
 ## TODO
 
-- [ ] Push the branch: `git push -u origin <branch-name>`
-- [ ] Create the PR: `gh pr create --title "<title>" --body "<description>"` (or update existing)
+- [ ] Run `/dev-workflow-v2:create-pr` to push the current branch and create the PR with the standard repo format
 - [ ] Record the PR: `/dev-workflow-v2:workflow record-pr <PR_NUMBER> [PR_URL]`
 - [ ] Transition to AWAITING_CI: `/dev-workflow-v2:workflow transition AWAITING_CI`