td-ai-tools 1.0.2

package/skills/pr-solver/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: pr-solver
+description: Resolve GitHub pull request feedback by querying unresolved review conversations with the GitHub GraphQL API and implementing code changes for each unresolved thread. Use when a task includes a GitHub PR URL, asks to address open review comments, or asks to clear unresolved conversations; request a PR link if it is missing.
+---
+
+# GH PR Unresolved Conversations
+
+Follow this workflow to turn unresolved PR review feedback into code fixes.
+
+## Collect Input
+
+1. Parse a GitHub PR link from the user request.
+2. Ask for the PR link if none is provided. Do not continue until a link is available.
+3. Accept `https://github.com/<owner>/<repo>/pull/<number>`.
+
+## Fetch Unresolved Conversations with GraphQL
+
+1. Use the GitHub GraphQL API, not the REST API, because unresolved status is only available on `reviewThreads.isResolved`.
+2. Ensure one of these environment variables is set before querying: `GH_TOKEN` or `GITHUB_TOKEN`.
+3. Run the bundled script:
+
+```bash
+python3 .agents/skills/pr-solver/scripts/list_unresolved_threads.py "<pr-url>" --format json
+```
+
+4. Treat each returned thread where `is_resolved` is `false` as work to address.
+5. If scripting is unavailable, run the GraphQL query in `references/github-pr-reviewthreads-graphql.md` directly.
+
+## Implement Fixes Thread by Thread
+
+1. Process unresolved threads one at a time.
+2. Read the entire conversation in each thread before editing.
+3. Convert the feedback into code changes in the referenced file and nearby context.
+4. Prioritize the newest comment while preserving requirements from earlier comments.
+5. Run targeted validation after each fix: tests, lint, or type checks relevant to touched files.
+6. Mark a thread as blocked only when required context is missing or the feedback cannot be satisfied safely.
+
+## Report Results
+
+1. Report every unresolved thread with one status: `fixed`, `partially fixed`, or `blocked`.
+2. Include file references for each implemented fix.
+3. Include validation commands executed and whether they passed.
+4. Include thread URLs for any partial or blocked outcomes.
+5. Note that GitHub conversation resolution should happen after verification in the PR UI.
+
+## Resources
+
+- `.agents/skills/pr-solver/scripts/list_unresolved_threads.py`: Query GitHub GraphQL `reviewThreads`, paginate, and output unresolved conversations.
+- `.agents/skills/pr-solver/references/github-pr-reviewthreads-graphql.md`: Direct GraphQL fallback query and field guidance.
+- The installer also mirrors this skill under `.claude/skills/pr-solver/`.

package/skills/pr-solver/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PR Solver"
+  short_description: "Fetch and solve PR conversations"
+  default_prompt: "Use $pr-solver to fix unresolved PR conversations with GitHub GraphQL."

package/skills/pr-solver/references/github-pr-reviewthreads-graphql.md

@@ -0,0 +1,63 @@
+# GitHub PR Review Threads GraphQL Reference
+
+Use this query when you cannot run `scripts/list_unresolved_threads.py`.
+
+## Why GraphQL
+
+Use GraphQL because unresolved status is exposed on `PullRequest.reviewThreads.nodes[].isResolved`.
+REST pull request review endpoints do not provide equivalent conversation resolution state.
+
+## Endpoint and Auth
+
+- Endpoint: `https://api.github.com/graphql`
+- Header: `Authorization: Bearer <GH_TOKEN or GITHUB_TOKEN>`
+- Header: `Content-Type: application/json`
+
+## Query
+
+```graphql
+query($owner: String!, $repo: String!, $number: Int!, $after: String) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $number) {
+      number
+      title
+      url
+      reviewThreads(first: 50, after: $after) {
+        nodes {
+          id
+          isResolved
+          isOutdated
+          path
+          line
+          startLine
+          originalLine
+          originalStartLine
+          diffSide
+          comments(first: 100) {
+            nodes {
+              id
+              body
+              createdAt
+              url
+              author {
+                login
+              }
+            }
+          }
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  }
+}
+```
+
+## Pagination
+
+1. Start with `after: null`.
+2. Repeat while `reviewThreads.pageInfo.hasNextPage` is `true`.
+3. Pass `endCursor` into the next request as `after`.
+4. Treat threads with `isResolved == false` as unresolved work items.

