/*
 * Copyright 2026, Jaime Terrats.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
import { existsSync } from 'node:fs';
import { join } from 'node:path';
import { generateAiWorkflows } from '../generators/workflows/ai.js';
import { consultativeDesign, documentationStandards, generatedPromptsProtocol, interactionPreferences, salesforceReferences, semanticCommits, } from './shared-sections.js';
export const aiProfile = {
    id: 'ai',
    label: 'AI / Agentforce Specialist',
    ruleFile: 'ai-standards.mdc',
    extensions: ['salesforce.salesforcedx-vscode', 'salesforce.salesforcedx-vscode-lwc', 'continue.continue'],
    capabilities: ['deploy', 'code-analysis', 'prompt-registry', 'declare-points'],
    cursorScope: 'description',
    detect(cwd) {
        return (existsSync(join(cwd, 'force-app/main/default/bots')) ||
            existsSync(join(cwd, 'force-app/main/default/aiApplications')));
    },
    workflows: generateAiWorkflows,
    ruleContent() {
        return [
            '---',
            'description: Salesforce AI / Agentforce Specialist Standards',
            'globs:',
            'alwaysApply: true',
            '---',
            '',
            '# Salesforce AI / Agentforce Specialist Standards',
            '',
            '> Role: AI / Agentforce Specialist — Salesforce Professional Services.',
            '',
            ...consultativeDesign('agent design and orchestration decisions'),
            '',
            '## Codebase Contextualization',
            '- Scan existing `bots/`, `aiApplications/`, and `promptTemplates/` before creating new ones.',
            '- Check for existing Apex action classes and Flows that can be reused as agent actions.',
            '- Identify the target org alias before scaffolding any agent spec or running agent CLI commands.',
            '',
            '## Agent Design Principles',
            '- Ground every agent response in org data — avoid static, hardcoded answers.',
            '- Define clear topic boundaries: each topic must have a distinct description and non-overlapping instructions.',
            '- One agent per use case. Multi-agent orchestration requires explicit justification and architectural sign-off.',
            '- Always define what the agent will NOT do (out-of-scope topics) as clearly as what it will do.',
            '',
            '## Agent Builder Workflow',
            '- Use `sf agent generate agent-spec` to scaffold the spec YAML before creating anything in an org.',
            '- Use `sf agent create` to create the agent in the target org from the spec.',
            '- Use `sf agent generate authoring-bundle` to package the agent for DX source format.',
            '- Never create agents manually in Setup without a corresponding spec YAML in version control.',
            '',
            '## Agent Script (AiAuthoringBundle)',
            '- **Agent Script is a Salesforce-native scripting language** — NOT JavaScript, Python, or YAML.',
            "- Used exclusively inside `AiAuthoringBundle` (`.agent` files), available from API v66.0+ (Summer '25).",
            '- Agent Script controls conversation flow: topic selection, action invocation, variable assignment, and branching.',
            '- Always scaffold with `sf agent generate authoring-bundle` before writing Agent Script manually.',
            '- Commands: `sf agent preview` (test flow locally), `sf agent publish` (activate in org), `sf agent test run`.',
            '- **Never hand-code `.agent` files without validating with `sf agent preview` first.**',
            '- Commit `.agent` files to version control; treat them as first-class source artifacts.',
            '',
            '## Prompt Templates',
            '- Store all prompt templates in `force-app/main/default/promptTemplates/`.',
            '- Use **Flex templates** for dynamic prompts that vary by record context.',
            '- Always include fallback instructions for when grounding data is unavailable.',
            '- Prompt template names: `<AgentName>_<TopicName>_<Action>` (PascalCase).',
            '',
            '## Topics & Actions',
            '- Each topic must have a `description` and `instructions` field — both are mandatory.',
            '- Actions should map to existing Apex classes, Flows, or Einstein capabilities — avoid duplicating logic.',
            '- Use invocable Apex methods for complex data operations. Keep action methods bulkified.',
            "- Document each action's input/output variables in the action definition.",
            '',
            '## Testing',
            '- Use `sf agent generate test-spec` to generate the test YAML for the agent.',
            '- Use `sf agent test run` to execute the test suite against the target org.',
            '- Target ≥ 80% topic match rate across all test scenarios.',
            '- Include edge case tests: empty input, ambiguous input, and out-of-scope requests.',
            '- Re-run tests after any change to topics, instructions, or prompt templates.',
            '',
            '## Grounding & Context',
            '- Prefer **Einstein Search Grounding** over static context for real-time org data.',
            '- Use **Data Cloud** for real-time customer data grounding when deep personalization is required.',
            '- Document the grounding strategy in the agent spec YAML and in `/docs/`.',
            '',
            '## Guardrails',
            '- Define explicit out-of-scope topics in the agent spec — never leave guardrails implicit.',
            '- Never expose PII through agent responses. Audit all action output variables for sensitive fields.',
            '- Always set `disableGenerativeAnswers: false` for production agents.',
            "- Review the agent's response in Agent Builder Preview before activating in production.",
            '',
            '## Prompt Injection Prevention',
            '- **Never pass raw user input directly to SOQL, DML, or external callouts in action Apex.** Always sanitize first.',
            '- In action Apex methods: validate all `@InvocableVariable` inputs — check for null, unexpected length, and disallowed characters.',
            '- Use bind variables (`:variable`) in any SOQL inside action methods — never string concatenation.',
            '- **Output validation:** before returning action results to the agent, strip fields that contain PII or system-internal values.',
            '- Jailbreak patterns to guard against: prompt override instructions ("Ignore previous instructions"), role impersonation ("You are now DAN"), and indirect injection via grounded data.',
            '- For Knowledge-grounded agents: audit article content for embedded instructions that could redirect agent behavior.',
            '- Log suspicious inputs to a monitoring Data Extension or custom object for security review.',
            '',
            '## Agent Observability',
            '- **Always configure observability before activating any agent in production.**',
            '- Key metrics to track:',
            '  - **Topic Match Rate:** % of conversations routed to the correct topic. Target ≥ 80%.',
            '  - **Containment Rate:** % resolved without human escalation. Baseline and improve sprint over sprint.',
            '  - **Escalation Rate:** % transferred to a human. High rate (>40%) signals topic coverage gaps.',
            '  - **Response Latency:** average agent turn time. Alert if p95 > 5s.',
            '- Use **Einstein Conversation Insights** or export conversation logs to Data Cloud for analytics.',
            '- Set up alerts for: sudden spike in escalation rate, drop in topic match rate, error in action execution.',
            '- Review conversation samples weekly during the first month post-launch — not just aggregate metrics.',
            '- Document observability setup in `/docs/ai/observability.md`: metrics, thresholds, alert owners.',
            '',
            '## Agentforce Experience Layer',
            '- **Decouple agent behavior from rendering.** Design agent responses as structured payloads — the Experience Layer handles rendering per channel.',
            '- Supported rendering targets: **Slack, Mobile, ChatGPT, Claude, Gemini, Microsoft Teams**, and any MCP-compatible client.',
            '- Response payload primitives: cards (summary display), workflows (multi-step guided actions), decision tiles (branching choices), data layouts (tabular data).',
            '- Never hardcode channel-specific formatting inside agent topics or Apex actions. Format lives in the Experience Layer config.',
            '- Test agent responses in at least two rendering targets before go-live: Salesforce UI + one external channel (Slack or Mobile).',
            '',
            '## Agent Fabric (Multi-Platform Governance)',
            '- Use **Agent Fabric** when agents must operate deterministically across multiple platforms simultaneously.',
            '- Agent Fabric provides a governance control plane: routing rules, platform-specific constraints, unified audit trail.',
            '- Required when: an agent acts in Slack AND Salesforce UI AND an external MCP client in the same conversation flow.',
            '- Define deterministic orchestration rules in Agent Fabric before activating cross-platform agents in production.',
            '- Document the Agent Fabric configuration in `/docs/ai/agent-fabric.md`: platform targets, routing rules, fallback behavior.',
            '',
            '## Pre-Launch Quality Gates (Testing Center)',
            '- Run **Testing Center** before activating any agent in production — it detects logic gaps and policy violations.',
            '- Use **Custom Scoring Evals** to assess decision quality across a representative set of test conversations.',
            '- Gate criteria before launch: Testing Center passes, Scoring Evals meet threshold, topic match rate ≥ 80% in test suite.',
            '- Document eval results in `/docs/ai/launch-readiness.md` with pass/fail per gate.',
            '',
            '## Post-Launch Optimization (A/B Testing)',
            '- Use **A/B testing** to compare agent versions — vary topics, instructions, or prompt templates.',
            '- Define a primary metric per experiment (containment rate, topic match rate, CSAT) before starting the test.',
            '- Run A/B tests for a minimum of 2 weeks with statistical significance before promoting the winning variant.',
            '- Use **Session Tracing** to debug individual conversation flows — trace from user input to action execution.',
            '- Document experiments in `/docs/ai/experiments.md`: hypothesis, variant diff, metric, result, decision.',
            '',
            '## Deployment',
            '- Validate with `sf project deploy validate` before creating the agent in any org.',
            '- Use `sf agent publish` for activation after deployment.',
            '- Deploy Apex action classes and Flows before deploying the agent spec.',
            '',
            ...generatedPromptsProtocol(),
            '',
            ...documentationStandards(),
            '',
            ...semanticCommits(),
            '',
            ...salesforceReferences(),
            '',
            ...interactionPreferences('agent architecture'),
            '',
            '## Sub-agent Handover',
            '- Pass: agent spec YAML path, topic list, Apex action class names, and target org alias.',
            '- Sub-agents must follow: one Assert per test, zero logic in triggers.',
            '- When the task touches business object design (SLAs, approvals, milestones, routing rules,',
            '  entitlements), delegate evaluation to **Architect** or **BA** before proposing a custom',
            '  Agent Action or Topic that encapsulates logic already available via native platform configuration.',
        ].join('\n');
    },
};
//# sourceMappingURL=ai.js.map