jules-orchestrator-kit 0.1.9 → 0.2.9

package/.agent/history/2026-07-27-dispatch-test-swarm-task.md

@@ -0,0 +1,9 @@
+---
+type: jules_dispatch
+title: "Test Swarm Task"
+timestamp: "2026-07-27T09:38:12.728Z"
+---
+# Jules Task Dispatch: Test Swarm Task
+
+## Prompt
+Test Prompt Description

package/.agent/jules-queue/README.md

@@ -16,7 +16,14 @@ Implement sliding window rate limiting for public API routes.
 - Must pass `npm test` before submitting PR.
 ```
 
-Dispatch queued tasks using `scripts/jules-dispatch.mjs`:
+Process all queued tasks in batch:
+
+```bash
+npm run jules:queue
+# or node scripts/jules-queue-runner.mjs
+```
+
+Or dispatch a single queued task using `scripts/jules-dispatch.mjs`:
 
 ```bash
 node scripts/jules-dispatch.mjs "TASK-001 Rate Limiting" .agent/jules-queue/TASK-001-rate-limiting.md

package/.env.example

@@ -0,0 +1,17 @@
+# Google Jules Orchestration Kit - Environment Configuration Example
+# Copy this file to .env and populate with your credentials/settings.
+
+# Google Jules API Key (Required for direct REST API dispatches)
+JULES_API_KEY=your_google_jules_api_key_here
+
+# Target GitHub Repository (Format: owner/repo)
+JULES_REPO=FullThrottle83/jules-orchestrator-kit
+
+# Base Branch for PR Audits & Merge-Base Calculations (Default: main)
+BASE_BRANCH=main
+
+# Swarm Concurrency Limit (Maximum parallel dispatches, default: 3)
+JULES_SWARM_CONCURRENCY=3
+
+# Swarm Dispatch Stagger Interval in Milliseconds (Default: 1500)
+JULES_SWARM_STAGGER_MS=1500

package/.github/workflows/jules-audit.yml

@@ -0,0 +1,32 @@
+name: Jules PR Audit & Test Gatekeeper
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  audit-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Run Unit Tests
+        run: npm test
+
+      - name: Run Jules PR Self-Audit Gatekeeper
+        if: github.event_name == 'pull_request' && (startsWith(github.actor, 'google-labs-jules') || contains(github.actor, 'jules'))
+        run: node scripts/jules-self-audit.mjs
+        env:
+          CI: "true"
+          BASE_BRANCH: "main"
+

package/.github/workflows/jules-nightly.yml

@@ -0,0 +1,21 @@
+name: Jules Nightly Self-Audit
+
+on:
+  schedule:
+    - cron: '0 3 * * *'
+  workflow_dispatch:
+
+jobs:
+  nightly-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Dispatch Nightly Maintenance to Jules
+        env:
+          JULES_API_KEY: ${{ secrets.JULES_API_KEY }}
+          JULES_REPO: ${{ github.repository }}
+        run: |
+          node scripts/jules-nightly.mjs

package/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Auto Publish to npm
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm test
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/JULES_RULES_TEMPLATE.md

@@ -24,6 +24,8 @@ Dispatch tasks to Jules when ALL of the following apply:
     <rule>2. READ-BEFORE-WRITE (ZERO HALLUCINATION): You are FORBIDDEN from guessing internal API signatures. Before editing, you MUST use code search or MCP doc tools to inspect exact function signatures.</rule>
     <rule>3. VERIFICATION LOOP: After patching code, you MUST execute the project's verification commands (tests/build) and ensure 0 errors.</rule>
     <rule>4. ABORT CONDITION: On repeated unresolvable test failures (4+ attempts), output <status>ABORT_UNRESOLVABLE</status> and terminate immediately.</rule>
