archify-pr · v3.2 · 2026-11-17 · sha256 d8cd57fb583c134d

archify-pr v3.2A

Immutable. This exact content never changes and is served at /api/v1/blob/d8cd57fb583c134d.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_gz64ox5mnpmjccoa/d8cd57fb583c134d2e3c5920cb22330b6739b17dced614560cf9a38fb39ce89c.json

Then /plugin install archify-pr@markdownregistry-gz64ox5mnpmjccoa in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: archify-pr
description: "Explain git branch changes, diffs, and pull requests with visual architecture, workflow, sequence, ERD, or lifecycle walkthroughs. When a pull request carries material architectural, flow, schema, or async-state changes, lightly offer optional Archify PR diagrams and their review benefit without forcing them; build and attach Camo-safe dual-theme story or static diagrams when the user agrees or explicitly asks. Requires the companion archify core Skill."
license: Apache-2.0
metadata:
  version: "3.2"
  author: tt-a1i
---

# Archify PR

Turn a branch change or pull request into diagrams that show what changed, where it propagates, and with what neighbours. Read the code as the authority; report evidence, never a risk verdict.

Every command goes through this Skill's wrapper, `bin/archify-pr.mjs`:

```bash
node <archify-pr-root>/bin/archify-pr.mjs pr validate <manifest.json> --repo-root <repo> --json
```

The wrapper delegates unchanged to the installed core `archify/bin/archify.mjs`. It never downloads or installs anything.

## Route the request

### Explicit PR visualization

When the user asks to explain or visualize a PR, a branch change, or a `git diff`, or to run `archify pr`, start the workflow directly. Read [`references/pr-workflow.md`](references/pr-workflow.md), pin the three-dot range from `git merge-base`, and build the pack; do not ask whether a diagram is wanted.

If the target is a shared PR that already has a written description and the user did not name an update target (`body` or `--target comment`), confirm the target, or show the `pr attach --dry-run` summary before changing the online PR.

### Ordinary PR preparation

When the user only asks to create or summarize a PR:

1. Read the mode. Default is `ask`.
2. Run the materiality filter below.
3. Follow the mode:
   - `on-demand`: stay silent and complete the text-only PR flow.
   - `ask`: make the optional offer only when the filter recommends it.
   - `proactive` (opt-in only): attach a diagram to a material PR without asking.

## Interaction modes

- `ask` (default, no rules line needed): offer diagrams for material changes only, then follow the user's answer.
- `on-demand`: never offer; act only on an explicit request. Rule line: `[archify pr: on-demand]`.
- `proactive`: build and attach for material changes without asking. Only when the user explicitly requests this mode. Rule line: `[archify pr: proactive]`.

To switch modes, only when the user asks, write or replace one `[archify pr: <mode>]` line in the current agent's global rules file (such as `~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md` or `~/.config/devin/AGENTS.md`) and name the file. Deleting the line restores `ask`. Never switch to `proactive` unasked.

## Materiality filter

Run `git diff --stat <merge-base>...HEAD` and classify the changed files. Stay silent, without asking, when the change is any of:

- docs, Markdown, comments or copy only;
- lockfiles, version or dependency manifests, or simple configuration values;
- formatting, lint fixes, or file renames without a logic change;
- tests only, with no production architecture, interface or state change;
- a small single-point edit: one or two files clearly under about 40 changed lines, with no cross-module chain, API contract, state machine or migration change.

Offer a diagram only when at least one is true:

- a cross-module or cross-service topology or responsibility change spanning two or more layers or three or more core modules;
- an async queue, scheduled job, retry, idempotency or state-machine transition change;
- a database schema, foreign-key or index migration, or an added, removed or changed public API contract.

When unsure, stay silent. A missed offer costs less than an unwanted interruption.

## The offer

Use the user's current language and at most three short lines:

1. Name the part of this diff that is hard to read, concretely.
2. State the concrete value: for example one looping story walkthrough plus collapsible static before/after diagrams, hosted through GitHub `user-attachments` with no files added to the branch.
3. Say it is optional. If the user declines or ignores it, finish the text-only PR and do not ask again.

## Build and attach

When the user agrees, or asks explicitly, read [PR workflow](references/pr-workflow.md) for the full manifest, change-mark, story, command and attach loop. It covers:

- the `git merge-base` three-dot range and pinned `baseSha` / `headSha`;
- merged-superset views with one hop of context and change marks;
- the Story dynamic walkthrough with `storyOnly` helper views and `collapsed` static references;
- `detail.mode: "diff"` excerpts from real Git revisions;
- `pr validate`, `pr build`, `pr attach --dry-run`, then `pr attach`;
- diagnostic repair for `pr-pack/*`, `pr-story/*` and `pr-attach/*`.

## Missing core Skill

If the wrapper exits with `archify-pr/core-skill-missing`, the core `archify` Skill is not installed or `ARCHIFY_BIN` is wrong. Report the diagnostic and the install command it suggests to the user. Never run `npx skills add`, install, update or uninstall the core Skill yourself unless the user explicitly asks.

## Evidence rules

- Reproduce the three-dot diff the forge shows; never diff the working tree or a moved two-dot base.
- Cite repository paths and lines at the pinned revisions.
- Never write `SAFE`, `LOW RISK`, `MERGEABLE`, `NO IMPACT`, `VERIFIED PR` or any other risk verdict. Report counts, names and diagrams; the reviewer owns the verdict.
- Do not pad a pack with a view whose only content is `unchanged`.