@silverassist/agents-toolkit 2.5.1 → 2.6.0

package/README.md

@@ -77,7 +77,7 @@ AGENTS.md                             # Copilot Coding Agent instructions (proje
 └── skills/                           # Canonical store (single source of truth)
     ├── domain-driven-design/
     ├── testing-patterns/
-    └── ...                           # 9 skills total, filtered by --stack
+    └── ...                           # 13 skills total, filtered by --stack
 ```
 
 > **Skills follow the [`npx skills`](https://github.com/vercel-labs/skills) standard.** The real skill files live once in the canonical `.agents/skills/` store, and each agent's `skills/` directory contains symlinks to it — a single source of truth shared across Copilot, Claude Code, and Codex. Use `--copy` to materialize real copies instead of symlinks (e.g. on Windows without developer mode; symlinks also fall back to copies automatically when unsupported).
@@ -105,7 +105,7 @@ CLAUDE.md                             # Project instructions for Claude Code (pr
 └── skills/                           # Canonical skills store (single source of truth)
     ├── domain-driven-design/
     ├── testing-patterns/
-    └── ...                           # 9 skills total, filtered by --stack
+    └── ...                           # 13 skills total, filtered by --stack
 .claude/
 ├── commands/
 │   ├── _partials/
@@ -165,7 +165,7 @@ AGENTS.md                             # Project instructions for Codex (project
 └── skills/                           # Canonical store (single source of truth)
     ├── domain-driven-design/
     ├── testing-patterns/
-    └── ...                           # 9 skills total, filtered by --stack
+    └── ...                           # 13 skills total, filtered by --stack
 ```
 
 ### Global Install (Optional)
@@ -240,6 +240,11 @@ The same set of prompts is available for all supported tools.
 | `review-code` | Quick code review | — |
 | `fix-issues` | Fix lint/type/test errors | — |
 | `add-tests` | Add tests for components | `{target-file}` |
+| `audit-ai-seo` | Audit a page for AI Search / agent-friendliness (E-E-A-T, semantic HTML, JSON-LD) | `{target-url}` |
+| `new-wp-component` | Scaffold a new component in a Silver Assist WordPress plugin | `{component-name}` |
+| `new-wp-plugin` | Scaffold a new Silver Assist WordPress plugin from scratch | `{plugin-name}` |
+| `quality-check` | Run the full quality pipeline (PHPCS, PHPStan level 8, PHPUnit) for a WP plugin | — |
+| `resolve-github-reviews` | Fetch, reply to, resolve & close PR review threads (Copilot/human) | `{pr-number}`, `{repo}` |
 
 ### Workflow Stages
 
@@ -427,12 +432,18 @@ File-type specific guidelines applied automatically by Copilot and available as
 | Instruction | Applies To | Description |
 |-------------|------------|-------------|
 | `typescript.instructions.md` | `*.ts, *.tsx` | TypeScript best practices |
+| `tsdoc-standards.instructions.md` | `*.ts, *.tsx` | TSDoc (not JSDoc) doc-comment standard: allowed tags, forbidden JSDoc patterns, templates |
 | `react-components.instructions.md` | `*.tsx` | React component patterns |
 | `server-actions.instructions.md` | `**/actions/*.ts` | Next.js Server Actions |
 | `tests.instructions.md` | `*.test.ts, *.test.tsx` | Testing patterns |
+| `testing-standards.instructions.md` | `tests/**/*.php` | PHPUnit testing standards for Silver Assist WordPress plugins |
 | `css-styling.instructions.md` | `*.css, *.tsx` | Tailwind CSS & shadcn/ui standards |
 | `caching.instructions.md` | `next.config.*, src/proxy.ts, src/lib/**, **/route.ts, **/page.tsx` | Next.js caching: read-vs-mutation fetch caching, ISR tiers, CDN invalidation |
 | `seo-ai-optimization.instructions.md` | `*.tsx` | Semantic HTML, accessibility tree, metadata, JSON-LD & E-E-A-T for AI Search |