+    <rule>5. NO OUT-OF-BAND RUNNER SCRIPTS / CHEATING: You are FORBIDDEN from creating temporary shell scripts (e.g. patch.sh, test-fix.sh), disabling assertions, or bypassing verification tooling to force tests to pass.</rule>
+    <rule>6. ASSERTION QUALITY: Unit tests created or modified MUST contain explicit, non-trivial assertions (e.g. assert/expect) testing realistic input/output contracts. Empty test functions or tests asserting tautologies (e.g. true === true) are strictly forbidden.</rule>
   </strict_invariants>
 </MCP_DIRECTIVE>
 ```
@@ -32,20 +34,22 @@ Dispatch tasks to Jules when ALL of the following apply:
 
 ## 3. Dynamic Command Resolution
 
-Jules automatically infers test and build verification commands based on project manifest files:
-- `package.json` -> `npm test && npm run build`
-- `Cargo.toml` -> `cargo test --workspace && cargo build`
-- `go.mod` -> `go test ./... && go build ./...`
-- `pyproject.toml` -> `pytest`
-- `pom.xml` -> `mvn test`
-- `build.gradle` -> `./gradlew test`
-- `.agent/jules.yml` -> Custom user commands
+Jules automatically infers test and build verification commands via `scripts/command-resolver.mjs`:
+- `.agent/jules.yml` -> Custom user commands (`test_cmd`, `build_cmd`)
+- `package.json` -> `testCmd: "npm test"` (or `"npm run lint && npm test"`), `buildCmd: "npm run build"`
+- `Cargo.toml` -> `testCmd: "cargo test --workspace"`, `buildCmd: "cargo build"`
+- `go.mod` -> `testCmd: "go test ./..."`, `buildCmd: "go build ./..."`
+- `pyproject.toml` -> `testCmd: "pytest"`, `buildCmd: ""`
+- `pom.xml` -> `testCmd: "mvn test"`, `buildCmd: "mvn compile"`
+- `build.gradle` -> `testCmd: "./gradlew test"`, `buildCmd: "./gradlew assemble"`
+- Workspace graphs (`turbo.json`, `pnpm-workspace.yaml`, `nx.json`) -> targeted affected package filters
 
 ---
 
 ## 4. Operational & Code Quality Directives
 
 - **Read Before Write**: Always inspect target files and surrounding symbol signatures (via grep or view tools) before applying changes.
+- **Scope Locks**: Strictly adhere to designated file bounds. Do NOT modify files outside the explicit task scope or alter shared infrastructural components unless assigned.
 - **Rebase Before PR**: Fetch latest `main`, rebase onto `origin/main`, re-execute verification suite. If the resulting diff is empty, close/abort PR without pushing.
 - **Minimal Interference**: Preserve existing function signatures, comments, and style conventions.
 - **Falsifiable Claims**: Base all code changes on explicit error logs, file paths, line numbers, or test results.

package/README.md

@@ -1,132 +1,262 @@
-# Google Jules Orchestration Kit
+# Google Jules Orchestration Kit 🤖⚡
 
 [![npm version](https://img.shields.io/npm/v/jules-orchestrator-kit.svg)](https://www.npmjs.com/package/jules-orchestrator-kit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green.svg)](https://nodejs.org)
+[![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-blue.svg)](#)
 
-A lightweight, framework-agnostic toolkit for turning **Google Jules** into a deterministic, autonomous background code builder for any repository (Next.js, Vite, Node, Bun, Deno, Python, Go, Rust, Elixir, Ruby, Swift, Java, C/C++, Monorepos, etc.).
+A lightweight, zero-dependency toolkit that upgrades **Google Jules** into a **fully autonomous, self-correcting background code builder** for any repository (Next.js, Vite, Node, Bun, Deno, Python, Go, Rust, Elixir, Ruby, Swift, Java, C/C++, Monorepos, etc.).
 
-> **TL;DR**: Don't use Google Jules like a chat assistant. Use it as an autonomous background worker. Run `npx jules-orchestrator-kit` inside any repository to automatically detect your tech stack, generate prompt guardrails, set up test/build verification gates, and install Jules orchestration scripts.
+Whether you are a beginner looking to automate bug fixes without breaking your app, or a power user orchestrating parallel AI task swarms, this kit handles the heavy lifting of prompting, testing, security, and verification.
+
+> **TL;DR**: Don't just chat with Google Jules—put it to work. Run `npx jules-orchestrator-kit` inside your project. Assign tasks, and the kit will automatically test the AI's code, tell it to fix any mistakes, and only present you with working, tested Pull Requests.
+
+---
+
+## 🎯 Who is this for?
+
+**🌱 For Everyday Developers:**  
+AI agents can write broken code or skip tests. This kit acts as an automated safety net: it detects your tech stack, runs your tests against the AI's code, catches errors, and prompts the AI to self-correct *before* you review the Pull Request.
+
+**🔥 For Power Users & Senior Engineers:**  
+Unlock deterministic, production-grade orchestration. Includes Git Worktree multi-task swarms, Shannon Entropy secret redaction, MCP (Model Context Protocol) directive envelopes, OODA self-healing feedback loops, and scope boundary locks.
 
 ---
 
-## ⚡ 1-Step Quick Setup for Any Project
+## 🚀 Quick Start: Zero to Autonomous AI
 
-Run this command inside the root of **any target repository**:
+### 1. Initialize your project
+Run this command inside the root of **any target repository**. It automatically detects your tech stack and sets up safety guardrails:
 
 ```bash
 npx jules-orchestrator-kit
