Merge pull request #447 from jmbish04/feat/jules-planning-enhancements

Author: jmbish04

.agent/rules/agent-registry.md

@@ -7,8 +7,9 @@
 
 ## 2. The Specialist Pattern
 
-- Avoid creating numerous bespoke subclasses of `HonoBaseAgent` (e.g., `DataAgent`, `UXAgent`, `SREAgent`) unless they require fundamentally distinct toolsets or event lifecycles.
-- Default to using **ONE** flexible `SpecialistAgent` class.
+- Avoid creating numerous bespoke specialist Durable Object classes unless they require fundamentally distinct toolsets or event lifecycles.
+- Do not reintroduce `HonoBaseAgent` or `BaseAgent`; the specialist pattern is now Honi-based.
+- Default to using **ONE** flexible specialist runtime created with `createAgent(...)`.
 - Dictate the specific persona dynamically at runtime by overriding the `systemPrompt` or passing a `specialty` configuration parameter when the frontend initiates the session.
 - **Why?** This prevents sprawling class files, keeps the agent execution logic DRY, and enables the system to spin up arbitrary expert subsets without code deployments.
 

.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/rules/cross-repo-architecture.md

@@ -0,0 +1,6 @@
+# Cross-Repository Architecture Standards
+
+- **Separation of Concerns:** `core-github-api` (Cloudflare Worker) is the state manager, API gateway, and real-time broadcaster. `core-github-standardization` is the asynchronous compute engine for long-running scripts, AI tasks, and Git mutations.
+- **Parity Requirement:** Whenever a new task type is added to `unified-api-worker.yml` in the standardization repo, a corresponding Zod validation schema and webhook ingestion handler MUST be created in the `core-github-api`.
+- **Data Traceability:** Every `repository_dispatch` event must carry a unique `taskId` generated by the API. This ID must be returned in the `callback_url` webhook payload to guarantee exactly-once processing and accurate D1 logging.
+- **OpenAPI Compliance:** All inter-service webhooks and dispatch triggers must be strictly typed and registered in the Hono OpenAPI registry (`/openapi.json`).

.agent/rules/error-handling.md

@@ -0,0 +1,35 @@
+# Rule: Global Error Handling & Logging
+
+## Context
+When an error occurs anywhere in the stack, we must ensure it is persistently logged and properly surfaced to the user. We DO NOT rely on generic `console.error` throws or hardcoded inline alerts in the frontend.
+
+## 1. Backend Error Logging (D1 Mirror)
+Whenever a backend tool, AI agent, or API action fails, you **MUST** record the failure into the D1 `system_logs` table.
+
+- **Import the Logger**: `import { Logger } from '@/lib/logger'` 
+- **Initialize**: `const logger = new Logger(env, 'ContextName');`
+- **Record**: `logger.error("Description", { details: error.message, ...context })`
+- **Mandatory Flush**: Call `await logger.flush()` before the request terminates to commit the array of logs to the database.
+
+## 2. Frontend Error UI (Shadcn + Copy)
+When a frontend component catches an error, you **MUST** pass the literal error string to the centralized error service. This service invokes a Shadcn Sonner toast that includes the raw error stack and a "Copy to Clipboard" button.
+
+- **Import the Service**: `import { handleGlobalError } from '@/lib/error-handler'`
+- **Usage**:  
+  ```ts
+  try {
+      const res = await fetch('/api/endpoint');
+      if (!res.ok) {
+          const data = await res.json();
+          // Pass the literal error string from the server
+          throw new Error(data.error || "Server error");
+      }
+  } catch (err) {
+      handleGlobalError(err);
+  }
+  ```
+- **Forbidden**: Do not use `console.error(err)` as the sole failure mechanism. Do not write local `<Alert variant="destructive">` blocks for API failures unless it's a localized form validation constraint.
+
+## 3. Strict Passthrough
+Agents must ensure that backend routes return the actual error string generated by the failed service (e.g. GitHub API 404s, Stripe 402s). 
+- **Forbidden**: Returning `error: "Failed to extract comments"` masking the true `"Resource not found"` from Octokit.

.agent/rules/full-code-output.md

@@ -0,0 +1,33 @@
+---
+trigger: always_on
+---
+
+# Rule: Full-Code Output Only
+
+## Core Requirement
+- When generating, rewriting, or reviewing code, always return complete, ready-to-use code for every file or function you touch.
+- If a file is in scope, return the full file content for that file.
+- If a function is rewritten, return the full rewritten function.
+
+## Forbidden Output
+Do not use placeholders, elisions, or shorthand such as:
+
+- `// ... rest of the function remains the same ...`
+- `// leaving as is`
+- `// ... rest of code ...`
+- `# existing code omitted`
+- `/* unchanged */`
+
+## Required Behavior
+- Do not replace omitted code with commentary.
+- Do not describe skipped sections in prose.
+- Either provide the complete code for the touched file or leave the file out of the response entirely.
+- When returning structured outputs that contain code fields, those fields must contain the full final code, not a partial patch summary.
+
+## Applies To
+- onboarding agents
+- repository specialist agents
+- coding assistants
+- slash-command agents
+- planning/codegen helpers
+- documentation agents when they emit code examples

