Add frontend design and independent design-review skills to UI workflows

[rochecompaan]

Problem

Patchmill's recommended skill pack does not include dedicated frontend design guidance or a frontend design review. Visible UI work therefore relies on the generic specification, implementation, and code-review instructions. This can produce specifications without a concrete visual reference and can let visual or UX problems survive an otherwise successful code review.

Desired behavior

Keep the existing workflow:

1. brainstorming writes the specification.
2. writing-plans writes the implementation plan.
3. The configured implementation workflow implements the plan.
4. The normal code-review workflow runs.

Augment that workflow conditionally for visual frontend work. Do not introduce a separate design phase or replace the existing planning, implementation, or code-review skills.

Specification augmentation

When the proposed work requires user-visible frontend changes:

• The specification author must use the configured frontend-design skill while writing the specification.
• The specification work must include a runnable, responsive, full-page HTML mockup for the proposed UI.
• The mockup must show changed components in page context rather than only as isolated fragments.
• The specification must reference the mockup artifact.
• The subsequent writing-plans step continues to operate normally, consuming the specification and its referenced mockup.

Use Anthropic's frontend-design as the upstream design guidance:

• Skill: https://github.com/anthropics/skills/blob/41bbe19d1a1a7eaab5e7bb9050a417e5c6cffc8f/skills/frontend-design/SKILL.md
• License: https://github.com/anthropics/skills/blob/41bbe19d1a1a7eaab5e7bb9050a417e5c6cffc8f/skills/frontend-design/LICENSE.txt

Wrap it with Patchmill-specific process for specification-time mockup creation and references. Existing project design systems and approved product requirements take precedence over generic aesthetic guidance.

Implementation and review augmentation

When the completed implementation includes user-visible frontend changes:

• Complete the existing validation and normal code-review process first.
• Then run an independent frontend design review using the configured frontend-review skill.
• The frontend reviewer must report actionable findings and direct the implementation agent to fix them.
• Repeat the frontend review after fixes as needed.
• Rerun affected validation and normal code review when a frontend-review fix changes production code.
• Preserve the existing visual-evidence behavior; use available visual evidence as review input rather than adding a new top-level workflow stage.

Base the review guidance on Vercel's Web Interface Guidelines:

• Skill wrapper: https://github.com/vercel-labs/agent-skills/blob/ba46938889d48fe25b412aeef77941764aedd976/skills/web-design-guidelines/SKILL.md
• Pinned rules: https://github.com/vercel-labs/web-interface-guidelines/blob/e3d624baaf29dc1fc645aff3e38f03e564d2d6b1/command.md
• Rules license: https://github.com/vercel-labs/web-interface-guidelines/blob/e3d624baaf29dc1fc645aff3e38f03e564d2d6b1/LICENSE

Create a self-contained Patchmill wrapper. Do not retain the upstream skill's runtime WebFetch dependency or fetch mutable review rules. Project policy and the approved specification must override opinionated generic rules. Findings should include severity, user impact, evidence, and file:line where applicable.

Acceptance criteria

• The recommended skill pack installs pinned frontend-design guidance and the applicable license/attribution files.
• Patchmill provides a specification-time frontend-design wrapper that conditionally activates for user-visible frontend changes.
• The wrapper requires a full-page HTML mockup and a reference to it from the specification.
• The normal brainstorming and writing-plans workflow remains intact.
• Patchmill provides a self-contained frontend-review skill based on pinned Vercel rules, with no mutable runtime fetch.
• Frontend review runs independently and only after normal code review for implementations with user-visible frontend changes.
• Frontend-review findings are routed to the implementation agent for fixes and can trigger a repeated review pass.
• Existing validation, normal code review, and visual-evidence behavior remain intact.
• Repository-specific design rules and the approved specification take precedence over generic skill opinions.
• Skill-pack config, metadata, tests, and live dependency references resolve to the same pinned upstream versions.
• Documentation explains the conditional behavior, mockup artifact, review order, and override precedence.

Notes

The frontend implementation skill and frontend-review skill are deliberately complementary. The former influences specification quality and provides a concrete visual artifact. The latter is an independent review pass and must not replace normal code review.

[rochecompaan]

Spec attached to this issue

Spec content

Issue 210 frontend design and review skills design

Status

Validated in an interactive planning session on 2026-09-07.

Summary

Patchmill will augment its existing workflows for meaningful user-visible
frontend changes. The change will not add a design phase or replace an existing
workflow skill.

During specification work, patchmill-planning will use a sibling copy of
Anthropic's frontend-design skill. The specification will include a
self-contained, full-page HTML mockup and will link to that mockup.

The existing specification prompt will still prohibit product implementation. It
will permit required planning-only companion artifacts and will require the
agent to commit them with the specification.

After implementation, each selectable implementation wrapper will use one shared
patchmill-frontend-review sibling. This review will occur after the wrapper's
existing validation and code-review gates. A fresh review-only agent will apply
pinned Vercel Web Interface Guidelines without a runtime network request.

Goals

• Add pinned Anthropic frontend design guidance to the recommended skill pack.
• Add specification rules for a responsive, full-page HTML mockup.
• Preserve the normal brainstorming and writing-plans sequence.
• Add one shared, independent frontend-review skill.
• Use that review skill from all three selectable implementation wrappers.
• Preserve each wrapper's existing implementation, validation, review, visual
  evidence, landing, and PR-check behavior.
• Keep skill installation and updates offline.
• Record upstream repositories, commits, source paths, installed paths, and
  license evidence in skill-pack metadata.
• Package the vendored files in npm and Nix outputs.

Non-goals

• Do not add a top-level design phase.
• Do not add frontend design or review keys to patchmill.config.json.
• Do not add a Pi resource profile, configuration key, or new runtime prompt
  seam.
• Do not replace brainstorming, writing-plans, or normal code review.
• Do not replace or duplicate the current visual-evidence stage.
• Do not fetch mutable design or review guidance at runtime.
• Do not require a mockup or frontend review for a copy-only edit unless it
  materially changes layout, interaction, accessibility, or user flow.
• Do not require pixel-perfect agreement between the mockup and implementation.

Approved upstream sources

Anthropic frontend design

• Repository: anthropics/skills
• Commit: 41bbe19d1a1a7eaab5e7bb9050a417e5c6cffc8f
• Skill source: skills/frontend-design/SKILL.md
• License source: skills/frontend-design/LICENSE.txt
• License: Apache License 2.0

Vercel review wrapper

• Repository: vercel-labs/agent-skills
• Commit: ba46938889d4e58635362fb8f618e1178ac3ec46
• Source: skills/web-design-guidelines/SKILL.md
• License: MIT, as declared in the repository README license section

The commit above replaces the invalid commit in the issue body:
ba46938889d48fe25b412aeef77941764aedd976.

Vercel Web Interface Guidelines

• Repository: vercel-labs/web-interface-guidelines
• Commit: e3d624baaf29dc1fc645aff3e38f03e564d2d6b1
• Rules source: command.md
• License source: LICENSE
• License: MIT

Approaches considered

Extend the existing wrappers with sibling skills (chosen)

patchmill-planning owns the conditional specification behavior. Each
implementation wrapper owns the point where it invokes the shared frontend
review. The skill pack installs the required siblings.

This approach follows the current composition pattern. It keeps workflow rules
near the workflows that use them. It also avoids new configuration and runtime
prompt seams.

Add a dedicated frontend specification wrapper

A new patchmill-frontend-specification skill could contain the mockup process.
patchmill-planning would invoke this skill, which would then invoke
frontend-design.

This split gives the specification augmentation its own file. It also adds a
shallow wrapper and an extra navigation step without adding independent
behavior.

Inject frontend behavior from TypeScript prompts

The run-once prompt builder could add design and review instructions. This
approach centralizes activation text in TypeScript.

It also splits workflow ownership between runtime code and skill wrappers. It
does not follow the current sibling-skill pattern.

Architecture

The existing Patchmill wrappers remain the workflow seam. The new skills are
recommended-pack siblings, not configured workflow skills.

The composition is:

patchmill-planning
├── brainstorming
├── frontend-design                  conditional specification guidance
└── writing-plans

single-subagent-dev-with-codex-and-thermo-reviews
subagent-dev-with-codex-and-thermo-reviews
subagent-dev-with-validation-and-pr-checks
└── patchmill-frontend-review        conditional final review
    └── local pinned Vercel rules

The project-local skill root is already available to Pi when a configured
project-local wrapper runs. The wrappers can therefore resolve their siblings
without a new skill configuration key or profile path.

The existing specification-creation prompt has one narrow compatibility change.
Its product-code guard will permit required planning-only artifacts, such as
HTML mockups. Its commit instruction will include required companion planning
artifacts. The prompt will not decide when frontend design activates, name a
frontend sibling, or orchestrate frontend design or review. The sibling skills
remain the only frontend workflow seam.

Skill layout

Anthropic skill

Patchmill will vendor these files without modification:

skills/frontend-design/SKILL.md
skills/frontend-design/LICENSE.txt

The recommended pack will install them as:

.patchmill/skills/frontend-design/SKILL.md
.patchmill/skills/frontend-design/LICENSE.txt

Patchmill frontend review

Patchmill will add this skill:

skills/patchmill-frontend-review/
├── SKILL.md
├── LICENSE
└── references/
    ├── upstream-web-design-guidelines.md
    └── web-interface-guidelines.md

SKILL.md is Patchmill-owned. It defines activation, inputs, precedence, review
output, and the repair loop.

references/upstream-web-design-guidelines.md is a verbatim copy of the pinned
Vercel agent skill. Its renamed file prevents Pi from discovering it as a second
active skill. The active wrapper does not obey its WebFetch instruction.

references/web-interface-guidelines.md is a verbatim copy of the pinned
command.md. The active wrapper reads this local file as its review rule set.

LICENSE is a verbatim copy of the MIT license from the pinned rules
repository. The third-party notice will also cite the MIT declaration for the
agent-skills wrapper.

The recommended pack will install the complete directory under
.patchmill/skills/patchmill-frontend-review/.

Specification workflow

Activation

patchmill-planning will activate frontend design when proposed work changes
one or more of these browser-visible areas:

• layout or responsive behavior;
• typography, color, spacing, imagery, or other styling;
• interaction or motion;
• accessibility behavior;
• navigation or user flow.

A copy-only edit does not activate the augmentation. It activates only when the
copy materially changes one of the areas above.

The planning agent will state whether it activated the augmentation. If it did
not activate it, the workflow will continue with its current behavior.

Guidance and precedence

When the augmentation activates, patchmill-planning must read
../frontend-design/SKILL.md. It will apply that guidance while it runs the
normal brainstorming process.

The precedence order is:

1. explicit user and approved product requirements;
2. repository policy and the existing design system;
3. Anthropic's generic frontend guidance.

The skill cannot replace approved project choices with a generic aesthetic.

Mockup artifact

Before the specification is final, the workflow must create:

docs/mockups/YYYY-MM-DD-<topic>.html

The mockup must meet these requirements:

• It is one self-contained HTML file.
• It embeds required CSS and JavaScript.
• It has no required network assets.
• It has no build step.
• It opens directly from disk in a browser.
• It supports mobile and desktop viewport widths.
• It shows the changed UI in a complete page context.
• It does not show only isolated components.
• It uses semantic HTML.
• It includes visible keyboard focus where controls exist.
• It honors reduced-motion preferences where motion exists.

The specification must link to the mockup with a repository-relative path. The
mockup must be committed with the specification as a companion planning
artifact.

