Make repo AI-ready: AGENTS.md, CI, templates, changelog

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,34 @@
+name: Bug Report
+description: Report a problem with one of the Plesk scripts
+labels: ["bug"]
+body:
+  - type: dropdown
+    id: script
+    attributes:
+      label: Affected script
+      options:
+        - mysql-backups (mysql-backup.sh / mysql-backup.bat)
+        - remove-old-wordpress-backups (remove-wordpress-backups.sh)
+        - pci-dss-scan (pci-dss-scan.sh / pci-dss-scan.bat)
+        - essential-plugin-malware-scan (essential-plugin-scan.sh)
+        - monitor-domain-hosting (monitor-aspnet.bat)
+        - Other / not sure
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: Platform and Plesk version
+      description: e.g. "Ubuntu 22.04, Plesk Obsidian 18.0.60" or "Windows Server 2022, Plesk Obsidian 18.0.60"
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: What happened?
+      description: Include the exact command you ran and the full output/error.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,20 @@
+name: Feature Request
+description: Suggest a new script or an improvement to an existing one
+labels: ["enhancement"]
+body:
+  - type: textarea
+    attributes:
+      label: What Plesk task should this automate?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Proposed approach
+      description: New script, or a change to an existing one? Which platform(s) — Windows, Linux, or both?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Additional context
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## Description
+
+<!-- What does this PR change and why? -->
+
+## Changes
+
+<!-- List the scripts/files touched -->
+
+## How to test
+
+<!-- Exact commands run, and against what Plesk environment (staging/dev), e.g.:
+     shellcheck mysql-backups/mysql-backup.sh
+     ./mysql-backups/mysql-backup.sh (tested on staging Plesk Obsidian 18.0.60) -->
+
+## Checklist
+
+- [ ] Updated both `.bat` and `.sh` versions for paired scripts (or N/A — single-platform script)
+- [ ] Ran `shellcheck` on any changed bash script
+- [ ] Updated `README.md` Features section if behavior/options changed
+- [ ] No hardcoded credentials — placeholders or environment-based auth only

.github/copilot-instructions.md

@@ -308,6 +308,18 @@ fi
   - `monitor-aspnet.bat`: Monitors ASP.NET enabled status and sends email alerts on change
 - **`README.md`**: User-facing documentation (must be updated when features change)
 
+## Maintenance Matrix
+
+When you change... | ...also update
+--- | ---
+`mysql-backups/mysql-backup.sh` | `mysql-backups/mysql-backup.bat` (platform parity), `README.md` Features/MySQL Backups section
+`remove-old-wordpress-backups/remove-wordpress-backups.sh` | `README.md` Features/Remove Old WordPress Backups section (Linux-only, no `.bat` counterpart)
+`pci-dss-scan/pci-dss-scan.sh` | `pci-dss-scan/pci-dss-scan.bat` (platform parity, basic-checks subset only), `README.md` PCI-DSS section
+`essential-plugin-malware-scan/essential-plugin-scan.sh` | `README.md` Essential Plugin Scanner section (Linux-only, no `.bat` counterpart)
+`monitor-domain-hosting/monitor-aspnet.bat` | `README.md` Domain Hosting Monitor section (Windows-only, no `.sh` counterpart)
+Any bash script's self-update block | `SCRIPT_RELATIVE_PATH` and `UPDATE_CHECK_FILE` constants inside that same script only — self-update blocks are copy-pasted per script, not shared
+Any script's env vars / CLI flags | That script's header comment block and its `README.md` section
+
 ## Common Pitfalls
 
 1. **Windows path handling**: Forgetting delayed expansion causes failures with Plesk's default path `C:\Program Files (x86)\Plesk`