-# or
-npx jules-init
+
+# Or launch the interactive setup wizard:
+npx jules-init --interactive
+```
+
+### 2. Dispatch your first task
+Once initialized, you can immediately send tasks to Jules. The Orchestrator handles prompting, testing, security, and self-correction in the background:
+
+```bash
+node scripts/jules-dispatch.mjs "Refactor rate limiter" "Implement sliding window rate limiting in src/utils/rate-limit.ts"
+```
+
+*(**Pro-tip:** Add `JULES_DRY_RUN=1` before the command to test prompt generation locally without executing the remote API).*
+
+---
+
+## 🧠 How It Works: The Autonomous Loop
+
+Instead of blindly trusting AI code mutations, the Orchestrator acts as a strict manager enforcing a **Tiered Verification Gate**:
+
+1. **Queue a Task:** Dispatch via CLI, REST API, or drop markdown files into `.agent/jules-queue/`.
+2. **Secret & Path Defense:** Hides passwords, API keys (`entropy > 3.6`), and blocks path traversal (`../`).
+3. **Jules Proposes Code:** Google Jules mutates code in an isolated environment.
+4. **Tiered Verification:** Enforces scope bounds (`git diff`), runs fast-fail linters/type-checks, then executes full test/build suites.
+5. **Self-Correction (OODA Loop):** If tests fail, stderr traces are fed back to Jules to self-correct (up to 4 attempts).
+6. **Clean Pull Request:** Once verified green, commits & pushes clean code to GitHub.
+
+<details>
+<summary><b>🔍 View System Architecture Diagram (For Power Users)</b></summary>
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant CLI as CI Trigger / CLI
+    participant Orc as jules-orchestrator
+    participant Jules as Google Jules Agent
+    participant Git as Git Worktree Sandbox
+
+    CLI->>Orc: Dispatch Task ("Refactor Auth")
+    
+    note over Orc,Git: Phase 1: Isolation & Setup
+    Orc->>Orc: Redact Secrets & Check Path Traversal
+    Orc->>Git: Provision Worktree (`git worktree add`)
+    Orc->>Jules: Dispatch Context, Invariants & Target Scope
+
+    loop Max Retries (Attempts < 4)
+        Jules->>Git: Propose Code Mutations
+        
+        note over Orc,Git: Phase 2: Tiered Verification
+        Orc->>Git: Scope Audit (`git diff --name-only` vs forbidden_paths)
+        alt Scope Breach
+            Git-->>Orc: Scope Violation Error
+        else Scope OK
+            Orc->>Git: Run Fast-Fail Checks (Lint / Typecheck)
+            opt Pass Static Checks
+                Orc->>Git: Run Heavy Suite (`build_cmd` & `test_cmd`)
+            end
+        end
+
+        alt Verification Gates Pass
+            Orc->>Git: Commit, Push & Cleanup Worktree
+            Orc->>CLI: Return Success + Metrics (.agent/history/metrics.jsonl)
+            note over Jules,Git: Exit Loop
+        else Verification Gates Fail (Attempts < 4)
+            Git-->>Orc: Execution Trace (stdout/stderr / Diff)
+            Orc->>Jules: Inject OODA Feedback & Error Context
+        end
+    end
+
+    opt Verification Gates Fail (Attempts >= 4)
+        Orc->>Git: Abort & Rollback Worktree (`git worktree remove --force`)
+        Orc->>CLI: Return Terminal Failure (.agent/history/errors.jsonl)
+    end
 ```
 