The mockup records visual intent. It is not a pixel-perfect contract. Written
requirements and repository rules take precedence. A material implementation
difference needs a product or technical reason.

Transition to the plan

The normal writing-plans step remains after specification approval. The plan
must identify both the specification and its referenced mockup as implementation
inputs. No new phase occurs between the specification and plan.

If the required mockup is absent or not linked, patchmill-planning must stop
before writing-plans.

Implementation and frontend-review workflow

Placement

All three selectable implementation wrappers will invoke the same sibling skill:

../patchmill-frontend-review/SKILL.md

The wrappers are:

• single-subagent-dev-with-codex-and-thermo-reviews;
• subagent-dev-with-codex-and-thermo-reviews;
• subagent-dev-with-validation-and-pr-checks.

Each wrapper will invoke frontend review after its existing implementation,
validation, and normal review gates close. The review occurs before landing and
PR-check completion.

The wrapper will skip this checkpoint when the final base-to-head scope has no
meaningful user-visible frontend change.

Independent reviewer

The invoking wrapper will dispatch a fresh-context, review-only reviewer
subagent. Fresh context is the independence requirement. A different model or
provider is not required.

The reviewer cannot edit files. Before dispatch, the parent workflow must list
available subagents and make sure that the canonical reviewer is executable.
The disabled code-reviewer compatibility role is not allowed.

Review inputs

The reviewer receives:

• the issue requirements;
• the approved specification;
• the referenced mockup, when the specification has one;
• the implementation base and current head;
• the changed frontend files;
• relevant repository policy and design-system guidance;
• available visual evidence.

The reviewer must inspect code and available visual evidence. The review cannot
create a new visual-evidence stage. Missing optional evidence does not block the
review.

Review precedence

The review uses this precedence order:

1. explicit user and approved product requirements;
2. repository policy and the existing design system;
3. the approved written specification;
4. the mockup as visual intent;
5. the pinned Vercel rules.

A higher-priority requirement can override a generic Vercel rule. The reviewer
must record the reason when it rejects a rule as not applicable.

Review output

The result is pass or a list of actionable findings. Each finding must
include:

• severity: critical, important, or minor;
• user impact;
• concrete evidence;
• file:line when a source location applies;
• the required correction.

The reviewer must not report personal preference as a finding. A finding must
connect to a requirement, design-system rule, mockup intent, or pinned Vercel
rule.

Repair and repeat

The parent workflow routes valid findings through its existing implementation
worker and repair process. The shared review skill does not create a second
implementation process.

If a repair changes production code, the parent must:

1. refresh the base-to-head scope;
2. rerun affected validation;
3. rerun the wrapper's normal review gates for the changed scope;
4. dispatch a new fresh-context frontend reviewer.

The loop ends when the reviewer returns pass. It can also end with an
evidenced external or operator blocker under the wrapper's existing blocked
contract.

The parent must resolve every review and repair subagent before it returns the
final Patchmill result.

Skill-pack model and metadata

Pack entry model

SkillPackSkill will keep its current name and installation source. The
source value identifies a local copy root. It does not claim authorship.

The type will add:

• requiredFiles, for files resolved relative to the skill directory;
• upstreamSources, for provenance of vendored or adapted material.

Each upstream source record contains:

• repository;
• commit;
• source files;
• target files below the packaged skill directory;
• license name;
• upstream license source;
• local license target when a license file exists.

Anthropic's skill has one upstream source record. The frontend-review skill has
two records because the wrapper and rule set come from different repositories.

Installed metadata

buildSkillPackMetadata will add a skills array to
patchmill-skill-pack.json. Each entry will record:

• skill name and installation source;
• required installed paths;
• upstream repository and commit;
• each original source path and installed path;
• license name and evidence path;
• an installed license path when applicable.

The existing files array remains the integrity record for every installed
file. It will continue to store installed paths and SHA-256 values.

The metadata parser will accept an older managed metadata file without the
skills array. A new installation or update will always write the array. The
update comparison will include this array, so a provenance-only change cannot
produce a false up-to-date result.

Required-file validation

Installation, update, and existing-directory validation must use the required
files from each recommended-pack entry. They must report a missing file before
copying or replacing the project-local pack.

The required set for the new skills is:

frontend-design/SKILL.md
frontend-design/LICENSE.txt
patchmill-frontend-review/SKILL.md
patchmill-frontend-review/LICENSE
patchmill-frontend-review/references/upstream-web-design-guidelines.md
patchmill-frontend-review/references/web-interface-guidelines.md

The patchmill-planning entry will require the sibling frontend-design skill
and license. Each implementation-wrapper entry will require the shared review
skill, its references, and its license. These relative requirements let the
existing doctor check report a missing sibling for the configured wrapper.

Existing-directory validation will also check the two new skill directories. The
operation must retain current safeguards for customized managed files and
new-file collisions.

Pack update

The recommended skill-pack version will increase. The update notice can explain
the new conditional UI behavior. It must not request a configuration change,
because configured planning and implementation paths stay the same.

The repository's tracked .patchmill/skills/ tree and metadata will be
regenerated from the updated source pack. This step keeps installed copies, file
hashes, and provenance aligned.

Packaging and notices

THIRD_PARTY_NOTICES.md will add entries for:

• the Anthropic frontend-design skill and Apache License 2.0;
• the Vercel agent-skills wrapper and its README MIT declaration;
• the Vercel Web Interface Guidelines rules and MIT license.

Each notice will include the repository, commit, source path, local path,
license, purpose, and modification status.

The npm package already includes skills/. Package checks will name the new
skill and license files so that an accidental omission fails.

Prettier and Markdownlint will ignore only the verbatim upstream Markdown files.
Patchmill-owned skill wrappers will remain subject to both tools.

The Nix package already copies the packaged skills/ directory. Its install
check will require the new source files and the files installed by
patchmill init.

No npm dependency or lock file change is required.

Documentation

The README will explain:

• when frontend design activates;
• where the HTML mockup is stored;
• the self-contained and full-page mockup contract;
• that writing-plans still follows specification approval;
• when independent frontend review runs;
• the repair and re-review order;
• the relationship with visual evidence;
• the override precedence;
• the pinned, offline review rule set.

Skill files remain the detailed operational documentation. The README will give
users the workflow contract without copying the complete rule sets.

Failure behavior

• If frontend specification work activates and frontend-design is missing, the
  planning workflow stops.
• If the required mockup is missing or unlinked, the planning workflow stops
  before writing-plans.
• If frontend implementation work activates and the frontend-review skill or a
  pinned reference is missing, the implementation workflow stops.
• The workflow cannot silently replace missing pinned rules with a web fetch.
• A review continues without optional visual evidence unless existing project
  policy already requires that evidence.
• External and operator blockers use the implementation wrapper's current
  blocked-result contract.
• A generic rule conflict is not a blocker when a higher-priority requirement
  resolves it. The review records the resolution.

Verification strategy

Automated behavior tests

Automated tests will cover behavior that can regress:

• the specification prompt prohibits product implementation but permits and
  commits required companion planning artifacts;
• recommended-pack entries expose all required files;
• metadata generation renders provenance and installed paths for a custom skill
  directory;
• old managed metadata remains updateable;
• provenance participates in up-to-date detection;
• installation copies both new skills and all required files;
• installation and existing-directory validation reject a missing required file;
• doctor reports a missing frontend sibling or pinned review reference;
• skill update adds new files without bypassing customization and collision
  safeguards;
• npm pack output contains the new skill, reference, and license files;
• the Nix install check finds packaged and project-installed copies.

Direct verification

The Testing Value Gate rejects new tests that only assert documentation text,
workflow prose, or literal commit strings. Direct verification will cover those
items:

• compare every verbatim vendored file with its pinned upstream URL;
• inspect the planning wrapper and all three implementation wrappers;
• inspect generated metadata and notices for consistent pins and paths;
• run Markdown and formatting checks;
• inspect the source and installed planning wrappers for the self-contained,
  full-page, mobile, and desktop mockup contract.

Final commands

The implementation plan must include focused tests for modified modules. Final
verification will also include:

npm test
npm run lint
npm pack --dry-run --json --ignore-scripts
nix build .#patchmill --no-link

Affected files

The expected source changes include:

• skills/frontend-design/SKILL.md
• skills/frontend-design/LICENSE.txt
• skills/patchmill-frontend-review/SKILL.md
• skills/patchmill-frontend-review/LICENSE
• skills/patchmill-frontend-review/references/upstream-web-design-guidelines.md
• skills/patchmill-frontend-review/references/web-interface-guidelines.md
• skills/patchmill-planning/SKILL.md
• skills/single-subagent-dev-with-codex-and-thermo-reviews/SKILL.md
• skills/subagent-dev-with-codex-and-thermo-reviews/SKILL.md
• skills/subagent-dev-with-validation-and-pr-checks/SKILL.md
• src/cli/commands/run-once/prompts.ts
• src/cli/commands/run-once/prompts.test.ts
• src/workflow/skill-pack.ts
• src/workflow/skill-pack.test.ts
• src/cli/commands/init/skill-installer.ts
• src/cli/commands/init/skill-installer.test.ts
• src/cli/commands/init/skill-installer-path-mode.test.ts
• src/cli/commands/doctor/checks.test.ts
• src/cli/commands/skills/update.ts
• src/cli/commands/skills/update.test.ts
• bin/package-files.test.ts
• nix/package.nix
• THIRD_PARTY_NOTICES.md
• README.md
• .prettierignore
• .markdownlint-cli2.jsonc
• generated files under .patchmill/skills/

No change is planned for:

• patchmill.config.json skill keys;
• src/workflow/skills.ts;
• src/workflow/skill-resolution.ts;
• src/workflow/bundled-skills.ts;
• src/pi/resource-profiles.ts;
• src/cli/commands/run-once/prompt-workflow.ts;
• package.json dependency fields or npm lock files.

Acceptance mapping

• The recommended pack installs pinned frontend design guidance and licenses:
  see Skill layout, Skill-pack model and metadata, and Packaging and
  notices.
• Specification-time frontend design activates only for meaningful visible UI
  work: see Specification workflow.
• A full-page responsive HTML mockup is required and linked: see Mockup
  artifact.
• The specification prompt permits required planning companions without owning
  frontend activation: see Architecture and Automated behavior tests.
• brainstorming and writing-plans remain intact: see Architecture and
  Transition to the plan.
• Frontend review uses pinned local Vercel rules without WebFetch: see
  Patchmill frontend review and Independent reviewer.
• Review occurs independently after normal review: see Placement and
  Independent reviewer.
• Findings return to the existing implementation process: see Repair and
  repeat.
• Existing validation, code review, and visual evidence remain intact: see
  Implementation and frontend-review workflow.
• Project rules and the approved specification override generic guidance: see
  both Guidance and precedence sections.
• Pins remain aligned across config-free pack definitions, metadata, installed
  files, tests, and notices: see Installed metadata and Verification
  strategy.
• User documentation covers activation, artifacts, review order, and precedence:
  see Documentation.

[rochecompaan]

Implementation plan attached to this issue

Implementation plan content

Frontend Design and Review Skills Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use
superpowers:subagent-driven-development (recommended) or
superpowers:executing-plans to implement this plan task-by-task. Steps use
checkbox (- [ ]) syntax for tracking.

Goal: Add conditional specification-time frontend design and independent
post-code-review frontend review to Patchmill's recommended skill pack.

Architecture: Keep patchmill-planning and the three selectable
implementation wrappers as the workflow seams. Install Anthropic's frontend
design skill and one self-contained Patchmill frontend-review skill as siblings,
then record their pinned upstream sources in generated skill-pack metadata.