+| `documentation-language.instructions.md` | `**` | English-only technical content, documentation, commit and PR conventions |
+| `github-workflow.instructions.md` | `**` | GitHub workflow: branch management, PRs, issues, releases, `gh` CLI |
+| `php-standards.instructions.md` | `*.php` | PHP coding standards, WordPress conventions, security, type safety, i18n |
+| `wordpress-plugin-architecture.instructions.md` | `*.php` | WordPress plugin architecture: LoadableInterface, PSR-4, MVC, singleton |
 
 ## Skills
 
@@ -440,10 +451,19 @@ Specialized knowledge guides for domain-specific patterns:
 
 | Skill | Description |
 |-------|-------------|
+| `ai-seo-optimization` | Optimize sites for Google generative AI features, agent-friendly HTML, E-E-A-T |
 | `component-architecture` | React component patterns, folder structure, naming conventions |
+| `core-review` | Whole-repo pre-review (before a PR / before pushing review fixes) run as a read-only pass — inline on Copilot/Codex, optionally a subagent on Claude Code — to preempt Copilot iterations |
+| `create-component` | Scaffold a new component in a Silver Assist WordPress plugin (LoadableInterface) |
 | `domain-driven-design` | DDD principles, domain organization, barrel exports |
+| `github-review-management` | Fetch, reply to, resolve & close GitHub PR review threads via `gh` CLI + GraphQL (backs `resolve-github-reviews`) |
 | `nextjs-caching` | Next.js caching strategy: read-vs-mutation fetch, ISR tiers, CDN invalidation, diagnosing dynamic-render leaks |
+| `plugin-creation` | Scaffold a new Silver Assist WordPress plugin from scratch (PSR-4, LoadableInterface, CI/CD) |
+| `quality-checks` | Run PHPCS, PHPStan (level 8), and PHPUnit for Silver Assist WordPress plugins |
+| `release-management` | Create and manage releases for Silver Assist WordPress plugins (unified build + GH Actions) |
+| `testing` | Write and run PHPUnit tests for Silver Assist WordPress plugins (`WP_UnitTestCase`) |
 | `testing-patterns` | Jest + RTL patterns for Next.js 15 and Server Actions |
