pi-dev-team 0.2.0

package/skills/project-init/evals/evals.json

@@ -0,0 +1,200 @@
+{
+  "skill_name": "project-init",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I need a new Node.js project for a CLI tool that processes CSV files. Just set up the project structure and tooling, I'll add the CSV logic myself.",
+      "expected_output": "A scaffolded JS project with package.json (type: module), eslint.config.js with functional rules, prettier.config.js, .editorconfig, .gitignore, vitest.config.js, and a starter src/index.js + src/index.test.js. No Playwright since this is a backend project. All lint/format/test commands should pass.",
+      "files": [],
+      "expectations": [
+        "package.json has \"type\": \"module\"",
+        "eslint.config.js exists and uses flat config format (export default [])",
+        "ESLint config bans ClassDeclaration and ClassExpression",
+        "prettier.config.js exists with singleQuote: true",
+        ".editorconfig exists with indent_size = 2",
+        ".gitignore includes node_modules and .env",
+        "vitest.config.js exists",
+        "No playwright.config.js (backend project)",
+        "src/index.js exports a pure function",
+        "src/index.test.js imports from src/index.js and has passing tests",
+        "npm run lint succeeds",
+        "npm test succeeds",
+        "The skill presented defaults and asked for confirmation before scaffolding"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Set up a new React project for a dashboard app. I want the full tooling — linting, formatting, testing, the works.",
+      "expected_output": "A scaffolded JS project with all standard configs plus Playwright for e2e testing. Should include playwright.config.js and an e2e/ directory. The package.json should have a test:e2e script.",
+      "files": [],
+      "expectations": [
+        "package.json has \"type\": \"module\"",
+        "playwright.config.js exists (frontend project detected)",
+        "e2e/ directory exists with at least one spec file",
+        "package.json scripts include test:e2e",
+        "eslint.config.js bans classes",
+        ".gitignore includes .env",
+        "vitest.config.js exists",
+        "The skill presented defaults and asked for confirmation before scaffolding"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Init a JS project but I want tabs instead of spaces, semicolons on, and 4-space tab width. Everything else can be default.",
+      "expected_output": "Standard scaffold but with customized formatting: prettier uses tabs, semicolons, tabWidth 4. EditorConfig uses tab indent. ESLint still has functional rules.",
+      "files": [],
+      "expectations": [
+        "prettier.config.js has useTabs: true",
+        "prettier.config.js has semi: true",
+        "prettier.config.js has tabWidth: 4",
+        ".editorconfig has indent_style = tab",
+        ".editorconfig has indent_size = 4 or tab_width = 4",
+        "eslint.config.js still bans ClassDeclaration",
+        "package.json has \"type\": \"module\"",
+        "npm run lint succeeds",
+        "npm test succeeds"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "Get this repo ready for the plugin.",
+      "expected_output": "Python detected from pyproject.toml + .py sources. The three-column plan shows ruff and mypy (and pytest, since no test runner is present) under 'missing and will add'; after confirmation they are added to the project's dev-dependency mechanism, nothing user-level or global. Post-install probes (command -v ruff / command -v mypy) reported.",
+      "files": [
+        { "path": "pyproject.toml", "contents": "[project]\nname = \"csvkit-lite\"\nversion = \"0.1.0\"\n" },
+        { "path": "src/app.py", "contents": "def add(a, b):\n    return a + b\n" }
+      ],
+      "expectations": [
+        "Detected stack is Python only",
+        "A three-column plan (found and keeping / missing and will add / found but can't participate) is presented before any write or install",
+        "ruff, mypy, and pytest appear under 'missing and will add'",
+        "The install lands in the project's dev-dependency mechanism (pyproject.toml dev group or requirements-dev.txt)",
+        "No pip install --user, pipx, or other user-level/global install is run",
+        "pyproject.toml's existing [project] section is not rewritten",
+        "The skill ends by running command -v ruff and command -v mypy and reporting per-lane status"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "Set up my project's toolchain.",
+      "expected_output": "C# detected from the .csproj. Nothing is installed — the skill verifies the .NET SDK is present (honoring the global.json pin) and that dotnet format responds, then reports the lane bound to the SDK-builtin tools.",
+      "files": [
+        { "path": "Api.csproj", "contents": "<Project Sdk=\"Microsoft.NET.Sdk\">\n  <PropertyGroup>\n    <TargetFramework>net8.0</TargetFramework>\n  </PropertyGroup>\n</Project>" },
+        { "path": "global.json", "contents": "{ \"sdk\": { \"version\": \"8.0.100\" } }" },
+        { "path": "Program.cs", "contents": "System.Console.WriteLine(\"hi\");\n" }
+      ],
+      "expectations": [
+        "Detected stack is C# only",
+        "The plan states there is nothing to install for C#",
+        "The global.json SDK pin is honored, not overwritten",
+        "dotnet format --version is verified to respond",
+        "The probe command -v dotnet is run and per-lane status reported"
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "Install the linters for this repo.",
+      "expected_output": "Java detected from pom.xml + .java sources. After confirmation the skill verifies a JDK, runs the plugin's pinned-PMD installer into repo-local .pmd/, and adds .pmd/ to .gitignore. The user never invokes the installer script by hand.",
+      "files": [
+        { "path": "pom.xml", "contents": "<project><modelVersion>4.0.0</modelVersion><groupId>x</groupId><artifactId>demo</artifactId><version>1.0</version></project>" },
+        { "path": "src/main/java/App.java", "contents": "public class App { public static void main(String[] a) {} }" }
+      ],
+      "expectations": [
+        "Detected stack is Java only",
+        "The plan shows PMD under 'missing and will add' before anything runs",
+        "The pinned-PMD installer script is run for the user (no manual script invocation asked of them)",
+        "PMD lands in repo-local .pmd/, and .pmd/ is added to .gitignore",
+        "No user-level or global install occurs",
+        "The probe checks .pmd/pmd-bin-*/bin/pmd first, then command -v pmd, and reports status"
+      ]
+    },
+    {
+      "id": 7,
+      "prompt": "Get this repo ready for the dev-team toolchain.",
+      "expected_output": "Mixed Python + TypeScript repo: both lanes are detected and both appear in one three-column plan; each lane's missing tools are installed repo-level after a single confirmation.",
+      "files": [
+        { "path": "pyproject.toml", "contents": "[project]\nname = \"mixed\"\nversion = \"0.1.0\"\n" },
+        { "path": "etl/main.py", "contents": "print(\"etl\")\n" },
+        { "path": "tsconfig.json", "contents": "{ \"compilerOptions\": { \"strict\": true } }" },
+        { "path": "src/index.ts", "contents": "export const add = (a: number, b: number): number => a + b;\n" },
+        { "path": "package.json", "contents": "{ \"name\": \"mixed\", \"private\": true, \"type\": \"module\" }" }
+      ],
+      "expectations": [
+        "Both Python and JS/TS lanes are detected (multi-stack setup)",
+        "One three-column plan covers both lanes before any install",
+        "Python: ruff and mypy under 'missing and will add', installed into the project's dev-dependency mechanism",
+        "JS/TS: oxlint under 'missing and will add', installed with npm install --save-dev oxlint",
+        "Post-install probes run for both lanes and per-lane status is reported"
+      ]
+    },
+    {
+      "id": 8,
+      "prompt": "Set up my project's toolchain. (If asked which stack, answer: something else — it's a Rust project.)",
+      "expected_output": "The directory has no detectable stack, so the skill asks the user, presenting the four supported stacks plus 'something else'. On 'something else' it explains what's supported and exits gracefully — no files written, nothing installed.",
+      "files": [
+        { "path": "README.md", "contents": "# my project\n" }
+      ],
+      "expectations": [
+        "The skill asks the user instead of assuming a stack",
+        "The four supported stacks (JS/TS, Python, C#, Java) plus 'something else' are offered",
+        "On 'something else' the skill explains what's supported",
+        "The skill exits without writing any file or installing anything"
+      ]
+    },
+    {
+      "id": 9,
+      "prompt": "Get this repo ready for the plugin.",
+      "expected_output": "Brownfield Python repo already configured with black + flake8: the inventory binds the pair as the autofix slot's provider (bind-don't-replace), so the plan shows them under 'found and keeping' and installs nothing for that slot; only mypy (the empty diagnostic slot) appears under 'missing and will add'.",
+      "files": [
+        { "path": "pyproject.toml", "contents": "[project]\nname = \"legacy\"\nversion = \"2.3.0\"\n\n[tool.black]\nline-length = 100\n" },
+        { "path": ".flake8", "contents": "[flake8]\nmax-line-length = 100\n" },
+        { "path": "requirements-dev.txt", "contents": "black==24.4.2\nflake8==7.0.0\npytest==8.2.0\n" },
+        { "path": "legacy/core.py", "contents": "def run():\n    return 42\n" }
+      ],
+      "expectations": [
+        "black + flake8 are bound as the autofix slot's provider and shown under 'found and keeping' (with the partial-mapping caveat noted)",
+        "ruff is NOT installed — the bound pair satisfies the slot",
+        "mypy appears under 'missing and will add' (empty diagnostic slot) and is the only install",
+        "pytest is not re-added (a test runner is already present)",
+        "The install goes into requirements-dev.txt (the mechanism the project already uses)",
+        "pyproject.toml's [tool.black] section and .flake8 are left untouched"
+      ]
+    },
+    {
+      "id": 10,
+      "prompt": "Install the linters for this repo.",
+      "expected_output": "Brownfield Python repo with pyright configured: pyright fails the qualification contract (its recognition adapter does not exist yet), so the plan surfaces it under 'found but can't participate' with that reason stated and mypy offered alongside — never silently replaced. Only the 'missing and will add' column installs.",
+      "files": [
+        { "path": "pyproject.toml", "contents": "[project]\nname = \"typed-app\"\nversion = \"0.5.0\"\n" },
+        { "path": "pyrightconfig.json", "contents": "{ \"typeCheckingMode\": \"strict\" }" },
+        { "path": "app/main.py", "contents": "def greet(name: str) -> str:\n    return f\"hi {name}\"\n" }
+      ],
+      "expectations": [
+        "pyright is listed under 'found but can't participate' with the reason (no recognition adapter yet) stated",
+        "mypy is offered alongside as the diagnostic default, not silently swapped in",
+        "Only tools in 'missing and will add' are installed",
+        "pyrightconfig.json is left untouched",
+        "The user confirms the plan before any install runs"
+      ]
+    },
+    {
+      "id": 11,
+      "prompt": "Set up my project's toolchain.",
+      "expected_output": "Mixed brownfield repo with an existing eslint.config.js and pyproject.toml: tools-only mode installs missing dependencies without modifying either file; the plan shows the existing configs under 'found and keeping' and the summary names them as left alone.",
+      "files": [
+        { "path": "package.json", "contents": "{ \"name\": \"web\", \"private\": true, \"type\": \"module\", \"devDependencies\": { \"eslint\": \"^9.0.0\" } }" },
+        { "path": "eslint.config.js", "contents": "export default [{ rules: { 'prefer-const': 'error' } }];\n" },
+        { "path": "src/index.js", "contents": "export const id = (x) => x;\n" },
+        { "path": "pyproject.toml", "contents": "[project]\nname = \"web-tools\"\nversion = \"1.0.0\"\n\n[tool.ruff]\nline-length = 100\n" },
+        { "path": "tools/gen.py", "contents": "print(\"gen\")\n" }
+      ],
+      "expectations": [
+        "Tools-only mode: no scaffold, no config file created or overwritten",
+        "eslint.config.js and pyproject.toml appear under 'found and keeping' and are byte-identical afterwards",
+        "ESLint binds with demotion noted (slice-boundary granularity) and one info line mentions the fast default (oxlint)",
+        "ruff binds from the existing [tool.ruff] config — not reinstalled over",
+        "Only genuinely empty slots' defaults are installed, into devDependencies / the project's Python dev mechanism",
+        "The summary names the untouched configs explicitly"
+      ]
+    }
+  ]
+}

package/skills/project-init/references/capability-tools.md

@@ -0,0 +1,55 @@
+# Capability-tools registry
+
+Single source of truth for the **capability tools** that `/project-init`
+installs beyond the four static-analysis lanes (JS/TS, Python, C#, Java).
+These are the CLIs and browsers that other skills and agents depend on. The
+skill's Step 4b reads this table: it runs each tool's **offer-when** signal,
+presents the warranted tools as their own group in the three-column plan,
+installs only the missing + confirmed ones with the **OS-aware install**
+command, and probes them with the **verify** command in Step 5.
+
+Detection-gated by design: a tool is only offered when its signal fires, so a
+Python-only repo with no Dockerfile is never asked about the docker scanners.
+Every offer is confirmed before anything installs — same gate as the lanes.
+
+## Install-level honesty
+
+The "always repo-level, never user/system" rule of the static-analysis lanes
+applies to **lane tools + Playwright**. The other capability tools are CLIs
+that are user/system-level by nature (`brew`, `pipx`, apt) — there is no
+repo-local install for a general-purpose CLI like `gh` or `semgrep`. So:
+
+- **Playwright** is the **repo-level exception among capability tools**: it
+  installs as an `npm` devDependency (`@playwright/test`), versioned with the
+  project, exactly like a lane tool. Only its Chromium browser download is
+  machine-level (a Playwright cache, not a repo file).
+- **semgrep, adr, gh, hadolint, trivy, grype** are **user/system-level**
+  CLIs. Install them with the OS package manager (or pipx/user-pip on Linux).
+  This is the deliberate, documented exception to "always repo-level".
+
+## Registry
+
+| Tool | Skills that need it | Offer-when signal | OS-aware install command | Verify probe |
+| --- | --- | --- | --- | --- |
+| **semgrep** | `/semgrep-analyze`, security-assessment | Any source lane detected (universal SAST) — opt-in, confirmable | macOS: `brew install semgrep`. Linux: `pipx install semgrep` (fallback `python3 -m pip install --user semgrep`). Windows: `pipx install semgrep`. | `semgrep --version` |
+| **Playwright + Chromium** | `/benchmark`, `/browse`, `/browser-testing`, `/performance-benchmark` | Frontend signals in an **existing** project: React/Svelte/Vue/Angular/Next/Nuxt/SvelteKit/Astro deps, or an `e2e/` dir, or a `playwright.config.*` file. (Greenfield JS scaffold installs it separately.) | Repo-level (npm devDependency): `npm i -D @playwright/test && npx playwright install chromium` | `npx --no-install playwright --version` |
+| **adr** (npryce/adr-tools) | `/adr-tools`, adr-author agent | `docs/adr/`, `docs/decisions/`, or existing ADR `*.md` files present | macOS: `brew install adr-tools`. Linux/Windows: `git clone https://github.com/npryce/adr-tools` and put its `src/` on `PATH` (e.g. symlink into `~/.local/bin`). | `adr help` |
+| **gh** (GitHub CLI) | `/issues-from-assessment` and other issue/PR skills | Git repo with a GitHub remote — `git remote -v` shows `github.com` | macOS: `brew install gh`. Linux: official apt repo (`cli.github.com`), or `webi`/binary download. Windows: `winget install GitHub.cli`. | `gh --version` |
+| **hadolint** | `/docker-image-audit` | A `Dockerfile`, `*.dockerfile`, or `compose.y*ml` present | macOS: `brew install hadolint`. Linux/Windows: official release binary from `hadolint/hadolint`. | `hadolint --version` |
+| **trivy** | `/docker-image-audit` | Same docker signal as hadolint | macOS: `brew install trivy`. Linux/Windows: official install script / release binary from `aquasecurity/trivy`. | `trivy --version` |
+| **grype** | `/docker-image-audit` | Same docker signal as hadolint | macOS: `brew install grype`. Linux/Windows: official install script / release binary from `anchore/grype`. | `grype --version` |
+| **codegraph** | code-intelligence (`codegraph_explore` MCP tool, `code-intelligence-nudge` hook) | Universal — opt-in, confirmable, offered on every repo like semgrep | Install/init is a multi-step state machine, not a single command — see Step 4c and [`codegraph-vs-graphify.md`](../../../knowledge/codegraph-vs-graphify.md). Manual install: `https://github.com/colbymchenry/codegraph#installation`. | `command -v codegraph`, `.codegraph/` present |
+| **graphify** | `/graphify` (native skill, this repo's own `.claude/skills/graphify/`), architecture/onboarding questions spanning code + docs | Universal — opt-in, confirmable | `uv tool install graphifyy` (fallback `pipx install graphifyy`, fallback `python3 -m pip install --user graphifyy`), then `graphify install --project` and `graphify hook install` — see Step 4c for the CLAUDE.md corruption guard this install requires. | `graphify --version` |
+
+macOS one-liner for the docker scanners: `brew install hadolint trivy grype`.
+
+**codegraph and graphify get their own step (4c)**, not just a table row: codegraph's install+init flow is a stateful branch (installed × initialized), and graphify's install writes to the target repo's own `CLAUDE.md` and needs a corruption guard — both too complex for a single table row's install command. See `SKILL.md` Step 4c.
+
+## OS awareness
+
+Mirror the OS detection used by `/setup` — `uname -s` → `Darwin`
+(macOS, brew), `Linux` (apt/dnf/yum/pacman, else pipx/user-pip/binary),
+`MINGW*`/`MSYS*` (Windows Git Bash, winget/choco/scoop). WSL reports `Linux`
+and follows the Linux column. When no package manager is detected, print the
+manual install pointer from the table and continue — a missing capability
+tool degrades the dependent skill gracefully; it never fails `/project-init`.

package/skills/project-init/references/configs.md

@@ -0,0 +1,221 @@
+# Configuration File Templates
+
+Exact contents for each config file created by the project-init skill. Use these as-is unless the user requested customizations at the confirmation gate.
+
+## eslint.config.js
+
+```js
+import js from '@eslint/js'
+import prettier from 'eslint-config-prettier'
+
+export default [
+  js.configs.recommended,
+  prettier,
+  {
+    rules: {
+      // Functional style: no classes
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector: 'ClassDeclaration',
+          message: 'Use functions and closures instead of classes.',
+        },
+        {
+          selector: 'ClassExpression',
+          message: 'Use functions and closures instead of classes.',
+        },
+        {
+          selector: 'ThisExpression',
+          message: 'Avoid "this" — use closures and explicit parameters instead.',
+        },
+      ],
+
+      // Immutability
+      'prefer-const': 'error',
+      'no-var': 'error',
+      'no-param-reassign': 'error',
+
+      // Clean code
+      'no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      eqeqeq: ['error', 'always'],
+      'no-console': 'warn',
+    },
+  },
+  {
+    ignores: ['node_modules/', 'dist/', 'build/', 'coverage/'],
+  },
+]
+```
+
+## prettier.config.js
+
+```js
+export default {
+  semi: false,
+  singleQuote: true,
+  trailingComma: 'all',
+  printWidth: 100,
+  tabWidth: 2,
+  useTabs: false,
+  arrowParens: 'always',
+  endOfLine: 'lf',
+}
+```
+
+## .editorconfig
+
+```ini
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+```
+
+## .gitignore
+
+```
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+build/
+
+# Test coverage
+coverage/
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Editor directories
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Logs
+*.log
+npm-debug.log*
+
+# dev-team plugin: shared human-invoked report output (/review-agent,
+# /code-review, /triage) — local-only, regenerated per run. Anchored
+# deny-all + re-included tracked exception for /test-improve's
+# git-tracked report data/ sibling directory (issue #1412). The
+# re-include must stay directory-level (test-improve/), not narrowed to
+# e.g. */data/ — git never re-includes a path whose parent directory is
+# itself excluded, so a narrower exception would silently match nothing.
+/.dev-team-reports/*
+!/.dev-team-reports/test-improve/
+```
+
+## vitest.config.js
+
+```js
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.js'],
+  },
+})
+```
+
+## playwright.config.js (frontend projects only)
+
+```js
+import { defineConfig } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './e2e',
+  timeout: 30000,
+  retries: 0,
+  use: {
+    headless: true,
+    baseURL: 'http://localhost:3000',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { browserName: 'chromium' },
+    },
+  ],
+})
+```
+
+## .husky/pre-commit
+
+```bash
+npx lint-staged
+```
+
+## .husky/pre-push
+
+```bash
+npm test
+```
+
+Frontend projects append the e2e suite:
+
+```bash
+npm test
+npm run test:e2e
+```
+
+## src/index.js (starter file)
+
+```js
+/**
+ * Add two numbers together.
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {number} The sum of a and b
+ */
+export const add = (a, b) => a + b
+```
+
+## src/index.test.js (starter test)
+
+```js
+import { describe, it, expect } from 'vitest'
+import { add } from './index.js'
+
+describe('add', () => {
+  it('adds two positive numbers', () => {
+    expect(add(2, 3)).toBe(5)
+  })
+
+  it('handles zero', () => {
+    expect(add(0, 5)).toBe(5)
+  })
+
+  it('handles negative numbers', () => {
+    expect(add(-1, 1)).toBe(0)
+  })
+})
+```
+
+## e2e/example.spec.js (frontend projects only)
+
+```js
+import { test, expect } from '@playwright/test'
+
+test('homepage loads', async ({ page }) => {
+  await page.goto('/')
+  await expect(page).toHaveTitle(/.+/)
+})
+```

package/skills/property-based-testing/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: property-based-testing
+description: Generate a runnable property-based test for a target function from its signature/docstring — a round-trip test when an encode/decode pair exists, or an invariant test when the docstring documents a postcondition (e.g. "returns sorted", "is idempotent"). Detects the project's language via project-init's stack detection, uses Hypothesis for Python and fast-check for JavaScript/TypeScript, and recommends running /mutation-testing against the generated suite afterward. Use when the user says "generate a property test", "property-based test this function", "add Hypothesis/fast-check tests", or wants round-trip/invariant coverage for a pure function rather than hand-written example-based tests.
+role: worker
+user-invocable: true
+argument-hint: "<module_path> <function_name>"
+allowed-tools: Read, Write, Bash(python3 "${CLAUDE_PLUGIN_ROOT}/skills/property-based-testing/scripts/detect_and_dispatch.py" *, python3 "${CLAUDE_PLUGIN_ROOT}/skills/property-based-testing/scripts/hypothesis_scaffold.py" *, npm install *, npx vitest *)
+---
+
+# Property-Based Testing
+
+Role: worker. This command derives and generates property-based tests
+directly — it does not replace example-based tests, and it does not
+fabricate a weak "doesn't crash" property when no round-trip pair or
+documented invariant can be found.
+
+## Procedure
+
+### Step 1: Detect the target language (reuse project-init — never re-derive)
+
+Run project-init's own stack detection —
+`${CLAUDE_PLUGIN_ROOT}/skills/project-init/SKILL.md` § "Step 1: Detect the
+stack" — over the target project. That section is this repo's canonical,
+single source of truth for stack detection (its own frontmatter says so);
+this skill reuses its result and never re-implements the filesystem-signal
+table (`package.json`/`tsconfig.json` for JS/TS, `pyproject.toml`/
+`requirements*.txt`/`setup.py` for Python, `*.sln`/`*.csproj` for C#,
+`pom.xml`/`build.gradle` for Java) itself.
+
+Reduce that step's result to a single detected-language value:
+
+- Exactly one stack detected → its display name, verbatim as project-init's
+  own stack table spells it (`Python`, `JS/TS`, `C#`, `Java`).
+- Zero or ambiguous signals (project-init's own "ask the user" branch) →
+  no detected language.
+
+### Step 2: Gate on support
+
+Pass the detected language (or nothing, when Step 1 found none) to
+[`scripts/detect_and_dispatch.py`](scripts/detect_and_dispatch.py):
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/property-based-testing/scripts/detect_and_dispatch.py" --language "<detected language>"
+```
+
+This script decides support — it does not detect anything itself (see its
+own module docstring). When the language is neither `Python` nor `JS/TS`,
+or no language was passed at all, it prints the exact message below and
+exits non-zero. **Stop here — no partial run, no file written**, exactly as
+the Gherkin "Unsupported or undetected language" scenario requires:
+
+```
+Unsupported language: <detected|unknown> — supported: Python, JS/TS.
+```
+
+`<detected>` is the actual detected language name (e.g. `Go`, `C#`) when
+Step 1 found one but it isn't supported; the literal word `unknown` when
+Step 1 found nothing at all.
+
+On a supported language, the script prints which generator to dispatch to
+next and exits `0` — continue to Step 3.
+
+### Step 3: Install the property-testing tool if missing
+
+Follow project-init's own detection-gated-tool install pattern (`Step 4:
+Install missing tools` of `project-init/SKILL.md`) rather than inventing a
+new install mechanism — the tool is only installed when it's actually
+missing from the target project:
+
+- **Python — Hypothesis.** Add `hypothesis` to the project's own
+  dev-dependency mechanism (`pyproject.toml` dev group or
+  `requirements-dev.txt`, creating the latter if neither exists), exactly
+  as project-init's Python lane already does for `ruff`/`mypy`/`pytest`.
+- **JS/TS — fast-check.** `npm install --save-dev fast-check`, mirroring
+  project-init's existing `npm` devDependency install shape for
+  `oxlint`/`@playwright/test`.
+
+Never a global/user-level install — same repo-level-only rule project-init
+states for every lane and capability tool.
+
+### Step 4: Generate the property test
+
+- **Python** — invoke Step 4.1's scaffold directly:
+
+  ```bash
+  python3 "${CLAUDE_PLUGIN_ROOT}/skills/property-based-testing/scripts/hypothesis_scaffold.py" <module_path> <function_name> [--out-dir <dir>]
+  ```
+
+  It derives a round-trip property (a literal `encode`/`decode` pair) or an
+  invariant property (a recognized docstring postcondition phrase near a
+  type hint), writes `test_<function_name>_properties.py`, and prints its
+  path. When neither heuristic matches, it prints the exact "No property
+  derived" message and writes nothing — report that message verbatim rather
+  than fabricating a property.
+
+- **JS/TS** — follow
+  [`references/languages/javascript.md`](references/languages/javascript.md)
+  for the fast-check equivalent of the Python scaffold above: the same
+  round-trip/invariant heuristic (an `encode`/`decode` export pair, or a
+  recognized postcondition phrase in a JSDoc comment near a type
+  signature), emitting a runnable `fc.assert(fc.property(...))` test file.
+
+### Step 5: Recommend the mutation-testing follow-up (documentation only)
+
+After Step 4 writes a test file, **recommend** — do not auto-run —
+verifying it actually catches behavioral changes:
+
+> Run `/mutation-testing` against the generated test file and report the
+> resulting mutation score.
+
+This skill never invokes `/mutation-testing` itself; that stays a separate,
+user-initiated step so this skill doesn't re-implement mutation-testing's
+own orchestration.
+
+## When not to apply
+
+- A function with no obvious round-trip pair or documented invariant — see
+  Step 4's "No property derived" message rather than generating a weak
+  "doesn't crash" test.
+- A language other than Python or JS/TS, or a project whose stack detection
+  is ambiguous — see Step 2's unsupported-language message.

package/skills/property-based-testing/fixtures/invariant_fixture.py

@@ -0,0 +1,15 @@
+"""Fixture module for hypothesis_scaffold.py's invariant heuristic (#2190).
+
+`sort_values`'s docstring documents a "returns sorted" postcondition next to
+a type-hinted return value — the exact narrow signal the scaffold's
+invariant heuristic looks for.
+"""
+
+
+def sort_values(values: list[int]) -> list[int]:
+    """Sort a list of integers.
+
+    Returns sorted output: a non-decreasing list containing the same
+    elements as ``values``.
+    """
+    return sorted(values)

package/skills/property-based-testing/fixtures/js-roundtrip/README.md

@@ -0,0 +1,42 @@
+# fast-check round-trip fixture (#2190)
+
+Minimal JS fixture project for `/property-based-testing`'s fast-check
+(JS/TS) path, documented in
+[`../../references/languages/javascript.md`](../../references/languages/javascript.md).
+
+- `roundtrip.js` — a pure `encode`/`decode` pair (string reversal; its own
+  inverse), the same literal-name round-trip heuristic Python's
+  `hypothesis_scaffold.py` looks for, mirrored here for JS/TS.
+- `roundtrip.properties.test.js` — the fast-check property test a scaffold
+  targeting `encode`/`decode` would generate: `fc.assert(fc.property(...))`
+  asserting `decode(encode(x)) === x`.
+
+## Test determinism & the vendoring boundary
+
+`node_modules/fast-check/` and `node_modules/pure-rand/` (fast-check's only
+dependency) are **vendored and checked into this repo** — `git add -f`, since
+the repo-root `.gitignore`'s blanket `node_modules/` rule normally excludes
+them and a nested `.gitignore` cannot un-ignore a directory a parent
+`.gitignore` already excludes. Both are pure JS with no native/platform
+binaries, ~1.8M total, so they're identical on every dev machine and CI
+runner — this is what satisfies this skill's "no live install of fast-check
+during a test run" determinism requirement.
+
+`vitest` (and its transitive deps) is **not** vendored. Newer vitest pulls
+in platform-native binaries (`@rolldown/binding-<platform>`,
+`lightningcss-<platform>`) that are specific to the host OS/arch — checking
+one platform's build into git would silently break on a maintainer's
+different platform (this repo's CI is `ubuntu-*`, but maintainers develop on
+macOS — see the repo `CLAUDE.md` "Gates are platform-bound too" note), and
+covering every platform would multiply the vendored size for no determinism
+benefit `fast-check` itself doesn't already provide. Resolving `vitest` via
+`npx vitest run` (or `npm install` first) is project-init's own normal
+live-install path for the project's test runner — a repo-level concern this
+fixture doesn't re-litigate.
+
+## Run
+
+```bash
+npm install   # fetches vitest + fast-check/pure-rand (already vendored) if missing
+npx vitest run
+```