Tech Stack: TypeScript, Node.js 24, node:test, Markdown Agent Skills, npm
packaging, and Nix

Spec:
docs/specs/2026-09-07-issue-210-frontend-design-and-review-skills-design.md

Global Constraints

• Anthropic repository: anthropics/skills.
• Anthropic commit: 41bbe19d1a1a7eaab5e7bb9050a417e5c6cffc8f.
• Anthropic files: skills/frontend-design/SKILL.md and
  skills/frontend-design/LICENSE.txt.
• Vercel wrapper repository: vercel-labs/agent-skills.
• Vercel wrapper commit: ba46938889d4e58635362fb8f618e1178ac3ec46.
• Vercel wrapper file: skills/web-design-guidelines/SKILL.md.
• Vercel rules repository: vercel-labs/web-interface-guidelines.
• Vercel rules commit: e3d624baaf29dc1fc645aff3e38f03e564d2d6b1.
• Vercel rules files: command.md and LICENSE.
• The active frontend-review skill must not use WebFetch or another runtime
  network request.
• Keep the existing
  brainstorming → writing-plans → implementation → normal review workflow.
• Do not add skill configuration keys, Pi resource-profile paths, a top-level
  design phase, or a new runtime prompt seam.
• Narrow the existing specification prompt so it prohibits product changes but
  permits required planning-only mockups and companion artifacts. Keep frontend
  activation and orchestration out of TypeScript.
• Use one shared patchmill-frontend-review sibling from all three selectable
  implementation wrappers.
• Store future mockups at docs/mockups/YYYY-MM-DD-<topic>.html as
  self-contained files.
• A future mockup is visual intent. Product requirements, repository policy, the
  design system, and the written specification take precedence.
• Issue Add frontend design and independent design-review skills to UI workflows #210 changes workflow resources, not browser-visible product UI. It does
  not require its own HTML mockup.
• Apply the Testing Value Gate. Use direct verification for upstream pins,
  Markdown text, documentation, and static configuration.
• Do not change npm dependencies or lock files.

---

File Structure

New source skills

• skills/frontend-design/SKILL.md: verbatim pinned Anthropic guidance.
• skills/frontend-design/LICENSE.txt: verbatim Apache License 2.0 text from
  Anthropic.
• skills/patchmill-frontend-review/SKILL.md: Patchmill-owned activation,
  reviewer, output, and repair contract.
• skills/patchmill-frontend-review/LICENSE: verbatim MIT license for the
  pinned Vercel rules.
• skills/patchmill-frontend-review/references/upstream-web-design-guidelines.md:
  renamed verbatim Vercel wrapper reference.
• skills/patchmill-frontend-review/references/web-interface-guidelines.md:
  verbatim pinned Vercel rule set.

Pack and installer modules

• src/workflow/skill-pack.ts: recommended-pack entries, required-file lookup,
  provenance types, and installed metadata rendering.
• src/cli/commands/init/skill-installer.ts: required-file preflight, install
  metadata input, and existing-pack validation.
• src/cli/commands/skills/update.ts: required-file preflight, provenance
  comparison, and metadata refresh.
• src/cli/commands/doctor/checks.ts: no production change expected; its
  existing requiredSkillFiles seam consumes the richer pack entries.

Workflow wrappers and documentation

• src/cli/commands/run-once/prompts.ts: planning-artifact permission and
  commit wording for specification creation.
• src/cli/commands/run-once/prompts.test.ts: specification-prompt behavior
  coverage.
• skills/patchmill-planning/SKILL.md: conditional specification and mockup
  rules.
• skills/single-subagent-dev-with-codex-and-thermo-reviews/SKILL.md: frontend
  checkpoint after its final validation gate.
• skills/subagent-dev-with-codex-and-thermo-reviews/SKILL.md: frontend
  checkpoint after its final validation gate.
• skills/subagent-dev-with-validation-and-pr-checks/SKILL.md: frontend
  checkpoint after its final validation gate.
• README.md: user-facing workflow summary.
• THIRD_PARTY_NOTICES.md: source, pin, license, local path, and modification
  notices.
• .prettierignore: exclusions for verbatim upstream Markdown.
• .markdownlint-cli2.jsonc: exclusions for verbatim upstream Markdown.

Generated and packaging files

• .patchmill/skills/: regenerated project-local recommended pack.
• .patchmill/skills/patchmill-skill-pack.json: regenerated file hashes and
  upstream source records.
• bin/package-files.test.ts: npm package-content coverage.
• nix/package.nix: Nix source and initialized-pack install checks.

---

Task 1: Add the pinned source skills and package-content coverage

Files:

• Create: skills/frontend-design/SKILL.md
• Create: skills/frontend-design/LICENSE.txt
• Create: skills/patchmill-frontend-review/SKILL.md
• Create: skills/patchmill-frontend-review/LICENSE
• Create:
  skills/patchmill-frontend-review/references/upstream-web-design-guidelines.md
• Create:
  skills/patchmill-frontend-review/references/web-interface-guidelines.md
• Modify: bin/package-files.test.ts:45-87
• Modify: THIRD_PARTY_NOTICES.md:1-30
• Modify: .prettierignore:1-20
• Modify: .markdownlint-cli2.jsonc:12-30

Interfaces:

• Consumes: the exact upstream repositories, commits, and paths in Global
  Constraints.

• Produces: two packaged sibling skill directories. Later tasks reference their
  exact names and relative files.

• Step 1: Add the failing npm package assertions

Add these assertions to
npm pack dry-run includes bundled runtime resources and notices after the
existing patchmill-planning assertion:

assert.equal(files.has("skills/frontend-design/SKILL.md"), true);
assert.equal(files.has("skills/frontend-design/LICENSE.txt"), true);
assert.equal(files.has("skills/patchmill-frontend-review/SKILL.md"), true);
assert.equal(files.has("skills/patchmill-frontend-review/LICENSE"), true);
assert.equal(
  files.has(
    "skills/patchmill-frontend-review/references/upstream-web-design-guidelines.md",
  ),
  true,
);
assert.equal(
  files.has(
    "skills/patchmill-frontend-review/references/web-interface-guidelines.md",
  ),
  true,
);

Do not add assertions for notice prose or literal commit values. Those items use
direct verification in Step 5.

• Step 2: Run the package test and make sure that it fails

Run:

node --test bin/package-files.test.ts

Expected: FAIL because the new paths are absent from npm pack --dry-run.

• Step 3: Fetch the verbatim upstream files from immutable URLs

Run:

mkdir -p skills/frontend-design
mkdir -p skills/patchmill-frontend-review/references

curl --fail --silent --show-error --location \
  https://raw.githubusercontent.com/anthropics/skills/41bbe19d1a1a7eaab5e7bb9050a417e5c6cffc8f/skills/frontend-design/SKILL.md \
  --output skills/frontend-design/SKILL.md
curl --fail --silent --show-error --location \
  https://raw.githubusercontent.com/anthropics/skills/41bbe19d1a1a7eaab5e7bb9050a417e5c6cffc8f/skills/frontend-design/LICENSE.txt \
  --output skills/frontend-design/LICENSE.txt
curl --fail --silent --show-error --location \
  https://raw.githubusercontent.com/vercel-labs/agent-skills/ba46938889d4e58635362fb8f618e1178ac3ec46/skills/web-design-guidelines/SKILL.md \
  --output skills/patchmill-frontend-review/references/upstream-web-design-guidelines.md
curl --fail --silent --show-error --location \
  https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/e3d624baaf29dc1fc645aff3e38f03e564d2d6b1/command.md \
  --output skills/patchmill-frontend-review/references/web-interface-guidelines.md
curl --fail --silent --show-error --location \
  https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/e3d624baaf29dc1fc645aff3e38f03e564d2d6b1/LICENSE \
  --output skills/patchmill-frontend-review/LICENSE

Do not edit these five fetched files. The Vercel wrapper has a new local file
name so Pi does not discover its mutable WebFetch workflow.

• Step 4: Write the self-contained Patchmill frontend-review skill

Create skills/patchmill-frontend-review/SKILL.md with this contract:

---
name: patchmill-frontend-review
description:
  Use after Patchmill implementation validation and normal code review when the
  final scope contains meaningful user-visible frontend changes. Runs an
  independent review against pinned local interface guidelines.
---

# Patchmill Frontend Review

Run one independent frontend review after the invoking implementation workflow
closes its existing validation and normal review gates. Do not add a new
implementation process or visual-evidence stage.

## Required local reference

Read `references/web-interface-guidelines.md` relative to this skill directory.
This file is the pinned review rule set. Do not use `WebFetch`, fetch newer
rules, or substitute mutable network content.

`references/upstream-web-design-guidelines.md` is provenance only. Do not follow
its instruction to fetch the latest rules.

If this skill or a required reference is missing, stop with an evidenced
blocker. Do not silently skip frontend review.

## Activation

Activate this review when the final base-to-head scope changes browser-visible:

- layout or responsive behavior;
- typography, color, spacing, imagery, or other styling;
- interaction or motion;
- accessibility behavior;
- navigation or user flow.

Do not activate it for a copy-only edit unless the copy materially changes one
of these areas.

## Preconditions and inputs

The invoking wrapper must close its existing implementation, validation, and
normal review gates first. Then refresh the implementation base, current HEAD,
worktree status, and changed files.

Give the frontend reviewer:

- the issue requirements;
- the approved specification;
- the referenced mockup, when present;
- the implementation base and current HEAD;
- all changed frontend files;
- relevant repository policy and design-system guidance;
- available visual evidence.

Use available visual evidence as review input. Do not require a new capture pass
unless the repository's existing visual-evidence policy already requires it.

## Precedence

Apply this order when requirements conflict:

1. Explicit user and approved product requirements.
2. Repository policy and the existing design system.
3. The approved written specification.
4. The mockup as visual intent.
5. The pinned Vercel rules.

A material difference from the mockup needs a product or technical reason. Do
not require pixel-perfect agreement. Record the reason when a higher-priority
requirement overrides a generic rule.

## Independent review

Before dispatch, list the available subagents. Use the canonical executable
`reviewer`. Do not use the disabled `code-reviewer` compatibility role.

Dispatch a fresh-context, review-only reviewer. Do not inherit implementation
context. A different model or provider is not required. The reviewer must not
edit files.

Tell the reviewer to read the pinned local rule file and inspect the supplied
code and evidence. The reviewer must not use runtime network access to obtain
review rules.

## Output contract

Return `pass` when no actionable finding remains. Otherwise, return findings in
this form:

```text
Status: findings

- Severity: critical | important | minor
  User impact: State the specific effect on a user.
  Evidence: Cite the observed code, behavior, or visual evidence.
  Location: Give file:line, or write "visual evidence" when no line applies.
  Required correction: State one bounded correction.
  Rule: Cite the project, specification, mockup, or pinned guideline basis.
```

Do not report personal preference as a finding. Each finding must connect to a
higher-priority requirement or a pinned rule.

## Repair and repeat

Route valid findings through the invoking wrapper's existing worker and repair
process. Do not create another implementation workflow.

If a repair changes production code:

1. Refresh the base-to-head scope.
2. Rerun affected validation.
3. Rerun the invoking wrapper's normal review gates for the changed scope.
4. Dispatch a new fresh-context frontend reviewer.

If a repair does not change production code, dispatch a new frontend reviewer
without adding unrelated review work.

Repeat until the reviewer returns `pass` or the existing workflow returns an
evidenced external or operator blocker. Resolve every review and repair subagent
before the parent returns its final Patchmill result.