.github/skills/ai-ready/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: ai-ready
+license: MIT
+metadata:
+  version: "1.2.0"
+description: "**ANALYSIS SKILL** — Analyze any repository and generate AI-ready configuration — AGENTS.md, copilot-instructions.md, skills, CI workflows, issue templates. WHEN: \"make this repo ai-ready\", \"set up AI config\", \"add copilot instructions\", \"prepare this repo for AI contributions\", \"generate AGENTS.md\". INVOKES: glob, grep, view, create, edit for repo analysis and file generation. FOR SINGLE OPERATIONS: use create/edit directly for individual config files."
+---
+
+# AI-Ready Repo Skill
+
+## Persona
+
+Adopt the perspective of an experienced repo maintainer who has managed high-traffic repos and reviewed thousands of PRs. Prioritize what **reduces review burden and contributor friction**. Every file you generate should earn its place — generic boilerplate creates noise.
+
+---
+
+Follow these steps in order to analyze the current repository and generate all missing AI-ready configuration assets.
+
+**First run vs. re-run:** On the first run, most assets will be missing — the skill creates them. On re-runs, it **audits** existing assets against the current codebase, checking for drift, stale content, and new conventions from recent PR reviews. The skill **never overwrites existing files without user approval**.
+
+**Skipping assets:** If the user's prompt mentions skipping specific assets (e.g., "skip CI and issue templates"), respect those exclusions. Still run the full analysis, but skip generation for the excluded assets.
+
+**Report-only mode:** If the user asks for a report without generating files (e.g., "how ai-ready is this repo?", "score this repo"), run the full analysis (Steps 0–1) and display the report (Step 11) — but skip all generation steps (Steps 2–10).
+
+### The 12 tracked assets
+
+Assets are grouped into three categories. Count assets with **Nailed It** status for the score.
+
+**🤖 AI Context** — what AI agents read to understand your repo
+
+| # | Asset | Generated in |
+|---|-------|-------------|
+| 1 | `AGENTS.md` | Step 2 |
+| 2 | `.github/copilot-instructions.md` | Step 3 |
+| 3 | Maintenance matrix (in `copilot-instructions.md`) | Step 8 |
+| 4 | `.mcp.json` | Step 4b |
+| 5 | `.github/workflows/copilot-setup-steps.yml` | Step 4 |
+
+**🔧 Dev Workflow** — what keeps PRs clean and contributors on track
+
+| # | Asset | Generated in |
+|---|-------|-------------|
+| 6 | CI workflow (`.github/workflows/ci.yml`) | Step 5 |
+| 7 | Issue templates (`.github/ISSUE_TEMPLATE/`) | Step 6 |
+| 8 | PR template (`.github/PULL_REQUEST_TEMPLATE.md`) | Step 6 |
+| 9 | `.github/dependabot.yml` | (checked, not generated) |
+
+**📖 Onboarding** — what helps new contributors get started
+
+| # | Asset | Generated in |
+|---|-------|-------------|
+| 10 | README Contributing section | Step 7 |
+| 11 | Changelog (`CHANGELOG.md`) | Step 9 |
+| 12 | Documentation (or explicit "not needed" note) | Step 10 |
+
+**Scoring:** 🟩 Nailed It (counted) · 🟨 Could Be Better (not counted) · ⬜ Missing (not counted)
+
+| Medal | Name | Count | What it means |
+|-------|------|-------|---------------|
+| 🥉 | **Getting Started** | 1–4 | Basics in place but AI agents are mostly guessing |
+| 🥈 | **On Track** | 5–7 | AI agents can help but miss your conventions |
+| 🥇 | **Solid** | 8–10 | AI agents follow your patterns and catch most expectations |
+| 🏆 | **AI-Ready** | 11–12 | AI agents contribute like your best team members |
+
+---
+
+## Step 0 — Detect GitHub context automatically
+
+**Zero user input required.** The skill is GitHub-native — it discovers everything from GitHub's tools.
+
+### 0a. Identify the repo
+
+Run `git remote -v` to extract the GitHub `owner/repo`. If not GitHub, fall back to local-only analysis.
+
+### 0b–0d. Fetch metadata, mine PR reviews, check community health
+
+Use GitHub MCP tools or `gh` CLI to auto-discover repo metadata, PR review patterns, and community health gaps. See [references/github-discovery.md](references/github-discovery.md) for the full API table, PR mining technique, and health gap mapping.
+
+Key insight: **PR review mining is the highest-value step.** Repeated reviewer feedback becomes conventions in `copilot-instructions.md`.
+
+---
+
+## Step 1 — Analyze the codebase
+
+GitHub context tells you *what* the repo is. Local analysis tells you *how* it works. Use glob, grep, and view combined with GitHub context from Step 0.
+
+### 1a. Detect languages, frameworks, and repo type
+
+Find manifest files and extract details. See [references/detection-tables.md](references/detection-tables.md) for the full manifest table, VS Code extension detection, multi-app collections, demo app patterns, and course/tutorial repo detection.
+
+Key detections: lockfiles, runtime version files, monorepo markers, notebooks, VS Code extensions, multi-app collections, demo apps.
+
+**Course repos** (3+ signals: numbered folders, lesson keywords, no primary app) adapt Steps 2–5. See detection-tables.md for the full signal list and step adaptations.
+
+### 1b. Detect test setup
+
+Identify test runner, find test directories (`tests/`, `__tests__/`, `spec/`, `e2e/`), extract test commands from scripts.
+
+### 1c. Detect CI/CD
+
+Check `.github/workflows/` for PR triggers. Check for other CI systems. Recognize community workflows (stale, welcome) as valid automation — not missing CI.
+
+### 1d. Check existing AI configuration
+
+Check for: `AGENTS.md`, `.github/copilot-instructions.md`, `.github/skills/`, `.github/agents/`, `.github/extensions/`, `.devcontainer/`.
+
+**copilot-setup-steps.yml** — check ALL known locations: `.github/workflows/copilot-setup-steps.yml` (canonical), `.github/copilot-setup-steps.yml` (legacy), and repo root. If found in a non-canonical location, flag it for consolidation into `.github/workflows/` — do not create a duplicate.
+
+If multiple instruction files exist, check for duplicates, contradictions, stale references, and scope clarity. See [references/detection-tables.md](references/detection-tables.md) for drift detection details.
+
+### 1e. Check repo configuration
+
+Check for: `CODEOWNERS`, `dependabot.yml`, issue templates, PR template, `LICENSE`, README Contributing section.
+
+### 1f–1g. Evaluate changelog and documentation
+
+Assess changelog health (exists, format, freshness). Assess docs (exists, framework, navigation, deploy pipeline, README linkage).
+
+### 1h. Scan directory structure
+
+List top-level directories and immediate children (skip `node_modules`, `.git`, `dist`, `build`, `target`, `vendor`).
+
+### 1i. Compile findings
+
+Produce a structured findings table combining GitHub context and codebase analysis with file-path evidence. See [references/detection-tables.md](references/detection-tables.md) for the full findings table template.
+
+List which of the 12 assets are missing. For existing assets, compare against analysis and flag drift as "Could Be Better."
+
+### 1j. Detect monorepo areas
+
+If workspace config found, list areas with name, path glob, and primary stack. For large library monorepos, map cross-package dependencies. See [references/detection-tables.md](references/detection-tables.md) for details.
+
+---
+
+## Step 2 — Generate AGENTS.md
+
+If missing, create `AGENTS.md` at the repo root. If it exists, compare against analysis and flag drift. **Do not overwrite.**
+
+Sections: Project Overview (never hardcode versions — reference manifests), Repository Structure, Tech Stack, Build & Run, Testing, Key Patterns and Conventions, CI/CD, Adding a New [Feature/Module] (trace the full registration chain — enums, index re-exports, config declarations), Screen Size / Responsive Rules (UI projects only), Common Pitfalls.
+
+---
+
+## Step 3 — Generate .github/copilot-instructions.md
+
+If missing, create it. If it exists, compare against analysis — especially new PR review patterns and maintenance matrix drift.
+
+Content: Language-Specific Conventions (separate subsections for multi-language repos), Notebook Conventions (if `.ipynb` detected), Course/Lesson Conventions (if course repo), Framework Patterns, Conventions Mined from PR Reviews, Test Conventions, Code Style Notes (reference linter configs), Asset/Content Rules (if assets detected), **Maintenance Matrix** (trace dependency graphs — the most valuable section).
+
+The maintenance matrix defines what must be updated when different parts of the codebase change. Populate with real file paths. Trace import chains and registration patterns — don't stop at top-level files.
+
+**Monorepo:** Create `.github/instructions/{area-name}.instructions.md` with `applyTo` patterns for areas with different stacks.
+
+---
+
+## Step 4 — Generate copilot-setup-steps.yml
+
+Check ALL locations first: `.github/workflows/copilot-setup-steps.yml`, `.github/copilot-setup-steps.yml`, and repo root. If one exists anywhere, do NOT create another — consolidate into `.github/workflows/` if at a legacy location.
+
+If truly missing from all locations, create `.github/workflows/copilot-setup-steps.yml`. Steps: checkout, set up runtime, install dependencies, install test dependencies, build. Derive from existing CI when possible. For .NET multi-target, install all required SDK versions.
+
+---
+
+## Step 4b — Generate .mcp.json
+
+If missing, generate `.mcp.json` at the repo root based on detected dependencies (databases, APIs, cloud platforms, browser automation, DevOps tools). Use `${VAR}` for secrets. Only include servers the project actually needs — do not speculatively add servers.
+
+*Why?*: Copilot CLI no longer supports `.vscode/mcp.json` — the correct location is `.mcp.json` at the repo root. If `.vscode/mcp.json` exists, flag it as "Could Be Better" and suggest migrating to `.mcp.json`.
+
+---
+
+## Step 5 — Generate CI workflow
+
+If no PR-triggered workflow exists, create `.github/workflows/ci.yml` with: `pull_request` + `push` triggers with `paths-ignore` for docs/config, a build-and-test job matching the project's actual toolchain. Use the **default branch** detected in Step 0b — do not hardcode `main`. Never modify existing workflows.
+
+---
+
+## Step 6 — Generate issue templates and PR template
+
+If missing, create bug report and feature request YAML forms, plus a PR template with description, changes, how-to-test, and checklist (derived from maintenance matrix). Note old-format `.md` templates as "Could Be Better."
+
+---
+
+## Step 7 — Update README Contributing section
+
+If README exists but has no Contributing section: link to `CONTRIBUTING.md` if it exists, otherwise add a Contributing section with fork/branch/PR instructions and test commands. Never rewrite the rest of the README.
+
+---
+
+## Step 8 — Verify maintenance matrix
+
+Verify the matrix in `copilot-instructions.md` covers file cross-references, change cascades, and cross-cutting concerns. Trace actual dependency graphs per language (`.csproj` ProjectReferences, import chains, `mod` declarations, `__init__.py` re-exports).
+
+---
+
+## Step 9 — Evaluate and improve changelog
+
+If missing, create `CHANGELOG.md` with Keep a Changelog format. If a pointer file, verify the target. If stale, flag with dates. Document non-standard locations in AGENTS.md.
+
+---
+
+## Step 10 — Evaluate and improve documentation
+
+If docs exist, add to AGENTS.md and copilot-instructions.md. If missing, assess whether needed by project type. Always document docs status in AGENTS.md.
+
+---
+
+## Step 11 — Display the AI-Readiness Report
+
+Display the report using the format in [references/report-template.md](references/report-template.md). Include the skill version from frontmatter `metadata.version` at the bottom of the report (e.g., `Assisted by ai-ready v1.0.0`). Then:
+1. Add AI-Ready badge (see report-template.md § 11a)
+2. Offer to create PR (see report-template.md § 11b)
+
+---
+
+## Important Rules
+
+### Do No Harm
+
+This skill's first obligation is to leave the repo in a **better state than it found it — never worse**. Every rule below serves this principle.
+
+- **NEVER create duplicates** — before creating any file, check ALL known locations (canonical, legacy, and root). If a file exists anywhere, do not create another copy. Consolidate instead.
+- **NEVER push directly to main/master** — always create a feature branch and open a PR for review. The only exception is if the user explicitly asks to commit to the default branch.
+- **NEVER overwrite existing files** — only create missing assets. Flag drift for user review.
+- **NEVER delete files without user approval** — if consolidating duplicates or removing stale files, include the deletion in the PR for review.
+
+### General Rules
+
+- **NEVER open a pager** — append `| cat` to every `gh`/`git` command. Use `git --no-pager`.
+- **ALWAYS customize to the repo's actual stack** — never produce generic boilerplate.
+- **Self-consistency** — every generated file must follow the conventions you establish. Cross-check before finalizing.
+- **GitHub-native by default** — auto-discover via MCP tools and `gh` CLI. Fall back to local analysis.
+- **Mine PR reviews** — turn repeated review feedback into `copilot-instructions.md` rules.
+- **Be specific** — real file paths, real commands, real patterns.
+- **Use `create` to write new files** — never `edit` from scratch.
+- **Run full analysis first (Steps 0–1)** — never guess.
+- **ALWAYS display the report at the end** — never skip or abbreviate.
+- **NEVER use markdown headings in user output** — use bold + emojis instead.
+- **ALWAYS mention the AI Ready skill in issue/PR communication** — when posting to an issue or PR (body or comment), include explicit attribution such as `Assisted by [ai-ready](https://github.com/johnpapa/ai-ready)`.
+- **ALWAYS update docs to repo standards** — when generated guidance or workflows change, update related docs and changelog per the repo's maintenance matrix (for this repo: `README.md`, `docs/how-it-works.md`, `AGENTS.md`, `CHANGELOG.md`).
+- **ALWAYS handle PR conflicts proactively** — when creating PRs, sync with the target branch and attempt conflict resolution; if conflicts remain, explicitly ask the user how they want to proceed.
+
+---
+
+## Training Repos
+
+See [references/training-repos.md](references/training-repos.md) for the full list of repos used to validate this skill's heuristics.