feat: enforce strict typing in workflows and modularize slash commands

Author: jmbish04

.agent/rules/refactor-guidelines.md

@@ -0,0 +1,7 @@
+# Rule: Webhook Refactor Standards
+
+- Every automation MUST extend `BaseAutomation` and live in its own isolated `.ts` file.
+- **Strict Conditional Routing**: The webhook router must NEVER contain conditional `if/else` logic regarding payload traits or repos. It must act strictly as a dumb dispatcher reading from D1, and it MUST call `await instance.shouldExecute()` to let the class decide if it applies to the payload.
+- All frontend components must use Shadcn strictly, ensuring the global dark theme is maintained without custom raw CSS.
+- The workflow execution logs must always be sorted by `createdAt DESC`.
+- **Global Automations**: Use the AutomationArchitect agent via the Workflows Dashboard to rapidly scaffold new automation files and ensure they are added to `AutomationRegistry.ts`.

.agent/workflows/implement-feature.md

@@ -1,21 +1,26 @@
-# .agent/workflows/implement-feature.md
+---
+description: How to implement a new Global Automation Workflow for GitHub events
+---
 
-# Implement BaseAgent-Powered Jules Overseer & Tiered Triage
+# Workflow: Implementing a New Automation Workflow
 
-## Context
+To add a new GitHub webhook automation to the repository, follow these standards:
 
-We are refactoring the `JulesOverseer` to inherit from the newly established `BaseAgent` class. This provides the Overseer with immediate, native access to the `@cloudflare/mcp-server-cloudflare` without writing custom HTTP fetch loops. We are also formalizing the Tier 1 / Tier 2 delegation strategy in the SRE prompts.
+1. **Domain Class Creation**:
+   - Create a new TypeScript file in `backend/src/automations/[domain]/[WorkflowName]Automation.ts`.
+   - Ensure the new class extends `BaseAutomation` from `@/core/BaseAutomation`.
 
-## Execution Steps
+2. **Lifecycle Hooks**:
+   - Implement the mandatory `shouldExecute()` function containing all conditional logic (checking the payload, identifying the target repo, checking if specific files exist contextually, etc.). The router will bypass execution if this returns `false`.
+   - Implement the `execute()` function containing the main action. Include detailed structured logging. Dual-authentication will automatically provide `this.octokit` (App Installation by default, fallback to PAT if configured in D1).
 
-1. **Update Prompts**
-   - Inject the updated `HealthDiagnostician` prompt into the agent's definition, establishing the hard logic branch between SMALL fixes (execute internally via Octokit) and COMPLEX fixes (delegate to `JulesService`).
+3. **Automation Registry**:
+   - Add your class name into `backend/src/core/AutomationRegistry.ts` under the registry object mapping the class name to its exported module.
+   - If the automation must run for every user invariably without opt-in (e.g. system telemetry), add it to the `SystemAutomations` array within the registry.
 
-2. **Refactor `JulesOverseer.ts`**
-   - Replace the file contents with the provided code.
-   - Note the simplified `evaluateStuckJules` method. It now calls `await this.runTextWithModel({...})`, letting `BaseAgent` handle the model routing, the ReAct loop, and the Cloudflare MCP queries.
-   - The method writes to the `alerts` table when `status === 'ready_for_pr'`.
+4. **Frontend Activation**:
+   - The UI Dashboard (`/workflows`) dynamically discovers missing configured classes via the registry and will populate the new automation in gray.
+   - An admin must visit the Workflows tab and toggle it "Active" with the correct Identity pattern (App / PAT) to provision it globally.
 
-3. **Verify Execution**
-   - Ensure the `delegate_to_jules` tool in `HealthDiagnostician` sets `autoPr: false` so the job lands in the Overseer's queue.
-   - When the chron triggers `/schedule/check`, verify via `wrangler tail` that the Overseer successfully pulls the stuck context, invokes `runTextWithModel`, and sends the generated strategy back to Jules via `julesService.sendMessage`.
+5. **Agentic Workflows**:
+   - Users can now use the **Automation Architect** agent in the `/workflows` sidebar to generate these class files automagically based on natural language prompts.

backend/drizzle.config.webhooks.ts