## Red flags

Never:

- run frontend review before normal validation and code review;
- let the frontend reviewer edit files;
- fetch mutable review rules;
- treat the mockup as a pixel-perfect contract;
- override project policy with a generic rule;
- add a second visual-evidence stage;
- bypass the invoking wrapper's worker or review topology;
- return success while a frontend review or repair run remains unresolved.

• Step 5: Register verbatim-file exclusions and add notices

Add these exact paths to .prettierignore:

skills/frontend-design/SKILL.md
skills/patchmill-frontend-review/references/upstream-web-design-guidelines.md
skills/patchmill-frontend-review/references/web-interface-guidelines.md

Add these exact paths to the ignores array in .markdownlint-cli2.jsonc:

"skills/frontend-design/SKILL.md",
"skills/patchmill-frontend-review/references/upstream-web-design-guidelines.md",
"skills/patchmill-frontend-review/references/web-interface-guidelines.md",

These exclusions protect verbatim upstream Markdown from local formatting
changes. The Patchmill-owned review wrapper remains subject to both tools.

Change the first sentence in THIRD_PARTY_NOTICES.md from “component” to
“components.” Then append these sections:

## Anthropic frontend-design skill

- Source:
  <https://github.com/anthropics/skills/tree/41bbe19d1a1a7eaab5e7bb9050a417e5c6cffc8f/skills/frontend-design>
- Repository: <https://github.com/anthropics/skills>
- Commit: `41bbe19d1a1a7eaab5e7bb9050a417e5c6cffc8f`
- License: Apache License 2.0 (`skills/frontend-design/LICENSE.txt`)
- Purpose: Provides specification-time visual design guidance for meaningful
  frontend changes.

Patchmill vendors the skill and license without modification under
`skills/frontend-design/`.

## Vercel web-design-guidelines wrapper

- Source:
  <https://github.com/vercel-labs/agent-skills/blob/ba46938889d4e58635362fb8f618e1178ac3ec46/skills/web-design-guidelines/SKILL.md>
- Repository: <https://github.com/vercel-labs/agent-skills>
- Commit: `ba46938889d4e58635362fb8f618e1178ac3ec46`
- License: MIT, as declared in the repository README license section
- Purpose: Provides the upstream review workflow on which Patchmill's local
  frontend-review contract is based.

Patchmill stores a verbatim, renamed reference at
`skills/patchmill-frontend-review/references/upstream-web-design-guidelines.md`.
The Patchmill-owned active wrapper removes the runtime fetch behavior.

## Vercel Web Interface Guidelines

- Source:
  <https://github.com/vercel-labs/web-interface-guidelines/blob/e3d624baaf29dc1fc645aff3e38f03e564d2d6b1/command.md>
- Repository: <https://github.com/vercel-labs/web-interface-guidelines>
- Commit: `e3d624baaf29dc1fc645aff3e38f03e564d2d6b1`
- License: MIT (`skills/patchmill-frontend-review/LICENSE`)
- Purpose: Provides the pinned, offline rule set for independent frontend
  review.

Patchmill stores the rules without modification at
`skills/patchmill-frontend-review/references/web-interface-guidelines.md`.

• Step 6: Compare the copies with upstream and run focused checks

Run:

tmp_dir="$(mktemp -d)"
trap 'rm -rf "$tmp_dir"' EXIT

curl -fsSL https://raw.githubusercontent.com/anthropics/skills/41bbe19d1a1a7eaab5e7bb9050a417e5c6cffc8f/skills/frontend-design/SKILL.md >"$tmp_dir/anthropic-skill.md"
curl -fsSL https://raw.githubusercontent.com/anthropics/skills/41bbe19d1a1a7eaab5e7bb9050a417e5c6cffc8f/skills/frontend-design/LICENSE.txt >"$tmp_dir/anthropic-license.txt"
curl -fsSL https://raw.githubusercontent.com/vercel-labs/agent-skills/ba46938889d4e58635362fb8f618e1178ac3ec46/skills/web-design-guidelines/SKILL.md >"$tmp_dir/vercel-skill.md"
curl -fsSL https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/e3d624baaf29dc1fc645aff3e38f03e564d2d6b1/command.md >"$tmp_dir/vercel-rules.md"
curl -fsSL https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/e3d624baaf29dc1fc645aff3e38f03e564d2d6b1/LICENSE >"$tmp_dir/vercel-license"

cmp "$tmp_dir/anthropic-skill.md" skills/frontend-design/SKILL.md
cmp "$tmp_dir/anthropic-license.txt" skills/frontend-design/LICENSE.txt
cmp "$tmp_dir/vercel-skill.md" skills/patchmill-frontend-review/references/upstream-web-design-guidelines.md
cmp "$tmp_dir/vercel-rules.md" skills/patchmill-frontend-review/references/web-interface-guidelines.md
cmp "$tmp_dir/vercel-license" skills/patchmill-frontend-review/LICENSE

! rg -n 'Fetch the latest|Use WebFetch to retrieve|raw\.githubusercontent\.com' skills/patchmill-frontend-review/SKILL.md
node --test bin/package-files.test.ts
npx prettier --check skills/patchmill-frontend-review/SKILL.md THIRD_PARTY_NOTICES.md bin/package-files.test.ts .markdownlint-cli2.jsonc
npx markdownlint-cli2 skills/patchmill-frontend-review/SKILL.md THIRD_PARTY_NOTICES.md

Expected: all cmp commands and checks exit 0. The negated rg command must
find no runtime-fetch instruction in the active wrapper.

• Step 7: Commit the source skills

git add skills/frontend-design skills/patchmill-frontend-review bin/package-files.test.ts THIRD_PARTY_NOTICES.md .prettierignore .markdownlint-cli2.jsonc
git commit -m "feat(skills): add pinned frontend guidance"

---

Task 2: Add required-file and upstream provenance models

Files:

• Modify: src/workflow/skill-pack.ts:9-180
• Modify: src/workflow/skill-pack.test.ts:1-189

Interfaces:

• Consumes: packaged skill-relative target paths from Task 1.

• Produces: requiredSkillFilesForEntry(skill), richer SkillPackSkill
  entries, and generated SkillPackMetadataFile.skills records for Tasks 3
  and 5.

• Step 1: Write failing tests for required files and metadata path
  rendering

Extend the imports in src/workflow/skill-pack.test.ts with the new entry
helper and types. Add behavior tests based on fixture provenance rather than
production commit literals:

import {
  // existing imports
  requiredSkillFilesForEntry,
  type SkillPackSkill,
} from "./skill-pack.ts";

const fixturePackSkill: SkillPackSkill = {
  name: "fixture-review",
  source: "patchmill",
  requiredFiles: ["SKILL.md", "../fixture-rules/LICENSE"],
  upstreamSources: [
    {
      repository: "example/rules",
      commit: "0123456789abcdef",
      files: [
        {
          sourcePath: "command.md",
          targetPath: "references/rules.md",
        },
      ],
      license: {
        name: "MIT",
        sourcePath: "LICENSE",
        targetPath: "LICENSE",
      },
    },
  ],
};

test("required skill files use pack entry requirements", () => {
  assert.deepEqual(requiredSkillFilesForEntry(fixturePackSkill), [
    "SKILL.md",
    "../fixture-rules/LICENSE",
  ]);
  assert.deepEqual(requiredSkillFiles("frontend-design"), [
    "SKILL.md",
    "LICENSE.txt",
  ]);
  assert.deepEqual(requiredSkillFiles("patchmill-planning"), [
    "SKILL.md",
    "../frontend-design/SKILL.md",
    "../frontend-design/LICENSE.txt",
  ]);
});

test("buildSkillPackMetadata renders installed provenance paths", () => {
  const metadata = buildSkillPackMetadata([], {
    skillDir: "custom/skills/",
    skills: [fixturePackSkill],
  });

  assert.deepEqual(metadata.skills, [
    {
      name: "fixture-review",
      source: "patchmill",
      requiredFiles: [
        "custom/skills/fixture-review/SKILL.md",
        "custom/skills/fixture-rules/LICENSE",
      ],
      upstreamSources: [
        {
          repository: "example/rules",
          commit: "0123456789abcdef",
          files: [
            {
              sourcePath: "command.md",
              installedPath: "custom/skills/fixture-review/references/rules.md",
            },
          ],
          license: {
            name: "MIT",
            sourcePath: "LICENSE",
            installedPath: "custom/skills/fixture-review/LICENSE",
          },
        },
      ],
    },
  ]);
});

Update the existing metadata test to expect a skills array. Pass a small
skills fixture to keep that test independent from the full recommended pack.
Use this input and expected field in that test:

const skills: SkillPackSkill[] = [
  { name: "writing-plans", source: "superpowers" },
];
const metadata = buildSkillPackMetadata(files, {
  skillDir: "custom/skills/",
  skills,
});

assert.deepEqual(metadata.skills, [
  {
    name: "writing-plans",
    source: "superpowers",
    requiredFiles: ["custom/skills/writing-plans/SKILL.md"],
  },
]);

Update the existing recommended-pack expectation for the new version and
entries. Keep the uniqueness assertion. Do not add a new test whose only purpose
is to pin a commit string.

• Step 2: Run the skill-pack tests and make sure that they fail

Run:

node --test src/workflow/skill-pack.test.ts

Expected: FAIL because the new types, helper, pack entries, and metadata field
do not exist.

• Step 3: Add the provenance types and metadata renderer

In src/workflow/skill-pack.ts, import posix from node:path and add these
public types:

export type SkillPackUpstreamFile = {
  sourcePath: string;
  targetPath: string;
};

export type SkillPackUpstreamLicense = {
  name: string;
  sourcePath: string;
  targetPath?: string;
};

export type SkillPackUpstreamSource = {
  repository: string;
  commit: string;
  files: SkillPackUpstreamFile[];
  license: SkillPackUpstreamLicense;
};

export type SkillPackSkill = {
  name: string;
  source: "patchmill" | "superpowers";
  requiredFiles?: string[];
  upstreamSources?: SkillPackUpstreamSource[];
};

export type SkillPackMetadataSkill = {
  name: string;
  source: SkillPackSkill["source"];
  requiredFiles: string[];
  upstreamSources?: Array<{
    repository: string;
    commit: string;
    files: Array<{ sourcePath: string; installedPath: string }>;
    license: {
      name: string;
      sourcePath: string;
      installedPath?: string;
    };
  }>;
};

Add skills?: SkillPackMetadataSkill[] to SkillPackMetadataFile. The field is
optional only so an old managed metadata file remains updateable.
buildSkillPackMetadata must always return it.

Add these interfaces for required files and path rendering:

export function requiredSkillFilesForEntry(skill: SkillPackSkill): string[] {
  return (
    skill.requiredFiles ?? requiredFilesForBundledSkillName(skill.name)
  ).slice();
}

export function requiredSkillFiles(skillName: string): string[] {
  const packSkill = PATCHMILL_RECOMMENDED_SKILL_PACK.skills.find(
    (skill) => skill.name === skillName,
  );
  return packSkill
    ? requiredSkillFilesForEntry(packSkill)
    : requiredFilesForBundledSkillName(skillName);
}

function installedSkillFilePath(
  skillDir: string,
  skillName: string,
  relativePath: string,
): string {
  return posix.normalize(
    `${trimTrailingSkillDirSlashes(skillDir)}/${skillName}/${relativePath}`,
  );
}