package/skills/pr-solver/scripts/list_unresolved_threads.py

@@ -0,0 +1,307 @@
+#!/usr/bin/env python3
+"""List GitHub PR review threads and unresolved conversations via GraphQL."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+from typing import Dict, List, Optional, Tuple
+
+GITHUB_GRAPHQL_URL = "https://api.github.com/graphql"
+
+PR_URL_PATTERN = re.compile(
+    r"^https?://github\.com/(?P<owner>[^/\s]+)/(?P<repo>[^/\s]+)/pull/(?P<number>\d+)(?:[/?#].*)?$"
+)
+PR_REF_PATTERN = re.compile(
+    r"^(?P<owner>[A-Za-z0-9_.-]+)/(?P<repo>[A-Za-z0-9_.-]+)#(?P<number>\d+)$"
+)
+
+QUERY = """
+query($owner: String!, $repo: String!, $number: Int!, $after: String) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $number) {
+      number
+      title
+      url
+      reviewThreads(first: 50, after: $after) {
+        nodes {
+          id
+          isResolved
+          isOutdated
+          path
+          line
+          startLine
+          originalLine
+          originalStartLine
+          diffSide
+          comments(first: 100) {
+            nodes {
+              id
+              body
+              createdAt
+              url
+              author {
+                login
+              }
+            }
+          }
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  }
+}
+"""
+
+
+def parse_pr(value: str) -> Tuple[str, str, int]:
+    match = PR_URL_PATTERN.match(value.strip())
+    if not match:
+        match = PR_REF_PATTERN.match(value.strip())
+    if not match:
+        raise ValueError(
+            "PR must be https://github.com/<owner>/<repo>/pull/<number> or <owner>/<repo>#<number>."
+        )
+
+    owner = match.group("owner")
+    repo = match.group("repo")
+    number = int(match.group("number"))
+    return owner, repo, number
+
+
+def resolve_token(token_env: str) -> str:
+    for key in [item.strip() for item in token_env.split(",") if item.strip()]:
+        token = os.getenv(key)
+        if token:
+            return token
+    raise RuntimeError(
+        f"Missing GitHub token. Set one of: {token_env}. "
+        "The token needs repo read permissions for private repositories."
+    )
+
+
+def graphql_request(query: str, variables: Dict[str, object], token: str) -> Dict[str, object]:
+    body = json.dumps({"query": query, "variables": variables}).encode("utf-8")
+    req = urllib.request.Request(
+        GITHUB_GRAPHQL_URL,
+        data=body,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "Accept": "application/vnd.github+json",
+        },
+    )
+
+    try:
+        with urllib.request.urlopen(req) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"GraphQL request failed: HTTP {exc.code}: {detail}") from exc
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"Network error while calling GitHub GraphQL: {exc}") from exc
+
+    if payload.get("errors"):
+        raise RuntimeError(f"GraphQL errors: {json.dumps(payload['errors'], indent=2)}")
+
+    data = payload.get("data")
+    if not isinstance(data, dict):
+        raise RuntimeError("GraphQL response did not include a valid data object.")
+    return data
+
+
+def fetch_review_threads(owner: str, repo: str, number: int, token: str) -> Tuple[Dict[str, object], List[Dict[str, object]]]:
+    all_threads: List[Dict[str, object]] = []
+    cursor: Optional[str] = None
+    pull_request: Optional[Dict[str, object]] = None
+
+    while True:
+        variables: Dict[str, object] = {
+            "owner": owner,
+            "repo": repo,
+            "number": number,
+            "after": cursor,
+        }
+        data = graphql_request(QUERY, variables, token)
+        repository = data.get("repository")
+        if not isinstance(repository, dict):
+            raise RuntimeError("Repository not found or not accessible with this token.")
+
+        pull_request = repository.get("pullRequest")
+        if not isinstance(pull_request, dict):
+            raise RuntimeError(f"Pull request #{number} was not found in {owner}/{repo}.")
+
+        review_threads = pull_request.get("reviewThreads") or {}
+        nodes = review_threads.get("nodes") or []
+        all_threads.extend([node for node in nodes if isinstance(node, dict)])
+
+        page_info = review_threads.get("pageInfo") or {}
+        has_next = bool(page_info.get("hasNextPage"))
+        if not has_next:
+            return pull_request, all_threads
+
+        next_cursor = page_info.get("endCursor")
+        if not isinstance(next_cursor, str) or not next_cursor:
+            return pull_request, all_threads
+        cursor = next_cursor
+
+
+def normalize_thread(thread: Dict[str, object]) -> Dict[str, object]:
+    comments_container = thread.get("comments") or {}
+    comment_nodes = comments_container.get("nodes") or []
+    comments: List[Dict[str, object]] = []
+    for comment in comment_nodes:
+        if not isinstance(comment, dict):
+            continue
+        author = comment.get("author") or {}
+        comments.append(
+            {
+                "id": comment.get("id"),
+                "author": (author.get("login") if isinstance(author, dict) else None),
+                "body": comment.get("body"),
+                "created_at": comment.get("createdAt"),
+                "url": comment.get("url"),
+            }
+        )
+
+    latest = comments[-1] if comments else {}
+    return {
+        "id": thread.get("id"),
+        "is_resolved": bool(thread.get("isResolved")),
+        "is_outdated": bool(thread.get("isOutdated")),
+        "path": thread.get("path"),
+        "line": thread.get("line"),
+        "start_line": thread.get("startLine"),
+        "original_line": thread.get("originalLine"),
+        "original_start_line": thread.get("originalStartLine"),
+        "diff_side": thread.get("diffSide"),
+        "latest_comment": latest,
+        "comments": comments,
+    }
+
+
+def shorten(text: object, max_chars: int) -> str:
+    if not isinstance(text, str):
+        return ""
+    compact = " ".join(text.split())
+    if len(compact) <= max_chars:
+        return compact
+    if max_chars <= 3:
+        return compact[:max_chars]
+    return f"{compact[:max_chars - 3]}..."
+
+
+def render_markdown(result: Dict[str, object], max_body_chars: int, include_resolved: bool) -> None:
+    pull_request = result["pull_request"]
+    threads: List[Dict[str, object]] = result["threads"]
+    unresolved_count = result["unresolved_count"]
+
+    print(f"# PR #{pull_request['number']}: {pull_request['title']}")
+    print(pull_request["url"])
+    print()
+    print(f"- Total review threads: {len(threads)}")
+    print(f"- Unresolved review threads: {unresolved_count}")
+    print()
+
+    if not threads:
+        print("No review threads were found.")
+        return
+
+    visible_threads = threads if include_resolved else [t for t in threads if not t["is_resolved"]]
+    for index, thread in enumerate(visible_threads, start=1):
+        location = thread["path"] or "(no file path)"
+        line = thread["line"] or thread["start_line"] or thread["original_line"] or "?"
+        latest = thread["latest_comment"] or {}
+        latest_author = latest.get("author") or "unknown"
+        latest_body = shorten(latest.get("body"), max_body_chars)
+        latest_url = latest.get("url") or ""
+
+        print(f"## Thread {index}")
+        print(f"- ID: {thread['id']}")
+        print(f"- Resolved: {thread['is_resolved']}")
+        print(f"- Outdated: {thread['is_outdated']}")
+        print(f"- Location: {location}:{line}")
+        print(f"- Latest comment author: {latest_author}")
+        if latest_url:
+            print(f"- Latest comment URL: {latest_url}")
+        if latest_body:
+            print(f"- Latest comment body: {latest_body}")
+        print(f"- Comment count: {len(thread['comments'])}")
+        print()
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Fetch PR review threads via GitHub GraphQL and list unresolved conversations."
+    )
+    parser.add_argument(
+        "pr",
+        help="PR URL (https://github.com/<owner>/<repo>/pull/<number>) or <owner>/<repo>#<number>",
+    )
+    parser.add_argument(
+        "--token-env",
+        default="GH_TOKEN,GITHUB_TOKEN",
+        help="Comma-separated env vars to check for a GitHub token (default: GH_TOKEN,GITHUB_TOKEN).",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("markdown", "json"),
+        default="markdown",
+        help="Output format (default: markdown).",
+    )
+    parser.add_argument(
+        "--include-resolved",
+        action="store_true",
+        help="Include resolved threads in output.",
+    )
+    parser.add_argument(
+        "--max-body-chars",
+        type=int,
+        default=800,
+        help="Maximum latest-comment body length in markdown output.",
+    )
+    args = parser.parse_args()
+
+    try:
+        owner, repo, number = parse_pr(args.pr)
+        token = resolve_token(args.token_env)
+        pull_request, raw_threads = fetch_review_threads(owner, repo, number, token)
+        threads = [normalize_thread(thread) for thread in raw_threads]
+        unresolved_count = sum(1 for thread in threads if not thread["is_resolved"])
+
+        result = {
+            "pull_request": {
+                "owner": owner,
+                "repo": repo,
+                "number": pull_request.get("number"),
+                "title": pull_request.get("title"),
+                "url": pull_request.get("url"),
+            },
+            "unresolved_count": unresolved_count,
+            "threads": threads,
+        }
+
+        if args.format == "json":
+            if not args.include_resolved:
+                result["threads"] = [thread for thread in threads if not thread["is_resolved"]]
+            print(json.dumps(result, indent=2))
+            return 0
+
+        render_markdown(result, args.max_body_chars, args.include_resolved)
+        return 0
+    except Exception as exc:  # pylint: disable=broad-except
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/pull-request/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: pull request
+description: Generates well-structured GitHub pull request descriptions for Shopify theme development teams by analyzing git diffs and gathering context. Use this skill whenever a developer asks to create a PR, open a pull request, write a PR description, or submit code for review — even if they just say "make a PR" or "create a pull request". Also trigger when someone mentions needing a PR title, PR summary, or PR testing steps.
+---
+
+# PR Description Generator
+
+Helps Shopify theme developers create well-structured pull request descriptions by analyzing code changes and collecting context. Follow these steps in order.
+
+---
+
+## Step 1: Get Branch Info
+
+Ask the developer for:
+1. **Source branch** — the feature/fix branch with their changes
+2. **Target branch** — the branch to merge into (e.g. `main`, `develop`, `release/x.x`)
+
+---
+
+## Step 2: Analyze the Diff
+
+Run this command to fetch and diff the branches:
+
+```bash
+git fetch origin && git diff origin/{target_branch}...origin/{source_branch}
+```
+
+Analyze the diff for:
+- Files changed, added, or deleted
+- Nature of changes (feature, bug fix, refactor, styling, etc.)
+- Key implementation details and patterns
+- Potential impacts or side effects
+- Testable and user-facing changes
+
+### Shopify-Specific Analysis Guide
+
+| File Type | What to Look For | Testing Implications |
+|-----------|-----------------|----------------------|
+| `.liquid` sections/blocks | Schema changes, new settings, render tags, conditionals | Test each new setting; test conditional states |
+| `.liquid` snippets | Parameters, usage contexts | Test in all contexts where snippet is used |
+| `.js` files | Event listeners, DOM manipulation, API calls | Test interactions; test error states |
+| `.css/.scss` files | Media queries, custom properties, animations | Test across breakpoints; test reduced motion |
+| `locales/*.json` | New translation keys | Verify translations appear correctly |
+| `config/*.json` | Theme settings | Test global settings impact |
+
+---
+
+## Step 3: Generate PR Content
+
+Based on the diff, generate:
+
+### PR Title
+Concise and descriptive. Use conventional commit style where appropriate (`feat:`, `fix:`, `refactor:`, `chore:`).
+
+### PR Summary
+1–2 sentences in plain, non-technical language describing what the changes accomplish from a user/business perspective.
+
+### Approach
+Technical description covering:
+- Key files modified and why
+- Implementation strategy
+- Notable patterns or techniques
+- Trade-offs or decisions made
+
+### Testing Steps
+Generate comprehensive, grouped testing steps as checkboxes. Cover all relevant categories:
+
+**Functional Testing**
+- New features or modified behavior
+- Form inputs, buttons, interactive elements
+- Conditional logic and different states
+
+**Visual/UI Testing**
+- Layout across breakpoints (mobile, tablet, desktop)
+- New or modified CSS
+- Section/block appearance in theme editor
+- Hover states, transitions, animations
+
+**Theme Editor Testing**
+- New settings in section/block schemas
+- Setting validations and default values
+- Live preview updates
+- Block add/remove/reorder
+
+**Edge Cases**
+- Empty states (no content, no images)
+- Maximum content (long text, many items)
+- Missing or broken assets
+
+**Accessibility**
+- Keyboard navigation
+- Screen reader compatibility
+- Focus states and tab order
+- Color contrast
+
+**Browser/Device**
+- Cross-browser compatibility
+- Mobile touch interactions
+
+Format example:
+```markdown
+**Feature Functionality**
+- [ ] Verify the "Show price" toggle appears in section settings
+- [ ] Confirm price displays when toggle is enabled
+- [ ] Confirm price is hidden when toggle is disabled
+
+**Responsive Behavior**
+- [ ] Test on mobile (< 768px) — items should stack vertically
+- [ ] Test on desktop (≥ 768px) — items should display in a grid
+```
+
+---
+
+## Step 4: Collect Additional Info
+
+Ask the developer for the following (cannot be inferred from code):
+
+1. **Basecamp Links** — Links to relevant Basecamp Cards or Todos
+2. **Other Considerations** — Edge cases, known limitations, notes for reviewers
+3. **Demo Links** — Shopify store preview URL and theme editor/customizer URL
+4. **Additional Information** — Any other relevant context
+
+Then present the generated testing steps and ask:
+- Any steps to remove (not applicable)?
+- Any additional scenarios to add?
+- Any specific test data or configuration needed?
+
+---
+
+## Step 5: Review & Confirm
+
+Present the complete PR description to the developer for final review. Ask them to confirm it's accurate or request changes.
+
+---
+
+## Step 6: Confirm PR Type
+
+Ask the developer to confirm the project type, as this determines the reviewer(s):
+
+| PR Type | Reviewer(s) |
+|---------|------------|
+| **Retainer** | `@matrjohnson` |
+| **Statamic** | `@matrjohnson` (use admin + preview links) |
+| **Project** | `@andisadiazl` |
+| **Component Library** | `@matrjohnson`, `@andisadiazl` |
+
+---
+
+## Step 7: Create the Pull Request
+
+Once confirmed, create the PR with GitHub CLI:
+
+```bash
+gh pr create \
+  --base "{target_branch}" \
+  --head "{source_branch}" \
+  --title "{auto_generated_title}" \
+  --body "{generated_pr_body}" \
+  --reviewer "{reviewers}"
+```
+
+- **On success**: Share the PR URL with the developer.
+- **On failure**: Display the error and troubleshoot:
+  - Not authenticated → `gh auth status` / `gh auth login`
+  - Branch not pushed → `git push -u origin {source_branch}`
+  - No commits between branches → inform developer
+  - PR already exists → provide link to existing PR
+
+---
+
+## PR Body Template
+
+Use this exact format for the `--body` parameter:
+
+```markdown
+### PR Summary: 
+{auto_generated_summary}
+
+### Tasks Included?
+{basecamp_links}
+
+### What approach did you take?
+{auto_generated_approach}
+
+### Other considerations
+{considerations}
+
+### Testing steps/scenarios
+{auto_generated_and_reviewed_testing_steps_as_checkboxes}
+
+### Demo links
+- [Store]({store_url})
+- [Editor]({editor_url})
+
+### Checklist
+- [ ] Followed [theme code principles](https://github.com/Shopify/dawn/blob/main/.github/CONTRIBUTING.md#theme-code-principles)
+- [ ] Linted with [Theme Check](https://github.com/Shopify/theme-check)
+- [ ] Tested on [mobile](https://shopify.dev/themes/store/requirements#mobile-browser-requirements)
+- [ ] Tested on [multiple browsers](https://shopify.dev/themes/store/requirements#desktop-browser-requirements)
+- [ ] Tested for [accessibility](https://shopify.dev/themes/best-practices/accessibility)
+
+### Additional Information
+{additional_info}
+```
+
+---
+
+## Workflow Summary
+
+1. Ask for source and target branches
+2. Fetch and analyze the diff
+3. Generate title, summary, approach, and testing steps
+4. Collect Basecamp links, demo URLs, and other info; review testing steps
+5. Present complete PR for final confirmation
+6. Confirm PR type and assign reviewer(s)
+7. Create the PR with `gh pr create` and share the URL

package/skills/pull-request/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Pull Request"
+  short_description: "Create a pull request"
+  default_prompt: "Use $pull-request to create a pull request."