🔄 POC Loop Engineering

Autonomous Closed-Loop Multi-Agent Software Delivery Pipeline for Salesforce

📖 Table of Contents

Overview
Key Features
System Architecture
The Multi-Agent Ecosystem
Persistent Living Memory
Interactive Slack & JIRA Features
Microsoft Teams Observability & Cards
Project Directory Structure
Prerequisites
Installation & Setup
Configuration Reference
Usage & Operational Modes
Testing & Verification
Contributing & Compliance
License

🎯 Overview

POC Loop Engineering establishes an autonomous, production-grade closed-loop software engineering lifecycle for Salesforce development. Rather than treating AI code generation as an isolated, single-prompt exercise, this system continuously drives work from JIRA ticket ingestion to Salesforce CLI deployment, automated GitHub PR review, and iterative QA bug validation, closing the loop by transitioning issues to Done when merged.

The Core Problem Solved

Traditional AI coding assistants lack state across days, cannot resolve ambiguous requirements interactively, do not validate changes directly against real Salesforce scratch/sandbox orgs, and require manual human review for every intermediate step.

POC Loop Engineering solves this with:

Event-Driven Automation: Reacts to JIRA and GitHub webhook transitions in real time.
Multi-Agent Specialization: Four distinct agent roles (Planner, Builder, Reviewer, Tester).
Git-Tracked Living Memory: Retains architectural decisions, schemas, and change histories across long-running projects.
Human-In-The-Loop (HITL) Clarification: Pauses on ambiguities, solicits Slack answers, and resumes deterministically.
Automated Gatekeepers & Self-Healing Loops: PR Review and QA validation enforce quality gates with automated bug-fix cycles.

✨ Key Features

⚡ End-to-End Autonomous Pipeline: Full lifecycle execution from To Do ➔ In Progress ➔ In Review ➔ Done.
🤖 Specialized Multi-Agent Roles:
- Agent 1 (Planner): Requirement parsing, schema inspection, and implementation planning.
- Agent 2 (Builder): Salesforce metadata generation, org deployment, git branch management, and PR creation.
- Agent 4 (PR Reviewer): GitHub PR diff audit against JIRA acceptance criteria with automated approval badges.
- Agent 3 (QA Tester): Salesforce org validation, test execution, defect detection, and bug-fix loop.
💬 Real-Time Slack Thread Notifications:
- Phase-by-phase updates (Started / Completed / Failed).
- Dynamic [JIRA] and [GitHub] redirect action buttons on cards.
- Interactive two-way HITL clarification via Slack Socket Mode.
🧠 Persistent Living Memory: Stored inside Git (agent-context/), eliminating context degradation across sprints.
🛡️ Quality Gate & Defect Loop: Unapproved PRs are strictly blocked from advancing; QA failures cycle tickets back to In Progress for Builder resolution until all tests pass.
🚀 Automated PR Merge Handling: Merging the feature PR to main automatically finalizes the linked JIRA issue to Done.
📢 Microsoft Teams Enterprise Channel Observability: Parallel real-time notifications dispatched to Microsoft Teams with branded HTML/Adaptive Cards, color-coded phase banners, direct JIRA & GitHub action buttons, and structured "Context & Execution Summary" cards delivered via Channel Email / Webhook with zero M365 admin friction.

🏛️ System Architecture

flowchart TD
    subgraph JIRA ["JIRA Cloud"]
        JT["Ticket Transition: 'In Progress'"]
    end

    subgraph Ingress ["Ingress Layer"]
        CF["Cloudflare Tunnel / Webhook Listener"]
    end

    subgraph Orchestration ["Orchestrator Engine (orchestrator.js)"]
        Lock["Task Lock & Debounce Cache"]
        SlackEngine["Slack Bolt Socket Mode"]
    end

    subgraph Agents ["Autonomous Multi-Agent Loop"]
        A1["Agent 1: Planner (plan.md)"]
        A2["Agent 2: Builder (force-app/ & PR)"]
        A4["Agent 4: PR Reviewer (PR Diff Audit)"]
        A3["Agent 3: QA Tester (Org Validation)"]
    end

    subgraph Platforms ["Target Systems"]
        SF["Salesforce Target Org (time-sheet)"]
        GH["GitHub Repository & Pull Requests"]
        Mem["Living Memory (agent-context/)"]
    end

    JT --> CF --> Ingress --> Lock
    Lock --> A1
    A1 -.->|"Ambiguity (NEEDS_INPUT)"| SlackEngine
    SlackEngine -.->|"Developer Answer"| A1
    A1 --> A2
    A2 --> SF
    A2 --> Mem
    A2 --> GH
    GH --> A4
    A4 -- "Changes Requested" --> A2
    A4 -- "Approved" --> A3
    A3 -- "Defect Found" --> A2
    A3 -- "Passed" --> GH
    GH -- "PR Merged" --> Orchestration
    Orchestration -->|"Transition to 'Done'"| JT

