Improve Claude workflows (#211)

* Use unified review API for code review comments

Switch from posting individual inline comments and separate summary to
GitHub's Pull Request Review API. All comments now submit together as
a single review event, matching native GitHub review flow.

* Add review thread management and resolution

Enables Claude to maintain conversation continuity by resolving fixed
issues and replying to existing threads instead of creating duplicate
comments on subsequent reviews.

- Fetch existing review threads via GraphQL before each review
- Resolve threads when issues are fixed using resolveReviewThread
- Reply to existing threads when issues persist
- Only create new comment threads for genuinely new issues

* Add superpowers workflow to Claude agent

Guides Claude through brainstorming, planning, and implementation when
invoked via @claude mentions. Uses autonomous Socratic brainstorming,
writes temporary planning docs, completes full implementation, then
performs self-review at the end for efficiency.

Author: ghostwriternr

.github/workflows/claude-code-review.yml

@@ -92,17 +92,65 @@ jobs:
             d. What tests are needed?
             e. Does this need documentation updates?
 
-            ### 6. Execute Review
+            ### 6. Fetch Existing Review Threads
+
+            Before creating your review, fetch existing Claude review threads to enable thread continuity:
+
+            ```bash
+            # Get PR owner and repo name
+            OWNER=$(gh repo view --json owner --jq '.owner.login')
+            REPO=$(gh repo view --json name --jq '.name')
+
+            # Fetch all review threads
+            gh api graphql -f query='
+            query($owner: String!, $name: String!, $pr: Int!) {
+              repository(owner: $owner, name: $name) {
+                pullRequest(number: $pr) {
+                  reviewThreads(first: 100) {
+                    nodes {
+                      id
+                      isResolved
+                      path
+                      line
+                      comments(first: 10) {
+                        nodes {
+                          id
+                          databaseId
+                          body
+                          author { login }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }' -f owner="$OWNER" -f name="$REPO" -F pr=${{ github.event.pull_request.number }}
+            ```
+
+            **Parse the response** - structure is:
+            ```
+            .data.repository.pullRequest.reviewThreads.nodes[]
+            ```
+
+            Filter for threads where `comments.nodes[0].author.login` is "claude" or "github-actions[bot]". These are your previous review comments.
+
+            **Important notes:**
+            - `line` can be `null` for file-level comments (not line-specific)
+            - Use `id` (format: PRRT_xxx) for resolveReviewThread mutations
+            - Use `databaseId` (format: 2518555173) for comment replies
+
+            ### 7. Execute Review
 
             Launch superpowers:code-reviewer subagent (Task tool) with the context gathered above:
             - Full PR diff from step 3
             - Relevant architecture patterns from CLAUDE.md
             - Documentation requirements from step 4
             - Previous review feedback (if incremental update from step 2)
+            - Existing review threads from step 6
 
             The code-reviewer will analyze correctness, architecture, testing, and code quality.
 
-            ### 7. Post Review
+            ### 8. Post Review
 
             **Writing style**:
             - Be direct. One clear point per issue.
@@ -111,7 +159,7 @@ jobs:
             - If issues found: State the issue, reference location, explain why it matters. Move on.
 
             **Format**:
-            - **Inline comments** (using `mcp__github_inline_comment__create_inline_comment`): Use for specific line-by-line code issues
+            - **Inline comments**: Use for specific line-by-line code issues (file path, line number, comment)
             - **Main comment**: Summary only - overall assessment, architectural concerns, testing strategy, verdict. Do NOT duplicate inline comments here.
 
             **Main comment - write naturally:**
@@ -121,14 +169,65 @@ jobs:
             - New concerns: "New issue: error handling in container.ts doesn't cover..."
             - Overall verdict: "Looks good" or "Needs fixes before merge"
 
-            **Post inline comments** for specific code issues using `mcp__github_inline_comment__create_inline_comment`
+            **Handle existing threads before submitting new review:**
 
-            **Post your main comment:**
+            For each thread from step 6, compare with your new findings:
+            - **Issue is fixed:** Mark for resolution (save thread ID)
+            - **Issue persists but needs update:** Mark for reply (save comment database ID)
+            - **Issue no longer relevant:** Mark for resolution
+
+            **Submit review as a single cohesive unit:**
+
+            1. Get the latest commit SHA:
             ```bash
-            gh pr comment ${{ github.event.pull_request.number }} --body "YOUR_REVIEW_HERE" --repo ${{ github.repository }}
+            COMMIT_SHA=$(gh pr view ${{ github.event.pull_request.number }} --json headRefOid --jq '.headRefOid')
             ```
 
+            2. Create review.json with ONLY NEW issues (don't duplicate existing thread issues):
+            ```json
+            {
+              "body": "## Claude Code Review\n\nYour overall assessment here...",
+              "event": "COMMENT",
+              "commit_id": "COMMIT_SHA_HERE",
+              "comments": [
+                {
+                  "path": "path/to/file.ts",
+                  "line": 42,
+                  "body": "Your inline comment here"
+                }
+              ]
+            }
+            ```
+
+            3. Post the unified review:
+            ```bash
+            gh api repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/reviews \
+              --method POST \
+              --input review.json
+            ```
+
+            4. **Manage existing threads (after review submission):**
+
+            Resolve fixed issues:
+            ```bash
+            gh api graphql -f query='
+            mutation($threadId: ID!) {
+              resolveReviewThread(input: {threadId: $threadId}) {
+                thread { id isResolved }
+              }
+            }' -f threadId="THREAD_ID_FROM_STEP_6"
+            ```
+
+            Reply to threads that need updates:
+            ```bash
+            gh api repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/comments/COMMENT_DATABASE_ID/replies \
+              --method POST \
+              -f body="Update: Issue has been partially addressed but..."
+            ```
+
+            **Important**: This workflow maintains conversation continuity - resolved issues show as "Resolved", ongoing issues have threaded replies, and only new issues create new comment threads.
+
             Always post a NEW comment - never update previous ones. Natural conversation flow.
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
-          claude_args: '--allowedTools "Task,Skill,mcp__github_inline_comment__create_inline_comment,mcp__cloudflare-docs__search_cloudflare_documentation,mcp__exa__get_code_context_exa,mcp__exa__web_search_exa,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh api:*),Bash(git *)"'
+          claude_args: '--allowedTools "Task,Skill,Write,mcp__cloudflare-docs__search_cloudflare_documentation,mcp__exa__get_code_context_exa,mcp__exa__web_search_exa,Bash(gh pr view:*),Bash(gh pr diff:*),Bash(gh repo view:*),Bash(gh api:*),Bash(git *)"'

.github/workflows/claude.yml

@@ -41,16 +41,60 @@ jobs:
           additional_permissions: |
             actions: read
 
-          # Custom prompt that ensures Claude reads CLAUDE.md first
           prompt: |
             REPO: ${{ github.repository }}
             ISSUE/PR: #${{ github.event.issue.number || github.event.pull_request.number }}
 
-            IMPORTANT: Before starting any work, read the CLAUDE.md file at the root of this repository. It contains critical project conventions, architecture patterns, and development guidelines that you must follow.
+            ## Task Context
 
-            After reading CLAUDE.md, proceed with the following task:
             ${{ github.event.comment.body || github.event.issue.body || github.event.review.body }}
 
+            ## Workflow Instructions
+
+            **STEP 1: Read project conventions**
+            Read CLAUDE.md at the root of this repository. It contains critical project conventions, architecture patterns, and development guidelines.
+
+            **STEP 2: Assess task complexity**
+            Determine if this task requires planning:
+            - **Needs planning**: New features, architectural changes, significant refactoring, adding major functionality
+            - **Direct execution**: Bug fixes, test fixes, investigations, documentation updates, simple one-line changes
+
+            **STEP 3: Execute appropriate workflow**
+
+            **For tasks needing planning:**
+            1. Use the brainstorming skill (`superpowers:brainstorming`) to:
+               - **IMPORTANT**: You are working autonomously (no user to answer questions)
+               - Use Socratic method on yourself: ask questions, explore answers, consider trade-offs
+               - The task context above contains all available information
+               - Explore 2-3 different approaches with pros/cons
+               - Design the solution covering: architecture, components, data flow, error handling, testing
+               - Save design to `/tmp/claude-plans/YYYY-MM-DD-<topic>-design.md` (temporary, not committed)
+
+            2. Use the writing-plans skill (`superpowers:writing-plans`) to:
+               - Create detailed, bite-sized implementation plan
+               - Include exact file paths, complete code examples, verification steps
+               - Save plan to `/tmp/claude-plans/YYYY-MM-DD-<feature>-implementation.md` (temporary, not committed)
+
+            3. Execute the complete implementation:
+               - Follow TDD for all code changes (write test first, watch fail, implement, verify pass)
+               - Complete the entire implementation
+               - Run all tests and verification steps
+               - **After completion**: Use requesting-code-review skill to review your own work
+               - Fix any issues found in self-review
+               - Commit changes following CLAUDE.md git guidelines
+
+            **For direct execution tasks:**
+            - Use test-driven-development for code changes
+            - Use systematic-debugging for investigations
+            - Use verification-before-completion before claiming done
+            - Follow CLAUDE.md conventions
+
+            **REMEMBER:**
+            - If a superpowers skill applies to your task, you MUST use it (not optional)
+            - Write tests before code (TDD iron law)
+            - Verify with evidence before claiming completion
+            - Create commits following CLAUDE.md git guidelines
+
           # Optional: Add claude_args to customize behavior and configuration
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options