@balazsbarta/mp-skills 0.1.0

package/.agents/skills/playwright/references/visual-regression.md

@@ -0,0 +1,206 @@
+# Visual Regression Testing
+
+Configure screenshot comparison testing with Playwright.
+
+## When to use this reference
+
+- Adding visual regression tests to catch UI changes
+- Configuring screenshot comparison thresholds
+- Managing visual snapshots across environments
+
+## Basic visual test
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('homepage visual', async ({ page }) => {
+  await page.goto('/');
+  await expect(page).toHaveScreenshot('homepage.png');
+});
+```
+
+First run creates the reference screenshot. Subsequent runs compare against it.
+
+## Element screenshot
+
+```typescript
+test('button visual', async ({ page }) => {
+  await page.goto('/components');
+  const button = page.getByRole('button', { name: 'Submit' });
+  await expect(button).toHaveScreenshot('submit-button.png');
+});
+```
+
+## Configuration options
+
+### Threshold
+
+```typescript
+await expect(page).toHaveScreenshot('page.png', {
+  maxDiffPixels: 100,        // Allow up to 100 different pixels
+});
+
+await expect(page).toHaveScreenshot('page.png', {
+  maxDiffPixelRatio: 0.01,   // Allow 1% pixel difference
+});
+
+await expect(page).toHaveScreenshot('page.png', {
+  threshold: 0.2,            // Per-pixel color threshold (0-1)
+});
+```
+
+### Global config
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixelRatio: 0.01,
+      threshold: 0.2,
+    },
+  },
+});
+```
+
+## Masking dynamic content
+
+Hide elements that change between runs (timestamps, ads, avatars):
+
+```typescript
+test('dashboard visual', async ({ page }) => {
+  await page.goto('/dashboard');
+  await expect(page).toHaveScreenshot('dashboard.png', {
+    mask: [
+      page.getByTestId('timestamp'),
+      page.getByTestId('avatar'),
+      page.locator('.ad-banner'),
+    ],
+  });
+});
+```
+
+## Updating snapshots
+
+```bash
+# Update all visual snapshots
+npx playwright test --update-snapshots
+
+# Update specific test
+npx playwright test visual.spec.ts --update-snapshots
+```
+
+## Snapshot directory structure
+
+```
+tests/
+├── visual.spec.ts
+└── visual.spec.ts-snapshots/
+    ├── homepage-chromium-linux.png
+    ├── homepage-firefox-linux.png
+    └── homepage-webkit-linux.png
+```
+
+Screenshots are browser and platform-specific by default.
+
+## Cross-platform snapshots
+
+### Problem
+
+Screenshots differ between macOS, Linux, and Windows (font rendering, anti-aliasing).
+
+### Solutions
+
+**Option 1: Generate on CI only** (recommended)
+
+```bash
+# Generate reference screenshots in CI
+npx playwright test --update-snapshots
+# Commit the snapshots from CI
+```
+
+**Option 2: Docker for consistent rendering**
+
+```bash
+docker run --rm -v $(pwd):/work -w /work mcr.microsoft.com/playwright:v1.49.0-noble \
+  npx playwright test --update-snapshots
+```
+
+**Option 3: Increase threshold**
+
+```typescript
+expect: {
+  toHaveScreenshot: {
+    maxDiffPixelRatio: 0.05,  // More lenient
+  },
+},
+```
+
+## Full page screenshots
+
+```typescript
+test('full page visual', async ({ page }) => {
+  await page.goto('/long-page');
+  await expect(page).toHaveScreenshot('full-page.png', {
+    fullPage: true,
+  });
+});
+```
+
+## Animations
+
+Disable animations to avoid flaky visual tests:
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    // Disable CSS animations and transitions
+    launchOptions: {
+      args: ['--force-prefers-reduced-motion'],
+    },
+  },
+});
+```
+
+Or via CSS:
+
+```typescript
+test('stable visual', async ({ page }) => {
+  await page.goto('/');
+  // Disable animations
+  await page.addStyleTag({
+    content: '*, *::before, *::after { animation: none !important; transition: none !important; }',
+  });
+  await expect(page).toHaveScreenshot('page.png');
+});
+```
+
+## CI workflow for visual tests
+
+```yaml
+- name: Run visual tests
+  run: npx playwright test --grep @visual
+
+- name: Upload diff artifacts
+  uses: actions/upload-artifact@v4
+  if: failure()
+  with:
+    name: visual-diffs
+    path: test-results/
+```
+
+## Troubleshooting
+
+### Screenshots always differ
+
+- Check for animations → disable them
+- Check for dynamic content → mask it
+- Check for font loading → wait for fonts
+- Increase `maxDiffPixelRatio` threshold
+
+### Different results on CI vs local
+
+- Use Docker for consistent rendering
+- Or generate snapshots in CI and commit them
+- Never mix snapshots from different platforms

package/.agents/skills/pull-request-lifecycle/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: pull-request-lifecycle
+description: "Deterministic Machinery Partner pull request workflow. Produces a fixed PR format, updates version/changelog, and creates a PR with GitHub CLI."
+license: MIT
+metadata:
+  author: Balazs Barta
+  version: "2.0.0"
+  repository: https://github.com/balazsbarta/mp-skills
+  tags:
+    - git
+    - pull-request
+    - changelog
+    - versioning
+    - github
+---
+
+# Machinery Partner Pull Request Workflow
+
+Use this skill when the user asks to prepare a pull request. This workflow is deterministic and always produces the same structure.
+
+## Workflow contract
+
+- Use exactly two checkpoints:
+  1. Step 0 review opt-in
+  2. Step 1 plan approval
+- Do not ask extra preference questions beyond these checkpoints.
+- Do not add extra PR description sections beyond the required template.
+- PR title format is always `[VERSION] - Description`.
+- CHANGELOG heading format is always `## [VERSION]() - YYYY-MM-DD`.
+
+## Prerequisites
+
+- `git` repository
+- `gh` CLI authenticated
+- `python3` available
+- `package.json` present
+- `CHANGELOG.md` present
+
+If a required file or command is missing, stop and report the exact missing dependency with a remediation command.
+
+## Step 0: Optional automated code review
+
+Ask exactly:
+
+`Would you like to run automated code review before creating the PR?`
+
+- If user says yes, run:
+  `python3 .agents/skills/pull-request-lifecycle/scripts/code_review.py`
+- If user says no, skip to Step 1.
+
+Interpret exit codes from the script:
+
+- `0`: Review passed or warnings only
+- `2`: Critical issues found
+- `1`: Script or tooling failure; stop and report output
+
+If exit code is `2`, present findings and ask the user to choose one:
+
+- Fix issues before continuing
+- Skip issues and proceed with PR
+- Cancel PR creation
+
+If user chooses cancel, stop the workflow.
+
+## Step 1: Present PR plan
+
+Analyze current changes and present exactly:
+
+- **Proposed PR Title**: `[VERSION] - Brief description`
+- **Proposed PR Description**: Using `references/pr-description-template.md`
+- **Version Bump Type**: `patch`, `minor`, or `major`
+- **CHANGELOG Entry**: New top entry for `CHANGELOG.md`
+
+Wait for approval or requested edits. Apply requested edits and re-present until approved.
+
+## Step 2: Execute PR preparation
+
+After approval, run in this exact order:
+
+1. Run tests:
+   `yarn test`
+   If tests fail, stop and report failures.
+2. Bump version in `package.json`:
+   `npm version <patch|minor|major> --no-git-tag-version`
+3. Add a new version section at the top of `CHANGELOG.md` using `references/changelog-versioning.md`.
+4. Stage all files:
+   `git add -A`
+5. Commit using Conventional Commits:
+   `<type>(pull-request-lifecycle): <summary>`
+6. Create PR:
+   `gh pr create --title "[VERSION] - Description" --body "<approved body>"`
+
+## Required PR description structure
+
+PR descriptions must follow `references/pr-description-template.md` exactly and include:
+
+- `### **User description**`
+- `### **Code Review**` (only if Step 0 review was run)
+- `### **PR Type**`
+- `### **Description**`
+
+## Requirements checklist
+
+- `yarn test` passes
+- `package.json` version bumped
+- `CHANGELOG.md` updated with new top version section
+- Commit uses Conventional Commits format
+- PR title uses `[VERSION] - Description`
+
+## References
+
+- PR description template: `references/pr-description-template.md`
+- Changelog and versioning: `references/changelog-versioning.md`
+- Automated review process: `references/review-process.md`
+- PR creation command guide: `references/merge-strategies.md`
+- Conventional commit format: `../conventional-commits/SKILL.md`