👥 The Multi-Agent Ecosystem

Agent	Name	Primary Responsibility	Input Context	Output Artifacts
Agent 1	Planner	Analyze requirements, check org schema, create plan	JIRA summary & ADF description, `MEMORY.md`, `PROJECT.md`	`agent-context/tickets/<KEY>/plan.md`
Agent 2	Builder	Create SFDX metadata, deploy to org, open PR	`plan.md`, `INSTRUCTIONS.md`, target org connection	`force-app/...`, GitHub PR, `MEMORY.md`, `CHANGELOG.md`
Agent 4	PR Reviewer	Audit PR diff against acceptance criteria & standards	GitHub PR diff, JIRA acceptance criteria, metadata XML	GitHub PR review badge, `pr-review.md`
Agent 3	QA Tester	Validate deployment, verify schema/logic, manage bug loop	Deployed org schema, `plan.md`, test cases	`test-report.md`, JIRA transitions (`Done` / `In Progress`)

🧠 Persistent Living Memory

All architectural decisions and cumulative system changes are tracked inside the repository under agent-context/:

agent-context/
├── PROJECT.md          # Static: Architecture, target org details, and coding standards
├── INSTRUCTIONS.md     # Static: Standing operational guidelines for all agents
├── MEMORY.md           # LIVING: Distilled inventory of deployed objects, fields, and automation
├── CHANGELOG.md        # Append-only: Ledger recording ticket, date, summary, files, and PR link
└── tickets/
    └── <TICKET-KEY>/   # Ticket-specific artifacts (plan.md, pr-review.md, test-report.md)

Before Planning: Agent 1 reads MEMORY.md first to build on previous tickets without redundant re-discovery.
After Implementation: Agent 2 updates MEMORY.md and appends an entry to CHANGELOG.md.

💬 Interactive Slack & JIRA Features

1. Phase-by-Phase Progress Tracking

Slack receives real-time progress cards for each milestone:

Phase 1: Planning & Schema Analysis
Phase 2 & 4: Implementation & Salesforce Deployment
Phase 5: Automated PR Review & Quality Gate
Phase 6: JIRA Finalization (In Review)
Phase 7: QA Testing & Org Validation

2. Direct Navigation Buttons

Every Slack card features dynamic action buttons:

[JIRA] ➔ Opens the specific ticket in Atlassian JIRA.
[GitHub] ➔ Opens the corresponding Pull Request.

3. Human-In-The-Loop (HITL) Q&A

When an agent outputs NEEDS_INPUT: <question>, the orchestrator pauses, notifies the Slack thread, waits for a human reply, and seamlessly resumes the agent with the provided answer.

4. Interactive AI Review & One-Click Auto-Fix

[ 🤖 Run AI Review ]: Immediately reviews the PR diff with Gemini, scoring quality (0-10) and identifying vulnerabilities.
[ 🛠️ Apply AI Fixes ]: One-click autonomous self-healing. Commands Agent 2 (Builder) to apply Gemini's suggested fixes, redeploy to time-sheet org, commit, push, and re-review.

5. Slash Commands & Channel Triggers

Developers can review any Pull Request on-demand directly from Slack:

Slash Commands: /review <PR# | Ticket Key> or /code-review 7
Channel Messages: Type !review 7, /review 7, or @bot review 7 in any channel
Thread Replies: Reply review PR 7 or apply fixes in any active delivery thread.

📢 Microsoft Teams Observability & Cards