function buildMetadataSkill(
  skill: SkillPackSkill,
  skillDir: string,
): SkillPackMetadataSkill {
  const upstreamSources = skill.upstreamSources?.map((source) => ({
    repository: source.repository,
    commit: source.commit,
    files: source.files.map((file) => ({
      sourcePath: file.sourcePath,
      installedPath: installedSkillFilePath(
        skillDir,
        skill.name,
        file.targetPath,
      ),
    })),
    license: {
      name: source.license.name,
      sourcePath: source.license.sourcePath,
      ...(source.license.targetPath
        ? {
            installedPath: installedSkillFilePath(
              skillDir,
              skill.name,
              source.license.targetPath,
            ),
          }
        : {}),
    },
  }));

  return {
    name: skill.name,
    source: skill.source,
    requiredFiles: requiredSkillFilesForEntry(skill).map((file) =>
      installedSkillFilePath(skillDir, skill.name, file),
    ),
    ...(upstreamSources ? { upstreamSources } : {}),
  };
}

Extend buildSkillPackMetadata options with skills?: SkillPackSkill[]. Use
the supplied entries or PATCHMILL_RECOMMENDED_SKILL_PACK.skills, and return
freshly mapped metadata:

export function buildSkillPackMetadata(
  files: Array<{ path: string; sha256: string }>,
  options: {
    installedAt?: string;
    skillDir?: string;
    skills?: SkillPackSkill[];
  } = {},
): SkillPackMetadataFile {
  const skillDir = trimTrailingSkillDirSlashes(
    options.skillDir ?? DEFAULT_PROJECT_SKILL_DIR,
  );
  const skills = options.skills ?? PATCHMILL_RECOMMENDED_SKILL_PACK.skills;

  return {
    pack: {
      name: PATCHMILL_RECOMMENDED_SKILL_PACK.name,
      version: PATCHMILL_RECOMMENDED_SKILL_PACK.version,
      source: PATCHMILL_RECOMMENDED_SKILL_PACK.source,
    },
    installedAt: options.installedAt ?? "<generated-by-init>",
    skillDir,
    metadataFile: SKILL_PACK_METADATA_FILE,
    skills: skills.map((skill) => buildMetadataSkill(skill, skillDir)),
    files: files.map((file) => ({ ...file })),
  };
}

• Step 4: Add the exact recommended-pack entries

Change the pack version to 2026.09.1. Add these entries while leaving all
existing Superpowers entries and their release source unchanged:

{
  name: "frontend-design",
  source: "patchmill",
  requiredFiles: ["SKILL.md", "LICENSE.txt"],
  upstreamSources: [
    {
      repository: "anthropics/skills",
      commit: "41bbe19d1a1a7eaab5e7bb9050a417e5c6cffc8f",
      files: [
        {
          sourcePath: "skills/frontend-design/SKILL.md",
          targetPath: "SKILL.md",
        },
        {
          sourcePath: "skills/frontend-design/LICENSE.txt",
          targetPath: "LICENSE.txt",
        },
      ],
      license: {
        name: "Apache-2.0",
        sourcePath: "skills/frontend-design/LICENSE.txt",
        targetPath: "LICENSE.txt",
      },
    },
  ],
},
{
  name: "patchmill-frontend-review",
  source: "patchmill",
  requiredFiles: [
    "SKILL.md",
    "LICENSE",
    "references/upstream-web-design-guidelines.md",
    "references/web-interface-guidelines.md",
  ],
  upstreamSources: [
    {
      repository: "vercel-labs/agent-skills",
      commit: "ba46938889d4e58635362fb8f618e1178ac3ec46",
      files: [
        {
          sourcePath: "skills/web-design-guidelines/SKILL.md",
          targetPath: "references/upstream-web-design-guidelines.md",
        },
      ],
      license: {
        name: "MIT",
        sourcePath: "README.md#license",
      },
    },
    {
      repository: "vercel-labs/web-interface-guidelines",
      commit: "e3d624baaf29dc1fc645aff3e38f03e564d2d6b1",
      files: [
        {
          sourcePath: "command.md",
          targetPath: "references/web-interface-guidelines.md",
        },
        { sourcePath: "LICENSE", targetPath: "LICENSE" },
      ],
      license: {
        name: "MIT",
        sourcePath: "LICENSE",
        targetPath: "LICENSE",
      },
    },
  ],
},

Set these exact new sibling requirements on the current wrapper entries:

const frontendReviewSiblingFiles = [
  "../patchmill-frontend-review/SKILL.md",
  "../patchmill-frontend-review/LICENSE",
  "../patchmill-frontend-review/references/upstream-web-design-guidelines.md",
  "../patchmill-frontend-review/references/web-interface-guidelines.md",
];

// On each of the three implementation wrapper entries:
requiredFiles: ["SKILL.md", ...frontendReviewSiblingFiles],

// On the patchmill-planning entry:
requiredFiles: [
  "SKILL.md",
  "../frontend-design/SKILL.md",
  "../frontend-design/LICENSE.txt",
],

Keep frontendReviewSiblingFiles private to the module. Place both new skill
entries before the Superpowers entries so installer output remains grouped by
source root.

• Step 5: Run the focused tests and make sure that they pass

Run:

node --test src/workflow/skill-pack.test.ts
npm run lint:ts -- --no-warn-ignored src/workflow/skill-pack.ts src/workflow/skill-pack.test.ts

Expected: PASS.

• Step 6: Commit the pack model

git add src/workflow/skill-pack.ts src/workflow/skill-pack.test.ts
git commit -m "feat(skills): record upstream skill provenance"

---

Task 3: Enforce required files during install, update, and doctor checks

Files:

• Modify: src/cli/commands/init/skill-installer.ts:24-454
• Modify: src/cli/commands/init/skill-installer.test.ts:1-562
• Modify: src/cli/commands/init/skill-installer-path-mode.test.ts:1-309
• Modify: src/cli/commands/skills/update.ts:15-404
• Modify: src/cli/commands/skills/update.test.ts:1-287
• Modify: src/cli/commands/doctor/checks.test.ts:1-914

Interfaces:

• Consumes: SkillPackSkill.requiredFiles, requiredSkillFilesForEntry, and
  metadata rendering from Task 2.

• Produces: atomic install/update behavior that validates every sidecar,
  backward-compatible metadata updates, and doctor diagnostics for missing
  configured-wrapper siblings.

• Step 1: Add failing installer tests

In skill-installer.test.ts, use a local packSkills variable in the main
custom-pack test. Pass that same array to installProjectSkills and to
buildSkillPackMetadata(..., { skills: packSkills }).

Add this preflight regression test:

test("installProjectSkills preflights declared required files", async () => {
  const repoRoot = await tempRoot("patchmill-install-required-repo-");
  const patchmillSource = await tempRoot("patchmill-install-required-source-");
  await writeSkill(patchmillSource, "frontend-design", brainstormingSkill);

  await assert.rejects(
    installProjectSkills({
      repoRoot,
      sourceRoots: {
        patchmillSkillsDir: patchmillSource,
        superpowersSkillsDir: await tempRoot(
          "patchmill-install-required-superpowers-",
        ),
      },
      packSkills: [
        {
          name: "frontend-design",
          source: "patchmill",
          requiredFiles: ["SKILL.md", "LICENSE.txt"],
        },
      ],
    }),
    /Missing required skill file: frontend-design\/LICENSE\.txt/u,
  );

  await assert.rejects(
    access(join(repoRoot, ".patchmill", "skills")),
    (error: unknown) =>
      error instanceof Error && "code" in error && error.code === "ENOENT",
  );
});

Add a default-pack test that installs into a temporary repository and reads all
six required new files. Assert that metadata.skills contains frontend-design
and patchmill-frontend-review, with installed paths below
.patchmill/skills/.

Use this test body:

test("installProjectSkills installs frontend workflow siblings", async () => {
  const repoRoot = await tempRoot("patchmill-install-frontend-repo-");
  const result = await installProjectSkills({
    repoRoot,
    installedAt: "2026-09-07T00:00:00.000Z",
  });

  const requiredPaths = [
    "frontend-design/SKILL.md",
    "frontend-design/LICENSE.txt",
    "patchmill-frontend-review/SKILL.md",
    "patchmill-frontend-review/LICENSE",
    "patchmill-frontend-review/references/upstream-web-design-guidelines.md",
    "patchmill-frontend-review/references/web-interface-guidelines.md",
  ];
  for (const path of requiredPaths) {
    assert.notEqual(
      (await readFile(join(repoRoot, ".patchmill", "skills", path))).length,
      0,
    );
  }

  const metadata = JSON.parse(
    await readFile(result.metadataPath, "utf8"),
  ) as ReturnType<typeof buildSkillPackMetadata>;
  const skillNames = new Set(metadata.skills?.map((skill) => skill.name));
  assert.equal(skillNames.has("frontend-design"), true);
  assert.equal(skillNames.has("patchmill-frontend-review"), true);
  assert.equal(
    metadata.skills?.every((skill) =>
      skill.requiredFiles.every((path) =>
        path.startsWith(".patchmill/skills/"),
      ),
    ),
    true,
  );
});

• Step 2: Add failing path-mode and doctor tests

In skill-installer-path-mode.test.ts, add a helper that writes minimal
frontend siblings:

async function writeFrontendWorkflowSkills(
  root: string,
  skillDir: string,
  omit?: string,
): Promise<void> {
  const files = {
    "frontend-design/SKILL.md": `---\nname: frontend-design\ndescription: Design frontend work.\n---\n`,
    "frontend-design/LICENSE.txt": "Apache-2.0\n",
    "patchmill-frontend-review/SKILL.md": `---\nname: patchmill-frontend-review\ndescription: Review frontend work.\n---\n`,
    "patchmill-frontend-review/LICENSE": "MIT\n",
    "patchmill-frontend-review/references/upstream-web-design-guidelines.md":
      "upstream wrapper\n",
    "patchmill-frontend-review/references/web-interface-guidelines.md":
      "pinned rules\n",
  };

  for (const [path, content] of Object.entries(files)) {
    if (path === omit) continue;
    await mkdir(join(root, skillDir, path, ".."), { recursive: true });
    await writeFile(join(root, skillDir, path), content);
  }
}

Extend writeBaseProjectLocalSkills with an optional
{ omitFrontendPath?: string } argument. Call
writeFrontendWorkflowSkills(repoRoot, "project-skills", options.omitFrontendPath)
at the end of that helper. This updates every existing successful fixture.

The test named
validateExistingSkillDirectory fails when planning wrapper siblings are missing
assembles its fixture without writeBaseProjectLocalSkills. Call
writeFrontendWorkflowSkills(repoRoot, "project-skills") in that test before
validation. Keep brainstorming/SKILL.md absent so the test still reaches its
intended assertion.

Call the same helper in every other manually assembled path-mode fixture that
must reach a later diagnostic. These tests cover the missing visual-evidence
helper, missing required triage skill, and directory-valued SKILL.md cases. Do
not add the helper to the new missing-frontend table because that table owns its
frontend setup.

In checks.test.ts, add a matching
writeProjectLocalFrontendWorkflowSkills(repoRoot) helper that writes all six
minimal frontend files below DEFAULT_PROJECT_SKILL_DIR. Call it in every
existing fixture that uses recommendedProjectLocalConfig() and must reach a
visual-evidence, metadata, smoke-load, or ignore-state assertion. Do not call it
in the new missing-frontend doctor test. That test must keep its missing
sibling.

Add this table-driven missing-file test:

