tribunal-kit 6.0.1 → 7.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.
- package/.agent/ARCHITECTURE.md +9 -6
- package/.agent/agents/accessibility-reviewer.md +23 -16
- package/.agent/agents/ai-code-reviewer.md +25 -21
- package/.agent/agents/anti-pattern-reviewer.md +12 -7
- package/.agent/agents/api-architect.md +1 -0
- package/.agent/agents/backend-specialist.md +23 -22
- package/.agent/agents/cloud-engineer.md +1 -0
- package/.agent/agents/code-archaeologist.md +1 -0
- package/.agent/agents/complexity-reviewer.md +10 -7
- package/.agent/agents/database-architect.md +3 -2
- package/.agent/agents/db-latency-auditor.md +6 -2
- package/.agent/agents/debugger.md +3 -2
- package/.agent/agents/dependency-reviewer.md +1 -0
- package/.agent/agents/devops-engineer.md +9 -8
- package/.agent/agents/documentation-writer.md +6 -5
- package/.agent/agents/explorer-agent.md +1 -0
- package/.agent/agents/frontend-reviewer.md +21 -17
- package/.agent/agents/frontend-specialist.md +23 -20
- package/.agent/agents/game-developer.md +1 -0
- package/.agent/agents/interaction-reviewer.md +10 -5
- package/.agent/agents/logic-reviewer.md +3 -0
- package/.agent/agents/minimalist-reviewer.md +6 -0
- package/.agent/agents/mobile-developer.md +7 -6
- package/.agent/agents/mobile-reviewer.md +14 -13
- package/.agent/agents/orchestrator.md +3 -0
- package/.agent/agents/penetration-tester.md +1 -0
- package/.agent/agents/performance-optimizer.md +6 -5
- package/.agent/agents/performance-reviewer.md +6 -6
- package/.agent/agents/pipeline-reviewer.md +144 -0
- package/.agent/agents/precedence-reviewer.md +1 -0
- package/.agent/agents/product-manager.md +1 -0
- package/.agent/agents/product-owner.md +1 -0
- package/.agent/agents/product-reviewer.md +12 -7
- package/.agent/agents/project-planner.md +3 -0
- package/.agent/agents/qa-automation-engineer.md +50 -43
- package/.agent/agents/resilience-reviewer.md +1 -0
- package/.agent/agents/schema-reviewer.md +1 -0
- package/.agent/agents/security-auditor.md +24 -24
- package/.agent/agents/seo-specialist.md +33 -23
- package/.agent/agents/sql-reviewer.md +5 -4
- package/.agent/agents/supervisor-agent.md +12 -2
- package/.agent/agents/swarm-worker-contracts.md +13 -13
- package/.agent/agents/swarm-worker-registry.md +51 -51
- package/.agent/agents/system-architect.md +1 -0
- package/.agent/agents/test-coverage-reviewer.md +25 -22
- package/.agent/agents/test-engineer.md +12 -11
- package/.agent/agents/throughput-optimizer.md +45 -40
- package/.agent/agents/type-safety-reviewer.md +5 -4
- package/.agent/agents/ui-ux-auditor.md +6 -4
- package/.agent/agents/ui-visual-auditor.md +3 -0
- package/.agent/agents/ux-reviewer.md +11 -6
- package/.agent/agents/visual-reviewer.md +11 -6
- package/.agent/agents/vitals-reviewer.md +5 -4
- package/.agent/history/memory/.memory.idx +1532 -1
- package/.agent/history/memory/MEMORY.md +102 -1
- package/.agent/mcp_config.json +1 -6
- package/.agent/routing_index.json +2033 -263
- package/.agent/rules/GEMINI.md +11 -9
- package/.agent/rules/GEMINI_PLANNER.md +19 -21
- package/.agent/scripts/_colors.js +52 -54
- package/.agent/scripts/_utils.js +52 -53
- package/.agent/scripts/auto_preview.js +39 -43
- package/.agent/scripts/bundle_analyzer.js +47 -60
- package/.agent/scripts/case_law_manager.js +200 -294
- package/.agent/scripts/checklist.js +73 -94
- package/.agent/scripts/cicd_validator.js +305 -0
- package/.agent/scripts/compile_router.py +4 -111
- package/.agent/scripts/context_broker.js +317 -412
- package/.agent/scripts/contract_engine.js +402 -0
- package/.agent/scripts/dependency_analyzer.js +112 -124
- package/.agent/scripts/graph_builder.js +75 -103
- package/.agent/scripts/graph_visualizer.js +10 -12
- package/.agent/scripts/graph_zoom.js +38 -55
- package/.agent/scripts/guardrail_engine.js +195 -145
- package/.agent/scripts/impact_classifier.js +55 -30
- package/.agent/scripts/inner_loop_validator.js +108 -159
- package/.agent/scripts/integrity_manifest.js +59 -67
- package/.agent/scripts/lint_runner.js +65 -75
- package/.agent/scripts/marathon_harness.js +131 -208
- package/.agent/scripts/migrate_skills_frontmatter.py +4 -63
- package/.agent/scripts/minify_context.js +29 -33
- package/.agent/scripts/minimal_change_engine.js +95 -87
- package/.agent/scripts/mutation_runner.js +46 -62
- package/.agent/scripts/pipeline_engine.js +320 -209
- package/.agent/scripts/prompt_compiler.js +118 -93
- package/.agent/scripts/schema_validator.js +73 -121
- package/.agent/scripts/security_scan.js +88 -117
- package/.agent/scripts/session_manager.js +52 -69
- package/.agent/scripts/signal_detector.js +24 -22
- package/.agent/scripts/skill_evolution.js +184 -245
- package/.agent/scripts/skill_integrator.js +35 -48
- package/.agent/scripts/socratic_gate_policy.js +15 -12
- package/.agent/scripts/strengthen_skills.js +29 -33
- package/.agent/scripts/swarm_dispatcher.js +120 -151
- package/.agent/scripts/test_runner.js +54 -56
- package/.agent/scripts/token_budget_broker.js +9 -7
- package/.agent/scripts/trace_engine.js +126 -0
- package/.agent/scripts/verify_all.js +76 -93
- package/.agent/scripts/visual_audit.js +16 -21
- package/.agent/skill_topic_map.json +22 -3
- package/.agent/skills/12-principles-of-animation/SKILL.md +7 -0
- package/.agent/skills/60fps-animation/SKILL.md +7 -0
- package/.agent/skills/accessible-animation/SKILL.md +5 -1
- package/.agent/skills/adapt/SKILL.md +7 -1
- package/.agent/skills/advanced-rag-pipelines/SKILL.md +1 -0
- package/.agent/skills/agent-organizer/SKILL.md +1 -0
- package/.agent/skills/agentic-patterns/SKILL.md +33 -25
- package/.agent/skills/agentic-workflows-2026/SKILL.md +6 -2
- package/.agent/skills/ai-app-hardening/SKILL.md +9 -8
- package/.agent/skills/ai-prompt-injection-defense/SKILL.md +7 -6
- package/.agent/skills/animation-on-scroll/SKILL.md +24 -15
- package/.agent/skills/animation-systems/SKILL.md +11 -10
- package/.agent/skills/antfu-conventions/SKILL.md +7 -2
- package/.agent/skills/api-patterns/SKILL.md +14 -10
- package/.agent/skills/api-security-auditor/SKILL.md +15 -14
- package/.agent/skills/app-builder/SKILL.md +1 -0
- package/.agent/skills/app-builder/templates/nextjs-fullstack/TEMPLATE.md +2 -2
- package/.agent/skills/app-builder/templates/nextjs-saas/TEMPLATE.md +1 -1
- package/.agent/skills/app-builder/templates/nextjs-static/TEMPLATE.md +12 -12
- package/.agent/skills/app-builder/templates/nuxt-app/TEMPLATE.md +3 -3
- package/.agent/skills/apple-design/SKILL.md +8 -7
- package/.agent/skills/architecture/SKILL.md +3 -2
- package/.agent/skills/audit-and-fix/SKILL.md +8 -5
- package/.agent/skills/authentication-best-practices/SKILL.md +9 -8
- package/.agent/skills/backend-security-expert/SKILL.md +1 -0
- package/.agent/skills/baseline-ui/SKILL.md +8 -7
- package/.agent/skills/bash-linux/SKILL.md +1 -0
- package/.agent/skills/behavioral-modes/SKILL.md +1 -0
- package/.agent/skills/better-colors/SKILL.md +11 -7
- package/.agent/skills/better-typography/SKILL.md +30 -16
- package/.agent/skills/better-ui/SKILL.md +17 -10
- package/.agent/skills/bolder/SKILL.md +6 -0
- package/.agent/skills/brainstorming/SKILL.md +6 -4
- package/.agent/skills/browser-native-ai/SKILL.md +5 -4
- package/.agent/skills/build-primitive/SKILL.md +5 -0
- package/.agent/skills/building-native-ui/SKILL.md +1 -0
- package/.agent/skills/cicd-pro/SKILL.md +2 -1
- package/.agent/skills/clarify/SKILL.md +19 -14
- package/.agent/skills/clean-code/SKILL.md +16 -15
- package/.agent/skills/cloud-architect/SKILL.md +1 -0
- package/.agent/skills/cobejs/SKILL.md +7 -9
- package/.agent/skills/code-review-checklist/SKILL.md +1 -0
- package/.agent/skills/codebase-design/SKILL.md +7 -2
- package/.agent/skills/colorize/SKILL.md +8 -3
- package/.agent/skills/compact-landing/SKILL.md +8 -3
- package/.agent/skills/company-logos/SKILL.md +6 -0
- package/.agent/skills/config-validator/SKILL.md +10 -9
- package/.agent/skills/containerization-pro/SKILL.md +6 -5
- package/.agent/skills/context-engineering-pro/SKILL.md +5 -4
- package/.agent/skills/create-design-md/SKILL.md +13 -5
- package/.agent/skills/critique/SKILL.md +10 -8
- package/.agent/skills/csharp-developer/SKILL.md +1 -0
- package/.agent/skills/data-validation-schemas/SKILL.md +28 -23
- package/.agent/skills/database-design/SKILL.md +2 -1
- package/.agent/skills/delight/SKILL.md +6 -0
- package/.agent/skills/deployment-procedures/SKILL.md +2 -1
- package/.agent/skills/design-lab/SKILL.md +5 -0
- package/.agent/skills/devops-engineer/SKILL.md +3 -2
- package/.agent/skills/devops-incident-responder/SKILL.md +2 -1
- package/.agent/skills/diagnosing-bugs/SKILL.md +12 -2
- package/.agent/skills/distill/SKILL.md +7 -2
- package/.agent/skills/documentation-templates/SKILL.md +3 -2
- package/.agent/skills/domain-modeling/SKILL.md +12 -4
- package/.agent/skills/duckdb-analytical-sql/SKILL.md +7 -3
- package/.agent/skills/edge-ai-mobile/SKILL.md +5 -1
- package/.agent/skills/edge-computing/SKILL.md +9 -8
- package/.agent/skills/emil-design-eng/SKILL.md +43 -27
- package/.agent/skills/error-resilience/SKILL.md +34 -16
- package/.agent/skills/expo-router-v4/SKILL.md +2 -1
- package/.agent/skills/extract-design-system/SKILL.md +12 -11
- package/.agent/skills/fabel-protocol/SKILL.md +24 -17
- package/.agent/skills/fixing-accessibility/SKILL.md +23 -16
- package/.agent/skills/fixing-metadata/SKILL.md +24 -13
- package/.agent/skills/fixing-motion-performance/SKILL.md +7 -5
- package/.agent/skills/framer-motion-expert/SKILL.md +29 -15
- package/.agent/skills/frontend-design/SKILL.md +21 -13
- package/.agent/skills/frontend-security-expert/SKILL.md +1 -0
- package/.agent/skills/game-design-expert/SKILL.md +1 -0
- package/.agent/skills/game-engineering-expert/SKILL.md +1 -0
- package/.agent/skills/generative-ui-expert/SKILL.md +3 -2
- package/.agent/skills/geo-fundamentals/SKILL.md +2 -1
- package/.agent/skills/git-pro/SKILL.md +10 -9
- package/.agent/skills/github-operations/SKILL.md +2 -1
- package/.agent/skills/gpt-taste/SKILL.md +7 -0
- package/.agent/skills/gsap-core/SKILL.md +26 -22
- package/.agent/skills/gsap-frameworks/SKILL.md +6 -5
- package/.agent/skills/gsap-performance/SKILL.md +4 -3
- package/.agent/skills/gsap-plugins/SKILL.md +34 -33
- package/.agent/skills/gsap-react/SKILL.md +9 -8
- package/.agent/skills/gsap-scrolltrigger/SKILL.md +34 -33
- package/.agent/skills/gsap-timeline/SKILL.md +18 -15
- package/.agent/skills/gsap-utils/SKILL.md +25 -24
- package/.agent/skills/harden/SKILL.md +9 -3
- package/.agent/skills/harness-protocol/SKILL.md +1 -0
- package/.agent/skills/i18n-localization/SKILL.md +10 -9
- package/.agent/skills/impeccable/SKILL.md +5 -0
- package/.agent/skills/improve-codebase-architecture/SKILL.md +10 -5
- package/.agent/skills/improve-ui/SKILL.md +12 -5
- package/.agent/skills/intelligent-routing/SKILL.md +7 -6
- package/.agent/skills/knowledge-graph/SKILL.md +1 -0
- package/.agent/skills/landing-page/SKILL.md +1 -0
- package/.agent/skills/lint-and-validate/SKILL.md +9 -4
- package/.agent/skills/llm-engineering/SKILL.md +55 -54
- package/.agent/skills/local-first/SKILL.md +20 -19
- package/.agent/skills/local-first-architecture/SKILL.md +6 -1
- package/.agent/skills/lottie-animation/SKILL.md +7 -3
- package/.agent/skills/marquee-loop/SKILL.md +1 -0
- package/.agent/skills/masked-reveal/SKILL.md +17 -4
- package/.agent/skills/mcp-builder/SKILL.md +13 -10
- package/.agent/skills/micro-interaction/SKILL.md +20 -5
- package/.agent/skills/mobile-design/SKILL.md +26 -15
- package/.agent/skills/monorepo-management/SKILL.md +3 -2
- package/.agent/skills/morphing-icons/SKILL.md +16 -6
- package/.agent/skills/motion-engineering/SKILL.md +19 -15
- package/.agent/skills/nextjs-react-expert/SKILL.md +26 -21
- package/.agent/skills/nodejs-best-practices/SKILL.md +89 -76
- package/.agent/skills/observability/SKILL.md +45 -44
- package/.agent/skills/opentelemetry-observability/SKILL.md +2 -1
- package/.agent/skills/page-transition-animation/SKILL.md +6 -3
- package/.agent/skills/parallel-agents/SKILL.md +7 -2
- package/.agent/skills/performance-profiling/SKILL.md +24 -13
- package/.agent/skills/plan-writing/SKILL.md +1 -0
- package/.agent/skills/platform-engineer/SKILL.md +3 -2
- package/.agent/skills/platform-engineering-opentofu/SKILL.md +1 -0
- package/.agent/skills/playwright-ai-e2e/SKILL.md +3 -2
- package/.agent/skills/playwright-best-practices/SKILL.md +29 -28
- package/.agent/skills/polish/SKILL.md +13 -12
- package/.agent/skills/powershell-windows/SKILL.md +1 -0
- package/.agent/skills/pricing-page/SKILL.md +8 -3
- package/.agent/skills/product-aware-heuristics/SKILL.md +122 -72
- package/.agent/skills/progressive-blur/SKILL.md +9 -4
- package/.agent/skills/project-idioms/SKILL.md +1 -0
- package/.agent/skills/property-based-testing/SKILL.md +10 -12
- package/.agent/skills/python-patterns/SKILL.md +1 -0
- package/.agent/skills/python-pro/SKILL.md +1 -0
- package/.agent/skills/quieter/SKILL.md +6 -0
- package/.agent/skills/react-doctor/SKILL.md +6 -0
- package/.agent/skills/react-specialist/SKILL.md +32 -28
- package/.agent/skills/readme-builder/SKILL.md +1 -0
- package/.agent/skills/realtime-patterns/SKILL.md +34 -33
- package/.agent/skills/red-team-tactics/SKILL.md +1 -0
- package/.agent/skills/redesign-skill/SKILL.md +6 -0
- package/.agent/skills/review-animations/SKILL.md +5 -2
- package/.agent/skills/review-animations/STANDARDS.md +37 -23
- package/.agent/skills/rust-pro/SKILL.md +1 -0
- package/.agent/skills/seo-fundamentals/SKILL.md +4 -3
- package/.agent/skills/server-management/SKILL.md +1 -0
- package/.agent/skills/shadcn-ui-expert/SKILL.md +28 -22
- package/.agent/skills/shape/SKILL.md +9 -2
- package/.agent/skills/skill-creator/SKILL.md +1 -0
- package/.agent/skills/soft-skill/SKILL.md +6 -0
- package/.agent/skills/sounds-on-the-web/SKILL.md +1 -0
- package/.agent/skills/sql-pro/SKILL.md +1 -0
- package/.agent/skills/supabase-postgres-best-practices/SKILL.md +1 -0
- package/.agent/skills/svg-animation/SKILL.md +16 -7
- package/.agent/skills/swiftui-expert/SKILL.md +1 -0
- package/.agent/skills/swiss-design/SKILL.md +5 -0
- package/.agent/skills/system-design-pro/SKILL.md +1 -0
- package/.agent/skills/systematic-debugging/SKILL.md +1 -0
- package/.agent/skills/tailwind-patterns/SKILL.md +25 -11
- package/.agent/skills/taste-skill/SKILL.md +6 -0
- package/.agent/skills/tdd-workflow/SKILL.md +5 -0
- package/.agent/skills/test-result-analyzer/SKILL.md +1 -0
- package/.agent/skills/testing-patterns/SKILL.md +123 -115
- package/.agent/skills/thermo-nuclear-code-quality-review/SKILL.md +5 -0
- package/.agent/skills/thinking-protocol/SKILL.md +3 -0
- package/.agent/skills/to-spring-or-not-to-spring/SKILL.md +9 -8
- package/.agent/skills/transitions-dev/SKILL.md +19 -6
- package/.agent/skills/trend-researcher/SKILL.md +1 -0
- package/.agent/skills/typescript-advanced/SKILL.md +23 -18
- package/.agent/skills/typeset/SKILL.md +10 -1
- package/.agent/skills/ui-reasoning-engine/SKILL.md +67 -48
- package/.agent/skills/ui-skill-packs/SKILL.md +6 -1
- package/.agent/skills/ui-skills-root/SKILL.md +39 -38
- package/.agent/skills/ui-ux-pro-max/SKILL.md +34 -26
- package/.agent/skills/ui-ux-researcher/SKILL.md +1 -0
- package/.agent/skills/vector-search-pgvector/SKILL.md +3 -2
- package/.agent/skills/vue-expert/SKILL.md +22 -19
- package/.agent/skills/vulnerability-scanner/SKILL.md +22 -21
- package/.agent/skills/web-accessibility-auditor/SKILL.md +2 -1
- package/.agent/skills/web-design-guidelines/SKILL.md +16 -10
- package/.agent/skills/web-quality-audit/SKILL.md +5 -0
- package/.agent/skills/webapp-testing/SKILL.md +14 -13
- package/.agent/skills/webgpu-performance/SKILL.md +1 -0
- package/.agent/skills/whimsy-injector/SKILL.md +9 -5
- package/.agent/skills/workflow-optimizer/SKILL.md +1 -0
- package/.agent/skills/zero-trust-passkeys/SKILL.md +11 -6
- package/.agent/templates/DESIGN.md +119 -110
- package/.agent/templates/design-tokens.json +9 -6
- package/.agent/workflows/acf.md +1 -0
- package/.agent/workflows/api-tester.md +1 -0
- package/.agent/workflows/audit.md +1 -0
- package/.agent/workflows/brainstorm.md +1 -0
- package/.agent/workflows/changelog.md +1 -0
- package/.agent/workflows/contract.md +60 -0
- package/.agent/workflows/create.md +1 -0
- package/.agent/workflows/debug.md +1 -0
- package/.agent/workflows/deploy.md +1 -0
- package/.agent/workflows/enhance.md +1 -0
- package/.agent/workflows/fix-ci.md +89 -0
- package/.agent/workflows/fix.md +1 -0
- package/.agent/workflows/generate.md +1 -0
- package/.agent/workflows/marathon.md +1 -0
- package/.agent/workflows/migrate.md +1 -0
- package/.agent/workflows/minimal.md +9 -7
- package/.agent/workflows/orchestrate.md +1 -0
- package/.agent/workflows/performance-benchmarker.md +1 -0
- package/.agent/workflows/pipeline.md +26 -21
- package/.agent/workflows/plan.md +1 -0
- package/.agent/workflows/preview.md +1 -0
- package/.agent/workflows/refactor.md +3 -2
- package/.agent/workflows/review-ai.md +4 -3
- package/.agent/workflows/review.md +1 -0
- package/.agent/workflows/session.md +1 -0
- package/.agent/workflows/status.md +1 -0
- package/.agent/workflows/strengthen-skills.md +1 -0
- package/.agent/workflows/super-prompt.md +1 -0
- package/.agent/workflows/swarm.md +15 -3
- package/.agent/workflows/test.md +8 -7
- package/.agent/workflows/tribunal-backend.md +3 -2
- package/.agent/workflows/tribunal-cicd.md +104 -0
- package/.agent/workflows/tribunal-database.md +1 -0
- package/.agent/workflows/tribunal-frontend.md +8 -6
- package/.agent/workflows/tribunal-full.md +2 -1
- package/.agent/workflows/tribunal-mobile.md +6 -5
- package/.agent/workflows/tribunal-performance.md +1 -0
- package/.agent/workflows/tribunal-speed.md +1 -0
- package/.agent/workflows/tribunal-ui.md +29 -21
- package/.agent/workflows/ui-ux-pro-max.md +19 -15
- package/CONTRIBUTING.md +3 -3
- package/README.md +94 -44
- package/SECURITY.md +10 -10
- package/bin/mcp-server.js +385 -252
- package/bin/tribunal-kit.js +29 -30
- package/bin/wrapper.js +40 -46
- package/dist/cli.js +6 -0
- package/dist/commands/case.js +2 -0
- package/dist/commands/contract.js +440 -0
- package/dist/commands/status.js +6 -0
- package/dist/index.d.ts +8 -1
- package/package.json +13 -12
- package/scripts/benchmark.js +62 -86
- package/scripts/changelog.js +67 -73
- package/scripts/fix-vbc.js +13 -15
- package/scripts/fix-vbc.ps1 +2 -118
- package/scripts/stress_benchmark.js +358 -0
- package/scripts/sync-version.js +71 -41
- package/scripts/validate-payload.js +23 -30
- package/scripts/visual_audit.js +23 -13
|
@@ -20,6 +20,7 @@ scripts-binding:
|
|
|
20
20
|
## Mandatory Pre-Flight Context Inspection
|
|
21
21
|
|
|
22
22
|
Before implementing UI component logic, you MUST inspect:
|
|
23
|
+
|
|
23
24
|
1. Component state tree → Verify presence of explicit loading skeleton, error boundary fallback, and empty states
|
|
24
25
|
2. CLS Prevention rules (Section 36) → Match skeleton placeholder dimensions exactly to incoming content elements
|
|
25
26
|
3. String Expansion (i18n) rules (Section 40) → Avoid hardcoded pixel widths (`width: 120px`); use `min-width` and flexible auto-layout
|
|
@@ -31,26 +32,31 @@ Ensure UI components gracefully handle network failures, missing data, slow conn
|
|
|
31
32
|
## 5 Resilience Domains
|
|
32
33
|
|
|
33
34
|
### 1. Zero-Data Empty States
|
|
35
|
+
|
|
34
36
|
- Never render empty blank slates or blank boxes.
|
|
35
37
|
- Always render a dedicated empty state component featuring:
|
|
36
38
|
- Contextual icon or subtle illustration
|
|
37
|
-
- Clear heading explaining the zero state (
|
|
38
|
-
- Secondary helper copy (
|
|
39
|
-
- Prominent primary action CTA button (
|
|
39
|
+
- Clear heading explaining the zero state (_"No active projects found"_)
|
|
40
|
+
- Secondary helper copy (_"Get started by creating your first project."_)
|
|
41
|
+
- Prominent primary action CTA button (_"Create Project"_)
|
|
40
42
|
|
|
41
43
|
### 2. Error Boundary UI & Retry Hooks
|
|
44
|
+
|
|
42
45
|
- Wrap high-risk component trees in React/framework Error Boundaries.
|
|
43
46
|
- Display localized inline error callouts with explicit "Retry" action buttons rather than crashing the full page view.
|
|
44
47
|
|
|
45
48
|
### 3. Cumulative Layout Shift (CLS) Loading Skeletons
|
|
49
|
+
|
|
46
50
|
- Match skeleton placeholder dimensions EXACTLY to incoming data elements.
|
|
47
51
|
- Use animated pulse keyframes (`@keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.4; } }`).
|
|
48
52
|
|
|
49
53
|
### 4. Extreme String Expansion (i18n)
|
|
54
|
+
|
|
50
55
|
- German, French, and Spanish strings are 30% - 50% longer than English.
|
|
51
56
|
- Avoid fixed button or container widths (`width: 120px`). Use `min-width` with flexible auto sizing and `flex-wrap: wrap` or text truncation.
|
|
52
57
|
|
|
53
58
|
### 5. Offline & Network Disconnection Handling
|
|
59
|
+
|
|
54
60
|
- Detect `navigator.onLine` state and display subtle offline status banners.
|
|
55
61
|
- Disable mutation buttons during offline mode with explicit tooltip explanation.
|
|
56
62
|
|
|
@@ -20,6 +20,7 @@ scripts-binding:
|
|
|
20
20
|
## Mandatory Pre-Flight Context Inspection
|
|
21
21
|
|
|
22
22
|
Before operating in Marathon long-running harness mode, you MUST inspect:
|
|
23
|
+
|
|
23
24
|
1. Active session ledger (`task.md`, `session_manager.js`) → Verify active feature specs and task completion status
|
|
24
25
|
2. Verification-Before-Completion (VBC) Protocol → Provide concrete proof (test run log, compiler pass) before calling `tk marathon mark pass`
|
|
25
26
|
3. Error recovery state machine → Escalate unrecoverable errors after 3 retries via `tk marathon mark fail`
|
|
@@ -20,6 +20,7 @@ scripts-binding:
|
|
|
20
20
|
## Mandatory Pre-Flight Context Inspection
|
|
21
21
|
|
|
22
22
|
Before engineering multilingual or i18n features, you MUST inspect:
|
|
23
|
+
|
|
23
24
|
1. Dictionary Interpolation (Section 15) → Use ICU parameter interpolation `t('greeting', { name })` instead of string concatenation
|
|
24
25
|
2. Native `Intl` API Formatting (Section 71) → Use native `Intl.NumberFormat` and `Intl.DateTimeFormat` with active locale instead of third-party string parsers
|
|
25
26
|
3. Logical CSS Properties for RTL (Section 94) → Use logical properties (`margin-inline-start`, `ms-4`) instead of physical `marginLeft`/`marginRight` for Arabic/Hebrew support
|
|
@@ -66,15 +67,15 @@ export function Header({ user, alertCount }) {
|
|
|
66
67
|
}
|
|
67
68
|
|
|
68
69
|
// ✅ GOOD: i18n Abstraction (using next-intl)
|
|
69
|
-
import { useTranslations } from
|
|
70
|
+
import { useTranslations } from 'next-intl';
|
|
70
71
|
|
|
71
72
|
export function Header({ user, alertCount }) {
|
|
72
|
-
const t = useTranslations(
|
|
73
|
+
const t = useTranslations('Dashboard');
|
|
73
74
|
|
|
74
75
|
return (
|
|
75
76
|
<header>
|
|
76
|
-
<h1>{t(
|
|
77
|
-
<p>{t(
|
|
77
|
+
<h1>{t('welcomeMessage', { name: user.name })}</h1>
|
|
78
|
+
<p>{t('unreadAlerts', { count: alertCount })}</p>
|
|
78
79
|
</header>
|
|
79
80
|
);
|
|
80
81
|
}
|
|
@@ -88,19 +89,19 @@ Do not install `moment.js` or write massive regex string parsers to format curre
|
|
|
88
89
|
|
|
89
90
|
```typescript
|
|
90
91
|
// Data/Currency Formatting correctly tied to the active locale
|
|
91
|
-
const locale =
|
|
92
|
+
const locale = 'de-DE';
|
|
92
93
|
|
|
93
94
|
// ✅ Currency
|
|
94
|
-
const price = new Intl.NumberFormat(locale, { style:
|
|
95
|
+
const price = new Intl.NumberFormat(locale, { style: 'currency', currency: 'EUR' }).format(1200.5);
|
|
95
96
|
// Output in Germany: "1.200,50 €"
|
|
96
97
|
|
|
97
98
|
// ✅ Dates
|
|
98
|
-
const date = new Intl.DateTimeFormat(locale, { dateStyle:
|
|
99
|
+
const date = new Intl.DateTimeFormat(locale, { dateStyle: 'full' }).format(new Date());
|
|
99
100
|
// Output in Germany: "Freitag, 2. April 2026"
|
|
100
101
|
|
|
101
102
|
// ✅ Relative Time
|
|
102
|
-
const rtf = new Intl.RelativeTimeFormat(locale, { numeric:
|
|
103
|
-
rtf.format(-2,
|
|
103
|
+
const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
|
|
104
|
+
rtf.format(-2, 'day'); // Output: "vorgestern" (the day before yesterday)
|
|
104
105
|
```
|
|
105
106
|
|
|
106
107
|
---
|
|
@@ -20,6 +20,7 @@ scripts-binding:
|
|
|
20
20
|
## Mandatory Pre-Flight Context Inspection
|
|
21
21
|
|
|
22
22
|
Before designing or engineering frontend components, you MUST inspect:
|
|
23
|
+
|
|
23
24
|
1. `DESIGN.md` / `package.json` → Verify OKLCH color palettes, font pairings, and responsive container query setups
|
|
24
25
|
2. Core Pillars of Impeccable UI (Section 22) → Enforce `tabular-nums` on digits, `text-wrap: balance` on headings, and strict 8px grid math
|
|
25
26
|
3. Motion & Micro-Interactions (Section 34) → Limit micro-interactions to $\le 160\text{ms}$ and check `prefers-reduced-motion` fallbacks
|
|
@@ -31,22 +32,26 @@ The gold standard framework for crafting bespoke, world-class web applications t
|
|
|
31
32
|
## Core Pillars of Impeccable UI
|
|
32
33
|
|
|
33
34
|
### 1. Typography & Typographic Rhythm
|
|
35
|
+
|
|
34
36
|
- **Optical Sizing & Tracking**: Large display headings (32px+) require tight letter-spacing (`letter-spacing: -0.03em`). Small caption text (12px) requires positive tracking (`letter-spacing: +0.01em`).
|
|
35
37
|
- **Tabular Numbers**: Any numeric data that updates, increments, or displays in columns MUST use `font-variant-numeric: tabular-nums` or `font-feature-settings: "tnum"` to prevent visual jitter.
|
|
36
38
|
- **Text Wrapping & Balance**: Headings MUST use `text-wrap: balance` to prevent typographic orphans. Body paragraphs MUST use `text-wrap: pretty` (where supported) or max `65ch` width.
|
|
37
39
|
|
|
38
40
|
### 2. Color Systems & Gamut Precision
|
|
41
|
+
|
|
39
42
|
- **OKLCH Color Space**: Prefer `oklch()` over `hsl()` or `hex` for smooth perceptual uniformity across hue and lightness shifts.
|
|
40
43
|
- **Subtle Surface Steps**: Define surface colors with small perceptual lightness steps ($L \pm 2\%$) to create hierarchy without harsh dividers.
|
|
41
44
|
- **Adaptive Contrast**: Text contrast MUST adapt automatically across light/dark themes with high legibility ratios ($\ge 7:1$ for primary, $\ge 4.5:1$ for secondary).
|
|
42
45
|
|
|
43
46
|
### 3. Motion & Micro-Interactions
|
|
47
|
+
|
|
44
48
|
- **Intentional Motion**: Animations exist ONLY to convey spatial continuity, provide press feedback, or indicate state changes.
|
|
45
49
|
- **Duration Constraints**: Micro-interactions $\le 160\text{ms}$; dropdowns/popovers $\le 220\text{ms}$; page transitions $\le 300\text{ms}$.
|
|
46
50
|
- **Physically Grounded Entrances**: Elements scale in from `scale(0.96)` and opacity `0`, anchored to their trigger origin.
|
|
47
51
|
- **DOM Entry (@starting-style)**: Use `@starting-style` with `transition-behavior: allow-discrete` for smooth `display: none` to `display: block` entrance animations without JS overhead.
|
|
48
52
|
|
|
49
53
|
### 4. Layout Mechanics & Spatial Math
|
|
54
|
+
|
|
50
55
|
- **8px Grid System**: Every margin, padding, gap, and height MUST derive from an 8px grid (or 4px micro-grid).
|
|
51
56
|
- **Asymmetrical Balance**: Avoid cookie-cutter centered layouts for SaaS apps. Use strong left-aligned structural axes with generous negative space.
|
|
52
57
|
- **Container Queries**: Components adjust layout based on container size (`@container`), not viewport size (`@media`), making them context-agnostic.
|
|
@@ -20,6 +20,7 @@ scripts-binding:
|
|
|
20
20
|
## Mandatory Pre-Flight Context Inspection
|
|
21
21
|
|
|
22
22
|
Before refactoring or producing an architectural improvement roadmap, you MUST inspect:
|
|
23
|
+
|
|
23
24
|
1. Circular Dependency Breaking Rule (Section 24) → Identify circular imports (`A -> B -> C -> A`) and resolve via event buses or explicit interfaces
|
|
24
25
|
2. Monolithic Controller Line Threshold (500 lines) (Section 27) → Flag any controller/service >500 lines with mixed concerns for immediate decomposition
|
|
25
26
|
3. Incremental Refactoring Rule (Section 46) → Ban shotgun surgery across >5 files simultaneously; enforce phased, test-backed interface extractions
|
|
@@ -33,22 +34,26 @@ Audit an existing codebase for structural rot, circular dependencies, monolithic
|
|
|
33
34
|
## 4 Audit Steps
|
|
34
35
|
|
|
35
36
|
### 1. Dependency Graph Inspection
|
|
37
|
+
|
|
36
38
|
- Map import relationships across modules. Identify circular dependencies (`A -> B -> C -> A`) and break them by introducing event buses or interface abstractions.
|
|
37
39
|
|
|
38
40
|
### 2. Monolithic Controller Detection
|
|
41
|
+
|
|
39
42
|
- Flag files exceeding 500 lines of code containing mixed concerns (database queries, HTTP response handling, email sending, data validation).
|
|
40
43
|
|
|
41
44
|
### 3. Interface Shrinking (Deepening Modules)
|
|
45
|
+
|
|
42
46
|
- Audit public exports. Convert large multi-parameter interfaces into thin, single-responsibility contracts.
|
|
43
47
|
|
|
44
48
|
### 4. Prioritized Architectural Roadmap Output
|
|
49
|
+
|
|
45
50
|
Output audit findings in a clear prioritized Markdown table:
|
|
46
51
|
|
|
47
|
-
| Impact Level
|
|
48
|
-
|
|
|
49
|
-
| 🔴 **High Impact**
|
|
50
|
-
| 🟠 **Medium Impact** | Circular import between Auth and User modules
|
|
51
|
-
| 🟡 **Low Impact**
|
|
52
|
+
| Impact Level | Architectural Issue | Proposed Seam / Refactor |
|
|
53
|
+
| -------------------- | ------------------------------------------------ | ------------------------------------------------- |
|
|
54
|
+
| 🔴 **High Impact** | Direct DB queries inside React Server Components | Extract Repository layer pattern |
|
|
55
|
+
| 🟠 **Medium Impact** | Circular import between Auth and User modules | Introduce `EventBus` for user registration events |
|
|
56
|
+
| 🟡 **Low Impact** | Hardcoded API base URLs across 12 files | Centralize in typed `ConfigService` |
|
|
52
57
|
|
|
53
58
|
---
|
|
54
59
|
|
|
@@ -20,6 +20,7 @@ scripts-binding:
|
|
|
20
20
|
## Mandatory Pre-Flight Context Inspection
|
|
21
21
|
|
|
22
22
|
Before auditing UI surfaces or writing remediation plans, you MUST inspect:
|
|
23
|
+
|
|
23
24
|
1. Read-Only Constraint (Section 24) → Strictly NEVER modify product source code (`src/`, `components/`, `app/`) during an `improve-ui` audit session
|
|
24
25
|
2. 3-Proof Requirement (Section 40) → Every reported defect MUST present Observation (code line/element), Basis (token/grid violation), and Consequence
|
|
25
26
|
3. Plan Artifact Output (Section 25) → Write implementation plans to `design-plans/` or output structured markdown for execution
|
|
@@ -39,21 +40,27 @@ Audit a specific product surface against its governing design tokens and guideli
|
|
|
39
40
|
## 2. The 4-Phase Audit Protocol
|
|
40
41
|
|
|
41
42
|
### Phase 1: Surface Selection & Path Tracing
|
|
43
|
+
|
|
42
44
|
1. Focus on one deployable application and one coherent surface family (e.g. `Dashboard / Overview`).
|
|
43
45
|
2. Trace the path from route layout $\rightarrow$ page composition $\rightarrow$ shared UI primitives $\rightarrow$ tokens/CSS variables.
|
|
44
46
|
|
|
45
47
|
### Phase 2: Design Language Reconstruction
|
|
48
|
+
|
|
46
49
|
1. Inspect `DESIGN.md`, `index.css`, Tailwind tokens, or custom properties.
|
|
47
50
|
2. Record active background tokens, typography roles, spatial rules, and border/shadow contracts.
|
|
48
51
|
|
|
49
52
|
### Phase 3: Proof-Gated Defect Verification
|
|
53
|
+
|
|
50
54
|
Before reporting a finding, require 3 explicit proofs:
|
|
55
|
+
|
|
51
56
|
- **Observation**: Exact code line or rendered element showing the discrepancy.
|
|
52
57
|
- **Basis**: Violation of documented design token or 8px grid baseline.
|
|
53
58
|
- **Consequence**: Measurable degradation of visual hierarchy, readability, or interaction response.
|
|
54
59
|
|
|
55
60
|
### Phase 4: Implementation Plan Generation
|
|
61
|
+
|
|
56
62
|
Write a self-contained plan specifying:
|
|
63
|
+
|
|
57
64
|
- Files to modify
|
|
58
65
|
- Exact CSS/JSX diffs
|
|
59
66
|
- Verification steps (browser preview, contrast check, visual alignment)
|
|
@@ -62,11 +69,11 @@ Write a self-contained plan specifying:
|
|
|
62
69
|
|
|
63
70
|
## Anti-Slop Table
|
|
64
71
|
|
|
65
|
-
| Audit Pattern
|
|
66
|
-
|
|
|
67
|
-
| Rewriting entire components
|
|
68
|
-
| Guessing design tokens
|
|
69
|
-
| Speculative visual preferences | Reporting only verified WCAG/token violations | Prevents arbitrary churn
|
|
72
|
+
| Audit Pattern | Evidence-Based Rule | Rationale |
|
|
73
|
+
| ------------------------------ | --------------------------------------------- | -------------------------------- |
|
|
74
|
+
| Rewriting entire components | Targeted visual diff plan | Preserves business logic & state |
|
|
75
|
+
| Guessing design tokens | Citing verified `var(--...)` declarations | Ensures token adherence |
|
|
76
|
+
| Speculative visual preferences | Reporting only verified WCAG/token violations | Prevents arbitrary churn |
|
|
70
77
|
|
|
71
78
|
---
|
|
72
79
|
|
|
@@ -18,6 +18,7 @@ scripts-binding:
|
|
|
18
18
|
## Mandatory Pre-Flight Context Inspection
|
|
19
19
|
|
|
20
20
|
Before routing user prompts to specialized skills or agents, you MUST inspect:
|
|
21
|
+
|
|
21
22
|
1. `.agent/routing_index.json` → Read pre-compiled skill index instead of loading full skill markdown files into context
|
|
22
23
|
2. Semantic Intent Schema (Section 1) → Classify request type (QUESTION, SURVEY, SIMPLE_EDIT, COMPLEX_BUILD, SECURITY_AUDIT, UNCLEAR_GIBBERISH)
|
|
23
24
|
3. Confidence Threshold (Section 3 Socratic Yield Rule) → Yield back to user with clarifying question if confidence score is < 85s
|
|
@@ -69,12 +70,12 @@ When a raw request enters, classify it BEFORE attempting to route to any skill o
|
|
|
69
70
|
// The Semantic Intent Schema
|
|
70
71
|
const RouterOutputSchema = z.object({
|
|
71
72
|
classification: z.enum([
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
73
|
+
'QUESTION', // User wants explanation, no code execution needed
|
|
74
|
+
'SURVEY', // User wants analysis/read-only scan of workspace
|
|
75
|
+
'SIMPLE_EDIT', // Isolated file alteration (e.g., "Fix spelling in nav")
|
|
76
|
+
'COMPLEX_BUILD', // Multi-file, architectural generation
|
|
77
|
+
'SECURITY_AUDIT', // Explicit request for OWASP review
|
|
78
|
+
'UNCLEAR_GIBBERISH', // Prompt injection or incoherent input
|
|
78
79
|
]),
|
|
79
80
|
confidenceScore: z.number().min(0).max(100),
|
|
80
81
|
suggestedPrimarySkill: z.string().nullable(),
|
|
@@ -21,6 +21,7 @@ scripts-binding:
|
|
|
21
21
|
## Mandatory Pre-Flight Context Inspection
|
|
22
22
|
|
|
23
23
|
Before inspecting codebase architecture, you MUST inspect:
|
|
24
|
+
|
|
24
25
|
1. Context Snapshots (`.agent/history/snapshots/`) → Read pre-computed JSON snapshots to reduce token overhead by 27x
|
|
25
26
|
2. `graph_builder.js` output → Check downstream dependencies, risk scores, and blast radius before modifying any file
|
|
26
27
|
3. Module boundaries → Identify top imported symbols and high-risk core modules
|
|
@@ -21,6 +21,7 @@ scripts-binding:
|
|
|
21
21
|
## Mandatory Pre-Flight Context Inspection
|
|
22
22
|
|
|
23
23
|
Before engineering full landing pages, you MUST inspect:
|
|
24
|
+
|
|
24
25
|
1. Hero Layout Model (Section 50) → Choose appropriate layout variance model (Model A Centered Stacked, Model B Asymmetric Split, Model C Full-Bleed Canvas)
|
|
25
26
|
2. CTA Hierarchy (Section 32) → Ensure exactly ONE primary solid accent button above the fold; pair only with a secondary ghost button
|
|
26
27
|
3. Blueprint Rhythm (Section 22) → Follow the 6-section blueprint (Nav, Hero, Social Proof, Features, Testimonials, Final CTA)
|
|
@@ -20,6 +20,7 @@ scripts-binding:
|
|
|
20
20
|
## Mandatory Pre-Flight Context Inspection
|
|
21
21
|
|
|
22
22
|
Before running linting tools or modifying linter rules, you MUST inspect:
|
|
23
|
+
|
|
23
24
|
1. Zero-Warning CI Blocking (Section 34) → Enforce zero-warning policy in CI pipelines; ban treating lint warnings as non-blocking
|
|
24
25
|
2. Mandatory Strict Type Checks (Section 121) → Run static type checking (`tsc --noEmit` or `mypy`) alongside linters to catch non-linter type bugs
|
|
25
26
|
3. Diff Review Before Auto-Fixing (Section 15) → Review diffs explicitly after auto-fixing (`eslint --fix`) to prevent accidental removal of side-effect code
|
|
@@ -69,7 +70,11 @@ npx prettier --write .
|
|
|
69
70
|
```json
|
|
70
71
|
// .eslintrc.json
|
|
71
72
|
{
|
|
72
|
-
"extends": [
|
|
73
|
+
"extends": [
|
|
74
|
+
"eslint:recommended",
|
|
75
|
+
"plugin:@typescript-eslint/recommended",
|
|
76
|
+
"plugin:@typescript-eslint/recommended-requiring-type-checking"
|
|
77
|
+
],
|
|
73
78
|
"rules": {
|
|
74
79
|
"@typescript-eslint/no-explicit-any": "error",
|
|
75
80
|
"@typescript-eslint/no-floating-promises": "error",
|
|
@@ -197,9 +202,9 @@ repos:
|
|
|
197
202
|
|
|
198
203
|
## Scripts
|
|
199
204
|
|
|
200
|
-
| Script
|
|
201
|
-
|
|
|
202
|
-
| `.agent/scripts/lint_runner.js`
|
|
205
|
+
| Script | Purpose | Run With |
|
|
206
|
+
| ------------------------------- | ----------------------------------------- | --------------------------------------------------- |
|
|
207
|
+
| `.agent/scripts/lint_runner.js` | Runs project linting and reports findings | `node .agent/scripts/lint_runner.js <project_path>` |
|
|
203
208
|
|
|
204
209
|
---
|
|
205
210
|
|
|
@@ -20,6 +20,7 @@ scripts-binding:
|
|
|
20
20
|
## Mandatory Pre-Flight Context Inspection
|
|
21
21
|
|
|
22
22
|
Before engineering LLM integrations or tool calling loops, you MUST inspect:
|
|
23
|
+
|
|
23
24
|
1. Zod Schema Validation on JSON Outputs (Section 115) → Always run Zod validation (`Schema.parse(...)`) on LLM JSON responses, even in strict mode
|
|
24
25
|
2. Hybrid Vector + Keyword Search (Section 290) → Use hybrid vector + BM25 keyword search in RAG applications to prevent missing exact identifiers
|
|
25
26
|
3. System Prompt Secret Isolation (Section 69) → Never put private API keys, database credentials, or secret internal URLs into system prompts
|
|
@@ -76,7 +77,7 @@ const SYSTEM_PROMPT = `You are a customer support agent for Acme Corp.
|
|
|
76
77
|
- End with a follow-up question
|
|
77
78
|
|
|
78
79
|
## Context
|
|
79
|
-
Current date: ${new Date().toISOString().split(
|
|
80
|
+
Current date: ${new Date().toISOString().split('T')[0]}
|
|
80
81
|
User plan: {{user_plan}}
|
|
81
82
|
`;
|
|
82
83
|
|
|
@@ -88,11 +89,11 @@ User plan: {{user_plan}}
|
|
|
88
89
|
### Structured Output (JSON Mode)
|
|
89
90
|
|
|
90
91
|
```typescript
|
|
91
|
-
import { z } from
|
|
92
|
-
import OpenAI from
|
|
92
|
+
import { z } from 'zod';
|
|
93
|
+
import OpenAI from 'openai';
|
|
93
94
|
|
|
94
95
|
const SentimentSchema = z.object({
|
|
95
|
-
sentiment: z.enum([
|
|
96
|
+
sentiment: z.enum(['positive', 'negative', 'neutral']),
|
|
96
97
|
confidence: z.number().min(0).max(1),
|
|
97
98
|
reasoning: z.string(),
|
|
98
99
|
topics: z.array(z.string()),
|
|
@@ -101,49 +102,49 @@ const SentimentSchema = z.object({
|
|
|
101
102
|
// OpenAI — json_schema mode (strict = true enforces schema exactly)
|
|
102
103
|
async function analyzeSentiment(text: string) {
|
|
103
104
|
const response = await openai.chat.completions.create({
|
|
104
|
-
model:
|
|
105
|
+
model: 'gpt-4o-mini',
|
|
105
106
|
response_format: {
|
|
106
|
-
type:
|
|
107
|
+
type: 'json_schema',
|
|
107
108
|
json_schema: {
|
|
108
|
-
name:
|
|
109
|
+
name: 'sentiment_analysis',
|
|
109
110
|
strict: true,
|
|
110
111
|
schema: {
|
|
111
|
-
type:
|
|
112
|
+
type: 'object',
|
|
112
113
|
properties: {
|
|
113
|
-
sentiment: { type:
|
|
114
|
-
confidence: { type:
|
|
115
|
-
reasoning: { type:
|
|
116
|
-
topics: { type:
|
|
114
|
+
sentiment: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
|
|
115
|
+
confidence: { type: 'number' },
|
|
116
|
+
reasoning: { type: 'string' },
|
|
117
|
+
topics: { type: 'array', items: { type: 'string' } },
|
|
117
118
|
},
|
|
118
|
-
required: [
|
|
119
|
+
required: ['sentiment', 'confidence', 'reasoning', 'topics'],
|
|
119
120
|
additionalProperties: false, // required for strict mode
|
|
120
121
|
},
|
|
121
122
|
},
|
|
122
123
|
},
|
|
123
124
|
messages: [
|
|
124
|
-
{ role:
|
|
125
|
-
{ role:
|
|
125
|
+
{ role: 'system', content: 'Analyze sentiment.' },
|
|
126
|
+
{ role: 'user', content: text },
|
|
126
127
|
],
|
|
127
128
|
});
|
|
128
|
-
const raw = JSON.parse(response.choices[0].message.content ??
|
|
129
|
+
const raw = JSON.parse(response.choices[0].message.content ?? '{}');
|
|
129
130
|
return SentimentSchema.parse(raw); // always validate with Zod even in strict mode
|
|
130
131
|
}
|
|
131
132
|
|
|
132
133
|
// Gemini — response_mime_type + response_schema
|
|
133
|
-
import { GoogleGenerativeAI, SchemaType } from
|
|
134
|
+
import { GoogleGenerativeAI, SchemaType } from '@google/generative-ai';
|
|
134
135
|
const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);
|
|
135
136
|
const model = genAI.getGenerativeModel({
|
|
136
|
-
model:
|
|
137
|
+
model: 'gemini-2.0-flash',
|
|
137
138
|
generationConfig: {
|
|
138
|
-
responseMimeType:
|
|
139
|
+
responseMimeType: 'application/json',
|
|
139
140
|
responseSchema: {
|
|
140
141
|
type: SchemaType.OBJECT,
|
|
141
142
|
properties: {
|
|
142
|
-
sentiment: { type: SchemaType.STRING, enum: [
|
|
143
|
+
sentiment: { type: SchemaType.STRING, enum: ['positive', 'negative', 'neutral'] },
|
|
143
144
|
confidence: { type: SchemaType.NUMBER },
|
|
144
145
|
topics: { type: SchemaType.ARRAY, items: { type: SchemaType.STRING } },
|
|
145
146
|
},
|
|
146
|
-
required: [
|
|
147
|
+
required: ['sentiment', 'confidence', 'topics'],
|
|
147
148
|
},
|
|
148
149
|
},
|
|
149
150
|
});
|
|
@@ -159,32 +160,32 @@ const model = genAI.getGenerativeModel({
|
|
|
159
160
|
```typescript
|
|
160
161
|
const tools: OpenAI.ChatCompletionTool[] = [
|
|
161
162
|
{
|
|
162
|
-
type:
|
|
163
|
+
type: 'function',
|
|
163
164
|
function: {
|
|
164
|
-
name:
|
|
165
|
-
description:
|
|
165
|
+
name: 'search_products',
|
|
166
|
+
description: 'Search products by name, category, or price range',
|
|
166
167
|
parameters: {
|
|
167
|
-
type:
|
|
168
|
+
type: 'object',
|
|
168
169
|
properties: {
|
|
169
|
-
query: { type:
|
|
170
|
-
category: { type:
|
|
171
|
-
max_price: { type:
|
|
170
|
+
query: { type: 'string', description: 'Search query' },
|
|
171
|
+
category: { type: 'string', enum: ['electronics', 'clothing', 'home'] },
|
|
172
|
+
max_price: { type: 'number', description: 'Maximum price in USD' },
|
|
172
173
|
},
|
|
173
|
-
required: [
|
|
174
|
+
required: ['query'],
|
|
174
175
|
},
|
|
175
176
|
},
|
|
176
177
|
},
|
|
177
178
|
{
|
|
178
|
-
type:
|
|
179
|
+
type: 'function',
|
|
179
180
|
function: {
|
|
180
|
-
name:
|
|
181
|
-
description:
|
|
181
|
+
name: 'get_order_status',
|
|
182
|
+
description: 'Get the status of an order by order ID',
|
|
182
183
|
parameters: {
|
|
183
|
-
type:
|
|
184
|
+
type: 'object',
|
|
184
185
|
properties: {
|
|
185
|
-
order_id: { type:
|
|
186
|
+
order_id: { type: 'string', description: 'The order ID (e.g., ORD-12345)' },
|
|
186
187
|
},
|
|
187
|
-
required: [
|
|
188
|
+
required: ['order_id'],
|
|
188
189
|
},
|
|
189
190
|
},
|
|
190
191
|
},
|
|
@@ -193,18 +194,18 @@ const tools: OpenAI.ChatCompletionTool[] = [
|
|
|
193
194
|
// Tool execution loop
|
|
194
195
|
async function chatWithTools(userMessage: string) {
|
|
195
196
|
const messages: OpenAI.ChatCompletionMessageParam[] = [
|
|
196
|
-
{ role:
|
|
197
|
-
{ role:
|
|
197
|
+
{ role: 'system', content: SYSTEM_PROMPT },
|
|
198
|
+
{ role: 'user', content: userMessage },
|
|
198
199
|
];
|
|
199
200
|
|
|
200
201
|
let response = await openai.chat.completions.create({
|
|
201
|
-
model:
|
|
202
|
+
model: 'gpt-4o-mini',
|
|
202
203
|
messages,
|
|
203
204
|
tools,
|
|
204
205
|
});
|
|
205
206
|
|
|
206
207
|
// Process tool calls
|
|
207
|
-
while (response.choices[0].finish_reason ===
|
|
208
|
+
while (response.choices[0].finish_reason === 'tool_calls') {
|
|
208
209
|
const toolCalls = response.choices[0].message.tool_calls ?? [];
|
|
209
210
|
messages.push(response.choices[0].message);
|
|
210
211
|
|
|
@@ -212,14 +213,14 @@ async function chatWithTools(userMessage: string) {
|
|
|
212
213
|
const args = JSON.parse(call.function.arguments);
|
|
213
214
|
const result = await executeFunction(call.function.name, args);
|
|
214
215
|
messages.push({
|
|
215
|
-
role:
|
|
216
|
+
role: 'tool',
|
|
216
217
|
tool_call_id: call.id,
|
|
217
218
|
content: JSON.stringify(result),
|
|
218
219
|
});
|
|
219
220
|
}
|
|
220
221
|
|
|
221
222
|
response = await openai.chat.completions.create({
|
|
222
|
-
model:
|
|
223
|
+
model: 'gpt-4o-mini',
|
|
223
224
|
messages,
|
|
224
225
|
tools,
|
|
225
226
|
});
|
|
@@ -262,19 +263,19 @@ function chunkDocument(text: string, options: ChunkOptions = {}): Chunk[] {
|
|
|
262
263
|
const {
|
|
263
264
|
maxTokens = 512, // chunk size
|
|
264
265
|
overlapTokens = 50, // overlap between chunks
|
|
265
|
-
separator =
|
|
266
|
+
separator = '\n\n', // split on paragraph boundaries first
|
|
266
267
|
} = options;
|
|
267
268
|
|
|
268
269
|
const paragraphs = text.split(separator);
|
|
269
270
|
const chunks: Chunk[] = [];
|
|
270
|
-
let current =
|
|
271
|
+
let current = '';
|
|
271
272
|
|
|
272
273
|
for (const para of paragraphs) {
|
|
273
274
|
if (tokenCount(current + para) > maxTokens && current) {
|
|
274
275
|
chunks.push({ text: current.trim(), tokens: tokenCount(current) });
|
|
275
276
|
// Keep overlap from previous chunk
|
|
276
|
-
const words = current.split(
|
|
277
|
-
current = words.slice(-overlapTokens).join(
|
|
277
|
+
const words = current.split(' ');
|
|
278
|
+
current = words.slice(-overlapTokens).join(' ') + separator + para;
|
|
278
279
|
} else {
|
|
279
280
|
current += separator + para;
|
|
280
281
|
}
|
|
@@ -311,14 +312,14 @@ Milvus → Enterprise scale, GPU acceleration
|
|
|
311
312
|
|
|
312
313
|
```typescript
|
|
313
314
|
// Server-Sent Events for AI token streaming
|
|
314
|
-
app.get(
|
|
315
|
-
res.setHeader(
|
|
316
|
-
res.setHeader(
|
|
317
|
-
res.setHeader(
|
|
315
|
+
app.get('/api/chat', async (req, res) => {
|
|
316
|
+
res.setHeader('Content-Type', 'text/event-stream');
|
|
317
|
+
res.setHeader('Cache-Control', 'no-cache');
|
|
318
|
+
res.setHeader('Connection', 'keep-alive');
|
|
318
319
|
|
|
319
320
|
const stream = await openai.chat.completions.create({
|
|
320
|
-
model:
|
|
321
|
-
messages: [{ role:
|
|
321
|
+
model: 'gpt-4o-mini',
|
|
322
|
+
messages: [{ role: 'user', content: req.query.message as string }],
|
|
322
323
|
stream: true,
|
|
323
324
|
});
|
|
324
325
|
|
|
@@ -329,14 +330,14 @@ app.get("/api/chat", async (req, res) => {
|
|
|
329
330
|
}
|
|
330
331
|
}
|
|
331
332
|
|
|
332
|
-
res.write(
|
|
333
|
+
res.write('data: [DONE]\n\n');
|
|
333
334
|
res.end();
|
|
334
335
|
});
|
|
335
336
|
|
|
336
337
|
// Client-side consumption
|
|
337
338
|
const eventSource = new EventSource(`/api/chat?message=${encodeURIComponent(msg)}`);
|
|
338
|
-
eventSource.onmessage =
|
|
339
|
-
if (event.data ===
|
|
339
|
+
eventSource.onmessage = event => {
|
|
340
|
+
if (event.data === '[DONE]') {
|
|
340
341
|
eventSource.close();
|
|
341
342
|
return;
|
|
342
343
|
}
|