@majordigital/create-acorn 1.6.7 → 1.7.0

package/template/.claude/commands/audit-documentation-onboarding.md

@@ -0,0 +1,172 @@
+---
+description: "Run a Documentation & Onboarding audit on the current project (Module 10)"
+---
+
+# Audit: Documentation & Onboarding
+
+**Role:** Technical Writer & Developer Experience (DX) Lead
+
+**Objective:** Perform an exhaustive audit of knowledge transfer quality, developer onboarding experience, and documentation completeness. Do not limit yourself to the items listed — explore the file structure dynamically to find deep-seated gaps.
+
+---
+
+## Audit Workflow
+
+You MUST follow all phases in order. **Do NOT implement any fixes before the Stop & Review stage.**
+
+---
+
+### Phase 1: Static Analysis
+
+Inspect the codebase using Grep, Glob, and Read tools. Discover files dynamically — do not assume locations.
+
+**1. README Integrity**
+- Read the `README.md` (if present). Evaluate whether it clearly covers:
+  - Project overview and purpose
+  - Prerequisites (Node version, package manager, required accounts)
+  - Setup instructions (clone, install, environment variables, first run)
+  - CMS setup and content editing workflow (Prismic Slice Machine)
+  - Available npm scripts with descriptions
+  - Deployment notes
+  - Any known gotchas or setup friction
+- Flag any section that is missing, outdated, or insufficient for a new developer to get started in under 30 minutes.
+
+**2. Environment Variable Documentation**
+- Check for `.env.example` (or `.env.local.example`). Verify:
+  - Every required environment variable is listed with a placeholder value
+  - Each variable has an inline comment explaining what it's for and where to get it
+  - No real credentials or secrets are in the example file
+  - The list matches all variables actually used in the codebase (check `process.env.` usage)
+- Flag any variable used in code but missing from `.env.example`.
+
+**3. CLAUDE.md / AI Context Files**
+- Check if a `CLAUDE.md` exists. Verify it covers:
+  - Tech stack overview
+  - Project-specific commands and workflows
+  - Key architectural patterns (slice pattern, theme system, etc.)
+  - Naming conventions
+  - Key files and their purposes
+- This file directly impacts AI-assisted development quality — flag any major gaps.
+
+**4. Complex Code Documentation**
+- Search for non-obvious code patterns that lack explanatory comments:
+  - Custom hooks with complex logic
+  - Utility functions with non-obvious inputs/outputs (e.g., `toSlug()`, `getThemeClass()`, `fetchKnowledge()`)
+  - Workarounds or browser-specific fixes (these especially need a "why" comment)
+  - Third-party integration patterns (Zoho OAuth, Prismic preview mode)
+- Standard code (simple components, straightforward CRUD) does NOT need comments — flag only non-obvious logic.
+
+**5. CMS Slice / Architecture Guide**
+- Determine if a guide exists explaining how to:
+  - Create or extend a new Prismic slice
+  - Follow the variation pattern (`switch(toSlug(variation))`)
+  - Apply the theme system
+  - Register a new slice in the slice registry
+- This guide is critical for onboarding CMS developers and content engineers.
+- Flag if no such guide exists (in README, CLAUDE.md, or a separate doc).
+
+**6. Type Definitions & Self-Documentation**
+- Scan `src/types/` for shared type definitions.
+- Verify exported types have clear names that are self-explanatory.
+- Flag any complex union types or utility types that lack a JSDoc comment explaining their purpose.
+
+**7. Deployment & Operations Docs**
+- Verify documentation exists (in README or a separate doc) covering:
+  - How to deploy the project
+  - How ISR revalidation works (Prismic webhooks → `/api/revalidate`)
+  - How to rotate Zoho CRM OAuth tokens
+  - How Prismic preview mode is configured
+
+---
+
+### Phase 2: Research (Run in Parallel)
+
+**First**, read `.agents/patterns/documentation-onboarding.md` if it exists. Use it as a baseline — skip re-researching topics already covered unless the file is older than 3 months.
+
+Launch a research subagent to fetch current best practices. The subagent should search for:
+- Developer onboarding documentation best practices (2025–2026)
+- README standards for Next.js projects
+- JSDoc best practices for TypeScript projects
+- AI-assisted development context files (CLAUDE.md, Copilot instructions) standards
+
+Compile findings as a reference list with URLs.
+
+**Then**, create or update `.agents/patterns/documentation-onboarding.md` with any new research findings, best practices, code examples, and reference URLs. Pattern files should be refreshed every 3 months to stay current with evolving standards.
+
+---
+
+### Phase 3: Findings & Checklist
+
+Combine Phase 1 and Phase 2 results. For every issue found:
+- Assign a severity: **CRITICAL** / **HIGH** / **MEDIUM** / **LOW**
+- Include the exact file path (or "Missing — no file found")
+- State the recommended fix or content to add
+
+Save the full audit report to `.agents/audits/documentation-onboarding-{YYYY-MM-DD}.md`.
+
+Also create a condensed implementation checklist at `.agents/checklist/documentation-onboarding-{YYYY-MM-DD}.md` — group items by severity tier with commit-and-review gates between each tier. After implementing each tier: stage all changes (`git add`) but do **NOT** commit. Tell the user the changes are staged for review, and **wait for explicit approval** before proceeding to the next tier. The user will review the diff, commit themselves, and tell the agent when to continue. Reference existing files in `.agents/checklist/` for the pattern.
+
+Save the full audit report to `.agents/audits/documentation-onboarding-{YYYY-MM-DD}.md`:
+
+```markdown
+# Documentation & Onboarding Audit — {date}
+
+## Summary
+Brief overview of documentation coverage and key findings.
+
+## Research References
+- [Source](url) — why it's relevant
+
+## Findings Checklist
+
+- [ ] **[CRITICAL]** No .env.example file — new developers have no reference for required variables
+  - Fix: Create `.env.example` listing all `process.env.*` variables used in the codebase
+- [ ] **[HIGH]** README missing CMS setup instructions for Prismic Slice Machine
+  - Fix: Add section explaining `npm run slicemachine` and how to create/edit slices
+- [ ] **[MEDIUM]** `fetchKnowledge()` utility has no JSDoc — its parameters and return type are non-obvious — `src/lib/utils.ts:142`
+  - Fix: Add JSDoc comment explaining the function's purpose, parameters, and return shape
+
+## Command Outputs
+- .env.example check: {exists / missing}
+- README word count and sections found: {result}
+- CLAUDE.md check: {exists / missing}
+```
+
+---
+
+### 🛑 STOP & REVIEW
+
+**Do not proceed past this point until the user explicitly approves.**
+
+Present to the user:
+1. The full documentation gap report
+2. Each proposed fix — note that most fixes are documentation additions, not code changes
+3. Research references used
+
+Then ask:
+> "I've completed the Documentation & Onboarding audit. The checklist has been saved to `.agents/audits/documentation-onboarding-{date}.md`. Shall I proceed with implementing the fixes above?"
+
+**Wait for explicit confirmation before continuing.**
+
+---
+
+### Phase 4: Implementation
+
+After user approval, implement each approved fix in priority order. For each fix:
+- Make the change using Edit tools
+- Run `npm run check` after every meaningful change
+- Do not rewrite entire files — make targeted, focused additions
+- **Update the checklist immediately** — mark completed items with `[x]` in `.agents/checklist/documentation-onboarding-{YYYY-MM-DD}.md` as each item is implemented, not at the end
+- If the user skips or rejects an item, add it to the **Skipped / Rejected Changes** section at the bottom of the checklist using a heading + bullet format per item (e.g., `### #N — Item name` with `- **Status:**` and `- **Reason:**`)
+
+---
+
+### Phase 5: Update Checklist
+
+After all tiers are complete:
+- Verify every item is accounted for: completed `[x]`, deferred `[ ]` with reason, or logged in the Skipped / Rejected Changes section
+- Update the status line:
+```
+## Status: {Complete / Partially Complete — N items deferred, M items skipped}
+```
+- If any items were skipped or rejected, save the Skipped / Rejected Changes section to `.agents/checklist/skipped/documentation-onboarding-{YYYY-MM-DD}.md` so future audits don't re-suggest rejected changes

