Initial commit: Agentforce Data-Aware Agent project with documentation and Salesforce metadata

Author: dentity007

.DS_Store

@@ -0,0 +1,39 @@
+name: PR Validate (Scratch Org)
+on:
+  pull_request: { branches: [ main, master ] }
+  workflow_dispatch:
+permissions: { contents: read }
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    env:
+      SCRATCH_ALIAS: ci-${{ github.run_id }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: npm install --global @salesforce/cli
+      - run: sf --version
+      - name: Write JWT key
+        run: echo "$SF_JWT_KEY" > server.key && chmod 600 server.key
+        env: { SF_JWT_KEY: ${{ secrets.SF_JWT_KEY }} }
+      - name: Authenticate Dev Hub (JWT)
+        env:
+          SF_CONSUMER_KEY: ${{ secrets.SF_CONSUMER_KEY }}
+          SF_USERNAME: ${{ secrets.SF_USERNAME }}
+        run: |
+          sf org login jwt --client-id "$SF_CONSUMER_KEY" --jwt-key-file server.key --username "$SF_USERNAME" --instance-url "https://login.salesforce.com" --alias devhub --set-default-dev-hub true
+      - name: Create Scratch Org
+        run: sf org create scratch --definition-file config/project-scratch-def.json --alias "$SCRATCH_ALIAS" --set-default --duration-days 1 --wait 10
+      - name: Push Source
+        run: sf project deploy start --target-org "$SCRATCH_ALIAS" --ignore-conflicts --wait 30
+      - name: Assign Permission Set
+        run: sf org assign permset --name GenAIAgentPermission --target-org "$SCRATCH_ALIAS" || echo "Permset skipped"
+      - name: Run Apex Tests (JUnit)
+        run: mkdir -p test-results && sf apex run test --target-org "$SCRATCH_ALIAS" --result-format junit --code-coverage --output-dir test-results --wait 30
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with: { name: apex-junit, path: test-results }
+      - if: always()
+        run: sf org delete scratch --target-org "$SCRATCH_ALIAS" --no-prompt

.github/workflows/pr-validate.yml

@@ -0,0 +1,22 @@
+# Agentforce Data‑Aware Agent (SFDX)
+
+**What**: A Salesforce DX template for Agentforce AI agents that auto‑discover org schema and act safely (FLS/sharing aware).
+
+## Quick Start
+```bash
+sf org login web --alias devhub --set-default-dev-hub
+sf org create scratch --definition-file config/project-scratch-def.json --alias agent-data-aware --set-default --duration-days 7 --wait 10
+sf project deploy start --ignore-conflicts --wait 30
+sf org assign permset --name GenAIAgentPermission
+sf apex run --file scripts/apex/run_bootstrap.apex
+sf org open
+```
+
+## CI Badge
+[![PR Validate (Scratch Org)](https://github.com/dentity007/Agentforce-Data-Aware-Agent/actions/workflows/pr-validate.yml/badge.svg)](https://github.com/dentity007/Agentforce-Data-Aware-Agent/actions/workflows/pr-validate.yml)
+
+## Documentation
+- [Team Playbook](docs/Team_Playbook.md)
+- [Quick Start 2‑Pager](docs/Quick_Start_2Pager.md)
+- [Solution Architecture](docs/Solution_Architecture.md)
+- Diagrams: `docs/diagrams/`

README.md

@@ -0,0 +1,4 @@
+{
+  "orgName": "Agentforce Data Aware",
+  "edition": "Developer"
+}

config/project-scratch-def.json

@@ -0,0 +1,27 @@
+# Agentforce Data‑Aware Agent — Quick Start (Exec & PM 2‑Pager)
+
+**Why**: Faster ops, no manual field mapping, governed (FLS, deny‑list), auditable.  
+**Pilot metric ideas**: +30% triage speed, +15% timely follow‑ups, <1% permission violations.
+
+## Scope (4–6 weeks)
+- Use case: Lead qualification & follow‑up
+- Surfaces: Lightning / Slack (optional)
+- Data: Lead (+ related minimal fields), PII deny‑listed
+
+## RACI (pilot)
+Sponsor (A), PM (A), Admin (R), Dev (R), Security (C), Sales Ops (C).
+
+## Environments
+Dev Hub + Scratch (CI on PRs) → UAT Sandbox → Production
+
+## Checklist
+Week 0: GitHub secrets; deny‑list review.  
+Week 1: Scratch, deploy, bootstrap, smoke test.  
+Week 2–3: Tune prompts/actions; iterate.  
+Week 4: UAT metrics; approve; Prod.
+
+## How it works (plain English)
+Planner finds objects/fields/paths from a cached schema graph, then calls safe queries/Flows/Apex under user permissions. Only a small schema slice is sent with prompts; sensitive fields are blocked.
+
+## Governance & risk
+FLS enforcement; RestrictedField__mdt; audit stubs; rollback via PRs/tags.

docs/Agentforce_Solution_Architecture_Deck.pptx

@@ -0,0 +1,25 @@
+# Agentforce Data‑Aware Agent — Solution Architecture
+
+## Context & Data Flow
+User → Agent (Bot) → Planner → (FindObjects/FindFields/FindRelationshipPath) → ExecuteSOQL/RunFlow/Domain Actions → Salesforce Data → Response (+ audit)
+
+## Logical View
+- Agent Layer: Bot/BotVersion, Planner, Prompt
+- Intelligence: MetadataNavigatorTopic, SchemaGraph__c
+- Execution: GenAiFunctions (ExecuteSOQL/RunFlow/QueryDataCloud + domain actions), Apex services, Flows
+- Governance: RestrictedField__mdt, GenAiAudit, NightlyJob
+
+## Deployment
+Dev Hub + Scratch (PR validation) → UAT → Prod. Steps: deploy, assign permset, bootstrap graph, schedule nightly job.
+
+## Security
+Runs as the signed‑in user; FLS.enforce; deny‑list; prompt slicing; audit stubs.
+
+## NFRs
+Query P50<2s/P95<5s, ≤200 rows, ≤12 fields, ≤2 joins; prompt slice ≤3KB typical.
+
+## RACI (Build/Operate/Govern)
+Dev (R), Admin (R/A), PM (A), Security (A/R for policy), Sales Ops (C).
+
+## Sequences
+Happy path (status+task) and FLS‑denial path (sensitive field removed).

docs/Quick_Start_2Pager.md

@@ -0,0 +1,38 @@
+# Agentforce Data‑Aware Agent — Team Playbook
+
+This playbook explains how to set up, deploy, operate, and extend the Agentforce data‑aware agent template.
+
+## What you get
+- Auto‑discovery of org schema (objects/fields/relationships) with FLS/sharing awareness
+- SchemaGraph__c cache for fast lookups
+- Planner + Plugin + Functions so agents can find/use data without manual mapping
+- Guardrails: FLS enforcement, RestrictedField__mdt deny‑list, audit stubs
+- Lead Qualification demo (Flow + Apex invocable)
+- Unit tests and a GitHub Actions PR validation pipeline
+
+## Prereqs
+- Dev Hub with Scratch Orgs enabled, Salesforce CLI, GitHub repo, Connected App for JWT
+
+## Create scratch & push
+```bash
+sf org login web --alias devhub --set-default-dev-hub
+sf org create scratch --definition-file config/project-scratch-def.json --alias agent-data-aware --set-default --duration-days 7 --wait 10
+sf project deploy start --ignore-conflicts --wait 30
+sf org assign permset --name GenAIAgentPermission
+sf apex run --file scripts/apex/run_bootstrap.apex
+sf org open
+```
+
+## Lead Qualification demo
+Ask the bot: “Qualify this lead and follow up: 00Qxxxxxxxxxxxx; set status to Working”. Planner → FindFields → ExecuteSOQL → Flow (status) → Apex (task).
+
+## CI (PRs)
+JWT login → create scratch → deploy → run tests (JUnit) → upload results → delete org. Secrets: SF_CONSUMER_KEY, SF_USERNAME, SF_JWT_KEY.
+
+## Operating
+- Nightly schema refresh: OrgSchemaNightlyJob.scheduleNightly()
+- On‑demand rebuild: OrgSchemaBootstrap.buildSchemaGraph()
+- Add sensitive fields to RestrictedField__mdt; re‑run bootstrap
+
+## Extending
+- Add new GenAiFunction (Apex/Flow), list in Planner `<actions>`, add tests, open PR.