testdouble avatar

han-github

GitHub-specific extensions to Han. Provides skills to post code reviews as PR comments, update a PR description with a consistent format, and other GitHub-facing workflows.

version
2.3.2
GitHub stars
352

Install

/plugin install han-github@han

Run it inside Claude Code after adding the marketplace with /plugin marketplace add testdouble/han.

Contents

Discovered from source

Skills 3

When running a PR code review, follow the process outlined here.

Pre-requisites

  • gh CLI: !which gh 2>/dev/null || echo "not installed"
  • jq: !which jq 2>/dev/null || echo "not installed"

If gh is not found, inform the user it must be installed and configured; if jq is not found, inform the user it must be installed. In either case, immediately stop.

Project Context

  • current branch: !git branch --show-current 2>/dev/null || echo unknown
  • default branch: !git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo unknown
  • changed files: !gh pr diff --name-only 2>/dev/null || echo "no pr"
  • personal config directory: !bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
  • project .han/config.md: !cat .han/config.md 2>/dev/null || echo ""

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md probe supplies content, apply it per config-rule.md, which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Step 1: Validate PR State

If changed files is empty or reads no pr, or gh pr view --json number,url fails, inform the user no reviewable PR exists for the current branch and stop.

Step 2: Run Code Review

Invoke the /code-review skill to perform the full code review. Pass along any user-provided focus areas or context from the original arguments.

/code-review writes its report to a file and names the path in its closing message; it does not print the review into the conversation. Capture that path — Step 3 reads the report from it. After /code-review completes, proceed immediately to Step 3 — do not stop here.

Step 3: Offer to Post Review to GitHub

Ask the user whether they'd like to post the review to the PR on GitHub using AskUserQuestion with options "Yes, post the review to GitHub" and "No, just the local review". If the user declines, proceed to Step 5.

