feat: jules planning enhancements and fixes

Author: jmbish04

.agent/rules/ai-provider-standards.md

@@ -0,0 +1,20 @@
+# Rule: AI Provider Standards (Antigravity)
+
+## 1. Zod Supremacy
+- Every structured AI call (`generateStructuredResponse`, `generateStructuredWithTools`) MUST accept a `z.ZodType<T>` payload.
+- Weak interfaces (`any` or `Record<string, unknown>`) are forbidden for output generation.
+- Use `zod-to-json-schema` to natively pipe the schema into the payload's `response_format` for supported compat endpoints.
+- Always call `schema.parse(rawParsed)` on the final JSON result to guarantee structural integrity.
+
+## 2. Universal File Context
+- Any method ending in `*FromFiles` must handle payloads consisting of `FileInput` objects (`{ name, type, data, isBase64 }`).
+- Providers with native file processing (e.g., Gemini's `inlineData`) should construct standard multi-part arrays.
+- Providers without native large-file limits (e.g., Worker AI) MUST use the transparent Vectorize RAG chunking algorithm if the total string length exceeds 6,000 characters to prevent hitting input limits.
+
+## 3. Jules SDK Integration
+- Since Jules operates via long-running chat streams, large structured responses should be handled by getting broad context from Jules, and piping its output into `worker-ai` `generateStructuredResponse` to enforce strict formatting.
+- Explicit reasoning and agent orchestration features (`analyzeRepo`, `completeTask`, `createPlan`) should exclusively utilize Jules.
+
+## 4. No Vercel AI SDK
+- Under no circumstances will you import `ai` or `@ai-sdk/`. It has been banned due to edge runtime parsing inconsistencies on Workers. 
+- Use the native `fetch` API against the Cloudflare AI Gateway instead.

.agent/workflows/implement-feature.md

@@ -1,18 +1,17 @@
 ---
 description: Implement Universal AI Gateway REST Proxy
 ---
+# Implement Universal AI Gateway REST Proxy
 
-# Workflow: Implement Universal AI Gateway REST Proxy
+This workflow outlines the standard operating procedure for upgrading the AI Provider abstraction layer to support unified routing through Cloudflare's AI Gateway.
 
-**Objective:** Expose Cloudflare AI Gateway endpoints through the Hono API so that external GitHub Action python scripts can securely interface with Universal Routing.
+## Pre-Requisites
+1. Ensure the project's `wrangler.jsonc` contains the appropriate `AI_GATEWAY_NAME` and `FILE_EMBEDDINGS` Vectorize binding.
+2. Confirm `@google/jules-sdk`, `zod`, and `zod-to-json-schema` are installed in the `backend/` workspace.
 
-1.  **File Creation:** Created the modular `backend/src/routes/api/ai/gateway.ts`, `backend/src/routes/api/ai/utils/format-model-id.ts`, and `backend/src/routes/api/ai/schemas/gateway.schema.ts` files.
-2.  **Code Ingestion:** Built full TypeScript end-to-end functionality into each module.
-3.  **Module Wiring:**
-    - Navigated to the main routing registry (`backend/src/index.ts`).
-    - Imported `gatewayApp` from the new module: `import aiGatewayApi from '@/routes/api/ai/gateway';`
-    - Mounted the route: `app.route('/api/ai/gateway', aiGatewayApi);`
-4.  **Environment Setup:** Update `.dev.vars` (and `wrangler.toml`/`wrangler.jsonc` `[vars]` block if typed validation exists) to ensure `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` are active. Optionally add `GITHUB_ACTION_API_KEY` for dedicated auth isolation.
-5.  **Validation:**
-    - Run tests/CURL locally against `http://localhost:8787/api/ai/gateway/chat/completions`.
-    - Send a generic `Authorization: Bearer <token>` and payload `{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "ping"}]}` to confirm universal routing passthrough and Zod schema compliance.
+## Steps
+1. Route all provider calls (Worker AI, Gemini) through the Cloudflare AI Gateway compat or standard endpoint using native `fetch`. Do not use provider-specific SDKs.
+2. Enforce Zod schemas strictly. Convert `z.ZodType<T>` to JSON schema using `zodToJsonSchema` and utilize the provider's `response_format` JSON schema mode.
+3. For large file contexts (> 6000 chars), transparently chunk and vectorize the text using `@cf/baai/bge-large-en-v1.5` and Vectorize RAG. Query the prompt embedding against the index, and append the top matches to the final prompt.
+4. Integrate the `@google/jules-sdk` and polyfill missing features like structured output by piping the text response into a smaller, strict formatting model like `worker-ai`.
+5. Run `pnpm run check` to ensure strict TypeScript compilation completes successfully.

.agents/llms-txt/cloudflare-llms.txt

@@ -0,0 +1,273 @@
+##
+# .github/workflows/skill-sync.yml
+#
+# Skill Sync — checks configured skill repos for new or modified SKILL.md files
+# and copies them to .agent/skills/ in this repo. Optionally dispatches a Jules
+# session to wire updated skills into fetchRemoteSkill agent arrays.
+#
+# TRIGGERS: Pull Request, Manual (workflow_dispatch)
+#
+# REQUIRED SECRETS:
+#   GH_TOKEN     — Fine-grained PAT with read access to skill repos and write to this repo
+#   JULES_API_KEY — Jules SDK API key for the optional agent-wiring step
+#
+# SKILL_REPOS (env var) — space-separated list of "owner/repo" to scan for skills.
+##
+
+name: "🔧 Skill Sync"
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - ".agent/skills/**"
+      - ".github/workflows/skill-sync.yml"
+  workflow_dispatch:
+    inputs:
+      skill_repos:
+        description: "Space-separated list of 'owner/repo' to scan (overrides env default)"
+        required: false
+      dispatch_jules:
+        description: "Dispatch a Jules session to update agent fetchRemoteSkill arrays"
+        type: boolean
+        default: true
+
+concurrency:
+  group: skill-sync-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Default skill source repos — override via workflow_dispatch input or repo variable
+  DEFAULT_SKILL_REPOS: "jmbish04/core-github-standardization cloudflare/skills"
+  TARGET_SKILLS_DIR: ".agent/skills"
+
+jobs:
+  detect-changes:
+    name: "📡 Detect Skill Changes"
+    runs-on: ubuntu-latest
+    outputs:
+      changed_skills: ${{ steps.scan.outputs.changed_skills }}
+      has_changes: ${{ steps.scan.outputs.has_changes }}
+    steps:
+      - name: Checkout this repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Scan skill repos for changes
+        id: scan
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          SKILL_REPOS: ${{ github.event.inputs.skill_repos || env.DEFAULT_SKILL_REPOS }}
+        run: |
+          set -euo pipefail
+
+          node - <<'SCAN_SCRIPT'
+          const { execSync } = require('child_process');
+          const repos = process.env.SKILL_REPOS.trim().split(/\s+/);
+          const token = process.env.GH_TOKEN;
+          const changes = [];
+
+          for (const repo of repos) {
+            const [owner, repoName] = repo.split('/');
+            if (!owner || !repoName) continue;
+
+            try {
+              // List all SKILL.md files in the repo via GitHub API
+              const apiUrl = `https://api.github.com/repos/${owner}/${repoName}/git/trees/HEAD?recursive=1`;
+              const response = execSync(
+                `curl -sf -H "Authorization: Bearer ${token}" -H "Accept: application/vnd.github+json" "${apiUrl}"`
+              );
+              const tree = JSON.parse(response.toString());
+              const skillFiles = (tree.tree || [])
+                .map(e => e.path)
+                .filter(p => p && p.match(/SKILL\.md$/i));
+
+              for (const filePath of skillFiles) {
+                // Extract skill name from path (e.g. skills/agents-sdk/SKILL.md -> agents-sdk)
+                const parts = filePath.split('/');
+                const skillName = parts.length >= 2 ? parts[parts.length - 2] : null;
+                if (!skillName) continue;
+
+                const localPath = `.agent/skills/${skillName}/SKILL.md`;
+
+                // Check if local copy exists and compare content hash
+                let localContent = '';
+                try {
+                  localContent = require('fs').readFileSync(localPath, 'utf8');
+                } catch { /* file doesn't exist yet */ }
+
+                const rawUrl = `https://raw.githubusercontent.com/${owner}/${repoName}/HEAD/${filePath}`;
+                const remoteContent = execSync(
+                  `curl -sf -H "Authorization: Bearer ${token}" "${rawUrl}"`
+                ).toString();
+
+                if (remoteContent !== localContent) {
+                  changes.push({ repo, filePath, skillName, rawUrl });
+                }
+              }
+            } catch (err) {
+              console.error(`Failed to scan ${repo}:`, err.message);
+            }
+          }
+
+          require('fs').writeFileSync('/tmp/skill_changes.json', JSON.stringify(changes, null, 2));
+          console.log(`Found ${changes.length} skill changes`);
+          const core = { setOutput: (k, v) => process.stdout.write(`::set-output name=${k}::${v}\n`) };
+          core.setOutput('has_changes', changes.length > 0 ? 'true' : 'false');
+          core.setOutput('changed_skills', JSON.stringify(changes.map(c => c.skillName)));
+          SCAN_SCRIPT
+
+      - name: Upload changes manifest
+        uses: actions/upload-artifact@v4
+        with:
+          name: skill-changes
+          path: /tmp/skill_changes.json
+
+  copy-skills:
+    name: "📋 Copy Updated Skills"
+    needs: detect-changes
+    if: needs.detect-changes.outputs.has_changes == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout this repo
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GH_TOKEN }}
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Download changes manifest
+        uses: actions/download-artifact@v4
+        with:
+          name: skill-changes
+          path: /tmp
+
+      - name: Copy changed skills to .agent/skills/
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          node - <<'COPY_SCRIPT'
+          const { execSync } = require('child_process');
+          const fs = require('fs');
+          const path = require('path');
+          const token = process.env.GH_TOKEN;
+          const changes = JSON.parse(fs.readFileSync('/tmp/skill_changes.json', 'utf8'));
+
+          for (const { rawUrl, skillName } of changes) {
+            const targetDir = `.agent/skills/${skillName}`;
+            const targetFile = `${targetDir}/SKILL.md`;
+            fs.mkdirSync(targetDir, { recursive: true });
+            const content = execSync(`curl -sf -H "Authorization: Bearer ${token}" "${rawUrl}"`).toString();
+            fs.writeFileSync(targetFile, content);
+            console.log(`✅ Updated: ${targetFile}`);
+          }
+          COPY_SCRIPT
+
+      - name: Commit and push updated skills
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add "${{ env.TARGET_SKILLS_DIR }}/"
+          if git diff --cached --quiet; then
+            echo "No changes to commit."
+            exit 0
+          fi
+          git commit -m "chore(skills): sync updated skills from remote repos [skill-sync-bot]"
+          git push origin HEAD
+
+  dispatch-jules:
+    name: "🤖 Jules: Wire New Skills into Agents"
+    needs: [detect-changes, copy-skills]
+    if: |
+      needs.detect-changes.outputs.has_changes == 'true' &&
+      (github.event_name == 'workflow_dispatch' && github.event.inputs.dispatch_jules == 'true' ||
+       github.event_name == 'pull_request')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install Jules SDK
+        run: npm install -g @google/jules-sdk
+
+      - name: Download changes manifest
+        uses: actions/download-artifact@v4
+        with:
+          name: skill-changes
+          path: /tmp
+
+      - name: Dispatch Jules to update fetchRemoteSkill arrays
+        env:
+          JULES_API_KEY: ${{ secrets.JULES_API_KEY }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          CHANGED_SKILLS: ${{ needs.detect-changes.outputs.changed_skills }}
+        run: |
+          node - <<'JULES_SCRIPT'
+          const { jules } = require('@google/jules-sdk');
+
+          const changedSkills = JSON.parse(process.env.CHANGED_SKILLS || '[]');
+          if (changedSkills.length === 0) { console.log('No skills to wire.'); process.exit(0); }
+
+          const client = jules.with({ apiKey: process.env.JULES_API_KEY });
+          const repo = process.env.GITHUB_REPOSITORY;
+
+          const prompt = `
+          You are a Cloudflare Workers expert working on the repository \`${repo}\`.
+
+          The following skill files have been added or updated in \`.agent/skills/\`:
+          ${changedSkills.map(s => `- \`.agent/skills/${s}/SKILL.md\``).join('\n')}
+
+          Your task:
+          1. Read each new/updated SKILL.md to understand what skill it provides.
+          2. Open \`src/backend/src/services/octokit/skill-fetcher.ts\` and update the \`AGENT_SKILL_PATHS\` registry to include appropriate skill paths for each agent where the skill is relevant.
+          3. Skill paths follow the format: \`skills/{skill-name}/SKILL.md\`.
+          4. Do NOT remove existing skill paths — only add new ones.
+          5. Run \`cd src/backend && pnpm run build\` to verify no TypeScript errors.
+          6. Submit a PR titled: "feat(skills): integrate new remote skills into agent fetchRemoteSkill arrays"
+
+          Rules:
+          - Only modify \`src/backend/src/services/octokit/skill-fetcher.ts\`
+          - Keep all existing entries intact
+          - Use TypeScript strict mode
+          `.trim();
+
+          (async () => {
+            const session = await client.session({
+              prompt,
+              source: { github: repo, baseBranch: 'main' },
+              autoPr: true,
+            });
+            console.log('Jules session created:', session.id);
+
+            for await (const activity of session.stream()) {
+              if (activity.type === 'agentMessaged') {
+                console.log('Jules:', activity.message.slice(0, 120));
+              }
+              if (activity.type === 'progressUpdated') {
+                console.log('Progress:', activity.title);
+              }
+            }
+
+            const result = await session.result();
+            console.log('Session completed:', result.state);
+          })().catch(err => {
+            console.error('Jules dispatch failed:', err.message);
+            process.exit(1);
+          });
+          JULES_SCRIPT