-This single command will:
-1. **Detect your tech stack & workspace structure** (Node, Bun, Deno, Rust, Go, Python, Elixir, Ruby, Swift, Java, C/C++, Turborepo, Nx, pnpm) via `command-resolver.mjs`.
-2. **Generate `AGENTS.md`** pre-populated with pre-execution `<MCP_DIRECTIVE>` rules and verification invariants.
-3. **Create `.agent/jules.yml` (v2 Schema)** pre-configured with detected test/build commands and glob-based `forbidden_paths`.
-4. **Install `.agent/rules/dynamic-guardrails.json`** for RegEx-based dynamic prompt guardrail injection.
-5. **Install orchestration scripts** into `./scripts/` (`jules-dispatch.mjs`, `jules-self-audit.mjs`, `jules-swarm.mjs`, `jules-queue-runner.mjs`, `jules-nightly.mjs`).
+</details>
 
 ---
 
-## 💡 What This Toolkit Provides
+## 💡 Core Capabilities (8 Component Suite)
 
-1. **Init Scaffolding CLI (`bin/init.js`)**: Auto-scaffolds any repo in 1 second.
-2. **Monorepo & Command Resolver (`scripts/command-resolver.mjs`)**: Auto-detects project manifests and monorepo workspace graphs (`turbo.json`, `pnpm-workspace.yaml`, `nx.json`, `Cargo.toml` workspaces) to run targeted affected package verifications instead of full-repo test suites.
-3. **Dynamic Guardrail Composition (`.agent/rules/dynamic-guardrails.json`)**: RegEx-based rule matching that injects targeted stack guardrails into prompts on-the-fly.
-4. **Pre-Flight Secret Redaction & REST/stdin Dispatcher (`scripts/jules-dispatch.mjs`)**: Auto-redacts API keys (`ghp_`, `AKIA`, `sk-`, `Bearer`, RSA keys), streams prompts over REST / stdin to bypass OS `ARG_MAX` shell limits, and handles HTTP 429 rate limits.
+### 🛠️ The Basics
 
