jules-orchestrator-kit 0.1.9 → 0.2.8

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:25:41.107Z"
+---
+# 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,24 @@
+name: Auto Publish to npm
+
+on:
+  release:
+    types: [published]
+  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`
+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` -> `npm test` (or `npm run lint && npm test` if lint script exists)
 - `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
+- 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,90 +1,161 @@
-# 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
 ```
 
-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`).
+### 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).*
 
-## 💡 What This Toolkit Provides
+---
 
-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.
+## 🧠 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
+```
 
-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).
+</details>
 
 ---
 
-## 🛠️ Usage Examples
+## 💡 Core Capabilities (8 Component Suite)
 
-### Dispatch a single task to Jules
+### 🛠️ The Basics
 
-```bash
-node scripts/jules-dispatch.mjs "Refactor rate limiter" "Implement sliding window rate limiting using Redis. Must pass tests."
-```
+* **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).
 
-### Dispatch an entire queue of markdown task specifications
+### 🔒 Security & Guardrails
 
-```bash
-npm run jules:queue
-```
+* **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.
 
-```bash
-JULES_SWARM_CONCURRENCY=5 node scripts/jules-swarm.mjs tasks.json
-```
+### 🐝 Advanced Orchestration
 
-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" }
-]
-```
+* **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.
 
-### Run Nightly Maintenance Suite
+---
 
-```bash
-node scripts/jules-nightly.mjs --dry-run
-```
+## ⚙️ Configuration & Zero-Trust Security
 
-### Audit Jules PRs before merging
+The orchestrator creates an `.agent/jules.yml` file to manage repo-level verification and security:
 
-```bash
-node scripts/jules-self-audit.mjs
+```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: []
 ```
 
----
+> 🛡️ **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.
 
-## 🛠️ Supported Language Manifests & Workspace Graphs
+---
 
-The command resolver automatically sniffs your codebase and invokes the right verification chain:
+<details>
+<summary><b>🛠️ Supported Language Manifests & Workspace Graphs (15+ Tech Stacks)</b></summary>
 
 | Stack / Ecosystem | Manifest / Workspace File | Default Verification Command |
 |---|---|---|
@@ -93,40 +164,98 @@ The command resolver automatically sniffs your codebase and invokes the right ve
 | **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` |
+| **JavaScript / TypeScript** | `package.json` | `npm run lint && npm test` (or `npm run check:all`) |
 | **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` |
+| **Java (Maven/Gradle)** | `pom.xml` / `build.gradle` | `mvn test` / `./gradlew test` |
 | **C / C++** | `Makefile` | `make test && make build` |
-| **Custom Config (v2)** | `.agent/jules.yml` | Configurable `test_cmd`, `build_cmd`, `forbidden_paths` & `allow_paths` |
+
+</details>
 
 ---
 
-## ⚙️ Configuration (`.agent/jules.yml`)
+<details>
+<summary><b>📖 Advanced Workflows (Queues, Swarms, Nightly Maintenance)</b></summary>
 
-```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: []
+### 1. Process an entire queue of background tasks
+
+```bash
+npm run jules:queue
 ```
 
-> 🛡️ **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.
+### 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 JULES_USE_WORKTREES=true node scripts/jules-swarm.mjs tasks.json
+```
+
+*(Example `tasks.json` constraint: `[ { "id": "t1", "prompt": "Refactor auth", "scope": ["src/auth/**"] } ]`)*
+
+### 3. Run Nightly Maintenance Suite
+
+```bash
+node scripts/jules-nightly.mjs --dry-run
+```
+
+### 4. Audit Jules PRs before merging in CI
+
+```bash
+node scripts/jules-self-audit.mjs
+```
+
+</details>
+
+---
+
+<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>
+
+---
+
+<details>
+<summary><b>🤝 Contributing & Code Guidelines</b></summary>
+
+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 +264,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.*
-
-

package/bin/init.js

@@ -3,6 +3,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import readline from "node:readline/promises";
 import { resolveProjectCommands } from "../scripts/command-resolver.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -10,8 +12,27 @@ const __dirname = path.dirname(__filename);
 const kitRoot = path.resolve(__dirname, "..");
 const targetDir = process.cwd();
 
-const isHelp = process.argv.includes("--help") || process.argv.includes("-h");
-const isForce = process.argv.includes("--force") || process.argv.includes("-f");
+let isHelp = false;
+let isForce = false;
+let isInteractive = false;
+
+try {
+  const { values } = parseArgs({
+    options: {
+      help: { type: "boolean", short: "h", default: false },
+      force: { type: "boolean", short: "f", default: false },
+      interactive: { type: "boolean", short: "i", default: false },
+    },
+    allowPositionals: true,
+  });
+  isHelp = values.help;
+  isForce = values.force;
+  isInteractive = values.interactive;
+} catch (err) {
+  isHelp = process.argv.includes("--help") || process.argv.includes("-h");
+  isForce = process.argv.includes("--force") || process.argv.includes("-f");
+  isInteractive = process.argv.includes("--interactive") || process.argv.includes("-i");
+}
 
 if (isHelp) {
   console.log(`
@@ -22,8 +43,9 @@ Usage:
   npx jules-init [options]
 
 Options:
-  -f, --force    Overwrite existing AGENTS.md, .agent/jules.yml, and orchestration scripts.
-  -h, --help     Show this help message.
+  -f, --force          Overwrite existing AGENTS.md, .agent/jules.yml, and orchestration scripts.
+  -i, --interactive    Launch interactive wizard to prompt for repository and branch configuration.
+  -h, --help           Show this help message.
 `);
   process.exit(0);
 }