The pipeline includes an enterprise-grade Microsoft Teams observability engine (src/teams.js) that runs alongside Slack via non-blocking dual-dispatch:

1. Key Card Capabilities:

Status Badges & Accent Banners: Visually identifies execution state (⏳ Started, 🔄 In Progress, ✅ Completed, 🔍 In Review, ❌ Failed).
One-Click Action Buttons: Direct deep-link buttons pointing to the active [🎯 JIRA Ticket] and [🐙 GitHub PR].
📋 Detailed Context & Execution Summary: Parses complex agent activity into an organized card section featuring:
- Bulleted key-value metrics (• Ticket:, • Scope:, • Acceptance Criteria:, • Components Identified:).
- Inline monospace tags for Salesforce metadata files (TimesheetValidator.cls, force-app/...).
- Target org context indicator (time-sheet).

2. Dual Delivery Mechanisms (Zero Tenant-Admin Friction):

Enterprise Microsoft 365 tenants frequently block unauthenticated Power Automate webhooks or restrict two-way Azure bot sideloading. To eliminate administrative hurdles, this integration supports two modes:

Option A: Teams Channel Email via Secure SMTP (Default & Enterprise-Friendly):
- Directly routes rich HTML cards to the channel email address (e.g. channel@in.teams.ms) via standard SMTP (nodemailer + Gmail/SendGrid/SES).
- Requires zero M365 tenant-admin privileges or Azure App registrations.
Option B: Adaptive Cards 1.4 via Webhook:
- Dispatches native Adaptive Card 1.4 payloads to Power Automate / Workflows HTTP triggers when TEAMS_WEBHOOK_URL is provided.

3. Testing Teams Integration:

# Verify Teams detection, card compilation, and live delivery
npm run test:teams

📂 Project Directory Structure

poc-loop-engineering/
├── .github/                  # GitHub Actions CI/CD workflows
│   └── workflows/
│       └── pr-review.yml     # Automated PR Review Agent on pull_request events
├── .env.example              # Environment variables template
├── .gitignore                # Git ignore configuration
├── CONTRIBUTING.md           # Contribution guidelines & coding conventions
├── LICENSE                   # MIT License
├── README.md                 # Master project documentation
├── package.json              # Node.js project manifest & scripts
├── sfdx-project.json         # Salesforce SFDX project configuration
├── orchestrator.js           # Main Express server, webhooks & agent orchestration
│
├── agent-context/            # Persistent Living Memory system
│   ├── PROJECT.md            # Project overview & architectural guidelines
│   ├── INSTRUCTIONS.md       # Agent operational rules & protocols
│   ├── MEMORY.md             # Living state of deployed Salesforce metadata
│   ├── CHANGELOG.md          # Chronological ledger of completed tickets
│   └── tickets/              # Ticket-specific plans, reviews, and test reports
│
├── docs/                     # Detailed architectural & operational guides
│   ├── ARCHITECTURE_ANALYSIS.md  # Comprehensive technical analysis report
│   ├── POC_HANDOFF.md            # Initial loop engineering POC handoff spec
│   └── WORKFLOW_GUIDE.md         # Operational workflow & sequence documentation
│
├── force-app/                # Salesforce SFDX source tree
│   └── main/default/
│       ├── objects/          # Custom fields & validation rules (Account, Contact, Opportunity)
│       └── flows/            # Record-triggered flows & automation
│
├── scripts/                  # Operational & diagnostic utilities
│   ├── run-pr-review.js      # PR Review Agent runner (Local CLI & GitHub Actions)
│   ├── test-connections.js   # Verify JIRA, Slack & Teams connectivity
│   ├── test-teams-webhook.js # Verify Microsoft Teams Webhook / Channel Email delivery
│   └── deliver-scrum6.js     # Standalone ticket delivery execution script
│
└── src/                      # Orchestrator modules & integration services
    ├── agentRunner.js        # Antigravity CLI process execution & output parser
    ├── aiCodeReviewer.js     # Gemini 3.6 Flash code review engine (diff, security, limits)
    ├── githubPrClient.js     # GitHub PR client (diff fetcher, file filter, review submitter)
    ├── jira.js               # Atlassian JIRA REST API client & ADF parser
    ├── prReviewer.js         # Legacy PR review runner & switch evaluator
    ├── prompts.js            # Prompt templates for Agents 1, 2, 3, and 4
    ├── slack.js              # Slack Bolt app, Socket Mode, interactive cards & thread manager
    ├── statusResponder.js    # Thread query responder for live Slack status questions
    ├── switchManager.js      # Central state switch manager for GitHub Actions & local agents
    └── teams.js              # Microsoft Teams notification engine (Adaptive Cards & Channel Email)