-5. **PR Self-Auditor & Glob Boundary Gatekeeper (`scripts/jules-self-audit.mjs`)**: Unshallows git history in CI runners (`git fetch --unshallow`), filters token bloat, enforces dynamic glob-based security boundaries (`forbidden_paths`), and runs scoped workspace test suites.
-6. **Queue Runner (`scripts/jules-queue-runner.mjs`)**: Iterates through `.agent/jules-queue/`, dispatches queued markdown tasks, and moves finished tasks to `.agent/jules-queue/completed/`.
-7. **Rate-Limited Swarm Orchestrator (`scripts/jules-swarm.mjs`)**: Manages multi-task batches with controlled concurrency (`JULES_SWARM_CONCURRENCY`, default 3), staggered dispatches (1.5s interval), and batch cooldowns to eliminate API rate-limit thrashing.
-8. **Nightly Maintenance Suite (`scripts/jules-nightly.mjs`)**: Schedules automated background audits (security leak scans, WCAG accessibility checks, dead code pruning, unused env var cleanup).
+* **Auto-Configuration (`bin/init.js`)**: Instantly scaffolds your repo using `node:util.parseArgs` with an interactive TTY wizard (`-i`) or silent CI fallback.
+* **Queue Runner (`scripts/jules-queue-runner.mjs`)**: Drop markdown task specifications into `.agent/jules-queue/` and let the runner process them sequentially.
+* **Nightly Maintenance (`scripts/jules-nightly.mjs`)**: Schedules automated background audits (security leak scans, WCAG accessibility checks, dead code pruning).
+
+### 🔒 Security & Guardrails
+
+* **Secret & Traversal Redaction (`scripts/jules-dispatch.mjs`)**: Shannon Entropy detector strips API keys and secrets (`entropy > 3.6`, `length >= 20`) while preserving valid file paths. Supports dry-run testing (`JULES_DRY_RUN=1`).
+* **Dynamic Guardrails (`.agent/rules/dynamic-guardrails.json`)**: RegEx-based rule matching that injects targeted stack guardrails into prompts on-the-fly.
+
+### 🐝 Advanced Orchestration
+
+* **Monorepo Boundary Resolver (`scripts/command-resolver.mjs`)**: Auto-detects `turbo`, `nx`, `pnpm`, or `Cargo` workspaces to run targeted affected package verifications (`git diff`) instead of full-repo test suites.
+* **Self-Healing Gatekeeper (`scripts/jules-self-audit.mjs`)**: Unshallows git history in CI runners (`git fetch --unshallow`), enforces `forbidden_paths`, extracts OODA feedback error traces, and logs telemetry to `.agent/history/metrics.jsonl`.
+* **Git Worktree Swarms (`scripts/jules-swarm.mjs`)**: Manages multi-task batches in isolated Git worktrees (`JULES_USE_WORKTREES=true`) with scope boundary isolation.
 
 ---
 
-## 🛠️ Usage Examples
+## ⚙️ Configuration & Zero-Trust Security
 
-### Dispatch a single task to Jules
+The orchestrator creates an `.agent/jules.yml` file to manage repo-level verification and security:
 
-```bash
-node scripts/jules-dispatch.mjs "Refactor rate limiter" "Implement sliding window rate limiting using Redis. Must pass tests."
+```yaml
+# Google Jules Repository Configuration (Version 2)
+version: 2
+test_cmd: "npm test"
+build_cmd: "npm run build"
+forbidden_paths:
+  - ".github/**"
+  - "**/secrets/**"
+  - "**/*.pem"
+  - "**/lock-manager/**"
+  - "scripts/jules-*"
+  - ".agent/jules.yml"
+allow_paths: []
 ```
 
-### Dispatch an entire queue of markdown task specifications
+> 🛡️ **Zero-Trust Security Model**: `allow_paths` and `forbidden_paths` rules are read **strictly from the target base branch** (`origin/main`), never from untrusted PR branches. Even if an AI agent hallucinates and tries to modify its own security rules in a PR branch, the Orchestrator enforces the immutable rules defined on `main`.
+> ℹ️ Setting `build_cmd: ""` explicitly skips the build verification step (useful for pure test suites or scripts). Note that `.agent/jules.yml` uses a zero-dependency parser that supports flow (`[...]`) and block (`- item`) list subsets.
+> 📦 `.github/` is intentionally included in `package.json`'s `files` array so that `npx jules-init` can automatically scaffold `.github/workflows/jules-audit.yml` into target repositories.
+
+---
+
+<details>
+<summary><b>🛠️ Supported Language Manifests & Workspace Graphs (15+ Tech Stacks)</b></summary>
+
+| Stack / Ecosystem | Manifest / Workspace File | Test Command (`testCmd`) | Build Command (`buildCmd`) |
+|---|---|---|---|
+| **Turborepo** | `turbo.json` | `npx turbo run test --filter=<pkg>...` | `npx turbo run build --filter=<pkg>...` |
+| **pnpm Workspace** | `pnpm-workspace.yaml` | `pnpm --filter=...<pkg> test` | `pnpm --filter=...<pkg> build` |
+| **Nx Workspace** | `nx.json` | `npx nx run-many -t test -p <pkg> --with-deps` | `npx nx run-many -t build -p <pkg> --with-deps` |
+| **Bun** | `bunfig.toml` / `bun.lockb` | `bun test` | `bun run build` |
+| **Deno** | `deno.json` / `deno.jsonc` | `deno test` | `deno task build` |
+| **JavaScript / TypeScript** | `package.json` | `npm run lint && npm test` | `npm run build` |
+| **Rust** | `Cargo.toml` | `cargo test --workspace` | `cargo build` |
+| **Go** | `go.mod` | `go test ./...` | `go build ./...` |
+| **Python** | `pyproject.toml` / `requirements.txt` | `pytest` | *(none)* |
+| **Elixir** | `mix.exs` | `mix test` | `mix compile` |
+| **Ruby** | `Gemfile` | `bundle exec rake test` | *(none)* |
+| **Swift** | `Package.swift` | `swift test` | `swift build` |
+| **Java (Maven/Gradle)** | `pom.xml` / `build.gradle` | `mvn test` / `./gradlew test` | `mvn compile` / `./gradlew assemble` |
+| **C / C++** | `Makefile` | `make test` | `make build` |
+
+</details>
+
+---
+
+<details>
+<summary><b>📖 Advanced Workflows (Queues, Swarms, Nightly Maintenance)</b></summary>
+
+### 1. Process an entire queue of background tasks
 
 ```bash
 npm run jules:queue
 ```
 
+### 2. Run Rate-Limited Swarms with Scope Isolation
+
+Run massive parallel refactors safely. The orchestrator uses `tasks.json` file boundary `scope` segregation to prevent parallel task collisions:
+
 ```bash