test("validateExistingSkillDirectory rejects missing frontend workflow files", async () => {
  for (const missingPath of [
    "frontend-design/SKILL.md",
    "frontend-design/LICENSE.txt",
    "patchmill-frontend-review/SKILL.md",
    "patchmill-frontend-review/LICENSE",
    "patchmill-frontend-review/references/upstream-web-design-guidelines.md",
    "patchmill-frontend-review/references/web-interface-guidelines.md",
  ]) {
    const repoRoot = await tempRoot("patchmill-install-frontend-missing-");
    await writeBaseProjectLocalSkills(repoRoot, {
      omitFrontendPath: missingPath,
    });
    await writeValidationWrapperDependencies(repoRoot, "project-skills");

    await assert.rejects(
      validateExistingSkillDirectory(repoRoot, "project-skills"),
      new RegExp(
        `Missing required skill file: project-skills/${missingPath}`.replaceAll(
          "/",
          "\\/",
        ),
      ),
    );
  }
});

In checks.test.ts, add a doctor test for the configured planning wrapper:

test("runDoctorChecks fails when the planning frontend sibling is missing", async () => {
  const repoRoot = await tempRepo();
  await writeConfig(repoRoot, {
    host: { provider: "forgejo-tea", login: "triage-agent" },
    skills: {
      planning: `${DEFAULT_PROJECT_SKILL_DIR}/patchmill-planning`,
    },
  });
  await mkdir(join(repoRoot, "docs"), { recursive: true });
  await writeProjectLocalSkill(
    repoRoot,
    "patchmill-planning",
    skillDocument("patchmill-planning", "Plan Patchmill work."),
  );

  const results = await runDoctorChecks(
    runnerFrom(successMocks(REQUIRED_LABELS)),
    { repoRoot, teaRepoRootForTests: "/repo" },
  );
  const skills = results.find((result) => result.name === "skills");

  assert.equal(skills?.status, "fail");
  assert.match(
    skills?.message ?? "",
    /required skill file unreadable at .*frontend-design.*SKILL\.md/u,
  );
});

• Step 3: Add failing update tests

Update the current-pack fixture to use buildSkillPackMetadata with the exact
custom packSkills array. Then add a provenance-only update test:

test("updateProjectSkills refreshes changed provenance metadata", async () => {
  const repoRoot = await tempRoot("patchmill-skills-provenance-repo-");
  const patchmillSource = await tempRoot("patchmill-skills-provenance-source-");
  await writeSkill(patchmillSource, "fixture-review", {
    "SKILL.md": newPatchmillPlanning,
  });
  await writeFileEnsuringParent(
    join(repoRoot, ".patchmill", "skills", "fixture-review", "SKILL.md"),
    newPatchmillPlanning,
  );

  const oldSkill = {
    name: "fixture-review",
    source: "patchmill" as const,
    upstreamSources: [
      {
        repository: "example/rules",
        commit: "old-commit",
        files: [{ sourcePath: "command.md", targetPath: "SKILL.md" }],
        license: { name: "MIT", sourcePath: "LICENSE" },
      },
    ],
  };
  const newSkill = {
    ...oldSkill,
    upstreamSources: [{ ...oldSkill.upstreamSources[0], commit: "new-commit" }],
  };
  const files = [
    {
      path: ".patchmill/skills/fixture-review/SKILL.md",
      sha256: hashText(newPatchmillPlanning),
    },
  ];
  await writeMetadata(
    repoRoot,
    buildSkillPackMetadata(files, { skills: [oldSkill] }),
  );

  const result = await updateProjectSkills({
    repoRoot,
    sourceRoots: {
      patchmillSkillsDir: patchmillSource,
      superpowersSkillsDir: await tempRoot(
        "patchmill-skills-provenance-superpowers-",
      ),
    },
    packSkills: [newSkill],
    installedAt: "2026-09-07T00:00:00.000Z",
    dependencies,
  });

  assert.equal(result.status, "updated");
  assert.equal(result.status === "updated" && result.updatedFiles, 0);
  const metadata = JSON.parse(
    await readFile(
      join(repoRoot, ".patchmill", "skills", SKILL_PACK_METADATA_FILE),
      "utf8",
    ),
  ) as SkillPackMetadataFile;
  assert.equal(
    metadata.skills?.[0]?.upstreamSources?.[0]?.commit,
    "new-commit",
  );
});

Add a preflight regression test named
updateProjectSkills rejects a missing declared sidecar before mutation. Use a
custom Patchmill skill with requiredFiles: ["SKILL.md", "LICENSE"]. Put only
SKILL.md in its source directory. Seed an old managed installed copy and its
metadata. Save the installed file and metadata contents before the update. The
update must reject with Missing required skill file: fixture-review/LICENSE.
The installed file and metadata must remain byte-for-byte unchanged after
rejection.

Add table-driven malformed-metadata coverage to
updateProjectSkills rejects malformed metadata shapes. Keep the existing
malformed base record. Add present skills cases for:

• a non-array value;
• a skill without a valid name, source, or non-empty requiredFiles array;
• a required-file path outside .patchmill/skills/;
• an upstream record with an empty repository, commit, file source path, or
  license name;
• an upstream installed file or license path outside .patchmill/skills/.

Write each malformed record as raw JSON so TypeScript types do not hide the
invalid input. Each case must reject with the existing unmanaged-pack error.
These tests protect the update boundary rather than restate static metadata.

Keep oldMetadata without skills. The existing clean update test then proves
backward compatibility. Add the 2026.09.1 informational notice to its expected
notice list.

• Step 4: Run the focused tests and make sure that they fail

Run:

node --test \
  src/cli/commands/init/skill-installer.test.ts \
  src/cli/commands/init/skill-installer-path-mode.test.ts \
  src/cli/commands/skills/update.test.ts \
  src/cli/commands/doctor/checks.test.ts

Expected: FAIL on missing required-file enforcement, direct-path reporting,
metadata propagation, provenance comparison, malformed metadata validation, and
update atomicity.

• Step 5: Use entry requirements in installer and update preflight

Import requiredSkillFilesForEntry where needed.

Change assertRequiredSkillFiles in skill-installer.ts to accept a
SkillPackSkill | string. Use requiredSkillFilesForEntry for an entry and
requiredSkillFiles for a name:

async function assertRequiredSkillFiles(
  skill: SkillPackSkill | string,
  skillDir: string,
  displayRoot: string,
  dependencies: SkillInstallerDependencies = defaultDependencies,
): Promise<void> {
  const requiredFiles =
    typeof skill === "string"
      ? requiredSkillFiles(skill)
      : requiredSkillFilesForEntry(skill);
  for (const relativeFile of requiredFiles) {
    const displayPath = `${displayRoot}/${relativeFile}`;
    await assertSkillFile(
      join(skillDir, relativeFile),
      displayPath,
      dependencies,
    );
  }
}

Pass the complete skill entry from the install loop. Pass skills: packSkills
to buildSkillPackMetadata:

const metadata = buildSkillPackMetadata(files, {
  installedAt: options.installedAt ?? new Date().toISOString(),
  skillDir,
  skills: packSkills,
});

In update.ts, replace its one-file SKILL.md preflight with:

for (const relativeFile of requiredSkillFilesForEntry(skill)) {
  await assertSkillFile(
    join(sourceDir, relativeFile),
    `${skill.name}/${relativeFile}`,
    options.dependencies,
  );
}

Paths with .. are intentional sibling requirements. They validate local source
files but collectSourceFiles still copies only the current skill directory.

• Step 6: Validate existing frontend siblings

In validateExistingSkillDirectory, add these entries to the existing
required-skill loop:

{
  name: "frontend-design",
  skillPath: projectSkillPath("frontend-design", skillDir),
},
{
  name: "patchmill-frontend-review",
  skillPath: projectSkillPath("patchmill-frontend-review", skillDir),
},

Place both direct frontend-directory entries at the start of the validation
array. They must come before ...bundledRecommendedSkills,
patchmill-planning, and the configured implementation wrapper. This order
makes a missing direct frontend file report its normalized direct path before a
sibling dependency reports the same file through ...

Keep the existing explicit Superpowers scripts and shared prompt checks. Do not
move unrelated validation into the pack model.

The existing doctor implementation already asks requiredSkillFiles for a
configured skill's frontmatter name. No production change in checks.ts is
necessary.

• Step 7: Generate, validate, and compare metadata during update

Pass skills: packSkills to buildSkillPackMetadata in update.ts.

Add a validator for an optional metadata skills array. It must accept an
absent array for old metadata and reject malformed present records. Reuse
isProjectSkillFilePath for requiredFiles, installed source files, and
installed license paths. Require non-empty repository, commit, source path, and
license name values.

Add these validators beside the existing metadata guards:

function isMetadataUpstreamFile(value: unknown): boolean {
  return (
    isRecord(value) &&
    isNonEmptyString(value.sourcePath) &&
    isProjectSkillFilePath(value.installedPath)
  );
}

function isMetadataUpstreamLicense(value: unknown): boolean {
  return (
    isRecord(value) &&
    isNonEmptyString(value.name) &&
    isNonEmptyString(value.sourcePath) &&
    (value.installedPath === undefined ||
      isProjectSkillFilePath(value.installedPath))
  );
}

function isMetadataUpstreamSource(value: unknown): boolean {
  return (
    isRecord(value) &&
    isNonEmptyString(value.repository) &&
    isNonEmptyString(value.commit) &&
    Array.isArray(value.files) &&
    value.files.length > 0 &&
    value.files.every(isMetadataUpstreamFile) &&
    isMetadataUpstreamLicense(value.license)
  );
}

function isMetadataSkill(value: unknown): boolean {
  return (
    isRecord(value) &&
    isNonEmptyString(value.name) &&
    (value.source === "patchmill" || value.source === "superpowers") &&
    Array.isArray(value.requiredFiles) &&
    value.requiredFiles.length > 0 &&
    value.requiredFiles.every(isProjectSkillFilePath) &&
    (value.upstreamSources === undefined ||
      (Array.isArray(value.upstreamSources) &&
        value.upstreamSources.every(isMetadataUpstreamSource)))
  );
}

function isMetadataSkills(value: unknown): boolean {
  return (
    value === undefined ||
    (Array.isArray(value) && value.every(isMetadataSkill))
  );
}

Add this clause to assertPatchmillManagedProjectLocal:

!isMetadataSkills(metadata.skills) ||

Extend the up-to-date comparison:

const sameSkills =
  metadata.skills !== undefined &&
  JSON.stringify(metadata.skills) === JSON.stringify(newMetadata.skills);

if (
  metadata.pack.version === newMetadata.pack.version &&
  JSON.stringify(metadata.pack.source) ===
    JSON.stringify(newMetadata.pack.source) &&
  sameSkills &&
  sameFiles(metadata.files, newMetadata.files)
) {
  return { status: "up-to-date", version: newMetadata.pack.version };
}

An old metadata file has no skills, so the first update rewrites it. A change
to provenance also causes an update when file hashes do not change.

Add this notice to VERSION_NOTICES:

{
  version: "2026.09.1",
  message:
    "Patchmill's recommended skill pack now adds conditional frontend design guidance and independent frontend review for meaningful visible UI changes.\n" +
    "No patchmill.config.json change is required.",
},

• Step 8: Run focused tests and lint

Run:

node --test \
  src/workflow/skill-pack.test.ts \
  src/cli/commands/init/skill-installer.test.ts \
  src/cli/commands/init/skill-installer-path-mode.test.ts \
  src/cli/commands/skills/update.test.ts \
  src/cli/commands/doctor/checks.test.ts
