tribunal-kit 3.0.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (233) hide show
  1. package/.agent/ARCHITECTURE.md +99 -99
  2. package/.agent/GEMINI.md +52 -52
  3. package/.agent/agents/accessibility-reviewer.md +187 -220
  4. package/.agent/agents/ai-code-reviewer.md +199 -233
  5. package/.agent/agents/backend-specialist.md +215 -238
  6. package/.agent/agents/code-archaeologist.md +161 -181
  7. package/.agent/agents/database-architect.md +184 -207
  8. package/.agent/agents/debugger.md +191 -218
  9. package/.agent/agents/dependency-reviewer.md +103 -136
  10. package/.agent/agents/devops-engineer.md +218 -238
  11. package/.agent/agents/documentation-writer.md +201 -221
  12. package/.agent/agents/explorer-agent.md +160 -180
  13. package/.agent/agents/frontend-reviewer.md +160 -194
  14. package/.agent/agents/frontend-specialist.md +248 -237
  15. package/.agent/agents/game-developer.md +48 -52
  16. package/.agent/agents/logic-reviewer.md +116 -149
  17. package/.agent/agents/mobile-developer.md +200 -223
  18. package/.agent/agents/mobile-reviewer.md +162 -195
  19. package/.agent/agents/orchestrator.md +181 -211
  20. package/.agent/agents/penetration-tester.md +157 -174
  21. package/.agent/agents/performance-optimizer.md +183 -203
  22. package/.agent/agents/performance-reviewer.md +178 -211
  23. package/.agent/agents/precedence-reviewer.md +213 -0
  24. package/.agent/agents/product-manager.md +142 -162
  25. package/.agent/agents/product-owner.md +6 -25
  26. package/.agent/agents/project-planner.md +142 -162
  27. package/.agent/agents/qa-automation-engineer.md +225 -242
  28. package/.agent/agents/security-auditor.md +174 -194
  29. package/.agent/agents/seo-specialist.md +193 -213
  30. package/.agent/agents/sql-reviewer.md +161 -194
  31. package/.agent/agents/supervisor-agent.md +184 -203
  32. package/.agent/agents/swarm-worker-contracts.md +17 -17
  33. package/.agent/agents/swarm-worker-registry.md +46 -46
  34. package/.agent/agents/test-coverage-reviewer.md +160 -193
  35. package/.agent/agents/test-engineer.md +0 -21
  36. package/.agent/agents/type-safety-reviewer.md +175 -208
  37. package/.agent/patterns/generator.md +9 -9
  38. package/.agent/patterns/inversion.md +12 -12
  39. package/.agent/patterns/pipeline.md +9 -9
  40. package/.agent/patterns/reviewer.md +13 -13
  41. package/.agent/patterns/tool-wrapper.md +9 -9
  42. package/.agent/rules/GEMINI.md +63 -63
  43. package/.agent/scripts/append_flow.js +72 -0
  44. package/.agent/scripts/case_law_manager.py +525 -0
  45. package/.agent/scripts/compress_skills.py +167 -0
  46. package/.agent/scripts/consolidate_skills.py +173 -0
  47. package/.agent/scripts/deep_compress.py +202 -0
  48. package/.agent/scripts/minify_context.py +80 -0
  49. package/.agent/scripts/security_scan.py +1 -1
  50. package/.agent/scripts/skill_evolution.py +563 -0
  51. package/.agent/scripts/strip_tribunal.py +41 -0
  52. package/.agent/skills/agent-organizer/SKILL.md +100 -126
  53. package/.agent/skills/agentic-patterns/SKILL.md +0 -70
  54. package/.agent/skills/ai-prompt-injection-defense/SKILL.md +134 -160
  55. package/.agent/skills/api-patterns/SKILL.md +123 -215
  56. package/.agent/skills/api-security-auditor/SKILL.md +143 -177
  57. package/.agent/skills/app-builder/SKILL.md +334 -50
  58. package/.agent/skills/app-builder/templates/SKILL.md +13 -15
  59. package/.agent/skills/app-builder/templates/astro-static/TEMPLATE.md +16 -16
  60. package/.agent/skills/app-builder/templates/chrome-extension/TEMPLATE.md +22 -22
  61. package/.agent/skills/app-builder/templates/cli-tool/TEMPLATE.md +18 -18
  62. package/.agent/skills/app-builder/templates/electron-desktop/TEMPLATE.md +20 -20
  63. package/.agent/skills/app-builder/templates/express-api/TEMPLATE.md +17 -17
  64. package/.agent/skills/app-builder/templates/flutter-app/TEMPLATE.md +18 -18
  65. package/.agent/skills/app-builder/templates/monorepo-turborepo/TEMPLATE.md +21 -21
  66. package/.agent/skills/app-builder/templates/nextjs-fullstack/TEMPLATE.md +19 -19
  67. package/.agent/skills/app-builder/templates/nextjs-saas/TEMPLATE.md +26 -26
  68. package/.agent/skills/app-builder/templates/nextjs-static/TEMPLATE.md +26 -26
  69. package/.agent/skills/app-builder/templates/nuxt-app/TEMPLATE.md +19 -19
  70. package/.agent/skills/app-builder/templates/python-fastapi/TEMPLATE.md +18 -18
  71. package/.agent/skills/app-builder/templates/react-native-app/TEMPLATE.md +20 -20
  72. package/.agent/skills/appflow-wireframe/SKILL.md +95 -121
  73. package/.agent/skills/architecture/SKILL.md +169 -331
  74. package/.agent/skills/authentication-best-practices/SKILL.md +139 -173
  75. package/.agent/skills/bash-linux/SKILL.md +129 -154
  76. package/.agent/skills/behavioral-modes/SKILL.md +8 -69
  77. package/.agent/skills/brainstorming/SKILL.md +436 -104
  78. package/.agent/skills/building-native-ui/SKILL.md +152 -174
  79. package/.agent/skills/clean-code/SKILL.md +331 -360
  80. package/.agent/skills/code-review-checklist/SKILL.md +0 -62
  81. package/.agent/skills/config-validator/SKILL.md +115 -141
  82. package/.agent/skills/csharp-developer/SKILL.md +468 -528
  83. package/.agent/skills/database-design/SKILL.md +104 -369
  84. package/.agent/skills/deployment-procedures/SKILL.md +119 -145
  85. package/.agent/skills/devops-engineer/SKILL.md +295 -332
  86. package/.agent/skills/devops-incident-responder/SKILL.md +87 -113
  87. package/.agent/skills/doc.md +5 -5
  88. package/.agent/skills/documentation-templates/SKILL.md +27 -63
  89. package/.agent/skills/edge-computing/SKILL.md +131 -157
  90. package/.agent/skills/extract-design-system/SKILL.md +108 -134
  91. package/.agent/skills/framer-motion-expert/SKILL.md +111 -855
  92. package/.agent/skills/frontend-design/SKILL.md +151 -499
  93. package/.agent/skills/game-design-expert/SKILL.md +79 -105
  94. package/.agent/skills/game-engineering-expert/SKILL.md +96 -122
  95. package/.agent/skills/geo-fundamentals/SKILL.md +97 -124
  96. package/.agent/skills/github-operations/SKILL.md +279 -314
  97. package/.agent/skills/gsap-expert/SKILL.md +119 -826
  98. package/.agent/skills/i18n-localization/SKILL.md +113 -138
  99. package/.agent/skills/intelligent-routing/SKILL.md +167 -127
  100. package/.agent/skills/lint-and-validate/SKILL.md +16 -52
  101. package/.agent/skills/llm-engineering/SKILL.md +344 -357
  102. package/.agent/skills/local-first/SKILL.md +128 -154
  103. package/.agent/skills/mcp-builder/SKILL.md +92 -118
  104. package/.agent/skills/mobile-design/SKILL.md +213 -219
  105. package/.agent/skills/motion-engineering/SKILL.md +184 -0
  106. package/.agent/skills/nextjs-react-expert/SKILL.md +99 -698
  107. package/.agent/skills/nodejs-best-practices/SKILL.md +498 -559
  108. package/.agent/skills/observability/SKILL.md +293 -330
  109. package/.agent/skills/parallel-agents/SKILL.md +96 -122
  110. package/.agent/skills/performance-profiling/SKILL.md +217 -254
  111. package/.agent/skills/plan-writing/SKILL.md +92 -118
  112. package/.agent/skills/platform-engineer/SKILL.md +97 -123
  113. package/.agent/skills/playwright-best-practices/SKILL.md +137 -162
  114. package/.agent/skills/powershell-windows/SKILL.md +112 -146
  115. package/.agent/skills/project-idioms/SKILL.md +87 -0
  116. package/.agent/skills/python-patterns/SKILL.md +15 -35
  117. package/.agent/skills/python-pro/SKILL.md +148 -754
  118. package/.agent/skills/react-specialist/SKILL.md +123 -827
  119. package/.agent/skills/readme-builder/SKILL.md +23 -85
  120. package/.agent/skills/realtime-patterns/SKILL.md +269 -304
  121. package/.agent/skills/red-team-tactics/SKILL.md +18 -51
  122. package/.agent/skills/rust-pro/SKILL.md +623 -701
  123. package/.agent/skills/seo-fundamentals/SKILL.md +129 -154
  124. package/.agent/skills/server-management/SKILL.md +164 -190
  125. package/.agent/skills/shadcn-ui-expert/SKILL.md +181 -206
  126. package/.agent/skills/skill-creator/SKILL.md +24 -56
  127. package/.agent/skills/sql-pro/SKILL.md +579 -633
  128. package/.agent/skills/supabase-postgres-best-practices/SKILL.md +35 -66
  129. package/.agent/skills/swiftui-expert/SKILL.md +151 -176
  130. package/.agent/skills/systematic-debugging/SKILL.md +92 -118
  131. package/.agent/skills/tailwind-patterns/SKILL.md +516 -576
  132. package/.agent/skills/tdd-workflow/SKILL.md +111 -137
  133. package/.agent/skills/test-result-analyzer/SKILL.md +33 -73
  134. package/.agent/skills/testing-patterns/SKILL.md +512 -573
  135. package/.agent/skills/trend-researcher/SKILL.md +30 -71
  136. package/.agent/skills/ui-ux-pro-max/SKILL.md +8 -41
  137. package/.agent/skills/ui-ux-researcher/SKILL.md +51 -91
  138. package/.agent/skills/vue-expert/SKILL.md +127 -866
  139. package/.agent/skills/vulnerability-scanner/SKILL.md +354 -269
  140. package/.agent/skills/web-accessibility-auditor/SKILL.md +168 -193
  141. package/.agent/skills/web-design-guidelines/SKILL.md +25 -61
  142. package/.agent/skills/webapp-testing/SKILL.md +119 -145
  143. package/.agent/skills/whimsy-injector/SKILL.md +58 -132
  144. package/.agent/skills/workflow-optimizer/SKILL.md +28 -68
  145. package/.agent/workflows/api-tester.md +151 -151
  146. package/.agent/workflows/audit.md +127 -138
  147. package/.agent/workflows/brainstorm.md +110 -110
  148. package/.agent/workflows/changelog.md +112 -112
  149. package/.agent/workflows/create.md +124 -124
  150. package/.agent/workflows/debug.md +165 -189
  151. package/.agent/workflows/deploy.md +180 -189
  152. package/.agent/workflows/enhance.md +128 -151
  153. package/.agent/workflows/fix.md +114 -135
  154. package/.agent/workflows/generate.md +13 -4
  155. package/.agent/workflows/migrate.md +160 -160
  156. package/.agent/workflows/orchestrate.md +168 -168
  157. package/.agent/workflows/performance-benchmarker.md +114 -123
  158. package/.agent/workflows/plan.md +173 -173
  159. package/.agent/workflows/preview.md +80 -80
  160. package/.agent/workflows/refactor.md +161 -183
  161. package/.agent/workflows/review-ai.md +101 -129
  162. package/.agent/workflows/review.md +116 -116
  163. package/.agent/workflows/session.md +94 -94
  164. package/.agent/workflows/status.md +79 -79
  165. package/.agent/workflows/strengthen-skills.md +138 -139
  166. package/.agent/workflows/swarm.md +179 -179
  167. package/.agent/workflows/test.md +189 -211
  168. package/.agent/workflows/tribunal-backend.md +94 -113
  169. package/.agent/workflows/tribunal-database.md +95 -115
  170. package/.agent/workflows/tribunal-frontend.md +96 -118
  171. package/.agent/workflows/tribunal-full.md +93 -133
  172. package/.agent/workflows/tribunal-mobile.md +95 -119
  173. package/.agent/workflows/tribunal-performance.md +110 -133
  174. package/.agent/workflows/ui-ux-pro-max.md +122 -143
  175. package/README.md +30 -1
  176. package/bin/tribunal-kit.js +175 -12
  177. package/package.json +25 -4
  178. package/.agent/skills/api-patterns/api-style.md +0 -42
  179. package/.agent/skills/api-patterns/auth.md +0 -24
  180. package/.agent/skills/api-patterns/documentation.md +0 -26
  181. package/.agent/skills/api-patterns/graphql.md +0 -41
  182. package/.agent/skills/api-patterns/rate-limiting.md +0 -31
  183. package/.agent/skills/api-patterns/response.md +0 -37
  184. package/.agent/skills/api-patterns/rest.md +0 -40
  185. package/.agent/skills/api-patterns/security-testing.md +0 -122
  186. package/.agent/skills/api-patterns/trpc.md +0 -41
  187. package/.agent/skills/api-patterns/versioning.md +0 -22
  188. package/.agent/skills/app-builder/agent-coordination.md +0 -71
  189. package/.agent/skills/app-builder/feature-building.md +0 -53
  190. package/.agent/skills/app-builder/project-detection.md +0 -34
  191. package/.agent/skills/app-builder/scaffolding.md +0 -118
  192. package/.agent/skills/app-builder/tech-stack.md +0 -40
  193. package/.agent/skills/architecture/context-discovery.md +0 -43
  194. package/.agent/skills/architecture/examples.md +0 -94
  195. package/.agent/skills/architecture/pattern-selection.md +0 -68
  196. package/.agent/skills/architecture/patterns-reference.md +0 -50
  197. package/.agent/skills/architecture/trade-off-analysis.md +0 -77
  198. package/.agent/skills/brainstorming/dynamic-questioning.md +0 -360
  199. package/.agent/skills/database-design/database-selection.md +0 -43
  200. package/.agent/skills/database-design/indexing.md +0 -39
  201. package/.agent/skills/database-design/migrations.md +0 -48
  202. package/.agent/skills/database-design/optimization.md +0 -36
  203. package/.agent/skills/database-design/orm-selection.md +0 -30
  204. package/.agent/skills/database-design/schema-design.md +0 -56
  205. package/.agent/skills/frontend-design/animation-guide.md +0 -331
  206. package/.agent/skills/frontend-design/color-system.md +0 -329
  207. package/.agent/skills/frontend-design/decision-trees.md +0 -418
  208. package/.agent/skills/frontend-design/motion-graphics.md +0 -306
  209. package/.agent/skills/frontend-design/typography-system.md +0 -363
  210. package/.agent/skills/frontend-design/ux-psychology.md +0 -1116
  211. package/.agent/skills/frontend-design/visual-effects.md +0 -383
  212. package/.agent/skills/intelligent-routing/router-manifest.md +0 -65
  213. package/.agent/skills/mobile-design/decision-trees.md +0 -516
  214. package/.agent/skills/mobile-design/mobile-backend.md +0 -491
  215. package/.agent/skills/mobile-design/mobile-color-system.md +0 -420
  216. package/.agent/skills/mobile-design/mobile-debugging.md +0 -122
  217. package/.agent/skills/mobile-design/mobile-design-thinking.md +0 -357
  218. package/.agent/skills/mobile-design/mobile-navigation.md +0 -458
  219. package/.agent/skills/mobile-design/mobile-performance.md +0 -767
  220. package/.agent/skills/mobile-design/mobile-testing.md +0 -356
  221. package/.agent/skills/mobile-design/mobile-typography.md +0 -433
  222. package/.agent/skills/mobile-design/platform-android.md +0 -666
  223. package/.agent/skills/mobile-design/platform-ios.md +0 -561
  224. package/.agent/skills/mobile-design/touch-psychology.md +0 -537
  225. package/.agent/skills/nextjs-react-expert/1-async-eliminating-waterfalls.md +0 -312
  226. package/.agent/skills/nextjs-react-expert/2-bundle-bundle-size-optimization.md +0 -240
  227. package/.agent/skills/nextjs-react-expert/3-server-server-side-performance.md +0 -490
  228. package/.agent/skills/nextjs-react-expert/4-client-client-side-data-fetching.md +0 -264
  229. package/.agent/skills/nextjs-react-expert/5-rerender-re-render-optimization.md +0 -581
  230. package/.agent/skills/nextjs-react-expert/6-rendering-rendering-performance.md +0 -432
  231. package/.agent/skills/nextjs-react-expert/7-js-javascript-performance.md +0 -684
  232. package/.agent/skills/nextjs-react-expert/8-advanced-advanced-patterns.md +0 -150
  233. package/.agent/skills/vulnerability-scanner/checklists.md +0 -121