+| `tsdoc-standards` | Write & enforce TSDoc (not JSDoc): allowed tags, forbidden JSDoc patterns, templates, review checklist |
 
 Skills follow the [`npx skills`](https://github.com/vercel-labs/skills) standard: the real files live once in the canonical `.agents/skills/` store, and each agent's `skills/` directory symlinks to it (single source of truth, easy updates). Pass `--copy` to materialize real copies instead.
 

package/bin/cli.js

@@ -51,7 +51,7 @@ const DEFAULT_CONFIG = {
  */
 const FILE_CATEGORIES = {
   instructions: {
-    react: ['caching', 'css-styling', 'react-components', 'seo-ai-optimization', 'server-actions', 'tests', 'typescript'],
+    react: ['caching', 'css-styling', 'react-components', 'seo-ai-optimization', 'server-actions', 'tests', 'tsdoc-standards', 'typescript'],
     wordpress: ['php-standards', 'wordpress-plugin-architecture', 'testing-standards'],
     universal: ['documentation-language', 'github-workflow'],
   },
@@ -61,11 +61,11 @@ const FILE_CATEGORIES = {
     universal: [
       'analyze-ticket', 'work-ticket', 'analyze-github-issue', 'work-github-issue',
       'create-plan', 'create-pr', 'prepare-pr', 'finalize-pr',
-      'create-github-pr', 'finalize-github-pr',
+      'create-github-pr', 'finalize-github-pr', 'resolve-github-reviews',
       'review-code', 'fix-issues', 'add-tests', 'prepare-github-release',
     ],
     jira: ['analyze-ticket', 'work-ticket', 'create-pr', 'finalize-pr'],
-    github: ['analyze-github-issue', 'work-github-issue', 'create-github-pr', 'finalize-github-pr'],
+    github: ['analyze-github-issue', 'work-github-issue', 'create-github-pr', 'finalize-github-pr', 'resolve-github-reviews'],
   },
   partials: {
     react: ['release-node'],
@@ -75,9 +75,10 @@ const FILE_CATEGORIES = {
     universal: ['git-operations', 'pr-template', 'validations', 'documentation'],
   },
   skills: {
-    react: ['component-architecture', 'nextjs-caching', 'testing-patterns'],
+    react: ['component-architecture', 'nextjs-caching', 'testing-patterns', 'tsdoc-standards'],
     wordpress: ['create-component', 'plugin-creation', 'quality-checks', 'testing'],
-    universal: ['domain-driven-design', 'release-management'],
+    github: ['github-review-management', 'core-review'],
+    universal: ['domain-driven-design', 'release-management', 'github-review-management', 'core-review'],
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silverassist/agents-toolkit",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Reusable AI agent prompts for development workflows with Jira integration — supports GitHub Copilot, Claude Code, and Codex",
   "author": "Santiago Ramirez",
   "license": "PolyForm-Noncommercial-1.0.0",

package/src/index.js

@@ -3,7 +3,7 @@
  * @module @silverassist/agents-toolkit
  */
 
-export const VERSION = "2.5.1";
+export const VERSION = "2.6.0";
 
 export const PROMPTS = {
   workflow: [
@@ -26,6 +26,7 @@ export const PROMPTS = {
     "new-wp-component",
     "new-wp-plugin",
     "quality-check",
+    "resolve-github-reviews",
     "review-code",
   ],
 };
@@ -52,6 +53,7 @@ export const INSTRUCTIONS = [
   "server-actions",
   "testing-standards",
   "tests",
+  "tsdoc-standards",
   "typescript",
   "wordpress-plugin-architecture",
 ];
@@ -59,14 +61,17 @@ export const INSTRUCTIONS = [
 export const SKILLS = [
   "ai-seo-optimization",
   "component-architecture",
+  "core-review",
   "create-component",
   "domain-driven-design",
+  "github-review-management",
   "nextjs-caching",
   "plugin-creation",
   "quality-checks",
   "release-management",
   "testing",
   "testing-patterns",
+  "tsdoc-standards",
 ];
 
 export const HOOKS = ["validate-tsx", "lint-format"];

package/templates/agents/AGENTS.codex.md

@@ -24,7 +24,9 @@
 
 [Skills]|root:.github/skills
 |component-architecture/SKILL.md → Component design patterns
+|core-review/SKILL.md            → Whole-repo pre-review (inline read-only pass) to preempt Copilot iterations
 |domain-driven-design/SKILL.md   → DDD principles and structure
+|github-review-management/SKILL.md → Resolve GitHub PR review threads (gh + GraphQL)
 |testing-patterns/SKILL.md       → Testing strategies and patterns
 ```
 

package/templates/agents/AGENTS.md

@@ -19,15 +19,19 @@
 |seo-ai-optimization.instructions.md → Semantic HTML, a11y tree, metadata, JSON-LD for AI Search
 |server-actions.instructions.md      → Server action patterns, validation, error handling
 |tests.instructions.md               → Test structure, mocking, assertions
-|typescript.instructions.md          → Type safety, destructuring, JSDoc
+|tsdoc-standards.instructions.md     → TSDoc doc comments (not JSDoc): allowed tags, forbidden patterns, templates
+|typescript.instructions.md          → Type safety, destructuring, doc comments
 
 [Prompts]|root:.github/prompts
-|add-tests,analyze-ticket,create-plan,create-pr,finalize-pr,fix-issues,prepare-pr,review-code,work-ticket
+|add-tests,analyze-ticket,create-plan,create-pr,finalize-pr,fix-issues,prepare-pr,resolve-github-reviews,review-code,work-ticket
 
 [Skills]|root:.github/skills
-|component-architecture/SKILL.md → Component design patterns
-|domain-driven-design/SKILL.md   → DDD principles and structure
-|testing-patterns/SKILL.md       → Testing strategies and patterns
+|component-architecture/SKILL.md   → Component design patterns
+|core-review/SKILL.md              → Whole-repo pre-review (read-only pass, inline on Copilot) to preempt Copilot iterations
+|domain-driven-design/SKILL.md     → DDD principles and structure
+|github-review-management/SKILL.md → Resolve GitHub PR review threads (gh + GraphQL)
+|testing-patterns/SKILL.md         → Testing strategies and patterns
+|tsdoc-standards/SKILL.md          → TSDoc doc comments (not JSDoc)
 ```
 
 ---

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

@@ -0,0 +1,182 @@
+---
+description: TSDoc documentation standard (not JSDoc) for TypeScript — allowed tags, forbidden JSDoc patterns, and comment templates
+name: TSDoc Standards
+applyTo: "**/*.{ts,tsx}"
+---
+
+# TSDoc Standards
+
+All documentation comments in this project follow the **TSDoc** standard (not JSDoc).
+
+---
+
+## Core Rules
+
+### 1. No type annotations in `@param` or `@returns`
+
+```typescript
+// ❌ JSDoc style — FORBIDDEN
+/** @param {string} name - The user's name */
+/** @returns {boolean} True if valid */
+
+// ✅ TSDoc style — CORRECT
+/** @param name - The user's name */
+/** @returns True if valid */
+```
+
+### 2. Use `@typeParam` for generics (not `@template`)
+
+```typescript
+// ❌ FORBIDDEN
+/** @template T - The item type */
+
+// ✅ CORRECT
+/** @typeParam T - The item type */
+```
+
+### 3. Use `@packageDocumentation` for file headers (not `@module`)
+
+```typescript
+// ❌ FORBIDDEN
+/** @module lib/ccds/client */
+
+// ✅ CORRECT
+/**
+ * @packageDocumentation
+ * Base client for making requests to the CCDS API.
+ */
+```
+
+### 4. Document interface members inline (not `@property`)
+
+```typescript
+// ❌ FORBIDDEN
+/**
+ * @property {string} name - The community name
+ * @property {string} city - The city
+ */
+interface Community { name: string; city: string; }
+
+// ✅ CORRECT
+interface Community {
+  /** The community name. */
+  name: string;
+  /** The city where the community is located. */
+  city: string;
+}
+```
+
+---
+
+## Allowed TSDoc Tags
+
+| Tag | Format | Usage |
+|-----|--------|-------|
+| `@param` | `@param name - Description` | Function parameter (hyphen required) |
+| `@returns` | `@returns Description` | Return value (no type braces) |
+| `@remarks` | Block | Extended description, side effects |
+| `@example` | Block | Code example with fenced ` ```typescript ``` ` |
+| `@throws` | Block | Documented exceptions |
+| `@see` | Block | References to other symbols or URLs |
+| `@deprecated` | Block | Mark deprecated with migration guidance |
+| `@defaultValue` | Block | Default value of a property |
+| `@typeParam` | `@typeParam T - Description` | Generic type parameter |
+| `@packageDocumentation` | Modifier | Module-level doc (first comment in file) |
+| `{@link symbol}` | Inline | Hyperlink to a symbol |
+
+> **Note:** `@param` and `@returns` are optional — add them when they genuinely add clarity
+> (e.g., non-obvious parameters, complex return shapes). Do NOT add them to interfaces,
+> types, or constants.
+
+---
+
+## Comment Patterns
+
+### Server Action
+
+````typescript
+/**
+ * Submits the contact form and sends a notification email.
+ *
+ * @remarks
+ * Validates server-side, creates a DB record, dispatches email.
+ *
+ * @param formData - Submitted form data from the contact page
+ *
+ * @throws When the email service is unavailable
+ */
+export async function submitContactForm(formData: FormData): Promise<void> {}
+````
+
+### React Component
+
+````typescript
+/**
+ * Renders a responsive community card with name and location.
+ *
+ * @returns The community card JSX element
+ *
+ * @example
+ * ```tsx
+ * <CommunityCard community={community} className="mt-4" />
+ * ```
+ */
+export function CommunityCard({ community, className }: CommunityCardProps) {
+  return <article className={className}>{community.name}</article>;
+}
+````
+
+### Utility Function
+
+````typescript
+/**
+ * Formats a date string for display.
+ *
+ * @param dateString - ISO 8601 date string
+ * @returns Human-readable date (e.g., "January 15, 2025")
+ *
+ * @example
+ * ```typescript
+ * formatDate("2025-01-15"); // "January 15, 2025"
+ * ```
+ */
+export function formatDate(dateString: string): string {
+  return new Date(dateString).toLocaleDateString("en-US", { dateStyle: "long" });
+}
+````
+
+### File Header
+
+```typescript
+/**
+ * @packageDocumentation
+ * CCDS geo-search utilities for state, city, and community lookups.
+ */
+```
+
+---
+
+## Forbidden Patterns
+
+```typescript
+// ❌ Type braces in @param
+/** @param {string} name - Description */
+
+// ❌ Type braces in @returns
+/** @returns {boolean} True if valid */
+
+// ❌ @template (use @typeParam)
+/** @template T - The type */
+
+// ❌ @module (use @packageDocumentation)
+/** @module path/to/module */
+
+// ❌ @fileoverview (not a TSDoc tag)
+/** @fileoverview Description */
+
+// ❌ @typedef, @callback, @type (use TypeScript types instead)
+/** @typedef {Object} MyType */
+
+// ❌ @function, @async, @class, @enum (redundant with TypeScript)
+/** @function myFunction */
+```

package/templates/shared/prompts/README.md

@@ -23,18 +23,30 @@ prompts/
 │   ├── documentation.md        # Documentation standards
 │   └── pr-template.md          # Pull request templates
 │
-├── # Workflow Prompts (Main Flow)
-├── analyze-ticket.prompt.md    # 1. Analyze a Jira ticket
-├── create-plan.prompt.md       # 2. Create implementation plan
-├── work-ticket.prompt.md       # 3. Start working on a ticket
-├── prepare-pr.prompt.md        # 4. Prepare code for PR
-├── create-pr.prompt.md         # 5. Create a pull request
-├── finalize-pr.prompt.md       # 6. Finalize and merge PR
+├── # Workflow Prompts
+├── analyze-ticket.prompt.md         # Analyze a Jira ticket
+├── analyze-github-issue.prompt.md   # Analyze a GitHub issue
+├── create-plan.prompt.md            # Create implementation plan
+├── work-ticket.prompt.md            # Start working on a Jira ticket
+├── work-github-issue.prompt.md      # Start working on a GitHub issue
+├── prepare-pr.prompt.md             # Prepare code for PR
+├── create-pr.prompt.md              # Create a pull request (Jira)
+├── create-github-pr.prompt.md       # Create a pull request (GitHub)
+├── finalize-pr.prompt.md            # Finalize and merge PR (Jira)
+├── finalize-github-pr.prompt.md     # Finalize and merge PR (GitHub)
+├── prepare-github-release.prompt.md # Prepare a GitHub release
 │
 ├── # Utility Prompts
-├── review-code.prompt.md       # Quick code review
-├── fix-issues.prompt.md        # Fix lint/type/test errors
-└── add-tests.prompt.md         # Add tests for components
+├── review-code.prompt.md            # Quick code review
+├── fix-issues.prompt.md             # Fix lint/type/test errors
+├── add-tests.prompt.md              # Add tests for components
+├── audit-ai-seo.prompt.md           # Audit a page for AI Search / agent-friendliness
+├── resolve-github-reviews.prompt.md # Fetch/reply/resolve GitHub PR review threads
+│
+└── # WordPress Prompts
+    ├── new-wp-component.prompt.md    # Scaffold a WordPress plugin component
+    ├── new-wp-plugin.prompt.md       # Scaffold a WordPress plugin
+    └── quality-check.prompt.md       # Run PHPCS / PHPStan / PHPUnit
 ```
 
 ## Workflow Stages

package/templates/shared/prompts/create-github-pr.prompt.md

@@ -62,13 +62,57 @@ npm run build --if-present
 
 Fix any issues before proceeding.
 
-### 5. Push Branch
+### 5. Pre-PR core review (whole repo)
+
+**First, remove the planning document** created by `work-github-issue` (e.g.
+`docs/{feature-name}-plan.md`) — it has served its purpose. Deleting it now, **at PR creation
+(not at finalization)**, keeps it out of the base branch instead of accumulating in `docs/` after
+the merge. Do this **before** the review below, so the pass covers the *final* branch state and
+catches any now-stale reference to the removed file (links, indexes, mentions):
+
+```bash
+# Remove it only if it exists — a missing file is fine, but a real `git rm` error
+# (permissions, path typo) must surface, so do not blanket-mask with `|| true`.
+if [ -f docs/{feature-name}-plan.md ]; then
+  git rm docs/{feature-name}-plan.md
+fi
+```
+
+Now run a **whole-repo** consistency review to catch the doc↔code drift, invalid code examples,
+broken links, and stale indexes that otherwise trigger multi-round Copilot reviews. Review the
+whole repo — not just the diff — because Copilot re-reviews entire files.
+
+Run the **`core-review` skill** (`.agents/skills/core-review/SKILL.md`) as a dedicated,
+read-only review pass. It works on every agent — only the mechanism differs (subagents are a
+Claude-Code-only optimization, not a requirement):
+
+- **GitHub Copilot / Codex** — no subagents; run the checklist **inline as a distinct pass** over
+  the **whole repository** (not just the diff), producing the prioritized findings list.
+- **Claude Code** — optionally delegate to a read-only subagent (`Explore` / `general-purpose`)
+  with the brief "review the whole repo against the core-review checklist; report
+  `severity | file:line | problem | suggested fix`; do not edit files."
+
+Apply every `critical` and `warning` finding — including any stale reference exposed by removing
+the planning doc — re-run the checks from Step 4, then **commit the fixes and the doc removal and
+confirm a clean worktree** (`git status`) so they are included in the push. **Re-review until the
+pass reports zero findings** before continuing. See the skill for the full checklist.
+
+```bash
+# No `|| true`: a failed commit (hooks, signing, identity) must stop the flow, not be masked —
+# otherwise Step 6 would push without the planning-doc removal or the review fixes.
+git commit -m "docs: Remove planning doc for #{issue-number} ahead of PR (+ review fixes)"
+
+# The worktree must be clean before pushing — this must print nothing.
+git status --porcelain
+```
+
+### 6. Push Branch
 
 ```bash
 git push -u origin $(git branch --show-current)
 ```
 
-### 6. Create Pull Request
+### 7. Create Pull Request
 
 #### PR Title
 ```
@@ -133,7 +177,7 @@ EOF
 - **Target**: `<base-branch>` resolved from `.agents-toolkit.json` (fallback: `main`)
 - **Reviewers**: Based on changed files
 
-### 7. Comment on GitHub Issue
+### 8. Comment on GitHub Issue
 
 Add a comment linking to the PR:
 

package/templates/shared/prompts/finalize-github-pr.prompt.md

@@ -46,6 +46,12 @@ gh pr review --request-changes --body "..." | cat
 gh pr review --approve | cat
 ```
 
+> **Before pushing any fix commit**, run a **whole-repo core review** (not just the changed
+> files) using the **`core-review` skill** (`.agents/skills/core-review/SKILL.md`) as a dedicated
+> read-only pass (inline on Copilot/Codex; optionally a subagent on Claude Code). Apply everything
+> it flags first — pushing an adjacent, unfixed issue only starts a fresh Copilot round. For the
+> full fetch → reply → resolve loop, use the `resolve-github-reviews` prompt.
+
 ### 3. Sync with Base Branch
 
 ```bash
@@ -124,6 +130,6 @@ gh issue close {issue-number} --comment "Completed in PR #<pr-number>." | cat
 
 ### 8. Clean Up
 
-- [ ] Delete temporary planning docs from `docs/` (if applicable)
+- [ ] Planning docs were removed at **PR creation** (see `create-github-pr`) — verify none linger in `docs/`
 - [ ] Ensure final documentation is complete
 - [ ] Verify commit history is clean