npm run lint:ts -- --no-warn-ignored \
  src/workflow/skill-pack.ts \
  src/workflow/skill-pack.test.ts \
  src/cli/commands/init/skill-installer.ts \
  src/cli/commands/init/skill-installer.test.ts \
  src/cli/commands/init/skill-installer-path-mode.test.ts \
  src/cli/commands/skills/update.ts \
  src/cli/commands/skills/update.test.ts \
  src/cli/commands/doctor/checks.test.ts

Expected: PASS.

• Step 9: Commit installer and update behavior

git add \
  src/cli/commands/init/skill-installer.ts \
  src/cli/commands/init/skill-installer.test.ts \
  src/cli/commands/init/skill-installer-path-mode.test.ts \
  src/cli/commands/skills/update.ts \
  src/cli/commands/skills/update.test.ts \
  src/cli/commands/doctor/checks.test.ts
git commit -m "feat(skills): validate frontend skill sources"

---

Task 4: Compose frontend design and review into existing wrappers

Files:

• Modify: src/cli/commands/run-once/prompts.ts:687-703
• Modify: src/cli/commands/run-once/prompts.test.ts:105-145
• Modify: skills/patchmill-planning/SKILL.md:12-78
• Modify:
  skills/single-subagent-dev-with-codex-and-thermo-reviews/SKILL.md:20-307
• Modify: skills/subagent-dev-with-codex-and-thermo-reviews/SKILL.md:18-270
• Modify: skills/subagent-dev-with-validation-and-pr-checks/SKILL.md:19-209
• Modify: README.md:50-90

Interfaces:

• Consumes: sibling skill paths from Task 1 and the review contract in
  patchmill-frontend-review/SKILL.md.

• Produces: a compatible specification-artifact prompt plus conditional
  specification and final-review behavior without a new configuration or runtime
  seam.

• Step 1: Add a failing specification-prompt behavior test

Extend buildSpecCreationPrompt instructs Pi to save and commit the spec in
prompts.test.ts with these assertions:

assert.match(prompt, /Do not implement product changes/);
assert.match(
  prompt,
  /Required planning-only companion artifacts, such as HTML mockups, are allowed when the configured planning skill requires them/,
);
assert.match(
  prompt,
  /Commit the spec document and any required companion planning artifacts using one Conventional Commit message/,
);
assert.doesNotMatch(prompt, /Do not implement code/);
assert.doesNotMatch(prompt, /Commit only the spec document/);

Run:

node --test src/cli/commands/run-once/prompts.test.ts

Expected: FAIL because the prompt still prohibits all code and permits only the
specification in its commit. This test passes the Testing Value Gate because it
protects an executable runtime contract.

• Step 2: Permit required specification companion artifacts

In buildSpecCreationPrompt, replace the broad product-change guard with:

`Treat \`${ready}\` as meaning the issue is clear enough for automation to write a design spec. Do not implement product changes. Required planning-only companion artifacts, such as HTML mockups, are allowed when the configured planning skill requires them.`,

Replace the specification commit instruction with:

"Commit the spec document and any required companion planning artifacts using one Conventional Commit message. Do not commit product implementation changes.",

Do not add frontend activation rules, sibling names, mockup paths, or review
orchestration to TypeScript. Those rules remain in the sibling skills.

Run:

node --test src/cli/commands/run-once/prompts.test.ts
npm run lint:ts -- --no-warn-ignored \
  src/cli/commands/run-once/prompts.ts \
  src/cli/commands/run-once/prompts.test.ts

Expected: PASS.

• Step 3: Extend patchmill-planning with the frontend sibling

Add this required sibling after the existing brainstorming and writing-plans
bullets:

- For meaningful user-visible frontend work, read `../frontend-design/SKILL.md`
  during the brainstorming process. This is supporting design guidance, not a
  phase after brainstorming. Existing project design systems and approved
  product requirements take precedence.

Add this section after Spec artifacts:

### Frontend specification augmentation

Activate this augmentation when proposed work changes browser-visible layout,
responsive behavior, styling, interaction, motion, accessibility, navigation, or
user flow. Do not activate it for a copy-only edit unless the copy materially
changes one of those areas. State whether the augmentation activates.

When it activates:

1. Follow the normal sibling `brainstorming` workflow.
2. Read and apply the sibling `frontend-design` guidance while shaping the
   design.
3. After design approval, create `docs/mockups/YYYY-MM-DD-<topic>.html` in the
   active issue worktree.
4. Make the mockup a self-contained file with embedded CSS and JavaScript, no
   required network assets, and no build step.
5. Make sure that the mockup opens directly from disk without a local server.
6. Show the changed UI in a complete responsive page at mobile and desktop
   widths. Do not show only isolated components.
7. Use semantic HTML, visible keyboard focus, and reduced-motion handling where
   applicable.
8. Link the mockup from the specification with a repository-relative path.
9. Commit the mockup with the specification as a companion planning artifact.

The mockup records visual intent. It is not a pixel-perfect contract. Written
requirements, repository policy, and the existing design system take precedence.

If the required mockup is absent, not self-contained, or not linked from the
specification, stop before the sibling `writing-plans` workflow. When writing
the plan, list the specification and its mockup as implementation inputs.

This wrapper text explicitly overrides the upstream brainstorming statement that
no implementation skill follows brainstorming. It uses frontend-design during
brainstorming and still transitions only to writing-plans afterward.

• Step 4: Add the shared review dependency to all implementation
  wrappers

In each implementation wrapper's required-skills section, add:

- **REQUIRED SUB-SKILL:** For meaningful user-visible frontend changes, read
  `../patchmill-frontend-review/SKILL.md` and follow its independent
  final-review contract. If the skill or its pinned local references are
  missing, stop with evidence instead of fetching substitutes or skipping
  review.

Do not change the existing worker and reviewer topology.

• Step 5: Add the frontend checkpoint to the two Codex and thermo
  wrappers

In both:

• single-subagent-dev-with-codex-and-thermo-reviews/SKILL.md
• subagent-dev-with-codex-and-thermo-reviews/SKILL.md

insert this stage after Fix final validation findings and before landing:

### 9. Run independent frontend review when applicable

Inspect the refreshed base-to-head scope. If it contains no meaningful
user-visible frontend change, record that this checkpoint does not apply and
continue to landing.

If it does apply, read `../patchmill-frontend-review/SKILL.md`. Dispatch its
fresh-context, review-only `reviewer` only after the Codex, thermo-nuclear, and
final validation-readiness gates are closed. Supply the approved specification,
referenced mockup, current scope, project design guidance, and available visual
evidence.

Route accepted findings through this skill's existing `worker` repair contract.
If a repair changes production code, rerun affected validation and return to the
Codex review gate with the refreshed scope. Close the Codex, thermo-nuclear, and
final validation-readiness gates again before another fresh frontend review.

Continue until frontend review returns `pass` or the existing blocked contract
applies. Resolve every frontend reviewer and repair worker before landing.

Renumber Complete landing and verify PR checks to step 10. Change “all three
final review gates” to “all four final review gates.” Add frontend review to the
landing summary and success prerequisites.

• Step 6: Add the frontend checkpoint to the validation-only wrapper

Insert this stage after Fix final validation findings and before landing:

### 5. Run independent frontend review when applicable

Inspect the refreshed base-to-head scope. If it contains no meaningful
user-visible frontend change, record that this checkpoint does not apply and
continue to landing.

If it does apply, read `../patchmill-frontend-review/SKILL.md`. Dispatch its
fresh-context, review-only `reviewer` only after task-level reviews and the
final validation-readiness gate are closed. Supply the approved specification,
referenced mockup, current scope, project design guidance, and available visual
evidence.

Route accepted findings through this skill's existing `worker` repair contract.
If a repair changes production code, rerun affected validation, rerun the
existing task-level specification and code-quality review for the repair scope,
and close the final validation-readiness gate again. Then dispatch a new fresh
frontend reviewer.

Continue until frontend review returns `pass` or the existing blocked contract
applies. Resolve every frontend reviewer and repair worker before landing.

Renumber Complete landing and verify PR checks to step 6. Require final
validation and applicable frontend review to pass before direct landing or a PR
handoff.

• Step 7: Update wrapper supporting-file and red-flag sections

Add this exact supporting-file bullet to all three implementation wrappers:

- `../patchmill-frontend-review/SKILL.md` and its pinned local
  `references/web-interface-guidelines.md` rule set — conditional independent
  frontend review after normal validation and code review.

Add these exact red flags to all three wrappers:

- Run applicable frontend review before the existing normal review gates close.
- Fetch mutable frontend-review rules or substitute network content.
- Land or return final success while a frontend reviewer or repair worker is
  unresolved.

Preserve the current visual-evidence and PR-check rules. Do not copy Codex or
thermo language into the validation-only wrapper.

• Step 8: Document the user-facing workflow

Add a ## Frontend workflow augmentation section before Superpowers in
README.md:

## Frontend workflow augmentation

The recommended skill pack adds design guidance for meaningful user-visible
frontend changes. During specification work, `patchmill-planning` uses the
sibling Anthropic `frontend-design` skill and creates a self-contained,
responsive mockup at `docs/mockups/YYYY-MM-DD-<topic>.html`. The specification
links to this full-page mockup. The normal `writing-plans` step follows
specification approval.

After implementation validation and normal code review, the selected
implementation wrapper runs a fresh independent frontend review. The review uses
pinned local Vercel Web Interface Guidelines and available visual evidence. It
does not fetch mutable rules or add another visual-evidence stage. Accepted
findings return through the existing implementation and review workflow.

Explicit product requirements, repository policy, the design system, and the
approved specification take precedence over generic design guidance. The mockup
records visual intent rather than a pixel-perfect contract. Copy-only edits skip
this augmentation unless they materially change layout, interaction,
accessibility, or user flow.

• Step 9: Verify workflow and prompt contracts

Run:

node --input-type=module <<'NODE'
import { readFile } from "node:fs/promises";

const planning = await readFile("skills/patchmill-planning/SKILL.md", "utf8");
for (const fragment of [
  "../frontend-design/SKILL.md",
  "docs/mockups/YYYY-MM-DD-<topic>.html",
  "self-contained file",
  "opens directly from disk without a local server",
  "mobile and desktop widths",
  "Do not show only isolated components",
]) {
  if (!planning.includes(fragment)) {
    throw new Error(`planning wrapper omits: ${fragment}`);
  }
}

const wrappers = [
  {
    name: "single-subagent-dev-with-codex-and-thermo-reviews",
    finalGate: "### 8. Fix final validation findings",
    checkpoint: "### 9. Run independent frontend review when applicable",
    landing: "### 10. Complete landing and verify PR checks",
    rereview: "return to the Codex review gate",
  },
  {
    name: "subagent-dev-with-codex-and-thermo-reviews",
    finalGate: "### 8. Fix final validation findings",
    checkpoint: "### 9. Run independent frontend review when applicable",
    landing: "### 10. Complete landing and verify PR checks",
    rereview: "return to the Codex review gate",
  },
  {
    name: "subagent-dev-with-validation-and-pr-checks",
    finalGate: "### 4. Fix final validation findings",
    checkpoint: "### 5. Run independent frontend review when applicable",
    landing: "### 6. Complete landing and verify PR checks",
    rereview:
      "rerun the existing task-level specification and code-quality review",
  },
];

