@silverassist/agents-toolkit 2.0.0

package/templates/shared/instructions/github-workflow.instructions.md

@@ -0,0 +1,245 @@
+---
+description: GitHub workflow standards including branch management, PRs, issues, releases, and gh CLI usage for Silver Assist plugins
+name: GitHub Workflow
+applyTo: "**"
+---
+
+# GitHub Workflow — Silver Assist Plugins
+
+---
+
+## Branch Management
+
+### Naming Conventions
+
+```
+main                 → Production branch (default)
+feature/description  → New features
+fix/description      → Bug fixes
+chore/description    → Maintenance tasks
+hotfix/description   → Emergency fixes
+release/vX.Y.Z       → Release preparation
+refactor/description → Code refactoring
+```
+
+### Workflow
+
+```bash
+# 1. Start new feature from main.
+git checkout main && git pull origin main
+git checkout -b feature/new-feature
+
+# 2. Work and commit.
+git add . && git commit -m "feat: Add new feature"
+
+# 3. MANDATORY: Run quality checks BEFORE pushing.
+vendor/bin/phpcs && vendor/bin/phpstan analyse && vendor/bin/phpunit
+
+# 4. Push and create PR.
+git push -u origin feature/new-feature
+gh pr create --title "feat: Add new feature" --base main | cat
+
+# 5. After merge, clean up branches.
+git checkout main && git pull origin main
+git branch -d feature/new-feature
+git push origin --delete feature/new-feature
+```
+
+### Rules
+
+- **NEVER** commit directly to `main`
+- **NEVER** merge without CI passing
+- **ALWAYS** delete branches after merge
+- **ALWAYS** run quality checks before pushing
+
+---
+
+## GitHub CLI — ALWAYS Pipe to `cat`
+
+**CRITICAL**: Always append `| cat` or use `GH_PAGER=cat` to prevent terminal pagination:
+
+```bash
+# ✅ CORRECT
+gh issue list | cat
+gh pr view 42 | cat
+GH_PAGER=cat gh run list --limit 5
+
+# ❌ WRONG — Will hang waiting for pager input.
+gh issue list
+gh pr view 42
+```
+
+### Quick Reference
+
+```bash
+# Issues.
+gh issue list | cat
+gh issue create --label "enhancement" | cat
+gh issue view NUMBER | cat
+gh issue close NUMBER --comment "Completed in PR #XX" | cat
+
+# Pull Requests.
+gh pr list | cat
+gh pr create --base main | cat
+gh pr view NUMBER | cat
+gh pr checks NUMBER | cat
+gh pr merge NUMBER --squash --delete-branch | cat
+
+# Releases.
+gh release list | cat
+gh release view TAG | cat
+
+# Workflows.
+GH_PAGER=cat gh run list --limit 5
+GH_PAGER=cat gh workflow list
+```
+
+---
+
+## Issue Management
+
+### Required Labels
+
+**Type**: `enhancement`, `bug`, `documentation`, `refactoring`, `testing`, `security`, `performance`
+
+**Priority**: `major-release` (X.0.0), `minor-release` (1.X.0), `patch-release` (1.3.X)
+
+---
+
+## PR Reviews vs Comments (CRITICAL)
+
+| Type | Location | How to Reply |
+|------|----------|--------------|
+| **Reviews** | "Files changed" tab, inline on code | `gh api graphql` mutation |
+| **Comments** | "Conversation" tab | `gh pr comment` or MCP |
+
+### Replying to PR Review Threads
+
+```bash
+# 1. Get review threads.
+gh api graphql -f query='
+query {
+  repository(owner: "SilverAssist", name: "REPO_NAME") {
+    pullRequest(number: PR_NUMBER) {
+      reviewThreads(first: 50) {
+        nodes {
+          id
+          path
+          isResolved
+          comments(first: 5) { nodes { body author { login } } }
+        }
+      }
+    }
+  }
+}' | cat
+
+# 2. Reply to thread (SEPARATE mutation per thread).
+gh api graphql -f query='
+mutation {
+  addPullRequestReviewThreadReply(input: {
+    pullRequestReviewThreadId: "PRRT_kwDOXXXXX",
+    body: "Applied in commit [SHA](url). **Description.**"
+  }) { comment { id } }
+}' | cat
+```
+
+---
+
+## Semantic Versioning
+
+| Version | Type | When to Use |
+|---------|------|-------------|
+| MAJOR (X.0.0) | Breaking changes | Architecture refactoring |
+| MINOR (1.X.0) | New features | Backwards compatible additions |
+| PATCH (1.3.X) | Bug fixes | Documentation, small fixes |
+
+---
+
+## Post-PR Merge Checklist
+
+```bash
+# 1. Clean up branches.
+git checkout main && git pull origin main
+git branch -d feature/your-feature
+git push origin --delete feature/your-feature
+git fetch --prune
+
+# 2. Close related issues.
+gh issue close ISSUE_NUMBER --comment "✅ Completed in PR #XX" | cat
+```
+
+---
+
+## GitHub Actions Best Practices
+
+### Dependabot Auto-merge Workflow
+
+When creating jobs that only run for Dependabot PRs, **NEVER** use job-level `if: github.actor == 'dependabot[bot]'`. This causes the job to be "skipped", which can:
+- Fail branch protection rules that require the job to pass
+- Show confusing status in the PR checks
+
+**❌ WRONG — Job skipped for non-Dependabot PRs:**
+```yaml
+jobs:
+  auto-merge-dependabot:
+    runs-on: ubuntu-latest
+    if: github.actor == 'dependabot[bot]'  # ❌ Job will be SKIPPED
+    steps:
+      - name: Dependabot metadata
+        uses: dependabot/fetch-metadata@v2
+```
+
+**✅ CORRECT — Job runs, steps conditionally execute:**
+```yaml
+jobs:
+  auto-merge-dependabot:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request' && success()  # ✅ Always runs for PRs
+    steps:
+      - name: Check if Dependabot PR
+        id: check-actor
+        run: |
+          if [ "${{ github.actor }}" = "dependabot[bot]" ]; then
+            echo "is_dependabot=true" >> $GITHUB_OUTPUT
+            echo "✅ This is a Dependabot PR, proceeding with auto-merge checks."
+          else
+            echo "is_dependabot=false" >> $GITHUB_OUTPUT
+            echo "ℹ️ Not a Dependabot PR, skipping auto-merge steps."
+          fi
+      
+      - name: Dependabot metadata
+        if: steps.check-actor.outputs.is_dependabot == 'true'
+        id: metadata
+        uses: dependabot/fetch-metadata@v2
+      
+      - name: Auto-approve PR
+        if: |
+          steps.check-actor.outputs.is_dependabot == 'true' && (
+            steps.metadata.outputs.update-type == 'version-update:semver-patch' ||
+            steps.metadata.outputs.update-type == 'version-update:semver-minor'
+          )
+        run: gh pr review --approve "$PR_URL"
+```
+
+### Action Version Pinning
+
+**ALWAYS** pin GitHub Actions to full commit SHA with version comment:
+
+```yaml
+# ✅ CORRECT — SHA pinned with version comment.
+uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+# ❌ WRONG — Floating tag, insecure.
+uses: actions/checkout@v4
+```
+
+### Standard Workflow Files
+
+Every Silver Assist plugin should have these workflows in `.github/workflows/`:
+
+| File | Purpose |
+|------|---------|
+| `quality-checks.yml` | PHPCS, PHPStan, PHPUnit on PRs and pushes |
+| `release.yml` | Automated releases on tag push |
+| `dependency-updates.yml` | Weekly dependency checks + Dependabot auto-merge |
+| `copilot-setup-steps.yml` | Reusable setup for Copilot Coding Agent |