package/.agents/skills/pull-request-lifecycle/references/changelog-versioning.md

@@ -0,0 +1,72 @@
+# Machinery Partner Changelog and Versioning
+
+This workflow uses a deterministic SemVer bump and changelog insertion flow.
+
+## Version bump types
+
+- `patch`: Backward-compatible bug fixes and small corrections
+- `minor`: Backward-compatible features and enhancements
+- `major`: Breaking changes
+
+## Required changelog heading format
+
+Every release entry must start with:
+
+```markdown
+## [VERSION]() - YYYY-MM-DD
+```
+
+Use the version selected in Step 1 and the current date in `YYYY-MM-DD` format.
+
+## Allowed category headings
+
+Use only these categories:
+
+- `Added`
+- `Changed`
+- `Deprecated`
+- `Removed`
+- `Fixed`
+- `Security`
+
+Only include categories that contain at least one bullet item.
+
+## Canonical entry format
+
+```markdown
+## [10.11.4]() - 2025-11-11
+
+### Fixed
+- Description of fix
+
+### Added
+- Description of new feature
+
+### Changed
+- Description of change
+```
+
+## Placement rules
+
+1. Insert the new version section at the top of `CHANGELOG.md`, directly under any title/introduction block.
+2. Keep newest versions first.
+3. Keep one blank line between heading and category blocks.
+4. Keep one blank line between category blocks.
+
+## Category selection guidance
+
+- `Added`: New capabilities
+- `Changed`: Behavioral updates to existing capability
+- `Deprecated`: Features marked for future removal
+- `Removed`: Features deleted in this release
+- `Fixed`: Defect corrections
+- `Security`: Security hardening, patches, or policy improvements
+
+## Workflow-aligned commands
+
+```bash
+# Bump package version without creating a tag
+npm version <patch|minor|major> --no-git-tag-version
+```
+
+After bumping, use the resulting `package.json` version in the changelog heading.