-JULES_SWARM_CONCURRENCY=5 node scripts/jules-swarm.mjs tasks.json
+JULES_SWARM_CONCURRENCY=5 JULES_USE_WORKTREES=true node scripts/jules-swarm.mjs tasks.json
 ```
 
-Where `tasks.json` is formatted as:
-```json
-[
-  { "id": "t1", "title": "Refactor Auth", "prompt": "Refactor auth middleware to ESM" },
-  { "id": "t2", "title": "Fix Memory Leak", "prompt": "Fix listener memory leak in websocket event loop" }
-]
-```
+*(Example `tasks.json` constraint: `[ { "id": "t1", "prompt": "Refactor auth", "scope": ["src/auth/**"] } ]`)*
 
-### Run Nightly Maintenance Suite
+### 3. Run Nightly Maintenance Suite
 
 ```bash
 node scripts/jules-nightly.mjs --dry-run
 ```
 
-### Audit Jules PRs before merging
+### 4. Audit Jules PRs before merging in CI
 
 ```bash
 node scripts/jules-self-audit.mjs
 ```
 
+</details>
+
 ---
 
-## 🛠️ Supported Language Manifests & Workspace Graphs
-
-The command resolver automatically sniffs your codebase and invokes the right verification chain:
-
-| Stack / Ecosystem | Manifest / Workspace File | Default Verification Command |
-|---|---|---|
-| **Turborepo** | `turbo.json` | `npx turbo run test --filter=<pkg>...` |
-| **pnpm Workspace** | `pnpm-workspace.yaml` | `pnpm --filter=...<pkg> test` |
-| **Nx Workspace** | `nx.json` | `npx nx run-many -t test -p <pkg> --with-deps` |
-| **Bun** | `bunfig.toml` / `bun.lockb` | `bun test && bun run build` |
-| **Deno** | `deno.json` / `deno.jsonc` | `deno test && deno task build` |
-| **JavaScript / TypeScript** | `package.json` | `npm run check:all` or `npm test` |
-| **Rust** | `Cargo.toml` | `cargo test -p <pkg>` / `cargo test --workspace` |
-| **Go** | `go.mod` | `go test ./... && go build ./...` |
-| **Python** | `pyproject.toml` / `requirements.txt` | `pytest` |
-| **Elixir** | `mix.exs` | `mix test && mix compile` |
-| **Ruby** | `Gemfile` | `bundle exec rake test` |
-| **Swift** | `Package.swift` | `swift test && swift build` |
-| **Java (Maven)** | `pom.xml` | `mvn test && mvn compile` |
-| **Java (Gradle)** | `build.gradle` | `./gradlew test && ./gradlew assemble` |
-| **C / C++** | `Makefile` | `make test && make build` |
-| **Custom Config (v2)** | `.agent/jules.yml` | Configurable `test_cmd`, `build_cmd`, `forbidden_paths` & `allow_paths` |
+<details>
+<summary><b>🌐 Integration Interfaces: CLI, REST API & MCP Directives</b></summary>
+
+`jules-orchestrator-kit` supports three primary integration channels:
+
+### 1. Direct REST API Mode (`jules.googleapis.com`)
+When `JULES_API_KEY` and `JULES_REPO` are present in your environment (`.env` or CI secrets), payloads are dispatched directly to the official Google Jules REST API endpoint.
+- Handles HTTP 429 rate limits gracefully.
+- Automatically maps `startingBranch` and `sourceContext`.
+
+### 2. Native Jules CLI Fallback (`jules new`)
+If no API key is configured, the kit seamlessly falls back to invoking your local `jules` CLI binary. Prompts are piped directly via `stdin` to bypass OS `ARG_MAX` shell argument length limits.
+
+### 3. MCP (Model Context Protocol) Directives
+All task dispatches dynamically inject `<MCP_DIRECTIVE>` envelopes into task prompts:
+```xml
+<MCP_DIRECTIVE>
+  <system_state>HEADLESS_CI_MODE</system_state>
+  <strict_invariants>
+    <rule>1. READ-BEFORE-WRITE: Inspect symbol definitions before editing.</rule>
+    <rule>2. VERIFICATION LOOP: Execute test_cmd and pass with 0 errors.</rule>
+    <rule>3. ABORT CONDITION: Terminate on 4+ repeated test failures.</rule>
+    <rule>4. ASSERTION QUALITY: Unit tests created or modified MUST contain explicit assertions.</rule>
+  </strict_invariants>
+</MCP_DIRECTIVE>
+```
+This forces Jules to adhere to strict read-before-write invariants and deterministic execution when operating alongside MCP server tools.
+
+</details>
 
 ---
 
-## ⚙️ Configuration (`.agent/jules.yml`)
-
-```yaml
-# Google Jules Repository Configuration (Version 2)
-version: 2
-test_cmd: "npm test"
-build_cmd: "npm run build"
-forbidden_paths:
-  - ".github/**"
-  - "**/secrets/**"
-  - "**/*.pem"
-  - "**/lock-manager/**"
-  - "scripts/jules-*"
-  - ".agent/jules.yml"
-allow_paths: []
-```
+<details>
+<summary><b>🤝 Contributing & Code Guidelines</b></summary>
 
-> 🛡️ **Security Trust Model**: `allow_paths` is read **strictly from the target base branch** (`origin/main`), never from untrusted PR branches. Any path specified in `allow_paths` on `main` overrides the immutable default forbidden paths for automated background workers.
+We welcome contributions! Please follow these core principles when submitting Pull Requests:
 
+1. **Zero External Dependencies**: Keep the orchestrator engine 100% dependency-free. Use ONLY native Node.js built-in modules (`node:fs`, `node:path`, `node:child_process`, `node:crypto`, `node:util`).
+2. **Verification Suite**: Ensure 100% of unit tests pass cleanly (`npm test`).
+3. **Conventional Commits**: Use standardized commit message prefixes (`feat:`, `fix:`, `docs:`, `test:`, `chore:`).
+4. **Cross-Platform Compatibility**: Always normalize Windows backslashes (`\`) to POSIX slashes (`/`) for glob patterns and paths.
 
+</details>
 
 ---
 
@@ -135,5 +265,3 @@ allow_paths: []
 MIT License - feel free to use, modify, and share!
 
 *Disclaimer: This is an independent open-source orchestration tool and is not officially affiliated with or endorsed by Google.*
-
-