⚙️ Prerequisites

Ensure the following tools are installed and configured on your host system:

Node.js: v18.0.0 or higher
Salesforce CLI (sf): Authenticated with target org (default: time-sheet)
```
sf org display --target-org time-sheet
```
GitHub CLI (gh): Authenticated with the nandini-teqfocus account
```
gh auth status
```
Antigravity CLI (agy): Configured and accessible in your system PATH
Cloudflare Tunnel (cloudflared): (Optional for local webhook exposure)

🚀 Installation & Setup

1. Clone the Repository

git clone https://github.com/nandini-teqfocus/poc-loop-engineering.git
cd poc-loop-engineering

2. Configure Git Identity

Important

Always verify that your repository commits use the authorized nandini-teqfocus account:

git config user.name "nandini-teqfocus"
git config user.email "nandini.singh@teqfocus.com"

3. Install Dependencies

npm install

4. Configure Environment Variables

Copy the template and fill in your credentials:

cp .env.example .env

5. Verify Connections

Run the connection test script to confirm connectivity to JIRA and Slack:

npm run test:connections

🔧 Configuration Reference

Variable	Description	Required	Example
`PORT`	Local server listening port	No	`3000`
`SLACK_APP_TOKEN`	Slack App-level token (`connections:write`)	Yes	`xapp-1-...`
`SLACK_BOT_TOKEN`	Slack Bot User OAuth token (`chat:write`, etc.)	Yes	`xoxb-...`
`SLACK_SIGNING_SECRET`	Slack app signing secret	Yes	`3e9984fcaba0...`
`SLACK_SOCKET_MODE`	Enable Bolt Socket Mode	Yes	`true`
`SLACK_CHANNEL_ID`	Slack channel for progress updates	Yes	`C0C03V63H16`
`TEAMS_WEBHOOK_URL`	Microsoft Teams incoming webhook / Workflow URL	No (Optional)	`https://prod-xx.westus.logic.azure.com/...`
`TEAMS_CHANNEL_EMAIL`	Microsoft Teams channel email address (Zero-admin mode)	No (Optional)	`channel@in.teams.ms`
`SMTP_HOST`	SMTP server host for Teams channel email dispatch	No (Required if using Teams email)	`smtp.gmail.com`
`SMTP_PORT`	SMTP server port (465 SSL or 587 TLS)	No (defaults to 465)	`465`
`SMTP_USER`	SMTP username / sender email	No (Required if using SMTP)	`developer@gmail.com`
`SMTP_PASS`	SMTP application password	No (Required if using SMTP)	`xxxx xxxx xxxx xxxx`
`RESEND_API_KEY`	Resend API key for fallback email dispatch	No (Optional)	`re_123456...`
`JIRA_BASE_URL`	JIRA Cloud instance URL	Yes	`https://yourdomain.atlassian.net`
`JIRA_USER_EMAIL`	JIRA user email address	Yes	`developer@domain.com`
`JIRA_API_TOKEN`	JIRA Cloud REST API token	Yes	`ATATT3...`
`ENABLE_PR_REVIEW_AGENT`	Master switch to enable/disable PR Review Agent	No (defaults to `true`)	`true` or `false`
`GEMINI_API_KEY`	Google Gemini API Key for AI Code Review Agent	Yes (for AI Review)	`AIzaSy...`
`GEMINI_MODEL`	Gemini model to use for code review	No (defaults to `gemini-2.5-flash`)	`gemini-2.5-flash`

🤖 Gemini AI Code Review Agent (Google Gen AI SDK)

The repository features a dedicated, zero-Jira AI PR Code Review Agent powered by the Google Gen AI SDK (@google/genai) and Gemini 2.5 Flash:

Key Highlights:

Strictly Code-Focused: Ignores Jira tickets, user stories, acceptance criteria, and business feasibility. Focuses 100% on Code Quality, Bugs, Security, Performance, and Maintainability.
Review Scope: Evaluates only changed lines & files in the PR diff, filtering out non-code assets (lockfiles, documentation, build outputs).
Dual-Tier PR Delivery:
1. Top-Level Review Summary: Posts an executive summary with score (1-10), verdict badge (APPROVED, CHANGES_REQUESTED, COMMENT), security advisories, and code highlights.
2. Line-by-Line Inline Comments: Attaches actionable comments directly to specific diff lines, including GitHub Markdown suggested code fixes (suggestion ... ).
Workflow Automation: Runs in GitHub Actions (.github/workflows/pr-code-review.yml) on PR events (opened, synchronize, reopened), or on demand via workflow_dispatch.

Running Locally:

# Run local test suite against sample Apex code
npm run test:ai-review

# Run against a specific GitHub Pull Request
node scripts/run-ai-code-review.js --pr 6

Triggering Directly from Slack:

Interactive Button: Click the [ 🤖 Run AI Review ] button attached to any Slack card with a PR link.
Natural Language in Thread: Mention or type in any ticket thread:
- review PR 6
- run AI review
- review code The bot will run the Gemini review, post findings back to the Slack thread, and submit review comments on GitHub.

🤖 GitHub Actions PR Agent & Configurable Switch

To optimize model token usage and decouple PR review from the long-running local process, the PR Review Agent can run directly in GitHub Actions while also preserving the existing local orchestrator workflow.

1. GitHub Actions Workflow (`.github/workflows/pr-review.yml`)

Triggers: Automatically runs whenever a pull request is opened, synchronize (updated with new commits), reopened, or marked ready_for_review. Can also be manually dispatched via workflow_dispatch.
Functionality:
- Audits PR diff against JIRA acceptance criteria and Salesforce metadata standards (force-app/main/default/).
- Verifies custom field naming conventions (__c), XML structure, and Living Memory records (agent-context/CHANGELOG.md).
- Submits PR approval or change request badges directly on the GitHub PR.
- Automatically posts real-time review verdict cards into the corresponding Slack thread.
- Generates rich GitHub Actions Step Summaries for pull request reviewers.

2. Dual-Engine Switch & Interactive Buttons

The pipeline supports dynamic toggling between GitHub Actions Mode and Local Agent Mode with live synchronization across GitHub, the orchestrator, and Slack:

Switch State	GitHub Action (`pr-review.yml`)	Local Orchestrator (Phase 5)	Best For
`🚀 GitHub Actions (Active)`	ENABLED on GitHub. Runs PR code audits automatically on PR events.	Bypassed / Delegated. Phase 5 acknowledges cloud CI/CD execution and proceeds.	Standard development, saving local tokens, parallel CI review.
`💻 Local Agent (Active)`	DISABLED on GitHub (`gh workflow disable`). Will not run in CI/CD.	ACTIVE. Local Agent 4 executes multi-iteration review, commits fixes, and approves PR.	Offline development, local prompt debugging, or self-contained runs.

Ways to Toggle the Switch:

Interactive Web Dashboard Button (Recommended) Open http://localhost:3000 (or your Cloudflare tunnel URL) in your browser:
- Features a live glowing status badge and an interactive toggle button.
- Instantly enables/disables the GitHub workflow via the GitHub API.
- Includes a "💬 Send Switch Button to Slack" button to share the controller with the team.
Interactive Slack Button
- Click the [ 💻 Switch to Local Agent ] or [ 🚀 Switch to GitHub Actions ] button directly in any Slack notification card.
- Or type switch, toggle, or pr mode in Slack to have the bot drop the interactive control card into the channel.

Terminal CLI Command

# Toggle between modes
node scripts/toggle-switch.js

# Force specific mode
node scripts/toggle-switch.js --on     # Enable GitHub Actions (Active)
node scripts/toggle-switch.js --off    # Enable Local Agent (Active)
node scripts/toggle-switch.js --status # View current active engine

💻 Usage & Operational Modes

Mode 1: Automated Webhook Ingress (Production Mode)

Start the Cloudflare tunnel:

cloudflared tunnel --url http://localhost:3000

Configure your JIRA Webhook to target:

https://<your-tunnel>.trycloudflare.com/webhook/jira

Start the orchestrator:
```
npm start
```
Move any ticket in JIRA from To Do ➔ In Progress. The entire multi-agent loop executes autonomously.

Mode 2: Direct CLI Execution (Developer Mode)

Execute specific phases or complete workflows directly from the command line:

# Run complete end-to-end loop for a ticket
node orchestrator.js --ticket SCRUM-10

# Run only the PR Review Agent (Agent 4)
node orchestrator.js --review SCRUM-10

# Run only the QA Tester Workflow (Agent 3)
node orchestrator.js --tester SCRUM-10

# Simulate PR Merge finalization (moves ticket to Done)
node orchestrator.js --merge SCRUM-10

Mode 3: Manual HTTP Triggers (Testing & Integration Mode)

The orchestrator exposes convenient REST endpoints for testing:

# Trigger full delivery loop
curl -X POST http://localhost:3000/trigger/SCRUM-10

# Trigger standalone PR review
curl -X POST http://localhost:3000/trigger-review/SCRUM-10

# Trigger standalone QA testing
curl -X POST http://localhost:3000/trigger-tester/SCRUM-10

# Trigger PR merge handler
curl -X POST http://localhost:3000/trigger-merge/SCRUM-10

Mode 4: Standalone & GitHub Actions PR Review (CI/CD Mode)

Execute the PR Review Agent on-demand for any Pull Request without triggering the full loop:

# Run PR review on a specific PR number
node scripts/run-pr-review.js --pr 6

# Run PR review on a specific JIRA ticket
node scripts/run-pr-review.js --ticket SCRUM-10

# Test switch OFF behavior locally
ENABLE_PR_REVIEW_AGENT=false node scripts/run-pr-review.js --pr 6

In GitHub Actions, the workflow triggers automatically upon opening or updating a Pull Request.

🧪 Testing & Verification

Validated End-to-End Delivery Scenarios

The pipeline has been thoroughly verified across multiple live Salesforce development tasks:

SCRUM-6: Emergency & medical custom fields on Contact with Slack HITL blood group clarification.
SCRUM-8: Insurance tracking custom fields on Opportunity with automated deployment.
SCRUM-9: Custom fields on Contact with Agent 4 PR review verification.
SCRUM-10: Service tier picklist & onboarding date on Account with full end-to-end multi-agent execution.

Verifying Salesforce Org State

To inspect deployed metadata directly in the target org:

sf sobject describe --sobject Account --target-org time-sheet
sf sobject describe --sobject Contact --target-org time-sheet

Verifying Multi-Channel Notifications (Slack & Teams)

To test connectivity and card rendering across both communication channels:

# Test Slack & JIRA connections
npm run test:connections

# Test Microsoft Teams Webhook & Adaptive Card generation
npm run test:teams

🤝 Contributing & Compliance

We welcome contributions! Please review CONTRIBUTING.md for branch naming, commit standards, and coding conventions.

Mandatory GitHub Account: All operations touching the time-sheet org must be performed under the nandini-teqfocus GitHub account.
Quality Standards: All metadata additions must include PascalCase naming, user-facing descriptions/help text, and target org dry-run deployment verification.

📄 License

This project is licensed under the MIT License.

Name		Name	Last commit message	Last commit date
.claude/skills		.claude/skills
.github/workflows		.github/workflows
agent-context		agent-context
docs		docs
force-app/main/default/objects		force-app/main/default/objects
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
GEMINI.md		GEMINI.md
GEMINI_AI_CODE_REVIEW_SYSTEM.html		GEMINI_AI_CODE_REVIEW_SYSTEM.html
GEMINI_AI_CODE_REVIEW_SYSTEM.md		GEMINI_AI_CODE_REVIEW_SYSTEM.md
IMPLEMENTATION_PLAN.md		IMPLEMENTATION_PLAN.md
LICENSE		LICENSE
POC_ANALYSIS_REPORT.md		POC_ANALYSIS_REPORT.md
README.md		README.md
orchestrator.js		orchestrator.js
package-lock.json		package-lock.json
package.json		package.json
sfdx-project.json		sfdx-project.json

Latest commit

History

Folders and files

Repository files navigation