@silverassist/agents-toolkit 2.3.0 → 2.5.0

package/src/index.js

@@ -3,45 +3,84 @@
  * @module @silverassist/agents-toolkit
  */
 
-export const VERSION = "2.3.0";
+export const VERSION = "2.5.0";
 
 export const PROMPTS = {
   workflow: [
+    "analyze-github-issue",
     "analyze-ticket",
+    "create-github-pr",
     "create-plan",
-    "work-ticket",
-    "prepare-pr",
     "create-pr",
+    "finalize-github-pr",
     "finalize-pr",
+    "prepare-github-release",
+    "prepare-pr",
+    "work-github-issue",
+    "work-ticket",
+  ],
+  utility: [
+    "add-tests",
+    "audit-ai-seo",
+    "fix-issues",
+    "new-wp-component",
+    "new-wp-plugin",
+    "quality-check",
+    "review-code",
   ],
-  utility: ["review-code", "fix-issues", "add-tests"],
 };
 
 export const PARTIALS = [
-  "validations",
+  "documentation",
   "git-operations",
+  "github-integration",
   "jira-integration",
-  "documentation",
   "pr-template",
+  "release-node",
+  "release-wordpress",
+  "validations",
 ];
 
 export const INSTRUCTIONS = [
-  "typescript",
+  "caching",
+  "css-styling",
+  "documentation-language",
+  "github-workflow",
+  "php-standards",
   "react-components",
+  "seo-ai-optimization",
   "server-actions",
+  "testing-standards",
   "tests",
-  "css-styling",
+  "typescript",
+  "wordpress-plugin-architecture",
 ];
 
 export const SKILLS = [
+  "ai-seo-optimization",
   "component-architecture",
+  "create-component",
   "domain-driven-design",
+  "nextjs-caching",
+  "plugin-creation",
+  "quality-checks",
+  "release-management",
+  "testing",
   "testing-patterns",
-  "ai-seo-optimization",
 ];
 
 export const HOOKS = ["validate-tsx", "lint-format"];
 