@@ -3,7 +3,8 @@ import { defineConfig } from "drizzle-kit";
 export default defineConfig({
     schema: [
         "./backend/src/db/schemas/github/webhooks.ts",
-        "./backend/src/db/schemas/logs/audit.ts"
+        "./backend/src/db/schemas/logs/audit.ts",
+        "./backend/src/db/schemas/webhooks/automations.ts"
     ],
     out: "./migrations/webhooks",
     dialect: "sqlite",

backend/eslint.config.js

@@ -12,6 +12,10 @@ export default tseslint.config(
     languageOptions: {
       ecmaVersion: 'latest',
       sourceType: 'module',
+      parserOptions: {
+        project: '../tsconfig.json',
+        tsconfigRootDir: import.meta.dirname,
+      },
     },
     rules: {
       // Downgrades the 'any' error to a warning to unblock rapid iteration

backend/src/ai/agents/Gemini.ts

@@ -37,15 +37,15 @@ export class GeminiAgent extends BaseAgent<Env, GeminiState> {
  * @returns The agent's response and updated history.
  */
   @callable()
-  async chat(prompt: string, history?: any[]) {
+  async chat(prompt: string, history?: any[], customInstructions?: string) {
     try {
       await this.setState({ ...this.state, status: "running" });
 
       const fullResponse = await this.runTextWithModel({
         provider: "gemini",
         model: "google-ai-studio/gemini-2.5-flash",
         name: "cf_gateway_agent",
-        instructions: "You are an elite autonomous agent powered by Cloudflare AI Gateway. Provide structured, highly accurate responses.",
+        instructions: customInstructions || "You are an elite autonomous agent powered by Cloudflare AI Gateway. Provide structured, highly accurate responses.",
         prompt: prompt,
       });
 

backend/src/automations/issues/BugHunter.ts

@@ -0,0 +1,29 @@
+import { BaseAutomation } from '@/core/BaseAutomation';
+import { runBugHunterWorkflow, shouldRunBugHunter } from "@/routes/api/webhooks/workflows/bug-hunter";
+
+export class BugHunter extends BaseAutomation {
+  private deliveryId: string;
+
+  constructor(env: Env, payload: unknown, installationId: number | undefined, usePat: boolean, deliveryId: string) {
+    super(env, payload, installationId, usePat);
+    this.deliveryId = deliveryId;
+  }
+
+  async shouldExecute(): Promise<boolean> {
+    return shouldRunBugHunter(this.payload);
+  }
+
+  async execute(): Promise<void> {
+    try {
+      await runBugHunterWorkflow({
+        env: this.env,
+        payload: this.payload,
+        deliveryId: this.deliveryId,
+      });
+      await this.logExecution('success', 'BugHunter workflow dispatched');
+    } catch (error: unknown) {
+      console.error('[BugHunter] Workflow failed:', error);
+      await this.logExecution('failure', `BugHunter failed: ${error.message}`);
+    }
+  }
+}

backend/src/automations/issues/JulesAutoFix.ts

@@ -0,0 +1,48 @@
+import { BaseAutomation } from '@/core/BaseAutomation';
+import { JulesService } from "@/services/jules/jules";
+import { GitHubConditionals } from '@/utils/github/conditionals';
+
+interface JulesPayload {
+  action?: string;
+  issue?: { number?: number };
+  comment?: { body?: string; user?: { login?: string; type?: string; }};
+  repository?: { name?: string; owner?: { login?: string; } };
+}
+
+export class JulesAutoFix extends BaseAutomation {
+  async shouldExecute(): Promise<boolean> {
+    const payload = this.payload as JulesPayload;
+    if (!payload.comment) return false;
+
+    const isGemini = GitHubConditionals.isBotOrAgentUser(payload.comment?.user);
+    
+    return !!isGemini && payload.action === 'created' && !!payload.issue?.number;
+  }
+
+  async execute(): Promise<void> {
+    const payload = this.payload as JulesPayload;
+    const feedback = payload.comment?.body;
+    const prNumber = payload.issue?.number;
+
+    if (feedback && (feedback.includes('Review') || feedback.includes('suggestion'))) {
+      try {
+          const julesService = JulesService.getInstance(this.env);
+          const prompt = `Gemini Code Assist provided a review on PR #${prNumber}.\n\nFeedback:\n${feedback}\n\nPlease apply the fixes suggested in the feedback.`;
+          await julesService.startSession({
+              prompt: prompt,
+              repo: { 
+                  owner: payload.repository?.owner?.login || '', 
+                  repo: payload.repository?.name || '',
+              },
+              autoPr: true 
+          });
+          await this.logExecution('success', 'Jules auto-fix session started', prNumber);
+      } catch (err: unknown) {
+          console.error(`[Jules] Failed to trigger auto-fix:`, err);
+          await this.logExecution('failure', `Jules startSession failed: ${err instanceof Error ? err.message : String(err)}`, prNumber);
+      }
+    } else {
+      await this.logExecution('skipped', 'No actionable feedback keywords found', prNumber);
+    }
+  }
+}

backend/src/automations/issues/SlashCommand.ts

@@ -0,0 +1,54 @@
+import { BaseAutomation } from '@/core/BaseAutomation';
+import { SlashCommandRouter } from "@/routes/api/webhooks/workflows/gardener/router";
+import { withCompatOctokit } from "@/services/octokit/compat";
+
+export class SlashCommand extends BaseAutomation {
+  private c: unknown;
+
+  constructor(env: Env, payload: unknown, installationId: number | undefined, usePat: boolean, c: unknown) {
+    super(env, payload, installationId, usePat);
+    this.c = c;
+  }
+
+  async shouldExecute(): Promise<boolean> {
+    const isIssue = !!this.payload.issue && !this.payload.comment;
+    const isIssueComment = !!this.payload.comment;
+    
+    if (isIssue) {
+      if (this.payload.action === 'opened' || this.payload.action === 'edited') {
+          return this.payload.issue?.body?.includes('/colby') || false;
+      }
+    } else if (isIssueComment) {
+      if (this.payload.action === 'created') {
+          return this.payload.comment?.body?.includes('/colby') || false;
+      }
+    }
+    return false;
+  }
+
+  async execute(): Promise<void> {
+    try {
+      const octokit = withCompatOctokit(await this.getGitHubClient());
+      const body = this.payload.comment ? this.payload.comment.body : this.payload.issue?.body;
+
+      await SlashCommandRouter.handleAndReply(
+        body,
+        {
+          env: this.env,
+          executionCtx: { ...(this.c as { executionCtx: unknown }).executionCtx, exports: {} as Record<string, unknown> },
+          repo: { 
+            owner: this.payload.repository?.owner?.login, 
+            name: this.payload.repository?.name, 
+            defaultBranch: this.payload.repository?.default_branch 
+          },
+          octokit
+        },
+        { issueNumber: this.payload.issue?.number, issueBody: this.payload.issue?.body }
+      );
+      await this.logExecution('success', 'Slash command processed');
+    } catch (err: unknown) {
+      console.error('[SlashCommand] Failed:', err);
+      await this.logExecution('failure', `Slash command failed: ${err.message}`);
+    }
+  }
+}

backend/src/automations/issues/TaskSync.ts

@@ -0,0 +1,99 @@
+import { BaseAutomation } from '@/core/BaseAutomation';
+import { getDb } from '@db';
+import { tasks, repos } from '@db/schema';
+import { eq, and } from 'drizzle-orm';
+import { generateUuid } from "@/utils/common";
+
+export class TaskSync extends BaseAutomation {
+  async shouldExecute(): Promise<boolean> {
+    return !!this.payload.issue && !this.payload.comment;
+  }
+
+  async execute(): Promise<void> {
+    const issuesPayload = this.payload;
+    const dbCore = getDb(this.env.DB);
+    const { TaskStatus, KanbanColumn } = await import('@/types/project-management/enums');
+    const { StatusMapper } = await import('@services/statusMapper');
+
+    try {
+        const repoRecord = await dbCore.select()
+            .from(repos)
+            .where(and(eq(repos.owner, issuesPayload.repository.owner.login), eq(repos.name, issuesPayload.repository.name)))
+            .limit(1);
+
+        if (repoRecord.length) {
+            const internalRepoId = repoRecord[0].id;
+            let assignee = issuesPayload.issue.assignee ? issuesPayload.issue.assignee.login : null;
+            if (issuesPayload.issue.body && issuesPayload.issue.body.includes('/colby')) {
+                assignee = 'system';
+            }
+
+            let status = TaskStatus.BACKLOG;
+            let kanbanColumn = KanbanColumn.BACKLOG;
+            if (issuesPayload.issue.state === 'closed') {
+                status = TaskStatus.DONE;
+                kanbanColumn = KanbanColumn.DONE;
+            } else {
+                if (assignee) {
+                    status = TaskStatus.TODO;
+                    kanbanColumn = StatusMapper.mapStatusToColumn(status);
+                }
+                const actionName = (issuesPayload as Record<string, unknown>).action;
+                if (actionName === 'assigned' || actionName === 'unassigned') {
+                    kanbanColumn = assignee ? KanbanColumn.PLANNED : KanbanColumn.BACKLOG;
+                    status = StatusMapper.mapColumnToStatus(kanbanColumn);
+                } else if (issuesPayload.action === 'edited' && kanbanColumn !== KanbanColumn.DONE) {
+                    if (kanbanColumn !== KanbanColumn.BACKLOG) {
+                        status = TaskStatus.IN_PROGRESS;
+                        kanbanColumn = KanbanColumn.IN_PROGRESS;
+                    }
+                }
+            }
+
+            let endAt: string | undefined;
+            if (status === TaskStatus.DONE || kanbanColumn === KanbanColumn.DONE) {
+                endAt = new Date().toISOString();
+            }
+
+            if (issuesPayload.action === 'opened') {
+                await dbCore.insert(tasks).values({
+                    id: generateUuid(),
+                    repoId: internalRepoId,
+                    title: issuesPayload.issue.title,
+                    description: issuesPayload.issue.body,
+                    status: status,
+                    kanbanColumn: kanbanColumn,
+                    assignee: assignee,
+                    githubIssueId: issuesPayload.issue.number,
+                    githubHtmlUrl: issuesPayload.issue.html_url,
+                    createdAt: issuesPayload.issue.created_at,
+                    updatedAt: issuesPayload.issue.updated_at,
+                    endAt: endAt
+                });
+            } else if (['edited', 'closed', 'reopened'].includes(issuesPayload.action!)) {
+                const updatePayload: Record<string, unknown> = {
+                    title: issuesPayload.issue.title,
+                    description: issuesPayload.issue.body,
+                    status: status,
+                    kanbanColumn: kanbanColumn,
+                    assignee: assignee,
+                    updatedAt: new Date().toISOString(),
+                    endAt: endAt
+                };
+                if (status !== TaskStatus.DONE && kanbanColumn !== KanbanColumn.DONE) {
+                    updatePayload.endAt = null;
+                }
+                await dbCore.update(tasks)
+                    .set(updatePayload)
+                    .where(and(eq(tasks.repoId, internalRepoId), eq(tasks.githubIssueId, issuesPayload.issue.number)));
+            }
+            await this.logExecution('success', 'Task synced to DB', issuesPayload.issue.number);
+        } else {
+             await this.logExecution('skipped', 'Repo not tracked internally', issuesPayload.issue.number);
+        }
+    } catch (err: unknown) {
+        console.error('[TaskSync] failed', err);
+        await this.logExecution('failure', `Update failed: ${err.message}`, issuesPayload.issue?.number);
+    }
+  }
+}

backend/src/automations/pr/AgentTagger.ts

@@ -0,0 +1,74 @@
+import { BaseAutomation } from '@/core/BaseAutomation';
+import { withCompatOctokit } from "@/services/octokit/compat";
+import { appendSignature } from "@/utils/github/signature";
+import {
+  isCodeReviewBot,
+  formatAgentFixComment,
+  detectPRAuthorAgent,
+  type ExtractedReviewComment,
+} from "@/routes/api/webhooks/workflows/pr-agent-tagger";
+
+export class AgentTagger extends BaseAutomation {
+  async shouldExecute(): Promise<boolean> {
+    if (this.payload.action !== 'submitted' || !this.payload.review?.user?.login) return false;
+    return isCodeReviewBot(this.payload.review.user.login);
+  }
+
+  async execute(): Promise<void> {
+    try {
+      const prData = this.payload.pull_request;
+      const reviewerLogin = this.payload.review.user.login;
+      if (!prData || !this.payload.repository) return;
+
+      const octokit = withCompatOctokit(await this.getGitHubClient());
+      
+      const issueCommentsRes = await octokit.rest.issues.listComments({
+        owner: this.payload.repository.owner?.login,
+        repo: this.payload.repository.name,
+        issue_number: prData.number,
+        per_page: 100,
+      });
+
+      const agentInfo = detectPRAuthorAgent({
+        headRef: prData.head?.ref,
+        body: prData.body,
+        authorLogin: prData.user?.login,
+        authorHtmlUrl: prData.user?.html_url,
+        issueComments: issueCommentsRes.data.map((c: Record<string, unknown>) => ({ body: (c.body as string) || "" })),
+      });
+
+      if (!agentInfo) return;
+
+      const reviewCommentsRes = await octokit.rest.pulls.listReviewComments({
+        owner: this.payload.repository.owner?.login,
+        repo: this.payload.repository.name,
+        pull_number: prData.number,
+        per_page: 100,
+      });
+
+      const botComments: ExtractedReviewComment[] = reviewCommentsRes.data
+        .filter((c: Record<string, unknown>) => (c.user as { login?: string })?.login === reviewerLogin)
+        .map((c: Record<string, unknown>) => ({
+          path: c.path || '',
+          line: c.line || c.original_line || null,
+          body: c.body || '',
+          diff_hunk: c.diff_hunk,
+          suggestion: c.body?.match(/```suggestion\n([\s\S]*?)\n```/)?.[1] || undefined,
+        }));
+
+      if (botComments.length === 0) return;
+
+      const commentBody = appendSignature(formatAgentFixComment(agentInfo.tag, prData.number, botComments));
+      await octokit.rest.issues.createComment({
+        owner: this.payload.repository.owner?.login,
+        repo: this.payload.repository.name,
+        issue_number: prData.number,
+        body: commentBody,
+      });
+      await this.logExecution('success', 'Agent fix comment tagged', prData.number);
+    } catch (e: unknown) {
+      console.error('[AgentTagger] failed:', e);
+      await this.logExecution('failure', `AgentTagger failed: ${e.message}`, this.payload.pull_request?.number);
+    }
+  }
+}