for (const { name, finalGate, checkpoint, landing, rereview } of wrappers) {
  const text = await readFile(`skills/${name}/SKILL.md`, "utf8");
  if (!text.includes("../patchmill-frontend-review/SKILL.md")) {
    throw new Error(`${name} does not reference patchmill-frontend-review`);
  }

  const finalGateIndex = text.indexOf(finalGate);
  const checkpointIndex = text.indexOf(checkpoint);
  const landingIndex = text.indexOf(landing);
  if (
    finalGateIndex < 0 ||
    checkpointIndex <= finalGateIndex ||
    landingIndex <= checkpointIndex
  ) {
    throw new Error(`${name} has an invalid frontend checkpoint position`);
  }

  const checkpointText = text.slice(checkpointIndex, landingIndex);
  for (const fragment of [
    "fresh-context, review-only `reviewer`",
    "Route accepted findings through this skill's existing `worker` repair contract",
    rereview,
  ]) {
    if (!checkpointText.includes(fragment)) {
      throw new Error(`${name} frontend checkpoint omits: ${fragment}`);
    }
  }
}
NODE

node --test src/cli/commands/run-once/prompts.test.ts
npm run lint:ts -- --no-warn-ignored src/cli/commands/run-once/prompts.ts src/cli/commands/run-once/prompts.test.ts
! rg -n 'frontendDesign|frontendReview|frontend-design|patchmill-frontend-review' patchmill.config.json src/workflow/skills.ts src/pi/resource-profiles.ts src/cli/commands/run-once/prompt-workflow.ts src/cli/commands/run-once/prompts.ts
npx prettier --check README.md skills/patchmill-planning/SKILL.md skills/*subagent*reviews/SKILL.md skills/subagent-dev-with-validation-and-pr-checks/SKILL.md
npx markdownlint-cli2 README.md skills/patchmill-planning/SKILL.md skills/single-subagent-dev-with-codex-and-thermo-reviews/SKILL.md skills/subagent-dev-with-codex-and-thermo-reviews/SKILL.md skills/subagent-dev-with-validation-and-pr-checks/SKILL.md

Expected: PASS. The negated rg command must find no frontend activation or
review seam in configuration, resource profiles, or runtime prompts.

No new automated test asserts the Markdown text. The direct script checks the
cross-file workflow contract without creating a static prose test.

• Step 10: Commit the workflow composition

git add \
  src/cli/commands/run-once/prompts.ts \
  src/cli/commands/run-once/prompts.test.ts \
  skills/patchmill-planning/SKILL.md \
  skills/single-subagent-dev-with-codex-and-thermo-reviews/SKILL.md \
  skills/subagent-dev-with-codex-and-thermo-reviews/SKILL.md \
  skills/subagent-dev-with-validation-and-pr-checks/SKILL.md \
  README.md
git commit -m "feat(workflow): add conditional frontend review"

---

Task 5: Regenerate the project-local pack and strengthen Nix checks

Files:

• Modify: nix/package.nix:37-102
• Create: .patchmill/skills/frontend-design/SKILL.md
• Create: .patchmill/skills/frontend-design/LICENSE.txt
• Create: .patchmill/skills/patchmill-frontend-review/SKILL.md
• Create: .patchmill/skills/patchmill-frontend-review/LICENSE
• Create:
  .patchmill/skills/patchmill-frontend-review/references/upstream-web-design-guidelines.md
• Create:
  .patchmill/skills/patchmill-frontend-review/references/web-interface-guidelines.md
• Modify: .patchmill/skills/patchmill-planning/SKILL.md
• Modify:
  .patchmill/skills/single-subagent-dev-with-codex-and-thermo-reviews/SKILL.md
• Modify:
  .patchmill/skills/subagent-dev-with-codex-and-thermo-reviews/SKILL.md
• Modify:
  .patchmill/skills/subagent-dev-with-validation-and-pr-checks/SKILL.md
• Modify: .patchmill/skills/patchmill-skill-pack.json

Interfaces:

• Consumes: the completed source pack and installer/update behavior from Tasks 1
  through 4.

• Produces: a tracked project-local pack whose files, hashes, and provenance
  match the packaged source.

• Step 1: Add Nix install assertions for source and initialized copies

After the existing $out/share/${pname} resource assertions, add:

test -f "$out/share/${pname}/skills/frontend-design/SKILL.md"
test -f "$out/share/${pname}/skills/frontend-design/LICENSE.txt"
test -f "$out/share/${pname}/skills/patchmill-frontend-review/SKILL.md"
test -f "$out/share/${pname}/skills/patchmill-frontend-review/LICENSE"
test -f "$out/share/${pname}/skills/patchmill-frontend-review/references/web-interface-guidelines.md"

Inside the temporary project block, after patchmill init, add:

test -f .patchmill/skills/frontend-design/SKILL.md
test -f .patchmill/skills/frontend-design/LICENSE.txt
test -f .patchmill/skills/patchmill-frontend-review/SKILL.md
test -f .patchmill/skills/patchmill-frontend-review/LICENSE
test -f .patchmill/skills/patchmill-frontend-review/references/upstream-web-design-guidelines.md
test -f .patchmill/skills/patchmill-frontend-review/references/web-interface-guidelines.md

• Step 2: Regenerate the tracked recommended pack

Run from the repository root:

node bin/patchmill.ts skills update

Expected: the command updates the pack from its old version to 2026.09.1 and
reports that no configuration change is required.

If the command reports a customized managed file or a new-file collision, stop
and inspect the reported path. Do not overwrite it manually.

• Step 3: Check source-to-installed equality and metadata

Run:

cmp skills/frontend-design/SKILL.md .patchmill/skills/frontend-design/SKILL.md
cmp skills/frontend-design/LICENSE.txt .patchmill/skills/frontend-design/LICENSE.txt
cmp skills/patchmill-frontend-review/SKILL.md .patchmill/skills/patchmill-frontend-review/SKILL.md
cmp skills/patchmill-frontend-review/LICENSE .patchmill/skills/patchmill-frontend-review/LICENSE
cmp skills/patchmill-frontend-review/references/upstream-web-design-guidelines.md .patchmill/skills/patchmill-frontend-review/references/upstream-web-design-guidelines.md
cmp skills/patchmill-frontend-review/references/web-interface-guidelines.md .patchmill/skills/patchmill-frontend-review/references/web-interface-guidelines.md
cmp skills/patchmill-planning/SKILL.md .patchmill/skills/patchmill-planning/SKILL.md
cmp skills/single-subagent-dev-with-codex-and-thermo-reviews/SKILL.md .patchmill/skills/single-subagent-dev-with-codex-and-thermo-reviews/SKILL.md
cmp skills/subagent-dev-with-codex-and-thermo-reviews/SKILL.md .patchmill/skills/subagent-dev-with-codex-and-thermo-reviews/SKILL.md
cmp skills/subagent-dev-with-validation-and-pr-checks/SKILL.md .patchmill/skills/subagent-dev-with-validation-and-pr-checks/SKILL.md

node --input-type=module <<'NODE'
import { readFile } from "node:fs/promises";

const metadata = JSON.parse(
  await readFile(".patchmill/skills/patchmill-skill-pack.json", "utf8"),
);
if (metadata.pack.version !== "2026.09.1") {
  throw new Error(`unexpected pack version: ${metadata.pack.version}`);
}
const byName = new Map(metadata.skills.map((skill) => [skill.name, skill]));
for (const name of ["frontend-design", "patchmill-frontend-review"]) {
  if (!byName.has(name)) throw new Error(`missing metadata for ${name}`);
}
const commits = new Set(
  metadata.skills.flatMap((skill) =>
    (skill.upstreamSources ?? []).map((source) => source.commit),
  ),
);
for (const commit of [
  "41bbe19d1a1a7eaab5e7bb9050a417e5c6cffc8f",
  "ba46938889d4e58635362fb8f618e1178ac3ec46",
  "e3d624baaf29dc1fc645aff3e38f03e564d2d6b1",
]) {
  if (!commits.has(commit)) throw new Error(`missing upstream commit ${commit}`);
}
NODE

Expected: every comparison and metadata check exits 0.

• Step 4: Run packaging and installer checks

Run:

node --test \
  bin/package-files.test.ts \
  src/workflow/skill-pack.test.ts \
  src/cli/commands/init/skill-installer.test.ts \
  src/cli/commands/init/skill-installer-path-mode.test.ts \
  src/cli/commands/skills/update.test.ts \
  src/cli/commands/doctor/checks.test.ts
npm pack --dry-run --json --ignore-scripts > /tmp/patchmill-issue-210-pack.json
node --input-type=module <<'NODE'
import { readFile } from "node:fs/promises";
const pack = JSON.parse(await readFile("/tmp/patchmill-issue-210-pack.json", "utf8"));
const files = new Set(pack[0].files.map((file) => file.path));
for (const path of [
  "skills/frontend-design/SKILL.md",
  "skills/frontend-design/LICENSE.txt",
  "skills/patchmill-frontend-review/SKILL.md",
  "skills/patchmill-frontend-review/LICENSE",
  "skills/patchmill-frontend-review/references/upstream-web-design-guidelines.md",
  "skills/patchmill-frontend-review/references/web-interface-guidelines.md",
]) {
  if (!files.has(path)) throw new Error(`npm pack omitted ${path}`);
}
NODE

Expected: PASS.

• Step 5: Commit generated and Nix resources

git add .patchmill/skills nix/package.nix
git commit -m "chore(skills): refresh recommended frontend pack"

---

Task 6: Run final consistency and repository verification

Files:

• Review: all files changed since the implementation base
• Review:
  docs/specs/2026-09-07-issue-210-frontend-design-and-review-skills-design.md
• Review: docs/plans/2026-09-07-frontend-design-and-review-skills.md

Interfaces:

• Consumes: all deliverables from Tasks 1 through 5.

• Produces: final evidence that source skills, installed skills, metadata,
  packages, and workflows agree.

• Step 1: Make sure that no forbidden configuration or dependency change
  exists

Run:

git diff --name-only 470891c...HEAD
test -z "$(git diff --name-only 470891c...HEAD -- package.json package-lock.json npm-shrinkwrap.json patchmill.config.json)"
git diff --check 470891c...HEAD

Expected: the listed files match the plan. The negated dependency and
configuration diff exits 0. git diff --check reports no whitespace errors.

• Step 2: Recheck all upstream copies and license evidence

Repeat Task 1 Step 6. Also fetch the pinned Vercel agent-skills README and make
sure that its license section declares MIT:

vercel_readme="$(mktemp)"
trap 'rm -f "$vercel_readme"' EXIT
curl -fsSL https://raw.githubusercontent.com/vercel-labs/agent-skills/ba46938889d4e58635362fb8f618e1178ac3ec46/README.md \
  --output "$vercel_readme"
grep -A2 -E '^## Licen[cs]e$' "$vercel_readme" \
  | grep -x 'MIT'
rm -f "$vercel_readme"
trap - EXIT

Expected: all comparisons pass and the README command prints MIT.

• Step 3: Run the complete test and lint commands

Run:

npm test
npm run lint

Expected: PASS.

• Step 4: Verify npm and Nix packaging

Run:

npm pack --dry-run --json --ignore-scripts
nix build .#patchmill --no-link

Expected: both commands exit 0. The Nix install check initializes a project and
finds both new skills and their required files.

• Step 5: Review acceptance coverage and repository state

Run:

git status --short --branch
git log --oneline 470891c..HEAD
git diff --stat 470891c...HEAD

Then compare the final diff with every acceptance item in the specification.
Make sure that:

• all three implementation wrappers invoke the shared review;
• the planning wrapper keeps both normal sibling workflows;
• the active review wrapper contains no runtime fetch;
• generated metadata uses the corrected Vercel commit;
• source and installed files match;
• no subagent, dependency, service, or temporary artifact remains active or
  untracked.

Do not create an empty verification commit. If verification changes a tracked
file, rerun the affected checks and commit that correction with a focused
Conventional Commit.