@@ -32,6 +54,52 @@ console.log("\n🚀 Initializing Google Jules Orchestration Kit...\n");
 console.log(`📁 Target Directory: ${targetDir}`);
 if (isForce) console.log("⚠️ Force mode enabled (existing files will be overwritten).");
 
+let answerRepoVal = "";
+let answerBranchVal = "";
+
+// Dual TTY Interactive Wizard
+if (process.stdin.isTTY && (isInteractive || (!fs.existsSync(path.join(targetDir, ".agent/jules.yml")) && !process.env.CI))) {
+  try {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answerRepo = await rl.question("📦 Enter target GitHub repository (e.g. owner/repo) [optional]: ");
+    if (answerRepo.trim()) {
+      answerRepoVal = answerRepo.trim();
+      process.env.JULES_REPO = answerRepoVal;
+    }
+    const answerBranch = await rl.question("🌿 Enter base branch [default: main]: ");
+    if (answerBranch.trim()) {
+      answerBranchVal = answerBranch.trim();
+      process.env.BASE_BRANCH = answerBranchVal;
+    }
+    rl.close();
+  } catch (err) {
+    console.warn("⚠️ Interactive setup prompt failed:", err.message);
+  }
+}
+
+// 0. Persist wizard values to .env if provided
+const envPath = path.join(targetDir, ".env");
+let envAdditions = [];
+if (answerRepoVal) envAdditions.push(`JULES_REPO="${answerRepoVal}"`);
+if (answerBranchVal) envAdditions.push(`BASE_BRANCH="${answerBranchVal}"`);
+
+if (envAdditions.length > 0) {
+  if (fs.existsSync(envPath)) {
+    const existingEnv = fs.readFileSync(envPath, "utf-8");
+    const toAppend = envAdditions.filter((line) => {
+      const key = line.split("=")[0];
+      return !existingEnv.includes(`${key}=`);
+    });
+    if (toAppend.length > 0) {
+      fs.appendFileSync(envPath, `\n${toAppend.join("\n")}\n`, "utf-8");
+      console.log("✅ Appended interactive configuration to .env");
+    }
+  } else {
+    fs.writeFileSync(envPath, `${envAdditions.join("\n")}\n`, "utf-8");
+    console.log("✅ Created: .env with repository configuration");
+  }
+}
+
 // 1. Detect Stack & Manifests
 const detected = resolveProjectCommands(targetDir);
 console.log(`🔍 Detected Project Type: ${detected.source}`);
@@ -102,6 +170,21 @@ if ((!fs.existsSync(reviewTarget) || isForce) && fs.existsSync(reviewSource)) {
   console.log("✅ Created: .agent/workflows/jules-review.md");
 }
 
+// Scaffold .github/workflows/jules-audit.yml
+const githubWorkflowsDir = path.join(targetDir, ".github/workflows");
+const auditWfSource = path.join(kitRoot, ".github/workflows/jules-audit.yml");
+const auditWfTarget = path.join(githubWorkflowsDir, "jules-audit.yml");
+
+if (fs.existsSync(auditWfSource)) {
+  if (!fs.existsSync(githubWorkflowsDir)) {
+    fs.mkdirSync(githubWorkflowsDir, { recursive: true });
+  }
+  if (!fs.existsSync(auditWfTarget) || isForce) {
+    fs.copyFileSync(auditWfSource, auditWfTarget);
+    console.log("✅ Scaffolded CI Audit Workflow: .github/workflows/jules-audit.yml");
+  }
+}
+
 // 4. Copy scripts/ directory with PER-FILE existence guard
 const targetScriptsDir = path.join(targetDir, "scripts");
 if (!fs.existsSync(targetScriptsDir)) {
@@ -121,7 +204,9 @@ if (fs.existsSync(sourceScriptsDir)) {
       fs.copyFileSync(srcFile, destFile);
       try {
         fs.chmodSync(destFile, 0o755);
-      } catch (_) {}
+      } catch (err) {
+        console.warn(`⚠️ Could not set executable permissions on ${file}:`, err.message);
+      }
       copiedCount++;
     } else {
       skippedCount++;
@@ -156,7 +241,9 @@ if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
       fs.writeFileSync(targetPkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
       console.log("✅ Injected jules:* helper scripts into package.json");
     }
-  } catch (_) {}
+  } catch (err) {
+    console.warn("⚠️ Failed to inject helper scripts into target package.json:", err.message);
+  }
 }
 
 console.log("\n🎉 Google Jules Orchestration Kit successfully initialized!");
@@ -164,4 +251,3 @@ console.log("\nNext Steps:");
 console.log("  1. Set environment variables: JULES_REPO=\"owner/repo\"");
 console.log("  2. Dispatch your first task:  node scripts/jules-dispatch.mjs \"Task Title\" \"Task prompt\"");
 console.log("  3. Run pre-merge PR audit:    node scripts/jules-self-audit.mjs\n");
-