package/template/.claude/commands/audit-edge-api-resilience.md

@@ -0,0 +1,156 @@
+---
+description: "Run an Edge & API Resilience audit on the current project (Module 8)"
+---
+
+# Audit: Edge & API Resilience
+
+**Role:** Site Reliability Engineer (SRE) & API Architect
+
+**Objective:** Perform an exhaustive audit of caching strategy, error boundaries, loading states, and infrastructure resilience. Do not limit yourself to the items listed — explore the file structure dynamically and run terminal commands to find deep-seated issues.
+
+---
+
+## Audit Workflow
+
+You MUST follow all phases in order. **Do NOT implement any fixes before the Stop & Review stage.**
+
+---
+
+### Phase 1: Static Analysis
+
+Inspect the codebase using Grep, Glob, and Read tools. Discover files dynamically — do not assume locations.
+
+**1. Caching Strategy**
+- Search all `fetch()` calls in server components and API routes. For each:
+  - Identify whether `force-cache`, `no-store`, or `revalidate` is set
+  - Verify CMS data fetches use appropriate ISR revalidation (not `no-store` unnecessarily)
+  - Confirm static assets use `force-cache`
+  - Flag any CMS fetch without a `next: { tags: [...] }` revalidation tag (required for on-demand ISR)
+- Check for a webhook revalidation endpoint (`/api/revalidate`). Verify it uses `revalidateTag()` or `revalidatePath()` correctly.
+
+**2. Error Boundaries**
+- Search for `error.tsx` files across `src/app/`. Verify:
+  - A root-level `error.tsx` exists as a global fallback
+  - Key route segments (products, knowledge, etc.) have their own `error.tsx` for scoped error handling
+  - The error component renders a meaningful message (not a blank screen or raw error dump)
+  - The error component includes a recovery mechanism (e.g., "Try again" button using `reset()`)
+- Search for `not-found.tsx`. Verify a custom 404 page exists and is appropriately designed.
+
+**3. Loading States & Suspense**
+- Search for `loading.tsx` files. Verify they exist for heavy data-fetching routes.
+- Search for `<Suspense>` boundaries in server components and page files. Verify:
+  - Heavy data-fetching sections are wrapped in Suspense with a meaningful `fallback`
+  - No route renders a completely blank page while data loads ("white-screen" flash)
+- Check for streaming: are large pages using `generateStaticParams` or streaming to progressively render?
+
+**4. API Route Resilience**
+- Inspect all files in `src/app/api/`. For each route handler, verify:
+  - External API calls (Zoho CRM, Prismic, etc.) have try/catch error handling
+  - Timeouts are set for external fetch calls (or a default Next.js timeout is configured)
+  - Error responses return meaningful HTTP status codes (not always 200 with an error body)
+  - No sensitive information (stack traces, API keys) is leaked in error responses
+
+**5. Edge Middleware**
+- Inspect `middleware.ts` (if it exists). Verify:
+  - No heavy computation runs at the Edge (database queries, large data processing)
+  - Middleware is scoped to only the routes it needs (use `matcher` config)
+  - Any logic that could be moved to a server component or API route is flagged
+
+**6. Third-Party Service Fallbacks**
+- Identify all third-party dependencies (Prismic CMS, Zoho CRM, external configurator, analytics).
+- For each, check:
+  - What happens if the service is unavailable? Does the site degrade gracefully?
+  - Is there a fallback UI for the external configurator iframe?
+  - Do form submissions fall back to Netlify Forms if Zoho CRM is unavailable?
+
+---
+
+### Phase 2: Research (Run in Parallel)
+
+**First**, read `.agents/patterns/edge-api-resilience.md` if it exists. Use it as a baseline — skip re-researching topics already covered unless the file is older than 3 months.
+
+Launch a research subagent to fetch current best practices. The subagent should search for:
+- Next.js 15 App Router caching and ISR best practices (2025–2026)
+- Next.js error.tsx and Suspense patterns for resilient UIs
+- Edge Middleware performance guidelines for Next.js
+- API resilience patterns: timeouts, fallbacks, circuit breakers
+
+Compile findings as a reference list with URLs.
+
+**Then**, create or update `.agents/patterns/edge-api-resilience.md` with any new research findings, best practices, code examples, and reference URLs. Pattern files should be refreshed every 3 months to stay current with evolving standards.
+
+---
+
+### Phase 3: Findings & Checklist
+
+Combine Phase 1 and Phase 2 results. For every issue found:
+- Assign a severity: **CRITICAL** / **HIGH** / **MEDIUM** / **LOW**
+- Include the exact file path and line number
+- State the recommended fix
+
+Save the full audit report to `.agents/audits/edge-api-resilience-{YYYY-MM-DD}.md`.
+
+Also create a condensed implementation checklist at `.agents/checklist/edge-api-resilience-{YYYY-MM-DD}.md` — group items by severity tier with commit-and-review gates between each tier. After implementing each tier: stage all changes (`git add`) but do **NOT** commit. Tell the user the changes are staged for review, and **wait for explicit approval** before proceeding to the next tier. The user will review the diff, commit themselves, and tell the agent when to continue. Reference existing files in `.agents/checklist/` for the pattern.
+
+Save the full audit report to `.agents/audits/edge-api-resilience-{YYYY-MM-DD}.md`:
+
+```markdown
+# Edge & API Resilience Audit — {date}
+
+## Summary
+Brief overview of audit scope — routes checked, third-party dependencies identified, key findings.
+
+## Research References
+- [Source](url) — why it's relevant
+
+## Findings Checklist
+
+- [ ] **[CRITICAL]** No error.tsx at root level — entire site crashes on unhandled error
+  - Fix: Create `src/app/error.tsx` with a recovery UI and `reset()` button
+- [ ] **[HIGH]** Zoho CRM API call has no timeout — `src/app/api/zoho-lead/route.ts:34`
+  - Fix: Add `signal: AbortSignal.timeout(5000)` to the fetch call
+
+## Command Outputs
+- Error boundary coverage: {files found}
+- Loading state coverage: {files found}
+- Middleware inspection: {result}
+```
+
+---
+
+### 🛑 STOP & REVIEW
+
+**Do not proceed past this point until the user explicitly approves.**
+
+Present to the user:
+1. The full findings checklist including all Single Points of Failure identified
+2. Each proposed fix with file and line reference
+3. Research references used
+
+Then ask:
+> "I've completed the Edge & API Resilience audit. The checklist has been saved to `.agents/audits/edge-api-resilience-{date}.md`. Shall I proceed with implementing the fixes above?"
+
+**Wait for explicit confirmation before continuing.**
+
+---
+
+### Phase 4: Implementation
+
+After user approval, implement each approved fix in priority order. For each fix:
+- Make the change using Edit tools
+- Run `npm run check` after every meaningful change
+- For new files (error.tsx, loading.tsx), verify the Next.js App Router picks them up correctly
+- **Update the checklist immediately** — mark completed items with `[x]` in `.agents/checklist/edge-api-resilience-{YYYY-MM-DD}.md` as each item is implemented, not at the end
+- If the user skips or rejects an item, add it to the **Skipped / Rejected Changes** section at the bottom of the checklist using a heading + bullet format per item (e.g., `### #N — Item name` with `- **Status:**` and `- **Reason:**`)
+
+---
+
+### Phase 5: Update Checklist
+
+After all tiers are complete:
+- Verify every item is accounted for: completed `[x]`, deferred `[ ]` with reason, or logged in the Skipped / Rejected Changes section
+- Update the status line:
+```
+## Status: {Complete / Partially Complete — N items deferred, M items skipped}
+```
+- If any items were skipped or rejected, save the Skipped / Rejected Changes section to `.agents/checklist/skipped/edge-api-resilience-{YYYY-MM-DD}.md` so future audits don't re-suggest rejected changes