If the user accepts:

  1. Gather PR metadata by running ${CLAUDE_SKILL_DIR}/scripts/pr-metadata.sh, which outputs JSON with owner_repo, pr_number, head_sha, pr_author_login, and current_user_login.
  2. Read the report file at the path captured in Step 2, then build the review body from it: Review Summary table, Review Recommendation, and all findings organized by severity, plus any optional sections that are present. Treat every section other than the Review Summary table and the Review Recommendation as optional — the code-review skill renders a section only when it has content, so a section (the Review Coverage section, the What's Good section, an absent severity section on a clean review, the Security Vulnerabilities section, the Remediation note) may simply not be there. Include each section when present and omit it without error or an empty heading when absent. Review Coverage always crosses when present. It appears only when no specialist read the change, and a reviewer on the pull request is the reader who most needs to know that.
  3. Continue to Step 4 — do not post yet.

Step 4: Pre-Post Clarity Check

Because the review body will be publicly visible on the PR, run a clarity pass on the draft before posting.

Match the body's length to what the review found. Every finding earns its place by naming a specific problem at a specific location. Skip filler sections, a restated summary of the diff, and boilerplate the reader can see for themselves on the PR. Three sections are exempt from that length-matching and are never cut or shortened: the Review Summary table, the Review Recommendation, and the Review Coverage section. Review Coverage names no problem at any location by construction; it says which coverage the review did not have, and deleting it as filler would hide that from the widest audience the review reaches. Stay inside what the review covered: this step edits wording and severity, and never adds a finding /code-review did not raise.

  1. Write the draft review body to a temporary file (e.g., /tmp/post-code-review-to-pr-draft.md) using the Write tool.
  2. Launch a single han-core:junior-developer agent in artifact-review mode with the prompt: "You are reviewing the text of a code review that is about to be posted publicly on a GitHub pull request. The review is at {draft_path}. Do not re-review the code — review the review. Flag findings whose wording is unclear, severity is mis-assigned (CRIT used where WARN would be accurate, or vice versa), language is accusatory or blaming rather than evidence-based, or file_path:line_number references are missing or invalid. Leave the Review Summary table, the Review Recommendation, and any Review Coverage section as they are; they are not findings and are not subject to the length-matching bar. Return a short list of specific edits with before/after text; return an empty list if the review reads well as-is."
  3. Apply every actionable edit the agent returns. If the agent raises a severity-assignment issue, adjust the finding's task ID and the Review Summary table to match.
  4. Generate a unique temp file path by running ${CLAUDE_SKILL_DIR}/scripts/create-review-tempfile.sh. Write the final, edited review body to that path using the Write tool (not Bash).
  5. Post based on authorship: If pr_author_login matches current_user_login (self-authored PR), post as a PR comment (GitHub rejects formal reviews from PR authors) by running ${CLAUDE_SKILL_DIR}/scripts/post-pr-comment.sh {pr_number} {temp_file_path}. If they differ, determine event type (REQUEST_CHANGES if any CRIT or WARN findings exist, COMMENT if only SUGG) and post as a formal review by running ${CLAUDE_SKILL_DIR}/scripts/post-pr-review.sh {owner/repo} {pr_number} {head_sha} {event_type} {temp_file_path}.
  6. On success, report the PR URL. On failure, report the error.

Step 5: Offer to Create Fix Plan (Only If Issues Found)

If any Critical or Warning issues were identified, ask the user using AskUserQuestion — "Would you like me to create a plan to fix the identified issues?" with options "Yes, create a fix plan" and "No, just the review". If yes, enter plan mode and create a detailed implementation plan listing each Critical and Warning item by task ID, with specific code changes, file paths, and line numbers, ordered by priority (Critical first). If no Critical or Warning issues were found, the review is complete — suggestions alone do not warrant a fix plan.

Pre-requisites

  • gh CLI: !which gh 2>/dev/null || echo "not installed"

If the gh CLI is not found:

  • Inform the user that it needs to be installed and configured before this skill can be used
  • Immediately stop execution of this skill, as it cannot be executed

Project Context

  • current branch: !git branch --show-current 2>/dev/null || echo unknown
  • default branch: !git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo unknown
  • branch summary: !git log origin/HEAD..HEAD --oneline 2>/dev/null || echo unknown
  • branch stats: !git diff origin/HEAD...HEAD --stat 2>/dev/null || echo unknown
  • branch changes: !git diff origin/HEAD...HEAD 2>/dev/null || echo unknown
  • personal config directory: !bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
  • project .han/config.md: !cat .han/config.md 2>/dev/null || echo ""

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md probe supplies content, apply it per config-rule.md, which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Step 1: Validate Branch State

Before generating a PR description, verify the branch has content to describe:

  1. If default branch is empty or unknown — origin/HEAD is not set. Use AskUserQuestion to ask the user for the default branch name (e.g., main, master, develop). Use that branch as the base for all git commands in subsequent steps, and recompute branch summary, branch stats, and branch changes against it — their Project Context values may read unknown because they were derived from the unset origin/HEAD.

  2. If branch summary is empty — there are no commits on this branch relative to the default branch. Inform the user and stop.

  3. If branch stats is empty — there are no file changes despite having commits (e.g., empty commits or fully reverted changes). Inform the user and stop.

Step 2: Discover the Repository PR Template

Determine whether the repository defines its own GitHub pull-request template. If it does, the generated description must conform to that template's structure (Step 4). Do not assume any particular template shape — discover it, read it, and let its structure drive the output.

Use the Glob tool to look in GitHub's supported template locations. GitHub matches the filename case-insensitively; check both common casings since the working filesystem may be case-sensitive. Search these paths (most templates are .md; .txt is also valid):

  • Root of the repo: pull_request_template.md, PULL_REQUEST_TEMPLATE.md (and the .txt variants).
  • The .github/ directory: .github/pull_request_template.md, .github/PULL_REQUEST_TEMPLATE.md (and .txt).
  • The docs/ directory: docs/pull_request_template.md, docs/PULL_REQUEST_TEMPLATE.md (and .txt).
  • A multiple-template subdirectory: .github/PULL_REQUEST_TEMPLATE/*.md, docs/PULL_REQUEST_TEMPLATE/*.md, PULL_REQUEST_TEMPLATE/*.md.

Then resolve to a single template (or none):

  1. No template file found — the repository has no PR template. Record "no repository template" and continue. Step 4 uses the default structure.
  2. Exactly one single-file template found — Read it in full, including HTML comments. Record its path and full contents.
  3. A PULL_REQUEST_TEMPLATE/ directory with multiple templates — GitHub selects one per PR and the skill cannot know which applies. Use AskUserQuestion to ask which template to conform to, listing the filenames plus a "None — use the default structure" option. Read the chosen file in full and record its path and contents. If the user picks "None," record "no repository template."

Carry the recorded result (the template path and full contents, or "no repository template") into Step 4. Preserve the template's HTML comments verbatim in what you carry forward — they often state how the template is meant to be used.

Step 3: Analyze Changes

Review the branch diff, commits, and relevant source code to understand the PR. Identify the central mechanism — the primary purpose of the PR. If the PR is about feature flags, migrations, or behavioral changes, those ARE the point, not a side detail. Classify the change type (new feature, bug fix, refactoring, docs update, config change, etc.) and read related source files as needed to understand the full scope.

Find the headline behavioral effect — what changes for a user or caller and why — and the central mechanism's key facts (a flag and its default, a migration's direction, the new vs. old behavior). Do not catalog every config value, phase, or mode; the diff carries the specifics. The goal is a short description, not an exhaustive one.

While analyzing, count the significant changed files from branch stats, since that count gates the "What to look at first" section in Step 4. "Significant" means code files. Documentation and configuration files do not count as significant by default; one counts only when there is explicit justification for how it changes the behavior of the code changes in the PR.

Step 4: Generate the PR Description

Launch a single han-core:junior-developer agent to write the PR description directly. Junior-developer's fresh-reviewer perspective is the asset here: by authoring the description with the eyes of a teammate who lacks full project context, the result already anticipates what a reviewer needs to see, removing the need for a separate reviewer-context edit pass.

This skill sources the standard by invoking han-communication:readability-guidance and applies it as it writes the PR description, holding a named audience above the default: the reviewer evaluating the pull request, who will read the code. Scope that frame per section so the technical specifics a reviewer needs — a flag and its default, a migration's direction, the new vs. old behavior — are preserved rather than simplified away.

First, compose the structure directive based on the Step 2 result. The structure directive is the only part of the prompt that differs between the two cases; everything else is shared.

  • Option A — no repository template (Step 2 recorded "no repository template"). The structure directive is:

    Structure (required): Produce the description using this fixed structure and section order: Summary (the bolded TL;DR sentence only) → Behavior changes (its own ## section, present only when runtime behavior changes; omit for pure refactors and docs-only PRs) → What to look at first (only when the PR has more than ~8-10 files with significant changes; see the threshold rule below). The first line under ## Summary MUST be the bolded TL;DR sentence, and the Summary section contains nothing else — no bullet list, no file mentions. Include the ## Behavior changes section only when runtime behavior changes (flag flips, migrations, state-machine edits, config changes, API contract changes); omit it for pure refactors and docs-only PRs.

    Length (required): The whole description is at most 2-5 short paragraphs (the Summary sentence is one of them), and Behavior changes is 1-3 short paragraphs. A small table is fine only when several flags or modes genuinely interact; prefer prose otherwise.

    "What to look at first" inclusion rule: Include "What to look at first" only when the PR has more than ~8-10 files with significant changes. "Significant" means code files. Documentation and configuration files do not count as significant by default. A docs or config file counts as significant only when there is explicit justification for how that change affects the behavior of the code changes in the PR — and even when a docs/config file is deemed significant, it most likely should not be listed in "What to look at first" itself. When the count of significant (code) files is at or below ~8-10, omit "What to look at first" entirely, heading included. Only include it when a large code change genuinely needs a reading-order guide.

    Default template to follow: {paste the contents of template.md}

  • Option B — a repository template was found (Step 2 recorded a template path and contents). The structure directive is:

    Structure (required): Conform to the repository's pull-request template, reproduced below, following the conformance rules exactly. The template's headings and their order are authoritative.

    Conformance rules: {paste the contents of template-conformance.md}

    Repository PR template ({template path from Step 2}): {paste the full contents of the discovered template, including its HTML comments}

Then construct the agent prompt to include all of the following inline (the skill already has this context loaded — pass the actual values, not references):

  • Branch context — the values of current branch, default branch, branch summary, branch stats, and branch changes from the Project Context section.
  • Structure directive — Option A or Option B as composed above.

Use this prompt body (with the context above interpolated):

"Author the pull-request description for this branch. This task repurposes your fresh-reviewer perspective for writing instead of reviewing: the audience is another human teammate reviewing on GitHub without full project context. Your job is to give them a behavioral mental model in roughly thirty seconds of scanning, then point them at where the interesting decisions live. Lead with plain human language about behavior and feature changes — not file-list mechanics. Do not produce a review report, question log, or findings — produce only the final PR description in markdown.

Follow the structure directive below for how the description is organized and laid out. Follow the content rules below for what goes in it. When the structure directive provides a repository template, the template's structure wins over the default section names referenced in the content rules; map the content into the template's sections per the conformance rules.

Content rules across all sections:

  • Keep it short: the entire description is at most 2-5 short paragraphs (the Summary sentence counts as one), and Behavior changes is 1-3 short paragraphs. If you are writing more, you are adding detail a reviewer should read from the diff, not the description.
  • Lead the primary summary or description section with a single bolded TL;DR sentence in the form **This PR <verb> <behavior>, so that <why>.** — fill it before drafting anything else. Keep the Summary to that one sentence: no bullet list, no file mentions.
  • Lead Behavior changes with the central mechanism (a feature flag, migration, or behavioral change) in plain language: name it and its headline effect — a flag and its default, a migration's direction, the new vs. old behavior. Do not enumerate every config value, phase, or mode; a reviewer reads the diff for specifics.
  • Stay at the altitude of behavior and intent, not implementation. Say what changes for a user or caller and why, not how each file or function does it.
  • Only describe changes unique to the PR branch — never include changes merged from the default branch.
  • Define any internal flag, service, or acronym briefly on first use.
  • "What to look at first" is a 2-4 bullet reading-order guide for a large change, pointing at decisions, tradeoffs, or risks in the order to read them — it is NOT a file list. Include it ONLY when the PR has more than ~8-10 files with significant (code) changes per the inclusion rule in the structure directive; otherwise omit the section, heading included.
  • Readability: Apply the shared readability standard sourced via han-communication:readability-guidance. Lead each section with its main point, give sections descriptive headings, keep each paragraph to one idea carried by its first sentence, number anything sequential and bullet anything that is not, and reveal detail in layers (progressive disclosure). Do not simplify away a technical fact a reviewer needs, and do not disturb any required PR-template section structure.

Formatting: Never nest fenced code blocks inside the PR description — use inline backticks for short references, indented 4-space blocks for short snippets, prose descriptions, or small tables instead. Use ##/### headers for sections. Do not leave authoring-instruction HTML comments or template placeholder braces in the rendered output. Never include any form of 'Generated with Claude Code.'

Structure directive: {Option A or Option B from above}

Branch context:

  • Current branch: {current branch}
  • Default branch: {default branch}
  • Commits: {branch summary}
  • File stats: {branch stats}
  • Diff: {branch changes}

Read additional source files via your Read/Grep tools when the diff alone does not explain the change. Return only the final PR description text — no preamble, no review notes."

If the agent returns anything other than a PR description (a review report, question log, etc.), discard it and re-issue the prompt with an explicit reminder to return only the description text.

Once the draft description exists, dispatch a single han-communication:readability-editor agent to audit and rewrite it against the shared readability standard, operating on prose regions only — never inside code fences, table markup, or any commit, PR, or issue reference identifier. Pass it the draft description text and the named audience: the reviewer evaluating the pull request, who will read the code; the editor reads han-communication's own canonical rule, so pass no rule path. Instruct it to preserve every fact — every claim, quantity, named flag or service, and stated condition or qualifier — with its precision intact, and to leave any required PR-template section structure and its headings unchanged. Apply its rewrite as the working description.

Then run the standardized readability self-check (the shared standard is in your context from han-communication:readability-guidance) over the description's prose regions only — never inside code fences, diagram bodies, or commit/PR/issue reference identifiers. Confirm each criterion and fix any failure before finalizing:

Run the readability rule's standardized self-check, which is already in your context from the readability-guidance invocation above. Correct every failure before presenting. Its fidelity criterion is not optional: the standard governs how the content is said, and drops a required technical fact only when the reader asked for less and losing it would not change what they do next.

Step 5: Verify the PR Description

Before displaying the PR description, read it back and confirm. Use the checklist that matches the Step 2 result.

Always confirm (both cases):

  1. The primary summary or description section opens with a single bolded TL;DR sentence leading with behavior, and contains nothing else — no bullet list, no file mentions.
  2. "Behavior changes" carries the behavioral detail. It is present unless the PR is a pure refactor or docs-only change.
  3. The whole description is concise — at most 2-5 short paragraphs (the Summary sentence is one), with Behavior changes at 1-3. Trim anything that restates the diff or drops to implementation-level detail.
  4. "What to look at first" appears only when the PR has more than ~8-10 files with significant (code) changes — documentation and configuration files do not count as significant by default. Otherwise it is omitted entirely, heading included. When present, it is a 2-4 bullet reading-order guide pointing at decisions or risks, not a file list.
  5. Valid markdown, no nested fenced code blocks, no leftover authoring-instruction HTML comments or template placeholder braces ({...}), no "Generated with Claude Code."
  6. Only branch-specific changes described.

When Step 2 recorded "no repository template" (Option A), also confirm: the sections appear in the fixed order — Summary → Behavior changes (when applicable) → What to look at first (only when the significant-file threshold is met).

When Step 2 found a repository template (Option B), also confirm: unless the template was a replace-scaffold per the conformance rules, every heading the template defines is present and in the template's original order; "What to look at first" appears only as an appended section after the template's sections (or filled into an equivalent the template already had) and only when the significant-file threshold is met, never interleaved out of order; the template's checklists are reproduced verbatim with only diff-provable boxes checked and no fabricated attestations; the template's instructional comments and placeholder prompts are stripped from the output.

Fix any issues directly before proceeding to Step 6.

Step 6: Display and Update PR

  1. Display the PR description — Show the full result to the user, parsed and formatted for display.

  2. Check for an existing PR on the current branch by running gh pr view --json number,url. If this fails or returns nothing, the branch has no PR — the task is complete. Stop.

  3. If a PR exists: Use AskUserQuestion to ask whether to update the PR description on GitHub, with options "Yes, update it" and "No, just the markdown is fine". If the user declines, stop. If accepted, update the PR on GitHub by running gh pr edit --body {pr_description_content} passing the full PR description as the body argument. Report the PR URL when done.

Project Context

  • personal config directory: !bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
  • project .han/config.md: !cat .han/config.md 2>/dev/null || echo ""

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md probe supplies content, apply it per config-rule.md, which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Work Items to GitHub Issues

Take an already-broken-down work-items.md file (produced by /plan-work-items) and publish each slice as a GitHub issue in its target repo.

The breakdown work — drafting slices, assigning symbolic IDs, specifying dependencies, inventorying references — has already been done upstream. This skill's job is to map each slice to its target repo, validate the format, write a per-repo work-items file alongside the source, and run the publish pipeline.

Rules

  • Each slice lives in exactly one repo. Cross-repo coordination is documented in prose at the top of work-items.md — never as a native blocker link.
  • Native blocked_by relationships are within-repo only. A cross-repo Depends on is a format error to surface for repair.
  • Symbolic-ID prefixes: accept whatever the input uses. Both shapes are valid input — single-prefix across repos (e.g., W-N for every slice) and per-repo prefixes (e.g., V2-N backend, W-N frontend, EV-N events). The publish scripts accept any uppercase prefix.
  • Every slice issue body MUST link the reference artifacts an implementer needs — API/event contracts, design frames, schema docs, runbooks, ADRs, coding standards. Issues that consume an HTTP endpoint or event payload MUST link the contract section that defines it.
  • UI slices, when the plan folder has a ui-designs/ subfolder, MUST embed the relevant screenshots inline using same-target-repo raw URLs. See references/screenshot-embed-rules.md.
  • NEVER include process artifacts in issue bodies or the work-items preamble. Excluded categories — iteration histories, decision logs, review findings, team findings, facilitation summaries, gap analyses, and anything under an artifacts/ subfolder of the plan that is not a contract or design reference. Full include/exclude list in references/reference-artifact-inventory.md.

Process

1. Locate the work-items file

If the path is not provided, ask for it. The input is a single work-items.md produced by /plan-work-items. Read it.

If the user named a target repo (or repos), a label, or an assignee, note them for Steps 2 and 6. By default, issues are created with no label and no assignee — only apply a label or assignee when the user explicitly asked for one.

2. Build the SYM→repo map

Determine which repo each slice belongs to. Use both signals and reconcile them:

  • Primary — cross-repo work order prose. Most work-items.md files include an intro paragraph naming which SYMs ship to which repo (e.g., "W-1 through W-4 ship to acme-api. W-5 through W-9 ship to acme-web."). Parse this for the mapping.
  • Corroborating — file paths inside each slice. Each slice's **Work to be done.** and **References.** blocks reference files in the target repo. Path roots map cleanly: acme-api/... → acme/acme-api, acme-web/... → acme/acme-web, acme-events/... → acme/acme-events. Use this to verify the prose and to assign any slice the prose doesn't cover.

If the prose and the file-path evidence disagree for a slice, surface the conflict to the user before proceeding.

3. Validate the format with evidence-based repair

Check the work-items file against the format invariants in references/issue-template.md and references/work-items-file-format.md:

  • Heading shape. Every slice heading matches ## <SYM-N> — <title> with an em-dash separator (already-published headings annotated as ## <SYM-N> (#NNN) — <title> are valid too).
  • Depends on line. Literal bold marker **Depends on.**, trailing period, None. or comma-separated SYMs.
  • Within-repo blockers. Every SYM named in a Depends on line maps to the same target repo as the dependent slice (under the map from Step 2).
  • Screenshot URLs. When present, match https://github.com/<org>/<target-repo>/raw/<branch>/.github/issue-assets/<feature-slug>/<SYM-N>/<file>.<ext> against the target repo's default branch and a real file under <plan-folder>/ui-designs/, whose extension is one of the accepted set (png, jpg, jpeg, gif, webp, svg, pdf) and is copied into the URL unchanged. <feature-slug> is the kebab-cased basename of the plan folder.
  • References block. Present whenever the slice consumes an HTTP endpoint, event payload, design frame, ADR, coding standard, or other named artifact.
  • No process artifacts. No links to iteration histories, decision logs, review findings, team findings, facilitation summaries, gap analyses, or anything under an artifacts/ subfolder that is not a contract or design reference.

When a check fails, attempt evidence-based repair. Pull evidence from the source work-items.md, the parent plan referenced in its intro, the feature spec in the same folder, sibling files in the plan folder, and the target repo's ADRs / coding standards / docs:

  • Malformed heading — propose the corrected shape based on the surrounding text. Cite the line number.
  • Missing Depends on line — propose None. if no blockers are evident in the slice's prose. Cite the absence.
  • Cross-repo Depends on — propose moving the relationship to the cross-repo work-order prose at the top of the file and replacing the line with None. or remaining within-repo SYMs. Cite the SYM→repo map entries that prove the cross-repo split.
  • Missing References bullet for an HTTP-consuming slice — propose the contract section link by inspecting the parent plan's External Interfaces / API Contracts section. Cite the anchor.
  • Missing References bullet for a UI slice with ui-designs/ present — propose the design frame and screenshot files by inspecting the feature spec's Visual Reference table and the spec's inline screenshot embeds. Cite the spec section.
  • Process-artifact link found — propose removing the link and (if the slice still needs the context the artifact held) restating the decision in plain language, with a Plan decisions References bullet naming the ID plus a one-sentence description. Cite the include/exclude list.

After validation, report findings in plain language. For each finding, name:

  1. What is wrong — slice SYM, line reference, the failing invariant.
  2. What the proposed fill is — the corrected line, new bullet, removed link, etc.
  3. Evidence for the fill — file path with line number, document section, or named source.

Then give the user three actions:

  • Continue with fills — apply the proposed repairs to the source work-items.md (so the per-repo split files inherit them) and proceed to Step 4.
  • Correct the fills — user provides the right values; apply those and proceed.
  • Stop — exit without publishing. User edits the file by hand and re-runs.

If validation passes with no findings, proceed silently to Step 4.

4. Show the SYM→repo map for confirmation

Present a table for user review:

SYMTitleTarget repo
W-1Backend per-list validator generalizationacme/acme-api
W-2…acme/acme-api
W-5Frontend type widening and drift comparatoracme/acme-web

Wait for confirmation before writing files or creating issues.

5. Write per-repo work-items files

For each target repo named in the SYM→repo map, write a <repo-name>.work-items.md file in the same folder as the source work-items.md. The per-repo file is a filtered view of the source — it is the file the publish scripts consume:

  • Header section. Copy the source file's title, intro paragraph, and cross-repo work-order prose verbatim. This keeps each per-repo file self-contained for review.
  • Shared reference artifacts. Copy the source file's "Shared reference artifacts" section, filtered to entries that apply to at least one slice in this repo. When in doubt, include the entry.
  • Slices. Include only the slices whose SYM maps to this repo, in their original order from the source file.

The source work-items.md is not modified by the publish step. The per-repo files are what carry the (#NNN) issue-number annotations after publishing.

6. Publish each per-repo file to GitHub

For each per-repo file, publish it by running ${CLAUDE_SKILL_DIR}/scripts/publish-work-items.sh <per-repo-work-items-file> <org>/<target-repo> <plan-folder> [--label <name>] [--assignee <user>]. Pass the per-repo work-items file written in Step 5, the target repo as <org>/<target-repo>, and the plan folder that contains the ui-designs/ subfolder.

Created issues are unassigned and carry no label by default. Append --label <name> and/or --assignee <user> only when the user asked for a label or assignee (Step 1). Both flags are optional and may be omitted.

The wrapper runs three idempotent scripts in order:

  1. scripts/upload-screenshots.sh — extracts every .github/issue-assets/<feature-slug>/<SYM-N>/<file>.<ext> URL from the per-repo file and copies the matching file from <plan-folder>/ui-designs/ into the target repo, verifying each upload. The <feature-slug> segment (the kebab-cased plan-folder basename) keeps assets from different features that publish to the same repo from colliding. Upload is adaptive: by default each file is written directly to the default branch via the GitHub Contents API, but if that branch is protected and rejects the direct write (HTTP 409), the script falls back to committing the assets to an assets branch, opening a pull request, and printing the PR URL. The embedded image URLs always name the default branch, so on the PR path the inline designs render once that assets PR merges — the issues are still created immediately. Overwrites existing files cleanly and, on re-run, reuses the assets branch and open PR — but only a branch it created for this feature (one already carrying the feature's issue-assets/<feature-slug>/ tree); a same-named branch it does not own is refused rather than committed onto.
  2. scripts/create-issues.sh — creates one GitHub issue per ## <SYM-N> slice in file order (blocker-first), unassigned and unlabeled by default. When --label <name> is passed, it applies that label to every issue, creating it on the repo only if it does not already exist (an existing label's color and description are left intact); when --assignee <user> is passed, it assigns each issue to that user. Captures each returned issue number and rewrites the heading in place to ## <SYM-N> (#NNN) — <title>. Skips slices already annotated with (#NNN) so partial runs resume cleanly.
  3. scripts/link-blockers.sh — reads the SYM↔#NNN mapping from the rewritten headings, walks each **Depends on.** line, and POSTs repos/<repo>/issues/<N>/dependencies/blocked_by once per blocker. Errors out if a blocker SYM is not present in the same file (cross-repo dependencies are forbidden as native links — they belong in the cross-repo work-order prose).

When upload-screenshots.sh reports that it fell back to PR mode (it prints a NOTE: with an assets-branch pull request URL), surface that PR URL to the user and tell them the issues' inline designs render only once that assets PR merges. This is a required follow-up action; do not summarize it away.

The format invariants the scripts depend on (heading shape, URL scheme, Depends on syntax) are documented in references/issue-template.md. Edits to that template require matching script changes.

Sponsors

Details

Marketplace
testdouble/han
Source
han-github
Category
Community

More from testdouble/han

All 14