diff --git a/tools/dev-workflow-v2/.claude-plugin/plugin.json b/tools/dev-workflow-v2/.claude-plugin/plugin.json index f87d3e881..aa7feab4a 100644 --- a/tools/dev-workflow-v2/.claude-plugin/plugin.json +++ b/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" } diff --git a/tools/dev-workflow-v2/README.md b/tools/dev-workflow-v2/README.md index 808640257..a999cde5b 100644 --- a/tools/dev-workflow-v2/README.md +++ b/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//`. + +### 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 diff --git a/tools/dev-workflow-v2/commands/code-review.md b/tools/dev-workflow-v2/commands/code-review.md new file mode 100644 index 000000000..30a4114ef --- /dev/null +++ b/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//` +1. Build prompts for these three agents, each with the changed files list and its report path: + - `architecture-review` → `reviews//architecture-review.md` + - `code-review` → `reviews//code-review.md` + - `bug-scanner` → `reviews//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//.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. diff --git a/tools/dev-workflow-v2/commands/create-pr.md b/tools/dev-workflow-v2/commands/create-pr.md new file mode 100644 index 000000000..0569d5df6 --- /dev/null +++ b/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--...` + - 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= 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= gh issue view --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 +(): (#) +``` + +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 # + +## Summary +- <2-4 bullets describing the actual implemented changes> + +## Context +<1 short paragraph explaining the problem and why this PR exists> + +## Traceability +- PRD: +- PRD Section:
+- Dependencies: + +## Verification +~~~bash + +~~~ +``` + +1. Push the branch: `git push -u origin ` +1. Create the PR with `GITHUB_TOKEN= gh pr create --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. diff --git a/tools/dev-workflow-v2/commands/list-review-threads.md b/tools/dev-workflow-v2/commands/list-review-threads.md new file mode 100644 index 000000000..d0663e903 --- /dev/null +++ b/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. diff --git a/tools/dev-workflow-v2/states/checking_feedback.md b/tools/dev-workflow-v2/states/checking_feedback.md index 3b1f40bda..422bb5b68 100644 --- a/tools/dev-workflow-v2/states/checking_feedback.md +++ b/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` diff --git a/tools/dev-workflow-v2/states/reviewing.md b/tools/dev-workflow-v2/states/reviewing.md index 1e2e27c33..c2c7796c7 100644 --- a/tools/dev-workflow-v2/states/reviewing.md +++ b/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>`) diff --git a/tools/dev-workflow-v2/states/submitting_pr.md b/tools/dev-workflow-v2/states/submitting_pr.md index 08fe969dc..8a53af58b 100644 --- a/tools/dev-workflow-v2/states/submitting_pr.md +++ b/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`