package/.agents/skills/pull-request-lifecycle/references/merge-strategies.md

@@ -0,0 +1,33 @@
+# PR Creation Commands
+
+This workflow focuses on deterministic PR creation. Merge strategy selection is out of scope for this skill.
+
+## Required PR creation command
+
+Use the approved title and body exactly:
+
+```bash
+gh pr create --title "[VERSION] - Description" --body "<approved body>"
+```
+
+## Multiline body-safe variant
+
+Use a temporary file for large descriptions:
+
+```bash
+cat > /tmp/pr-body.md <<'PRBODY'
+[VERSION] - Brief description
+
+### **User description**
+...
+PRBODY
+
+gh pr create --title "[VERSION] - Description" --body-file /tmp/pr-body.md
+```
+
+## Scope boundary
+
+- In scope: opening a PR with the deterministic template
+- Out of scope: choosing squash/rebase/merge strategies and branch protection policy
+
+Those merge decisions should be handled by repository policy, not by this workflow.

package/.agents/skills/pull-request-lifecycle/references/pr-description-template.md

@@ -0,0 +1,72 @@
+# Machinery Partner PR Description Template
+
+Use this exact structure for every pull request body. Do not reorder sections.
+
+## Canonical template
+
+```markdown
+[VERSION] - Brief description
+
+### **User description**
+Detailed explanation of changes with grouped sections.
+
+**Category heading:**
+- Specific change details
+- More details
+
+___
+
+### **Code Review**
+**Quality Gates**: ✅ All passed / ⚠️ X warnings / ❌ X errors
+**Complexity**: No issues / X suggestions
+**Impact**: Files changed: X, Features affected: ...
+**Review Status**: Approved / Changes requested
+
+___
+
+### **PR Type**
+Bug fix, Enhancement, Feature, etc.
+
+___
+
+### **Description**
+- Concise bullet per change
+- Include component/file names
+```
+
+## Rule when Step 0 review is skipped
+
+If automated review is skipped, remove only the `### **Code Review**` block and keep all remaining sections in the same order.
+
+## Example with review block
+
+```markdown
+[2.4.1] - Improve changelog validation workflow
+
+### **User description**
+This update standardizes changelog generation and prevents malformed release entries.
+
+**Release automation:**
+- Added deterministic changelog section rendering
+- Added version/date formatting guardrails
+
+___
+
+### **Code Review**
+**Quality Gates**: ✅ All passed
+**Complexity**: No issues
+**Impact**: Files changed: 5, Features affected: release-workflow
+**Review Status**: Approved
+
+___
+
+### **PR Type**
+Enhancement
+
+___
+
+### **Description**
+- Updated `.agents/skills/pull-request-lifecycle/SKILL.md` with fixed PR workflow
+- Added `.agents/skills/pull-request-lifecycle/scripts/code_review.py`
+- Rewrote pull-request lifecycle reference templates for deterministic output
+```

package/.agents/skills/pull-request-lifecycle/references/review-process.md

@@ -0,0 +1,54 @@
+# Automated Review Process
+
+This reference defines Step 0 of the Machinery Partner pull-request workflow.
+
+## Step 0 prompt
+
+Ask exactly:
+
+`Would you like to run automated code review before creating the PR?`
+
+## Script command
+
+If the user says yes, run:
+
+```bash
+python3 .agents/skills/pull-request-lifecycle/scripts/code_review.py
+```
+
+## Exit code contract
+
+- `0`: Review completed with no critical issues (warnings allowed)
+- `2`: Critical issues found; user decision required
+- `1`: Script execution failure; stop and report output
+
+## Critical issue decision flow
+
+When exit code is `2`, present findings and ask the user to choose one:
+
+1. Fix issues before continuing
+2. Skip issues and proceed with PR
+3. Cancel PR creation
+
+If the user chooses cancel, stop immediately.
+
+## Required summary fields for PR body
+
+When review is run, include this block in PR description:
+
+```markdown
+### **Code Review**
+**Quality Gates**: ✅ All passed / ⚠️ X warnings / ❌ X errors
+**Complexity**: No issues / X suggestions
+**Impact**: Files changed: X, Features affected: ...
+**Review Status**: Approved / Changes requested
+```
+
+## Script output format expectations
+
+The script outputs:
+
+- Human-readable review summary
+- A JSON block between `BEGIN_REVIEW_JSON` and `END_REVIEW_JSON`
+
+Use the JSON fields to fill the PR `Code Review` section without rewording the labels.