package/templates/shared/instructions/php-standards.instructions.md

@@ -0,0 +1,293 @@
+---
+description: PHP coding standards, WordPress conventions, security, type safety, and i18n for Silver Assist WordPress plugins
+name: PHP Standards
+applyTo: "**/*.php"
+---
+
+# PHP Code Quality Standards — Silver Assist Plugins
+
+**Applies to**: All PHP files in Silver Assist WordPress plugins
+**Standards**: PHPCS (WordPress-Extra), PHPStan Level 8, PHP 8.2+
+
+---
+
+## Quality Gates (MANDATORY Before Commit)
+
+```bash
+# 1. Auto-fix formatting (REQUIRED FIRST).
+vendor/bin/phpcbf
+
+# 2. Check WordPress Coding Standards (MUST PASS — 0 errors).
+vendor/bin/phpcs
+
+# 3. Static Analysis Level 8 (MUST PASS — 0 errors).
+vendor/bin/phpstan analyse includes/ --level=8
+
+# 4. Run tests (MUST PASS — all green).
+vendor/bin/phpunit
+```
+
+**Zero tolerance**: Code with PHPCS or PHPStan errors will be rejected by CI/CD.
+
+---
+
+## WordPress Coding Standards (PHPCS)
+
+### 1. Inline Comments MUST End with Punctuation
+
+```php
+// ✅ CORRECT
+// This is a proper comment.
+the_content();
+
+// ❌ WRONG — Will fail PHPCS.
+// This is wrong
+the_content();
+```
+
+### 2. Use Tabs for Indentation (WordPress Standard)
+
+```php
+// ✅ CORRECT
+if ( $condition ) {
+	echo 'Use tabs';
+}
+
+// ❌ WRONG
+if ( $condition ) {
+    echo 'Spaces fail PHPCS';
+}
+```
+
+### 3. Spaces Inside Parentheses
+
+```php
+// ✅ CORRECT — Spaces inside parentheses.
+if ( $condition ) {
+    do_something( $param1, $param2 );
+}
+
+// ❌ WRONG — No spaces.
+if ($condition) {
+    do_something($param1, $param2);
+}
+```
+
+### 4. String Quotation
+
+```php
+// ✅ Single quotes for strings without interpolation.
+$status = 'error';
+__( 'Text', 'plugin-text-domain' );
+
+// ✅ Double quotes for interpolation.
+$message = "Error in form {$form_id}";
+
+// ❌ WRONG — Double quotes without interpolation.
+$status = "error";
+```
+
+### 5. WordPress Functions in Namespaced Code
+
+```php
+// ✅ Use backslash prefix for WordPress/global functions.
+\add_action( 'init', [ $this, 'init' ] );
+\get_option( 'option_name' );
+\sanitize_text_field( $input );
+
+// ❌ No prefix causes potential namespace resolution issues.
+add_action( 'init', [ $this, 'init' ] );
+```
+
+### 6. PHP File Header
+
+```php
+<?php
+/**
+ * File description.
+ *
+ * @package    SilverAssist\PluginName
+ * @subpackage Component
+ * @since      X.Y.Z
+ */
+
+namespace SilverAssist\PluginName\Component;
+
+\defined( 'ABSPATH' ) || exit;
+```
+
+---
+
+## Security (CRITICAL)
+
+### Nonce Validation (CSRF Protection)
+
+```php
+// ✅ CORRECT — Verify nonce FIRST in AJAX handlers.
+public function ajax_handler(): void {
+    check_ajax_referer( 'plugin_nonce', 'nonce' );
+
+    if ( ! current_user_can( 'manage_options' ) ) {
+        wp_send_json_error( 'Unauthorized', 403 );
+        return;
+    }
+
+    wp_send_json_success( $data );
+}
+```
+
+### Input Sanitization
+
+```php
+$text   = \sanitize_text_field( \wp_unslash( $_POST['field'] ) );
+$email  = \sanitize_email( $_POST['email'] );
+$url    = \esc_url_raw( $_POST['url'] );
+$int    = \absint( $_POST['number'] );
+$key    = \sanitize_key( $_POST['key'] );
+$array  = \array_map( 'sanitize_text_field', $_POST['items'] );
+```
+
+### Output Escaping
+
+| Function | Use Case | Example |
+|----------|----------|---------|
+| `esc_html()` | Plain text | `<h1><?php echo esc_html( $title ); ?></h1>` |
+| `esc_url()` | URLs (href, src) | `<a href="<?php echo esc_url( $url ); ?>">` |
+| `esc_attr()` | HTML attributes | `<div class="<?php echo esc_attr( $class ); ?>">` |
+| `wp_kses_post()` | Rich HTML content | `<?php echo wp_kses_post( $content ); ?>` |
+
+### Database Queries — Always Prepared Statements
+
+```php
+// ✅ CORRECT — Use %i for table/column names (WordPress 6.2+).
+$results = $wpdb->get_results(
+    $wpdb->prepare(
+        'SELECT * FROM %i WHERE status = %s AND form_id = %d',
+        $table_name,
+        $status,
+        $form_id
+    ),
+    ARRAY_A
+);
+
+// ❌ WRONG — Direct interpolation (SQL injection risk).
+$results = $wpdb->get_results(
+    "SELECT * FROM {$table_name} WHERE status = '{$status}'"
+);
+```
+
+**Placeholder Reference:**
+
+| Placeholder | Use Case |
+|-------------|----------|
+| `%i` | Identifiers (table/column names) |
+| `%s` | Strings |
+| `%d` | Integers |
+| `%f` | Floats |
+
+---
+
+## Type Safety (PHPStan Level 8)
+
+### Strict Types Required
+
+```php
+// ✅ Full type hints on all methods.
+public function process_log( int $log_id, string $status ): bool {
+    return true;
+}
+
+/**
+ * @param array<string, mixed> $filters Filter parameters.
+ * @return array<int, array<string, mixed>> Log entries.
+ */
+public function get_logs( array $filters ): array {
+    return [];
+}
+```
+
+### Nullable Types
+
+```php
+private ?int $log_id = null;
+
+public function get_log( int $log_id ): ?array {
+    // May return null if not found.
+}
+```
+
+### PHPDoc for Complex Types
+
+```php
+/**
+ * @param array{
+ *     id: int,
+ *     status: string,
+ *     error_message?: string,
+ * } $entry Entry data.
+ * @return array{items: array<int, array<string, mixed>>, total: int}
+ */
+public function process_entry( array $entry ): array {
+}
+```
+
+---
+
+## Internationalization (i18n)
+
+### Text Domain — Always Literal String
+
+```php
+// ✅ CORRECT — Literal text domain (extractable).
+__( 'Error occurred', 'plugin-text-domain' );
+esc_html_e( 'Success!', 'plugin-text-domain' );
+
+// ❌ WRONG — Variable/constant (NOT extractable by wp i18n make-pot).
+__( 'Error', $text_domain );
+```
+
+### Ordered Placeholders (MANDATORY for Multiple Args)
+
+```php
+// ✅ CORRECT — Positional placeholders with translator comment.
+sprintf(
+    /* translators: %1$s: form name, %2$d: submission count */
+    __( 'Form "%1$s" has %2$d submissions', 'plugin-text-domain' ),
+    $form_name,
+    $count
+);
+
+// ❌ WRONG — Unordered placeholders (PHPCS error).
+sprintf( __( 'Form "%s" has %d submissions', 'plugin-text-domain' ), $form_name, $count );
+```
+
+### Translation Functions Reference
+
+| Function | Use Case |
+|----------|----------|
+| `__()` | Return translated string |
+| `_e()` | Echo translated string |
+| `esc_html__()` | Return translated + escaped for HTML |
+| `esc_html_e()` | Echo translated + escaped for HTML |
+| `esc_attr__()` | Return translated + escaped for attribute |
+| `_n()` | Singular/plural forms |
+| `_x()` | Translation with context |
+
+### Pre-PR: Update .pot File
+
+```bash
+wp i18n make-pot . languages/plugin-text-domain.pot --domain=plugin-text-domain
+```
+
+---
+
+## Common PHPCS Errors & Quick Fixes
+
+| Error | Fix |
+|-------|-----|
+| `Inline comments must end in full-stops` | Add `.` to end of comment |
+| `Whitespace found at end of line` | Remove trailing spaces (phpcbf auto-fixes) |
+| `Tabs must be used to indent lines` | Replace spaces with tabs |
+| `Use single quotes when not evaluating` | Change `"string"` to `'string'` |
+| `Detected usage of a non-sanitized input` | Add `sanitize_*()` function |
+| `OutputNotEscaped` | Use `esc_html()`, `esc_url()`, `esc_attr()` |