package/template/.claude/commands/audit-headless-cms.md

@@ -0,0 +1,241 @@
+---
+description: "Run a Headless CMS Standards & SEO audit on the current project (Module 2)"
+---
+
+# Audit: Headless CMS Standards
+
+**Role:** Headless CMS Expert & Technical SEO Strategist
+
+**Objective:** Perform an exhaustive, multi-layered audit of the project's headless CMS integration. Do not limit yourself to the items listed — explore the file structure dynamically and run terminal commands to find deep-seated issues.
+
+---
+
+## Pre-Flight: CMS Detection
+
+Read the project's `package.json` and detect which headless CMS is in use:
+
+| CMS | Detection Key(s) |
+|-----|-------------------|
+| **Storyblok** | `@storyblok/react`, `storyblok-js-client` |
+| **Prismic** | `@prismicio/next`, `@prismicio/client`, `@prismicio/react` |
+| **DatoCMS** | `react-datocms`, `datocms-client`, `@datocms/cda-client` |
+
+If **none** of the above are found, notify the user that this audit module does not apply and stop.
+
+If a CMS is detected, announce which CMS was found and proceed to the matching section below.
+
+---
+
+## Audit Workflow
+
+You MUST follow all phases in order. **Do NOT implement any fixes before the Stop & Review stage.**
+
+---
+
+### Phase 1: Static Analysis
+
+Inspect the codebase using Grep, Glob, and Read tools. Do not assume file locations — discover them dynamically.
+
+Run the CMS-specific checks below based on what was detected in Pre-Flight, **plus** the shared checks that apply to all CMS integrations.
+
+---
+
+#### Shared Checks (All CMS Integrations)
+
+**1. Metadata API Audit**
+- Locate all `layout.tsx` and `page.tsx` files across `src/app/`.
+- For each file, verify:
+  - `export const metadata` or `export async function generateMetadata()` is implemented
+  - `title` and `description` fields are populated (not empty strings or undefined)
+  - `openGraph` object includes `title`, `description`, `images`, and `url`
+  - Twitter card metadata is present
+- Check root `layout.tsx` for `title.template` to ensure consistent site-wide title branding.
+
+**2. JSON-LD Structured Data**
+- Search for JSON-LD `<script type="application/ld+json">` blocks across page files.
+- Verify Schema.org markup is dynamically populated from CMS content (not hardcoded).
+- Flag pages that likely need structured data but don't have it (product pages, articles, events).
+
+**3. Preview / Draft Mode**
+- Verify preview API routes exist and are correctly implemented.
+- Check that the preview/draft client is only initialized in preview environments (not leaked into production builds).
+
+---
+
+#### Storyblok-Specific Checks
+
+**1. Bridge & Visual Editor**
+- Verify `@storyblok/react` is initialized correctly (check `storyblokInit` call).
+- Ensure the Storyblok bridge script is only loaded in draft/preview mode, not in production.
+- Check that `StoryblokStory` or equivalent live-editing wrapper is used on preview pages.
+
+**2. Image Handling**
+- Scan all `.tsx` and `.jsx` files for Storyblok image usage.
+- Verify images use the Storyblok Image Service URL transforms (e.g., `/m/` filters for size/quality) or `next/image` with proper optimization.
+- Ensure `alt` text is pulled from Storyblok asset metadata — not hardcoded.
+- Flag any raw `<img>` tags displaying Storyblok-hosted images without optimization.
+
+**3. Component Mapping (Bloks)**
+- Locate the component-to-blok mapping file (e.g., `bloks.ts` or `StoryblokProvider`).
+- Verify all registered bloks have corresponding components.
+- Spot-check 5 components and verify:
+  - Missing or empty Storyblok fields are handled gracefully (no runtime errors from undefined access)
+  - Nested bloks are rendered via `StoryblokComponent` or equivalent
+  - Rich text fields use `storyblok-rich-text-react-renderer` or `renderRichText` correctly
+
+**4. Content Fetching**
+- Audit data fetching functions for correct use of `storyblokApi.get()` or equivalent.
+- Verify `cv` (cache version) parameter is used appropriately.
+- Check that `version: 'draft'` is only used in preview/draft mode.
+
+**5. Link Handling**
+- Scan for Storyblok link fields being rendered.
+- Verify internal links resolve correctly (multilinks, story links).
+- Flag any manual URL construction from Storyblok slugs that could break with nested paths.
+
+---
+
+#### Prismic-Specific Checks
+
+**1. Image Component Compliance**
+- Scan all `.tsx` and `.jsx` files for image usage.
+- **Strict Policy:** Every Prismic image field must use `<PrismicNextImage>`. Flag any instance where:
+  - A raw `<img>` tag is used for a Prismic image field
+  - `next/image` `<Image>` is used directly instead of `<PrismicNextImage>`
+  - The `alt` prop is manually overridden (it must come from Prismic asset metadata — do not hardcode)
+- Note: `alt=""` is acceptable only for decorative images with no meaningful content.
+
+**2. Link Component Compliance**
+- Scan for all CMS-sourced links (fields from Prismic documents).
+- Verify they use `<PrismicNextLink>` — not a raw `<a>` tag or Next.js `<Link>` directly.
+- Flag every instance of `<a href={...}>` where the `href` value comes from a Prismic link field.
+
+**3. Slice & Component Patterns**
+- Inspect `src/slices/index.ts` (or equivalent) for the slice registry.
+- Spot-check 5 slices and verify:
+  - Each handles the `default` variation case
+  - Missing or empty Prismic fields are handled gracefully (no runtime errors from undefined access)
+  - `SliceComponentProps` typing is used correctly
+
+**4. Preview Mode**
+- Verify Prismic preview API routes (`/api/preview`, `/api/exit-preview`) exist and are correctly implemented.
+- Check that the preview client is only initialized in draft/preview environments.
+
+---
+
+#### DatoCMS-Specific Checks
+
+**1. Image Handling**
+- Verify all DatoCMS images use `<Image />` from `react-datocms` (not raw `<img>` or `next/image` directly).
+- Check that `responsiveImage` GraphQL fragment is used to get optimized srcSet, sizes, and blur-up placeholders.
+- Ensure `alt` text comes from the DatoCMS asset metadata — not hardcoded.
+
+**2. Structured Text Rendering**
+- Verify `<StructuredText />` from `react-datocms` is used for Structured Text fields.
+- Check that custom renderers are provided for inline records, blocks, and link-to-records within Structured Text.
+- Flag any manual parsing of Structured Text DAST nodes.
+
+**3. GraphQL Query Patterns**
+- Audit GraphQL queries for efficiency — flag missing `first`/`skip` pagination or overly broad queries.
+- Verify `_allMeta` count queries are used for pagination where applicable.
+- Check that draft content queries use the preview endpoint with proper authorization.
+
+**4. Preview / Web Previews**
+- Verify DatoCMS Web Previews or draft mode API routes are correctly configured.
+- Check that the preview token/endpoint is only used in draft environments.
+
+**5. SEO Fields**
+- Verify `_seoMetaTags` GraphQL fragment is used and rendered via `<Head />` or Next.js Metadata API.
+- Check that `faviconMetaTags` from the global `_site` query are included in the root layout.
+
+---
+
+### Phase 2: Research (Run in Parallel)
+
+**First**, read `.agents/patterns/headless-cms-standards.md` if it exists. Use it as a baseline — skip re-researching topics already covered unless the file is older than 3 months.
+
+Launch a research subagent to fetch current best practices for the **detected CMS**. The subagent should search for:
+- Latest documentation and migration notes for the detected CMS SDK (2025–2026)
+- Correct image and link component usage patterns
+- Next.js 15 Metadata API best practices with the detected CMS
+- Schema.org structured data for the site's content type
+
+Compile findings as a reference list with URLs.
+
+**Then**, create or update `.agents/patterns/headless-cms-standards.md` with any new research findings, best practices, code examples, and reference URLs. Pattern files should be refreshed every 3 months to stay current with evolving standards.
+
+---
+
+### Phase 3: Findings & Checklist
+
+Combine Phase 1 and Phase 2 results. For every issue found:
+- Assign a severity: **CRITICAL** / **HIGH** / **MEDIUM** / **LOW**
+- Include the exact file path and line number where possible
+- State the recommended fix
+
+Save the full audit report to `.agents/audits/headless-cms-{YYYY-MM-DD}.md`.
+
+Also create a condensed implementation checklist at `.agents/checklist/headless-cms-{YYYY-MM-DD}.md` — group items by severity tier with commit-and-review gates between each tier. After implementing each tier: stage all changes (`git add`) but do **NOT** commit. Tell the user the changes are staged for review, and **wait for explicit approval** before proceeding to the next tier. The user will review the diff, commit themselves, and tell the agent when to continue. Reference existing files in `.agents/checklist/` for the pattern.
+
+Save the full audit report to `.agents/audits/headless-cms-{YYYY-MM-DD}.md`:
+
+```markdown
+# Headless CMS Audit ({CMS Name}) — {date}
+
+## Summary
+Brief overview of audit scope and key findings.
+
+## CMS Detected
+{CMS Name} — detected via `{package}` in package.json
+
+## Research References
+- [Source](url) — why it's relevant
+
+## Findings Checklist
+
+- [ ] **[HIGH]** Description — `file/path:line`
+  - Fix: ...
+- [ ] **[MEDIUM]** Description — `file/path:line`
+  - Fix: ...
+
+## Command Outputs
+- Component mapping check: {result}
+```
+
+---
+
+### 🛑 STOP & REVIEW
+
+**Do not proceed past this point until the user explicitly approves.**
+
+Present to the user:
+1. The full findings checklist
+2. Each proposed fix with file and line reference
+3. Research references used
+
+Then ask:
+> "I've completed the Headless CMS audit (detected: {CMS Name}). The checklist has been saved to `.agents/audits/headless-cms-{date}.md`. Shall I proceed with implementing the fixes above?"
+
+**Wait for explicit confirmation before continuing.**
+
+---
+
+### Phase 4: Implementation
+
+After user approval, implement each approved fix in priority order. For each fix:
+- Make the change using Edit tools
+- Run `npm run check` after every meaningful change
+- **Update the checklist immediately** — mark completed items with `[x]` in `.agents/checklist/headless-cms-{YYYY-MM-DD}.md` as each item is implemented, not at the end
+- If the user skips or rejects an item, add it to the **Skipped / Rejected Changes** section at the bottom of the checklist using a heading + bullet format per item (e.g., `### #N — Item name` with `- **Status:**` and `- **Reason:**`)
+
+---
+
+### Phase 5: Update Checklist
+
+After all tiers are complete:
+- Verify every item is accounted for: completed `[x]`, deferred `[ ]` with reason, or logged in the Skipped / Rejected Changes section
+- Update the status line:
+```
+## Status: {Complete / Partially Complete — N items deferred, M items skipped}
+```
+- If any items were skipped or rejected, save the Skipped / Rejected Changes section to `.agents/checklist/skipped/headless-cms-{YYYY-MM-DD}.md` so future audits don't re-suggest rejected changes