.agent/rules/honi-mcp-integration.md

@@ -0,0 +1,5 @@
+- **Framework**: Do not use legacy local Node.js proxies (`workers-mcp` or `mcp-remote`). We are building a native Remote MCP Server. Use `McpServer` from `@modelcontextprotocol/sdk/server/mcp.js` and export it using `createMcpHandler(server)` from `agents/mcp`.
+- **No Node execution in Workers**: You cannot use `child_process`, `exec`, or `npx` inside a Cloudflare Worker. Any MCP server requiring a local Node process must be reverse-engineered into native `server.tool(...)` calls or hosted externally.
+- **SSE Client Transport**: When connecting to remote MCPs (like `docs.mcp.cloudflare.com`), always use `SSEClientTransport` instead of `StdioClientTransport`. Wrap the client connection in a try/finally block to ensure `.close()` is called, preventing hanging sockets on the edge.
+- **AI Gateway Binding**: Never hardcode standard `fetch` AI calls. Always use configuration suitable for Cloudflare's ecosystem to maintain multi-provider AI Gateway compliance.
+- **Completeness**: Provide full files start-to-finish without truncation or using `// ... rest of code` shortcuts.

.agent/rules/python-github-actions.md

@@ -0,0 +1,5 @@
+# Python in GitHub Actions Constraints
+
+- **Inline Python Indentation:** When utilizing `cat << 'EOF' > file.py` inside a YAML step, the contents must have strict, non-broken indentation. Python will fail to execute if YAML spacing mixes tabs or trailing spaces.
+- **AI Gateway URI Structuring:** When calling Cloudflare Workers AI models via the native `openai` python SDK, the `base_url` must target the `/workers-ai/v1` path wrapper on the gateway, not `/compat` or standard `/openai`.
+- **Dependency Completeness:** Any inline Python script containing imports from PyPI must have those exact matching packages installed in an upstream step (e.g., `github` package translates to `pip install PyGithub`).

.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/rules/unified-action-architecture.md

@@ -0,0 +1,6 @@
+# Unified Action Worker Constraints
+
+- **Single Source of Truth:** All cross-repository template syncing, heavy scraping, and complex Git mutations belong in `unified-api-worker.yml` (located in `core-github-standardization`). The Cloudflare Worker strictly acts as the orchestrator and state manager.
+- **Modular Dispatching:** Never hardcode disparate task payloads into a single massive function. Each task type MUST have its own dedicated module in `src/services/github/unified-action-worker/` that exports a strongly-typed function.
+- **WebSocket Delegation:** The GitHub Action is ephemeral and lacks direct access to the Cloudflare internal network bindings (D1, AI, DOs). It MUST use the WebSocket API to request the Cloudflare Worker to run DB queries, execute LLM prompts via bindings, or query the CF v4 API using the Worker's injected secrets.
+- **State Tracking:** Every dispatch must generate a `taskId` (UUID) before firing. This UUID is passed to the GitHub Action, which must echo it back during WebSocket connections and final webhook completions so the D1 `unified_action_logs` record can be updated securely.

.agent/rules/wrangler-cli-auth-delegation.md

@@ -0,0 +1,20 @@
+---
+trigger: always_on
+---
+
+# Rule: CLI Authentication Delegation (Zero-Touch Auth)
+
+## Context
+The host environment utilizes custom Just-In-Time (JIT) token wrappers in `.zshrc` that automatically intercept specific CLI tools (e.g., `wrangler`, `gh`). These wrappers dynamically fetch secrets (like `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, and `GH_TOKEN`) and inject them into the execution context for that single command. 
+
+## Directives
+1. **NEVER export secrets manually:** Do not generate commands that use `export CLOUDFLARE_API_TOKEN=...` or `export GH_TOKEN=...` before executing a script.
+2. **NEVER inline secrets:** Do not prepend environment variables to deployment or CLI commands. 
+    * ❌ **INCORRECT:** `CLOUDFLARE_API_TOKEN=your_token wrangler deploy`
+    * ❌ **INCORRECT:** `GH_TOKEN=your_token gh pr create`
+    * ❌ **INCORRECT:** `CLOUDFLARE_API_TOKEN=$MY_TOKEN pnpm run deploy`
+3. **USE standard invocations:** Always generate the simplest, standard invocation for the CLI tool or package script. Assume the host environment handles authentication transparently.
+    * ✅ **CORRECT:** `wrangler deploy`
+    * ✅ **CORRECT:** `pnpm run deploy`
+    * ✅ **CORRECT:** `gh repo view`
+4. **NO Auth Flags:** Do not attempt to pass tokens via command-line arguments or flags (e.g., avoid `--token`, `--auth`, etc.) unless specifically requested by the user for a novel CLI tool that lacks a `.zshrc` wrapper.