@@ -1,154 +1,129 @@
1
- ---
2
- name: seo-fundamentals
3
- description: Search Engine Optimization (SEO) mastery. Metadata implementation, Open Graph (OG) social card rendering, semantic HTML5 structuring, canonicalization, Core Web Vitals performance mapping, Sitemap/Robots configurations, structured data (JSON-LD), and Next.js SSR SEO implementations. Use when auditing site visibility or building consumer-facing web architectures.
4
- allowed-tools: Read, Write, Edit, Glob, Grep
5
- version: 2.0.0
6
- last-updated: 2026-04-02
7
- applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
8
- ---
9
-
10
- # SEO Fundamentals Visibility & Discoverability Mastery
11
-
12
- > If a consumer web app is not indexed efficiently, it does not mathematically exist on the internet.
13
- > Googlebot does not execute massive React payloads effectively. Server-Side Rendering is mandatory for SEO.
14
-
15
- ---
16
-
17
- ## 1. Core Meta Architecture (The Next.js 15 Standard)
18
-
19
- Do not use legacy `next/head` tags scattered across components. Use the built-in Metadata API explicitly.
20
-
21
- ```typescript
22
- // app/blog/[slug]/page.tsx
23
- import { Metadata } from 'next';
24
-
25
- export async function generateMetadata({ params }): Promise<Metadata> {
26
- const post = await fetchPost(params.slug);
27
-
28
- return {
29
- title: `${post.title} | MyBrand`,
30
- description: post.excerpt,
31
- keywords: post.tags,
32
- alternates: {
33
- canonical: `https://www.example.com/blog/${params.slug}`
34
- },
35
- openGraph: {
36
- title: post.title,
37
- description: post.excerpt,
38
- type: 'article',
39
- url: `https://example.com/blog/${params.slug}`,
40
- images: [{ url: post.coverImageUrl, width: 1200, height: 630 }],
41
- },
42
- twitter: {
43
- card: 'summary_large_image', // Critical for big Twitter link previews
44
- }
45
- };
46
- }
47
- ```
48
-
49
- ---
50
-
51
- ## 2. Semantic HTML & Heading Hierarchy
52
-
53
- Google establishes context by parsing the DOM outline. A massive application constructed purely of `<div className="text-xl font-bold">` tags will be heavily penalized.
54
-
55
- 1. **The H1 Law:** Exactly ONE `<h1>` per page. This is the primary subject.
56
- 2. **Hierarchy Integrity:** Never skip heading levels. An `<h2>` MUST precede an `<h3>`. Do not use heading tags for visual sizing; use them purely for document structure.
57
- 3. **Semantic Tags:** Wrap headers in `<header>`, menus in `<nav>`, main content in `<main>`, and sidebars in `<aside>`.
58
-
59
- ```html
60
- <!-- ✅ GOOD: Perfect SEO Document Outline -->
61
- <main>
62
- <article>
63
- <h1>The Future of AI Agents</h1>
64
- <p>Introduction...</p>
65
-
66
- <h2>Architectural Patterns</h2>
67
- <section>
68
- <h3>The Supervisor Pattern</h3>
69
- <p>Content regarding supervisors...</p>
70
- </section>
71
- </article>
72
- </main>
73
- ```
74
-
75
- ---
76
-
77
- ## 3. Structured Data (JSON-LD)
78
-
79
- Help search engines understand exact data graphs (Products, Reviews, Articles, Jobs) bypassingly standard text crawling. Inject standard `Schema.org` JSON-LD.
80
-
81
- ```typescript
82
- // Injecting JSON-LD structurally into a React/Next component
83
- export default function ProductPage({ product }) {
84
- const jsonLd = {
85
- '@context': 'https://schema.org',
86
- '@type': 'Product',
87
- name: product.name,
88
- image: product.image,
89
- description: product.description,
90
- offers: {
91
- '@type': 'Offer',
92
- price: product.price,
93
- priceCurrency: 'USD',
94
- availability: product.inStock ? 'https://schema.org/InStock' : 'https://schema.org/OutOfStock',
95
- },
96
- };
97
-
98
- return (
99
- <section>
100
- {/* Script injected cleanly into DOM */}
101
- <script
102
- type="application/ld+json"
103
- dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
104
- />
105
-
106
- <h1>{product.name}</h1>
107
- {/* ... rest of UI ... */}
108
- </section>
109
- );
110
- }
111
- ```
112
-
113
- ---
114
-
115
- ## 4. Robots & Sitemaps
116
-
117
- If a page shouldn't be indexed (e.g., dynamic search result matrices, user profiles), you must explicitly block it, otherwise Googlebot wastes "Crawl Budget" on infinite URLs.
118
-
119
- - **`robots.txt`**: Denies crawling of specific directories.
120
- - **`<meta name="robots" content="noindex, nofollow">`**: Denies indexing of a specific page instance.
121
- - **`sitemap.xml`**: A programmatic manifest mapped to root guiding crawlers mathematically through all valid indexable paths.
122
-
123
- ---
124
-
125
- ## 🤖 LLM-Specific Traps (SEO)
126
-
127
- 1. **The SPA Fallacy:** AI building a Client-Side Rendered (CSR) React App with `react-router` and assuring the user SEO is perfect. Googlebot struggles heavily with executing massive JS bundles. Force SSR Next.js/Astro architecture for consumer-facing sites.
128
- 2. **Missing Canonicals:** Failing to generate `<link rel="canonical">` tags on dynamic URL structures (`?category=shoes&brand=nike`), resulting in Google penalizing the main page for "Duplicate Content" against itself.
129
- 3. **OpenGraph Amputation:** Creating `<title>` tags perfectly but entirely omitting the `og:` and `twitter:` meta tags. The site will look like a broken ugly text link when shared on social media.
130
- 4. **`next/head` Obsession:** The AI relies on the legacy React `Helmet` library or Next 12 `Head` tag generation methods instead of utilizing the Next.js `generateMetadata()` App Router architectural API.
131
- 5. **Div Soups:** Generating 400 lines of UI where bold strings are mapped as `<span>` tags instead of strong semantic `<h2>` and `<h3>` document structural tags.
132
- 6. **NoIndex Blindness:** The AI scaffolds the staging `/dev/` URL environment but neglects to inject global `noindex` headers into staging layouts, causing Google to permanently index half-finished development drafts globally.
133
- 7. **Image Alt-Tag Exclusion:** Utilizing `<Image src="...">` without writing highly descriptive `alt="..."` attributes, wiping out all potential Google Images search traffic and destroying accessibility scores simultaneously.
134
- 8. **Invalid Schema Output:** Generating broken JSON-LD objects because the AI used generic un-validated JSON types instead of rigidly consulting the `schema.org` mandated data structures (e.g., omitting the required `priceCurrency` on an Offer schema).
135
- 9. **Sitemap Generation Forgetting:** Ensuring excellent SEO on specific pages but totally failing to scaffold dynamic `app/sitemap.ts` files that continually update the XML tree when new databases articles are published.
136
- 10. **The H1 Spam:** Putting multiple `<h1>` tags on a single page visually simply because they want the font to be large, heavily confusing the search engine content analyzers.
137
-
138
- ---
139
-
140
- ## 🏛️ Tribunal Integration
141
-
142
- ### ✅ Pre-Flight Self-Audit
143
- ```
144
- ✅ Have dynamic Meta tags (Title, Description) been localized into SSR native configuration (`generateMetadata`)?
145
- ✅ Did I guarantee the mathematical generation of Open Graph (OG) and Twitter Card payload tags?
146
- ✅ Is there strictly only one `<h1>` tag rendered structurally per page view?
147
- ✅ Is the DOM heavily semantic (`<main>`, `<article>`, `<nav>`) bypassing standard div-soups?
148
- ✅ Were Canonical URL alternates properly mapped on complex pagination/parameterized URL routes?
149
- ✅ Have standard `Schema.org` JSON-LD data graphs been injected for transactional/content entries?
150
- ✅ Has `alt` text been rigidly mandated and populated for all primary visual `<Image>` tags?
151
- ✅ Ensure that indexing prevention (robots noindex) is actively applied to user-private/admin/test routes?
152
- ✅ Was the SEO advice generated explicitly recognizing the difference between static SSR delivery vs CSR Javascript limits?
153
- ✅ Did I ensure the XML sitemap generation accurately captures dynamically generated database routes (e.g., blog slugs)?
154
- ```
1
+ ---
2
+ name: seo-fundamentals
3
+ description: Search Engine Optimization (SEO) mastery. Metadata implementation, Open Graph (OG) social card rendering, semantic HTML5 structuring, canonicalization, Core Web Vitals performance mapping, Sitemap/Robots configurations, structured data (JSON-LD), and Next.js SSR SEO implementations. Use when auditing site visibility or building consumer-facing web architectures.
4
+ allowed-tools: Read, Write, Edit, Glob, Grep
5
+ version: 2.0.0
6
+ last-updated: 2026-04-02
7
+ applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
8
+ ---
9
+
10
+ ## Hallucination Traps (Read First)
11
+ - ❌ Using `<div>` for everything instead of semantic HTML -> ✅ Use `<main>`, `<article>`, `<nav>`, `<section>` for crawler comprehension
12
+ - Multiple `<h1>` tags on a single page -> One `<h1>` per page; use `<h2>`-`<h6>` for hierarchy
13
+ - Generating meta descriptions with AI boilerplate -> Each page needs a unique, specific meta description under 160 characters
14
+ - ❌ Using client-side rendering for content pages -> ✅ SSR/SSG for pages that need to be indexed; CSR is invisible to crawlers without JS rendering
15
+
16
+ ---
17
+
18
+
19
+ # SEO Fundamentals Visibility & Discoverability Mastery
20
+
21
+ ---
22
+
23
+ ## 1. Core Meta Architecture (The Next.js 15 Standard)
24
+
25
+ Do not use legacy `next/head` tags scattered across components. Use the built-in Metadata API explicitly.
26
+
27
+ ```typescript
28
+ // app/blog/[slug]/page.tsx
29
+ import { Metadata } from 'next';
30
+
31
+ export async function generateMetadata({ params }): Promise<Metadata> {
32
+ const post = await fetchPost(params.slug);
33
+
34
+ return {
35
+ title: `${post.title} | MyBrand`,
36
+ description: post.excerpt,
37
+ keywords: post.tags,
38
+ alternates: {
39
+ canonical: `https://www.example.com/blog/${params.slug}`
40
+ },
41
+ openGraph: {
42
+ title: post.title,
43
+ description: post.excerpt,
44
+ type: 'article',
45
+ url: `https://example.com/blog/${params.slug}`,
46
+ images: [{ url: post.coverImageUrl, width: 1200, height: 630 }],
47
+ },
48
+ twitter: {
49
+ card: 'summary_large_image', // Critical for big Twitter link previews
50
+ }
51
+ };
52
+ }
53
+ ```
54
+
55
+ ---
56
+
57
+ ## 2. Semantic HTML & Heading Hierarchy
58
+
59
+ Google establishes context by parsing the DOM outline. A massive application constructed purely of `<div className="text-xl font-bold">` tags will be heavily penalized.
60
+
61
+ 1. **The H1 Law:** Exactly ONE `<h1>` per page. This is the primary subject.
62
+ 2. **Hierarchy Integrity:** Never skip heading levels. An `<h2>` MUST precede an `<h3>`. Do not use heading tags for visual sizing; use them purely for document structure.
63
+ 3. **Semantic Tags:** Wrap headers in `<header>`, menus in `<nav>`, main content in `<main>`, and sidebars in `<aside>`.
64
+
65
+ ```html
66
+ <!-- ✅ GOOD: Perfect SEO Document Outline -->
67
+ <main>
68
+ <article>
69
+ <h1>The Future of AI Agents</h1>
70
+ <p>Introduction...</p>
71
+
72
+ <h2>Architectural Patterns</h2>
73
+ <section>
74
+ <h3>The Supervisor Pattern</h3>
75
+ <p>Content regarding supervisors...</p>
76
+ </section>
77
+ </article>
78
+ </main>
79
+ ```
80
+
81
+ ---
82
+
83
+ ## 3. Structured Data (JSON-LD)
84
+
85
+ Help search engines understand exact data graphs (Products, Reviews, Articles, Jobs) bypassingly standard text crawling. Inject standard `Schema.org` JSON-LD.
86
+
87
+ ```typescript
88
+ // Injecting JSON-LD structurally into a React/Next component
89
+ export default function ProductPage({ product }) {
90
+ const jsonLd = {
91
+ '@context': 'https://schema.org',
92
+ '@type': 'Product',
93
+ name: product.name,
94
+ image: product.image,
95
+ description: product.description,
96
+ offers: {
97
+ '@type': 'Offer',
98
+ price: product.price,
99
+ priceCurrency: 'USD',
100
+ availability: product.inStock ? 'https://schema.org/InStock' : 'https://schema.org/OutOfStock',
101
+ },
102
+ };
103
+
104
+ return (
105
+ <section>
106
+ {/* Script injected cleanly into DOM */}
107
+ <script
108
+ type="application/ld+json"
109
+ dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
110
+ />
111
+
112
+ <h1>{product.name}</h1>
113
+ {/* ... rest of UI ... */}
114
+ </section>
115
+ );
116
+ }
117
+ ```
118
+
119
+ ---
120
+
121
+ ## 4. Robots & Sitemaps
122
+
123
+ If a page shouldn't be indexed (e.g., dynamic search result matrices, user profiles), you must explicitly block it, otherwise Googlebot wastes "Crawl Budget" on infinite URLs.
124
+
125
+ - **`robots.txt`**: Denies crawling of specific directories.
126
+ - **`<meta name="robots" content="noindex, nofollow">`**: Denies indexing of a specific page instance.
127
+ - **`sitemap.xml`**: A programmatic manifest mapped to root guiding crawlers mathematically through all valid indexable paths.
128
+
129
+ ---
@@ -1,190 +1,164 @@
1
- ---
2
- name: server-management
3
- description: Production Linux server administration mastery. Systemd services, Nginx reverse proxy architecture, UFW firewalls, SSH key security, cron scheduling, log rotation, and server hardening. Use when configuring bare-metal, VPS instances, or reviewing deployment architecture.
4
- allowed-tools: Read, Write, Edit, Glob, Grep
5
- version: 2.0.0
6
- last-updated: 2026-04-02
7
- applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
8
- ---
9
-
10
- # Server Management Production Linux Mastery
11
-
12
- > Never run a web server as root. Never expose raw ports securely.
13
- > A naked Node/Python process dies silently. A systemd service acts as its immortal guardian.
14
-
15
- ---
16
-
17
- ## 1. Systemd Service Architecture (Process Guard)
18
-
19
- Do not use `pm2`, `forever`, or custom `screen` sessions attached to SSH panels for server orchestration. Linux provides an enterprise-grade init system natively: systemd.
20
-
21
- ```ini
22
- # /etc/systemd/system/myapp.service
23
-
24
- [Unit]
25
- Description=My Application Node.js Server
26
- Documentation=https://example.com/docs
27
- After=network.target postgresql.service # Ensure DB and Network start first
28
-
29
- [Service]
30
- Type=simple
31
- User=appuser # NEVER run as root
32
- Group=appuser
33
- WorkingDirectory=/var/www/myapp
34
-
35
- # Explicitly declare environment limits and variables
36
- Environment=NODE_ENV=production
37
- Environment=PORT=3000
38
- EnvironmentFile=/var/www/myapp/.env
39
-
40
- # The execution target
41
- ExecStart=/usr/bin/node /var/www/myapp/build/index.js
42
-
43
- # Immortal behavior: Restart strictly on failure
44
- Restart=on-failure
45
- RestartSec=5
46
-
47
- # Security Hardening
48
- NoNewPrivileges=yes
49
- PrivateTmp=yes
50
- RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
51
-
52
- [Install]
53
- WantedBy=multi-user.target
54
- ```
55
-
56
- **Commands:**
57
- `sudo systemctl daemon-reload`
58
- `sudo systemctl enable myapp`
59
- `sudo systemctl start myapp`
60
- `journalctl -u myapp -f` (Follow logs seamlessly)
61
-
62
- ---
63
-
64
- ## 2. Nginx Reverse Proxy Architecture
65
-
66
- You must shield your internal application framework (Node/Python/Ruby) behind Nginx. Nginx handles SSL termination, static file caching, and DDOS mitigation.
67
-
68
- ```nginx
69
- # /etc/nginx/sites-available/myapp.com
70
-
71
- server {
72
- listen 80;
73
- server_name api.myapp.com;
74
-
75
- # Force SSL Redirect
76
- return 301 https://$host$request_uri;
77
- }
78
-
79
- server {
80
- listen 443 ssl http2;
81
- server_name api.myapp.com;
82
-
83
- # SSL Certs (Let's Encrypt / Certbot)
84
- ssl_certificate /etc/letsencrypt/live/api.myapp.com/fullchain.pem;
85
- ssl_certificate_key /etc/letsencrypt/live/api.myapp.com/privkey.pem;
86
-
87
- # Modern Security Headers
88
- add_header Strict-Transport-Security "max-age=63072000" always;
89
- add_header X-Content-Type-Options nosniff;
90
- add_header X-Frame-Options DENY;
91
-
92
- # GZIP Compression
93
- gzip on;
94
- gzip_types text/plain application/json;
95
-
96
- location / {
97
- # Proxy traffic to internal local process
98
- proxy_pass http://127.0.0.1:3000;
99
-
100
- # Forward original IP and Protocol for rate limiters
101
- proxy_set_header Host $host;
102
- proxy_set_header X-Real-IP $remote_addr;
103
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
104
- proxy_set_header X-Forwarded-Proto $scheme;
105
-
106
- # WebSocket support (Required for GraphQL subscriptions, TRPC, Socket.io)
107
- proxy_http_version 1.1;
108
- proxy_set_header Upgrade $http_upgrade;
109
- proxy_set_header Connection "upgrade";
110
- }
111
- }
112
- ```
113
-
114
- ---
115
-
116
- ## 3. Server Hardening Fundamentals
117
-
118
- ### SSH Security (`/etc/ssh/sshd_config`)
119
- ```bash
120
- PermitRootLogin no # Kill direct root login attacks immediately
121
- PasswordAuthentication no # Enforce SSH key-based login ONLY
122
- Port 2022 # (Optional) Obscurity defense against automated script-kiddie scanners
123
- ```
124
-
125
- ### Uncomplicated Firewall (UFW)
126
- A naked server with all ports open is a honeypot.
127
- ```bash
128
- sudo ufw default deny incoming
129
- sudo ufw default allow outgoing
130
- sudo ufw allow 22/tcp # Allow SSH
131
- sudo ufw allow 80/tcp # Allow HTTP
132
- sudo ufw allow 443/tcp # Allow HTTPS
133
- sudo ufw enable
134
- ```
135
-
136
- ### Fail2Ban
137
- Automatically bans IPs attempting brute force credential filling after 5 bad attempts.
138
-
139
- ---
140
-
141
- ## 4. Log Rotation (Prevent Disk Full Outages)
142
-
143
- A server will inevitably crash when `/var/log` consumes 100% of the disk.
144
-
145
- ```bash
146
- # /etc/logrotate.d/myapp
147
-
148
- /var/www/myapp/logs/*.log {
149
- daily # Rotate every day
150
- missingok # Ignore if file is missing
151
- rotate 14 # Keep 14 days of history
152
- compress # Gzip old logs
153
- delaycompress # Don't compress the one created yesterday
154
- notifempty # Do nothing if log is empty
155
- copytruncate # Copy then clear (avoids disrupting Node's open file handles)
156
- }
157
- ```
158
-
159
- ---
160
-
161
- ## 🤖 LLM-Specific Traps (Server Management)
162
-
163
- 1. **PM2 Fallacy:** AI frequently defaults to `pm2 start app.js` for production deployments. Demand raw `systemd`. It ensures startup order (Wait for network) and unified journalctl logging.
164
- 2. **Root Execution:** Suggesting `ExecStart=npm start` under the `User=root` directive. The application process should operate under a restricted `appuser` daemon tier.
165
- 3. **Missing Proxy Headers:** AI writing basic Nginx configs but omitting `X-Forwarded-For`. This causes the internal App to log all requests as coming from "127.0.0.1", instantly breaking IP Rate limiters.
166
- 4. **WebSocket Blocking:** Forgetting to pass `Upgrade` headers in Nginx proxy setups, breaking realtime web applications silently.
167
- 5. **Naked Node Ports:** Instructing users to run `node index.js` on `port 80`. Never natively bind unprivileged web processes to port 80. Bind to 3000 locally and use reverse proxy routing.
168
- 6. **Firewall Blindness:** Assuming Docker auto-secures ports. Executing `docker run -p 8080:80` on Ubuntu completely bypasses UFW restrictions through iptables hooks, exposing the database to the internet. Always bind `127.0.0.1:8080:80`.
169
- 7. **Password SSH Prompts:** Creating automation scripts utilizing raw passwords (e.g., `sshpass`). Always assume ed25519 identity keyfiles for automated CI deployments.
170
- 8. **Log Rotation Void:** Neglecting log rotation in custom bash script loops, guaranteeing a 100% disk usage outage 3 months later.
171
- 9. **GZIP Assumption:** Forgetting to enable `gzip on` in Nginx resulting in 10MB JSON payloads saturating the virtual server network adapter.
172
- 10. **In-place Nginx Modding:** Editing `/etc/nginx/nginx.conf` directly instead of writing symlinks between the `sites-available` and `sites-enabled` architecture.
173
-
174
- ---
175
-
176
- ## 🏛️ Tribunal Integration
177
-
178
- ### ✅ Pre-Flight Self-Audit
179
- ```
180
- ✅ Are persistent services orchestrated securely via `systemd` (not PM2)?
181
- ✅ Does the systemd service explicitly execute as a non-root `appuser`?
182
- ✅ Is the internal application shielded by an Nginx/Caddy reverse proxy?
183
- ✅ Does the reverse proxy explicitly forward realtime `Upgrade` (WebSocket) headers?
184
- ✅ Does the reverse proxy forward IP integrity headers (`X-Forwarded-For`)?
185
- ✅ Has SSH `PasswordAuthentication` been disabled defensively?
186
- ✅ Is UFW configured to strictly deny all incoming non-essential ports?
187
- ✅ If suggesting Docker, are database/internal ports scoped to `127.0.0.1:X:Y`?
188
- ✅ Have manual application log files been mapped in `logrotate.d`?
189
- ✅ Has `PermitRootLogin` been set to `no`?
190
- ```
1
+ ---
2
+ name: server-management
3
+ description: Production Linux server administration mastery. Systemd services, Nginx reverse proxy architecture, UFW firewalls, SSH key security, cron scheduling, log rotation, and server hardening. Use when configuring bare-metal, VPS instances, or reviewing deployment architecture.
4
+ allowed-tools: Read, Write, Edit, Glob, Grep
5
+ version: 2.0.0
6
+ last-updated: 2026-04-02
7
+ applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
8
+ ---
9
+
10
+ ## Hallucination Traps (Read First)
11
+ - ❌ Running services as root -> ✅ Create a dedicated service user with minimal permissions; never run as root
12
+ - Using password-based SSH -> Disable password auth; use SSH key pairs only with `PermitRootLogin no`
13
+ - Editing nginx config without testing -> Always run `nginx -t` before `systemctl reload nginx`; syntax errors take down all sites
14
+
15
+ ---
16
+
17
+
18
+ # Server Management — Production Linux Mastery
19
+
20
+ ---
21
+
22
+ ## 1. Systemd Service Architecture (Process Guard)
23
+
24
+ Do not use `pm2`, `forever`, or custom `screen` sessions attached to SSH panels for server orchestration. Linux provides an enterprise-grade init system natively: systemd.
25
+
26
+ ```ini
27
+ # /etc/systemd/system/myapp.service
28
+
29
+ [Unit]
30
+ Description=My Application Node.js Server
31
+ Documentation=https://example.com/docs
32
+ After=network.target postgresql.service # Ensure DB and Network start first
33
+
34
+ [Service]
35
+ Type=simple
36
+ User=appuser # NEVER run as root
37
+ Group=appuser
38
+ WorkingDirectory=/var/www/myapp
39
+
40
+ # Explicitly declare environment limits and variables
41
+ Environment=NODE_ENV=production
42
+ Environment=PORT=3000
43
+ EnvironmentFile=/var/www/myapp/.env
44
+
45
+ # The execution target
46
+ ExecStart=/usr/bin/node /var/www/myapp/build/index.js
47
+
48
+ # Immortal behavior: Restart strictly on failure
49
+ Restart=on-failure
50
+ RestartSec=5
51
+
52
+ # Security Hardening
53
+ NoNewPrivileges=yes
54
+ PrivateTmp=yes
55
+ RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
56
+
57
+ [Install]
58
+ WantedBy=multi-user.target
59
+ ```
60
+
61
+ **Commands:**
62
+ `sudo systemctl daemon-reload`
63
+ `sudo systemctl enable myapp`
64
+ `sudo systemctl start myapp`
65
+ `journalctl -u myapp -f` (Follow logs seamlessly)
66
+
67
+ ---
68
+
69
+ ## 2. Nginx Reverse Proxy Architecture
70
+
71
+ You must shield your internal application framework (Node/Python/Ruby) behind Nginx. Nginx handles SSL termination, static file caching, and DDOS mitigation.
72
+
73
+ ```nginx
74
+ # /etc/nginx/sites-available/myapp.com
75
+
76
+ server {
77
+ listen 80;
78
+ server_name api.myapp.com;
79
+
80
+ # Force SSL Redirect
81
+ return 301 https://$host$request_uri;
82
+ }
83
+
84
+ server {
85
+ listen 443 ssl http2;
86
+ server_name api.myapp.com;
87
+
88
+ # SSL Certs (Let's Encrypt / Certbot)
89
+ ssl_certificate /etc/letsencrypt/live/api.myapp.com/fullchain.pem;
90
+ ssl_certificate_key /etc/letsencrypt/live/api.myapp.com/privkey.pem;
91
+
92
+ # Modern Security Headers
93
+ add_header Strict-Transport-Security "max-age=63072000" always;
94
+ add_header X-Content-Type-Options nosniff;
95
+ add_header X-Frame-Options DENY;
96
+
97
+ # GZIP Compression
98
+ gzip on;
99
+ gzip_types text/plain application/json;
100
+
101
+ location / {
102
+ # Proxy traffic to internal local process
103
+ proxy_pass http://127.0.0.1:3000;
104
+
105
+ # Forward original IP and Protocol for rate limiters
106
+ proxy_set_header Host $host;
107
+ proxy_set_header X-Real-IP $remote_addr;
108
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
109
+ proxy_set_header X-Forwarded-Proto $scheme;
110
+
111
+ # WebSocket support (Required for GraphQL subscriptions, TRPC, Socket.io)
112
+ proxy_http_version 1.1;
113
+ proxy_set_header Upgrade $http_upgrade;
114
+ proxy_set_header Connection "upgrade";
115
+ }
116
+ }
117
+ ```
118
+
119
+ ---
120
+
121
+ ## 3. Server Hardening Fundamentals
122
+
123
+ ### SSH Security (`/etc/ssh/sshd_config`)
124
+ ```bash
125
+ PermitRootLogin no # Kill direct root login attacks immediately
126
+ PasswordAuthentication no # Enforce SSH key-based login ONLY
127
+ Port 2022 # (Optional) Obscurity defense against automated script-kiddie scanners
128
+ ```
129
+
130
+ ### Uncomplicated Firewall (UFW)
131
+ A naked server with all ports open is a honeypot.
132
+ ```bash
133
+ sudo ufw default deny incoming
134
+ sudo ufw default allow outgoing
135
+ sudo ufw allow 22/tcp # Allow SSH
136
+ sudo ufw allow 80/tcp # Allow HTTP
137
+ sudo ufw allow 443/tcp # Allow HTTPS
138
+ sudo ufw enable
139
+ ```
140
+
141
+ ### Fail2Ban
142
+ Automatically bans IPs attempting brute force credential filling after 5 bad attempts.
143
+
144
+ ---
145
+
146
+ ## 4. Log Rotation (Prevent Disk Full Outages)
147
+
148
+ A server will inevitably crash when `/var/log` consumes 100% of the disk.
149
+
150
+ ```bash
151
+ # /etc/logrotate.d/myapp
152
+
153
+ /var/www/myapp/logs/*.log {
154
+ daily # Rotate every day
155
+ missingok # Ignore if file is missing
156
+ rotate 14 # Keep 14 days of history
157
+ compress # Gzip old logs
158
+ delaycompress # Don't compress the one created yesterday
159
+ notifempty # Do nothing if log is empty
160
+ copytruncate # Copy then clear (avoids disrupting Node's open file handles)
161
+ }
162
+ ```
163
+
164
+ ---