+// Skills follow the `npx skills` standard: a single canonical copy lives in
+// .agents/skills/ and each agent's skills directory symlinks to it.
+export const SKILLS_LAYOUT = {
+  canonicalDir: ".agents/skills",
+  agentDirs: {
+    claude: ".claude/skills",
+    copilot: ".github/skills",
+  },
+};
+
 // Claude Code equivalents
 export const CLAUDE_COMMANDS = [
   "analyze-ticket",
@@ -58,4 +97,5 @@ export const CLAUDE_COMMANDS = [
 export const CLAUDE_FILES = {
   instructions: "CLAUDE.md",
   commandsDir: ".claude/commands",
+  skillsDir: ".claude/skills",
 };

package/templates/agents/AGENTS.md

@@ -13,11 +13,13 @@
 
 ```
 [Instructions]|root:.github/instructions
-|css-styling.instructions.md       → CSS/Tailwind patterns, cn() utility, responsive design
-|react-components.instructions.md  → Component structure, exports, props, early returns
-|server-actions.instructions.md    → Server action patterns, validation, error handling
-|tests.instructions.md             → Test structure, mocking, assertions
-|typescript.instructions.md        → Type safety, destructuring, JSDoc
+|caching.instructions.md             → Next.js caching: read-vs-mutation fetch, ISR tiers, CDN invalidation
+|css-styling.instructions.md         → CSS/Tailwind patterns, cn() utility, responsive design
+|react-components.instructions.md    → Component structure, exports, props, early returns
+|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
 
 [Prompts]|root:.github/prompts
 |add-tests,analyze-ticket,create-plan,create-pr,finalize-pr,fix-issues,prepare-pr,review-code,work-ticket
@@ -133,6 +135,30 @@ import { myFunction } from '@/lib/my-module';
 
 ---
 
+## 🗄️ Caching Rules (CRITICAL)
+
+| Rule | Requirement |
+|------|-------------|
+| **Cache by intent** | Cache reads, never mutations — decide on intent, NOT the HTTP method |
+| **POST reads** | A `POST` read (e.g. filter/`geo-search`) MUST set `next: { revalidate, tags }` to cache |
+| **Mutations** | `submit`/lead/`PUT`/`DELETE` → `cache: "no-store"` (flag with `mutation: true`) |
+| **ISR** | Every cacheable route exports `revalidate`; never on form/personalized routes |
+| **Invalidation** | `/api/revalidate` calls `revalidateTag`/`revalidatePath` AND the CDN invalidation |
+
+```ts
+// ❌ WRONG: leaves POST reads uncached → route turns dynamic (private, no-store)
+next: method === "GET" ? { revalidate, tags } : { revalidate: 0 }
+
+// ✅ CORRECT: reads cache regardless of method; mutations opt out
+const isMutation = mutation || method === "PUT" || method === "DELETE";
+...(isMutation ? { cache: "no-store" } : { next: { revalidate, tags } })
+```
+
+📄 **Full details:** `.github/instructions/caching.instructions.md`
+📄 **Project-specific context (if present):** `docs/CACHING.md`
+
+---
+
 ## 📝 Git Conventions
 
 | Type | Format |
@@ -190,6 +216,8 @@ Before ANY push to dev/staging/main:
 | Creating/editing components | `react-components.instructions.md` |
 | Writing CSS/Tailwind | `css-styling.instructions.md` |
 | Creating server actions | `server-actions.instructions.md` |
+| Data fetching / `next.config` / routes / ISR / revalidate | `caching.instructions.md` |
+| Pages, metadata, JSON-LD, accessibility/SEO | `seo-ai-optimization.instructions.md` |
 | Writing tests | `tests.instructions.md` |
 | TypeScript questions | `typescript.instructions.md` |
 | **Before pushing/PR** | `tests.instructions.md` + run quality checks |

package/templates/shared/hooks/lint-format.json

@@ -1,4 +1,5 @@
 {
+  "version": 1,
   "hooks": {
     "PostToolUse": [
       {

package/templates/shared/hooks/validate-tsx.json

@@ -1,4 +1,5 @@
 {
+  "version": 1,
   "hooks": {
     "PostToolUse": [
       {

package/templates/shared/instructions/caching.instructions.md

@@ -0,0 +1,121 @@
+---
+applyTo: "**/next.config.*,**/src/proxy.ts,**/src/lib/**/*.ts,**/src/app/**/route.ts,**/src/app/**/page.tsx"
+---
+# Caching Standards (CRITICAL)
+
+These rules are **mandatory** when touching data fetching, route segment configs, the asset/page
+proxy, image config, or the on-demand revalidate route. Caching has several **independent layers**
+(ISR page cache, data-fetch cache, request dedup, asset proxy, edge/CDN) — fixing one does not fix
+the others.
+
+> Apply to any Silver Side Next.js (App Router) frontend consuming the CCDS API and/or WordPress
+> (headless GraphQL). If the project keeps a `docs/CACHING.md`, treat it as the extended reference.
+
+## Hard rules
+
+1. **Cache reads, not mutations — decide on intent, NEVER on the HTTP method.**
+   Some reads must use `POST` because they take a body (e.g. CCDS `geo-search`). They still have to
+   cache like a `GET`. Mutations (`submit-review`, lead submit, and any `PUT`/`DELETE`/`PATCH`) must
+   stay uncached with `cache: "no-store"`. Expose a `mutation: true` flag on the client and mark every
+   write with it.
+   - ❌ **Never** gate caching on `method === "GET"` (e.g. `next: method === "GET" ? {...} : { revalidate: 0 }`).
+     That leaves POST reads uncached and forces the whole route into dynamic rendering
+     (`cache-control: private, no-store`).
+
+2. **A `POST` IS cacheable cross-request — but only with explicit `next` options.**
+   Next.js does not cache `POST` by default. Any read `fetch` to CCDS or the WP GraphQL endpoint —
+   GET or POST — must set `next: { revalidate, tags }`. The request body is part of the cache key, so
+   different filter bodies cache independently.
+
+3. **Always pair `tags` with a `revalidate` duration.** `next: { tags }` alone either holds stale data
+   indefinitely or (Next 16 default) does not cache at runtime at all. Use a `CACHE_DURATIONS`-style
+   default (e.g. 24h) so freshness survives a missed webhook.
+
+4. **`React.cache()` is request dedup only.** It collapses duplicate calls within a single render. It
+   does **not** cache across requests and is never a substitute for `next: { revalidate }`.
+
+5. **Every cacheable route exports `revalidate`.** Suggested tiers: listing 24h–30d, detail/city 24h
+   (`86400`), state/landing 7d (`604800`), WP catch-all 7d. Do **not** add `revalidate` to
+   mutation/personalized routes (forms, thank-you, wizards). Prefer `export const revalidate` over
+   `dynamic = "force-static"` so a failed ISR revalidation preserves the last good cache instead of
+   overwriting it with a broken page.
+
+6. **On-demand revalidation dual-invalidates.** `/api/revalidate` must call `revalidateTag`/
+   `revalidatePath` **and** the CDN invalidation (e.g. `invalidateCloudFrontPaths`) in the same
+   request, otherwise the CDN keeps serving stale until its own TTL.
+
+7. **Image config** in `next.config`: set `minimumCacheTTL: 2592000` (30d), `qualities`, and
+   `formats: ["image/avif", "image/webp"]`. No malformed `remotePatterns` hostnames.
+
+8. **Asset proxy TTLs** are type-keyed (image/css/font) at `365d + SWR 30d`.
+
+## Canonical snippet — API client (read vs. mutation)
+
+```ts
+interface FetchOptions {
+  endpoint: string;
+  method?: "GET" | "POST" | "PUT" | "DELETE";
+  body?: object | null;
+  revalidateTag?: string;
+  revalidate?: number;
+  /** Writes are never cached. Reads (default) cache regardless of method. */
+  mutation?: boolean;
+}
+
+export async function fetchData<T>({
+  endpoint,
+  method = "GET",
+  body = null,
+  revalidateTag,
+  revalidate = 86400, // 24h time-based fallback; pair with tags for surgical invalidation
+  mutation = false,
+}: FetchOptions): Promise<T | null> {
+  const isMutation = mutation || method === "PUT" || method === "DELETE";
+
+  const requestOptions: RequestInit = {
+    method,
+    // Reads (GET or POST) cache cross-request via `next`; mutations opt out.
+    ...(isMutation
+      ? { cache: "no-store" as RequestCache }
+      : { next: { revalidate, tags: revalidateTag ? [revalidateTag] : [] } }),
+  };
+
+  if ((method === "POST" || method === "PUT") && body) {
+    requestOptions.body = JSON.stringify(body);
+  }
+  // ...fetch + error handling...
+}
+```
+
+## Canonical snippet — WordPress GraphQL client (cached POST)
+
+```ts
+export const WP_CACHE_DURATIONS = {
+  pages: 86400, posts: 86400, menus: 86400, staticPages: 604800, default: 86400,
+} as const;
+
+export async function fetchWPAPI<T>(
+  query: string,
+  { variables, revalidate = WP_CACHE_DURATIONS.default, tags }: {
+    variables?: Record<string, unknown>; revalidate?: number; tags?: string[];
+  } = {},
+) {
+  const res = await fetch(WP_API_URL, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ query, variables }),
+    next: { revalidate, ...(tags && { tags }) }, // a POST IS cacheable WITH next options
+  });
+}
+```
+
+## Do NOT
+
+- ❌ `next: method === "GET" ? {...} : { revalidate: 0 }` — leaves POST reads uncached.
+- ❌ `fetch(API_URL, { method: "POST", body })` with no `next` options (bare, uncached POST read).
+- ❌ `next: { tags }` with no `revalidate`.
+- ❌ Adding `export const revalidate` to a form/mutation/personalized route.
+- ❌ Treating `React.cache()` as cross-request caching.
+- ❌ Caching a mutation (`submit-review`, lead submit, `PUT`/`DELETE`/`PATCH`).
+- ❌ Mixing `cacheComponents: true` (`"use cache"`) with route-segment `export const revalidate` —
+  that is a separate, deliberate migration; do not introduce it ad hoc.

package/templates/shared/instructions/seo-ai-optimization.instructions.md

@@ -0,0 +1,272 @@
+---
+applyTo: "**/*.tsx"
+---
+# SEO & AI Optimization Patterns
+
+These rules ensure components are optimized for Google's generative AI features (AI Overviews, AI
+Mode) and browser-agent interactions: agent-friendly HTML, a clean accessibility tree, semantic
+structure, and E-E-A-T signals. Pairs with the `ai-seo-optimization` skill and the `audit-ai-seo`
+prompt.
+
+---
+
+## Semantic HTML (CRITICAL)
+
+### Interactive Elements
+
+**NEVER use `<div>` or `<span>` with click handlers. Use proper semantic elements.**
+
+```tsx
+// ✅ CORRECT: Semantic button
+<button onClick={handleClick} type="button">
+  Click me
+</button>
+
+// ✅ CORRECT: Navigation link
+<Link href="/page">Go to page</Link>
+
+// ❌ WRONG: Non-semantic clickable div
+<div onClick={handleClick} className="cursor-pointer">
+  Click me
+</div>
+
+// ❌ WRONG: Span with role hack
+<span role="button" onClick={handleClick}>
+  Click me
+</span>
+```
+
+### Form Inputs
+
+**Every input MUST have an associated label. Placeholder is NOT a substitute.**
+
+```tsx
+// ✅ CORRECT: Label with htmlFor
+<label htmlFor="email">Email address</label>
+<input id="email" name="email" type="email" required aria-required="true" />
+
+// ✅ CORRECT: Wrapped label (implicit association)
+<label>
+  Email address
+  <input name="email" type="email" required />
+</label>
+
+// ❌ WRONG: Placeholder only (invisible to accessibility tree)
+<input placeholder="Enter your email" type="email" />
+
+// ❌ WRONG: aria-label without visible label (poor for agents)
+<input aria-label="Email" type="email" />
+```
+
+### Heading Hierarchy
+
+**Headings must follow logical order. Never skip levels.**
+
+```tsx
+// ✅ CORRECT: Proper hierarchy
+<h1>Page Title</h1>
+<section>
+  <h2>Section Title</h2>
+  <h3>Subsection</h3>
+</section>
+
+// ❌ WRONG: Skipping h2
+<h1>Page Title</h1>
+<h3>Subsection</h3>
+
+// ❌ WRONG: Using heading for styling only
+<h4 className="text-sm font-bold">Small bold text</h4>  // Use <p> with classes instead
+```
+
+### Lists
+
+```tsx
+// ✅ CORRECT: Semantic list
+<ul>
+  {items.map(item => <li key={item.id}>{item.name}</li>)}
+</ul>
+
+// ❌ WRONG: Div-based list
+<div className="flex flex-col gap-2">
+  {items.map(item => <div key={item.id}>{item.name}</div>)}
+</div>
+```
+
+---
+
+## Accessibility for AI Agents
+
+### Skip-to-Content Link
+
+The root layout MUST include a skip-to-content link as the first focusable element:
+
+```tsx
+<body>
+  <a
+    href="#main-content"
+    className="sr-only focus:not-sr-only focus:absolute focus:z-50 focus:p-4 focus:bg-background focus:text-foreground"
+  >
+    Skip to main content
+  </a>
+  {/* Header/Navigation */}
+  <main id="main-content">
+    {children}
+  </main>
+</body>
+```
+
+### Accessible Names
+
+All interactive elements MUST have an accessible name:
+
+```tsx
+// ✅ CORRECT: Button with text content (name from content)
+<button>Submit form</button>
+
+// ✅ CORRECT: Icon button with aria-label
+<button aria-label="Close dialog">
+  <XIcon className="h-4 w-4" />
+</button>
+
+// ❌ WRONG: Icon button without accessible name
+<button>
+  <XIcon className="h-4 w-4" />
+</button>
+```
+
+### Image Alt Text
+
+```tsx
+// ✅ CORRECT: Descriptive alt text
+<Image alt="Two-story brick building with a landscaped courtyard entrance" src={src} />
+
+// ✅ CORRECT: Decorative image (empty alt)
+<Image alt="" src={decorativeBg} aria-hidden="true" />
+
+// ❌ WRONG: Generic alt text
+<Image alt="photo" src={src} />
+<Image alt="image 1" src={src} />
+
+// ❌ WRONG: Missing alt
+<Image src={src} />
+```
+
+---
+
+## Metadata & SEO
+
+### generateMetadata Pattern
+
+Every page with dynamic content MUST implement `generateMetadata`:
+
+```tsx
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { slug } = await params;
+  const data = await getData(slug);
+  if (!data) return {};
+
+  return {
+    title: data.title,
+    description: data.description,
+    openGraph: {
+      title: data.title,
+      description: data.description,
+      images: data.image ? [{ url: data.image }] : undefined,
+    },
+    alternates: {
+      canonical: getCanonicalUrl(slug),
+    },
+  };
+}
+```
+
+### No Snippet Blocking
+
+**NEVER add `nosnippet` to content pages.** This prevents AI feature inclusion:
+
+```tsx
+// ❌ WRONG: Blocks AI features
+export const metadata = {
+  robots: { index: true, follow: true, nosnippet: true },
+};
+
+// ✅ CORRECT: Allow snippets (default behavior)
+export const metadata = {
+  robots: { index: true, follow: true },
+};
+```
+
+---
+
+## Structured Data (JSON-LD)
+
+### Implementation Pattern
+
+Use a dedicated JSON-LD component in layout components:
+
+```tsx
+export function JsonLd({ data }: { data: Record<string, unknown> }) {
+  return (
+    <script
+      type="application/ld+json"
+      dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }}
+    />
+  );
+}
+```
+
+### Required Schema by Page Type
+
+| Page Type | Required Schema |
+|-----------|----------------|
+| Homepage | `Organization`, `WebSite` with `SearchAction` |
+| Local business / Location | `LocalBusiness` with address, geo, rating |
+| Blog Post | `Article` with author (`Person`), dates |
+| Author Page | `Person` with credentials, `knowsAbout` |
+| FAQ Section | `FAQPage` with Q&A pairs |
+| All Pages | `BreadcrumbList` |
+
+---
+
+## Layout Stability (CLS Prevention)
+
+```tsx
+// ✅ CORRECT: Explicit dimensions prevent layout shift
+<Image src={src} alt="..." width={800} height={600} />
+
+// ✅ CORRECT: Aspect ratio container
+<div className="aspect-video relative">
+  <Image src={src} alt="..." fill className="object-cover" />
+</div>
+
+// ❌ WRONG: No dimensions (causes layout shift)
+<img src={src} alt="..." />
+```
+
+---
+
+## Server-Side Rendering
+
+**Critical content MUST render on the server.** Client Components should only wrap interactive UI, not content:
+
+```tsx
+// ✅ CORRECT: Content in Server Component
+export default async function DetailPage({ params }: Props) {
+  const item = await getItem(params.slug);
+  return (
+    <main id="main-content">
+      <h1>{item.name}</h1>
+      <p>{item.description}</p>
+      <ContactForm itemId={item.id} /> {/* Client Component for form only */}
+    </main>
+  );
+}
+
+// ❌ WRONG: Entire page as Client Component
+"use client";
+export default function DetailPage() {
+  const [item, setItem] = useState(null);
+  useEffect(() => { fetchItem().then(setItem); }, []);
+  // Content invisible to crawlers until JS executes
+}
+```

package/templates/shared/prompts/_partials/release-node.md

@@ -0,0 +1,58 @@
+# Release — Node / npm Partial
+
+Version-bump and quality-check mechanics for **Node.js / npm packages** (anything with a
+`package.json`). Included by `prepare-github-release` when the project is detected as a Node package.
+
+## Detection signal
+
+- A `package.json` exists at the repo root **and** there is no WordPress plugin header
+  (`*.php` file with a `Version:` plugin header). If both are present, prefer the WordPress partial.
+
+## Version source of truth
+
+| File | What to update |
+|------|----------------|
+| `package.json` | `"version": "X.Y.Z"` |
+| `package-lock.json` | top-level `version` **and** the root package entry under `packages[""].version` |
+
+Prefer the npm tooling so both files stay in sync automatically:
+
+```bash
+# Bumps package.json + package-lock.json and (by default) creates a commit + tag.
+# Use --no-git-tag-version to keep the version change uncommitted so it can go in the release branch/PR.
+npm version X.Y.Z --no-git-tag-version
+```
+
+If you edit `package.json` by hand instead, re-sync the lockfile without touching dependencies:
+
+```bash
+npm install --package-lock-only
+```
+
+## Quality checks (run BEFORE bumping)
+
+Inspect `package.json` `scripts` and run whatever exists — do not assume script names:
+
+```bash
+npm ci                       # clean install when a lockfile is present (CI parity)
+npm test --if-present
+npm run lint --if-present
+npm run type-check --if-present
+npm run build --if-present
+```
+
+Do **not** proceed if any check fails.
+
+## What the release usually produces
+
+- **npm publish** — most Node packages publish to the npm registry. The publish step almost always
+  lives in a workflow triggered by a GitHub Release (`on: release: [created|published]`) or a tag
+  push — confirm via the workflow-analysis step in the orchestrator before assuming a bare tag is enough.
+- Optional build artifacts (bundled `dist/`, types) attached to the Release.
+
+## Notes
+
+- `private: true` in `package.json` means the package is **not** published to npm — the release is
+  tag/GitHub-Release only. Surface this to the user.
+- The npm version in `package.json` is the source of truth that `publish.yml`-style workflows read,
+  so it must be committed before the tag/Release is created.

package/templates/shared/prompts/_partials/release-wordpress.md

@@ -0,0 +1,56 @@
+# Release — WordPress Plugin Partial
+
+Version-bump and quality-check mechanics for **Silver Assist WordPress plugins**. Included by
+`prepare-github-release` when the project is detected as a WordPress plugin. See the
+`release-management` skill for full documentation and troubleshooting.
+
+## Detection signal
+
+- A `*.php` file with a plugin header (`* Version: X.Y.Z`) at the repo root, usually alongside a
+  `composer.json` and often a `readme.txt`.
+
+## Version source of truth
+
+| File | What to update |
+|------|----------------|
+| Main plugin file | `* Version: X.Y.Z` header **and** the `VERSION` constant if defined |
+| `readme.txt` | `Stable tag: X.Y.Z` (if present) |
+| `composer.json` | `"version": "X.Y.Z"` (if present) |
+
+Prefer the bundled script so every file stays in sync:
+
+```bash
+./scripts/update-version.sh X.Y.Z
+# Some plugins ship the simple variant instead:
+./scripts/update-version-simple.sh X.Y.Z
+```
+
+## Quality checks (run BEFORE bumping)
+
+Do **not** proceed if any check fails:
+
+```bash
+./scripts/run-quality-checks.sh --skip-wp-setup phpcs phpstan
+```
+
+If the script is absent, fall back to the tools directly:
+
+```bash
+composer run phpcs   --if-present
+composer run phpstan --if-present
+composer run test    --if-present
+```
+
+## What the release usually produces
+
+- **Distributable ZIP** — the GitHub Actions release workflow builds the plugin ZIP and attaches it
+  to the GitHub Release. This almost always triggers on `on: release: [created|published]`, so a bare
+  tag is typically **not** enough — confirm via the workflow-analysis step in the orchestrator.
+- No npm publish; WordPress plugins are distributed as ZIP artifacts (and/or wordpress.org SVN).
+
+## Notes
+
+- Some plugins use `master` instead of `main` as the default branch (e.g.
+  `silver-assist-post-revalidate`) — always verify with `gh repo view --json defaultBranchRef`.
+- The plugin-header version is what WordPress and the release workflow read, so it must be committed
+  before the tag/Release is created.

package/templates/shared/prompts/_partials/validations.md

@@ -85,3 +85,4 @@ npm run build --if-present
 - [ ] No sensitive data exposed (API keys, secrets)
 - [ ] No `any` types introduced
 - [ ] JSDoc comments on new functions
+- [ ] If data fetching / routes / `next.config` changed: caching follows `caching.instructions.md` (reads cache regardless of method, mutations `no-store`, cacheable routes export `revalidate`)