jules-orchestrator-kit 0.9.4 → 0.21.0

package/.agent/prompts/Janitor.md

@@ -0,0 +1,11 @@
+# Janitor Protocol: Technical Debt & Dead Code Elimination
+
+You are **Janitor**, a specialist autonomous agent optimized for technical debt elimination, dead code pruning, and strict zero-dependency refactoring.
+
+## Strict Operational Invariants
+
+1. **Zero External Runtime Dependencies**: You are STRICTLY FORBIDDEN from adding third-party npm packages. Use ONLY native Node.js ESM built-in modules (`node:fs`, `node:path`, `node:crypto`, `node:child_process`, `node:os`).
+2. **Dead Code Elimination**: Prune unused variables, unreachable branches, and redundant helper functions.
+3. **Atomic Payload Limit**: Keep total patch payload under 75 KB (`git diff | wc -c`).
+4. **Verification Requirement**: Execute `npm test` and `npm run lint` to ensure 100% of tests pass with 0 lint errors before completing work.
+5. **No Assert Weakening**: Never weak or remove test assertions to make a test pass.

package/README.md

@@ -1,319 +1,321 @@
 # jules-orchestrator-kit
 
-*Disclaimer: This is an independent open-source orchestration tool and is not officially affiliated with or endorsed by Google.*
+*Disclaimer: This is an independent open-source orchestration tool for Google Jules and is not officially affiliated with or endorsed by Google.*
 
 [![Jules PR Audit](https://github.com/FullThrottle83/jules-orchestrator-kit/actions/workflows/jules-audit.yml/badge.svg)](https://github.com/FullThrottle83/jules-orchestrator-kit/actions/workflows/jules-audit.yml)
 [![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 Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
 
-**Turn Google Jules into an autonomous code builder that writes, tests, and fixes itself.**
-The orchestrator automates verification, scopes file boundaries, and prevents Jules from breaking your CI.
+> **High-Volume Autonomous Orchestration Engine for Google Jules**  
+> Built specifically to execute 300+ daily agent sessions and parallel swarms safely. Zero external runtime dependencies. Built strictly on native Node.js 18+ ESM.
 
-> [!WARNING]
-> **Alpha Release:** This kit is in active development. Please exercise caution before integrating it into critical production pipelines.
+---
+
+![Autonomous Orchestration Pipeline](docs/assets/hero-flow.svg?v=3)
 
-> [!CAUTION]
-> **Task Limit Warning:** Autonomous loops can quickly consume your daily API limits. We strongly recommend starting with `JULES_DRY_RUN=1` to understand the workflow before scaling up.
+---
 
-## Prerequisites
-To use this kit, you will need:
-- Node.js `18.0.0` or higher
-- `git` installed and available in your PATH
-- A Google Jules REST API key (set as `JULES_API_KEY`) **OR** the native `jules` binary in your PATH.
+## ⚡ 2-Minute Quickstart
+
+Get up and running in under 2 minutes with zero complex configuration:
 
-## Quick Start
-Initialize your repository:
 ```bash
+# 1. Initialize orchestrator structure in your target codebase
 npx jules-orchestrator-kit init
+
+# 2. Dispatch an autonomous task (Dry-Run mode for local simulation)
+JULES_DRY_RUN=1 npx agentctl dispatch \
+  --title "Add JWT Validator" \
+  --prompt "Implement JWT validation middleware with unit tests"
+
+# 3. Run the 4-phase security & verification gatekeeper
+npx agentctl gate
+
+# 4. Connect as a native stdio MCP server (for Claude Code, Cursor, or Antigravity)
+npx agentctl mcp
 ```
 
-Dispatch a task or run the queue using `agentctl`:
+> 📖 **Looking for production deployment patterns?**  
+> Check out [**EXAMPLES.md**](./EXAMPLES.md) for 6 real-world recipes (Nightly TODO Scanner, Composite CI Action, Multi-Worktree Swarms, OODA Auto-Fix, MCP IDE setup, and Specialist Rosters).
+
+---
+
+## 🎯 Why jules-orchestrator-kit?
+
+Whether you are dispatching your first automated coding task or managing high-throughput CI/CD swarms across large engineering teams, `jules-orchestrator-kit` provides total operational safety:
+
+| Feature | 🐣 For Rookies & Beginners | 🛠️ For Senior Developers & Infrastructure Engineers |
+| :--- | :--- | :--- |
+| **Safety First** | Never breaks `main` branch or pushes failing code. | 4-Phase Safety Gatekeeper fails closed on scope drift, high entropy secrets, or test regressions. |
+| **Token Budget Protection** | Prevents runaway loops from burning API quotas. | Sliding-window OODA thrash detector ($A \rightarrow B \rightarrow A \rightarrow B$) halts non-convergent repair cycles automatically. |
+| **Zero Setup Hassle** | Works out of the box with standard `npm test`. | **Zero External Runtime Dependencies** (`node:fs`, `node:path`, `node:crypto`, `node:child_process`). |
+| **Multi-Agent Swarms** | Run multiple tasks simultaneously without conflict. | Deterministic VFS mutex and 3-way structural merge engine resolve parallel worktree changes cleanly. |
+| **IDE & Tooling** | Seamlessly connects to your favorite editor. | Native Model Context Protocol (MCP) server over memory-bounded stdio streams. |
+
+---
+
+<details open>
+<summary><b>⚙️ Control Plane Architecture & Deep Dive</b></summary>
+
+<br/>
+
+![Control Plane Architecture Layers](docs/assets/architecture-layers.svg?v=3)
+
+<br/>
+
+![Self-Healing OODA Loop](docs/assets/ooda-loop-cycle.svg?v=3)
+
+### Engine System Highlights
+
+- **Linearizable VFS Mutex (`src/state.mjs`)**: Kernel-level directory mutex (`withVfsMutex`) guaranteeing serial linearizability for SHA-256 hash-chained session ledgers under high concurrency.
+- **PID Recycling & Stale Lock Protection (`src/state.mjs`)**: Linux `/proc/<pid>/stat` launch-time validation prevents false-positive lock reaps from recycled OS process IDs.
+- **Memory-Bounded Content-Length MCP Streaming (`src/mcp.mjs`)**: Native MCP server over stdio streams using `McpFrameDecoder` with a 4 MB memory safety ceiling and panic boundaries to prevent stdout stack trace leaks.
+- **Process Group Isolation (`src/process-group.mjs`)**: `ProcessGroupManager` creates isolated process groups (`detached: true`) and catches `SIGINT`/`SIGTERM`/`exit` signals to execute `process.kill(-pgid)`, guaranteeing zero zombie processes.
+- **TOCTOU & Symlink Defense (`src/security.mjs`)**: `safeAtomicWrite()` uses `O_CREAT | O_EXCL | O_WRONLY` temp files with `fsyncSync` + `renameSync` and `lstatSync`/`realpathSync` symlink checks.
+- **3-Way Structural AST/JSON Merge (`scripts/jules-merge-swarm.mjs`)**: Pure Node `deepMerge3Way()` algorithm for recursive object and array merges executed in isolated temporary directories (`os.tmpdir()`).
+
+</details>
+
+<details>
+<summary><b>🛡️ Zero-Trust Security Gatekeeper</b></summary>
+
+<br/>
+
+![Zero-Trust Security Guarantees](docs/assets/security-shield.svg?v=3)
+
+### The 4-Phase Safety Audit (`agentctl gate`)
+
+1. **Scope Fencing (`forbidden_paths`)**: Ensures agents cannot modify protected files (`package.json`, `.github/`, deployment keys) without explicit overrides.
+2. **Diff Payload Governor**: Rejects oversized diffs (> 75 KB) to prevent truncation and hidden payload injections.
+3. **Secret Entropy Scanner**: Scans diffs for high-confidence secrets (AWS keys, Stripe keys, GitHub tokens, SSH private keys) using Shannon Entropy analysis (> 3.6 bits).
+4. **Trusted Verification Suite**: Executes auto-detected unit tests and linters (`npm test`) to guarantee zero regressions before merging.
+
+> [!NOTE]
+> All security rules are fetched strictly from `origin/main` (never untrusted PR branches) to prevent prompt-injection attacks from altering security rules.
+
+</details>
+
+<details>
+<summary><b>🔌 Model Context Protocol (MCP) & IDE Integration</b></summary>
+
+<br/>
+
+![Dual-Way MCP Integration](docs/assets/mcp-integration.svg?v=3)
+
+### Connecting to Claude Desktop, Cursor, or Antigravity
+
+Start the native stdio MCP server:
+
 ```bash
-agentctl dispatch --title "Refactor Auth" --prompt "Implement JWT verification in auth handler"
-agentctl queue
-agentctl gate
+npx agentctl mcp
 ```
 
-> 💡 **Unified Engine CLI (`agentctl`)**:
-> `agentctl` is the zero-dependency CLI executable that powers dispatching, safety gate auditing, mutex locks, and swarm management across all project types (Node, Rust, Go, Python, etc.).
-> Legacy `scripts/jules-*.mjs` shims are preserved for backward compatibility.
+#### MCP Tool Registry Exposed:
+- `dispatch_jules_task`: Dispatch autonomous coding tasks directly from your LLM prompt.
+- `audit_jules_gate`: Execute the 4-phase safety gate against the workspace.
+- `check_risk_tier`: Classify workspace changes into Risk Tiers (R0 Cosmetic to R3 Restricted).
+- `get_jules_status`: Fetch real-time status of active, pending, and completed tasks.
 
----
+</details>
 
-## How It Works
-
-1. **You Assign Task:** Define what needs fixing or building (supports text and multimodal image mockups).
-2. **Jules Writes Code:** Proposes changes in an isolated Git worktree sandbox.
-3. **Run Tests & Linters:** The Gatekeeper runs your test suite, linters, and type checks.
-4. **Self-Correction:** If anything fails, Jules automatically retries with fixes (OODA loop).
-5. **Safe Delivery:** Once tests pass, the PR is verified and ready for review.
-
-```mermaid
-sequenceDiagram
-    autonumber
-    
-    box "Client Edge" #F4F4F4
-        actor Trigger as Client (CLI / CI / SDK)
-    end
-    
-    box "Control Plane" #E8F4F8
-        participant Orc as Orchestrator Core
-        participant Envelope as Task Envelope Validator
-        participant Gate as Self-Audit Gatekeeper
-    end
-    
-    box "Execution Sandbox" #F8E8E8
-        participant API as Google Jules API
-        participant Git as Git Worktree Sandbox
-    end
-
-    Trigger->>+Orc: Dispatch Task Payload / Envelope
-    
-    note over Orc,Envelope: Phase 1: Pre-Flight Premise & Security Validation
-    Orc->>+Envelope: Validate Envelope (referenced_paths exist? base commit fresh?)
-    alt Premise Failure / Missing Referenced Paths / Stale Base
-        Envelope-->>Orc: Validation Failed (Premise Error)
-        Orc-->>Trigger: Abort Pre-Dispatch (Exit 1)
-    else Envelope Validated
-        Envelope-->>-Orc: Envelope Approved
-        Orc->>Orc: Redact Secrets (Entropy > 3.6) & Enforce Dynamic Guardrails
-        Orc->>+Git: Provision Isolation Sandbox (git worktree)
-        Git-->>-Orc: Sandbox Ready
-    end
-    
-    loop OODA Repair Cycle (Max 3 Retries)
-        note over Orc,Git: Phase 2: Agent Execution & Dispatch
-        Orc->>+API: Dispatch Task + <MCP_DIRECTIVE> & Target Scope
-        API->>+Git: Apply Proposed Code Changes
-        Git-->>-API: Changes Written
-        API-->>-Orc: Execution Complete
-        
-        note over Orc,Gate: Phase 3: Multi-Gate Verification & Risk Classification
-        Orc->>+Gate: Trigger Self-Audit (trusted origin/main rules)
-        
-        Gate->>+Git: Run Scope, Payload & Stale-Base Audit (`git diff`)
-        Git-->>-Gate: Diff Stats & Base Commit Age
-        
-        alt Scope Breach / Payload > 75 KB / Stale Base > 25 commits
-            Gate-->>Orc: Security / Scope / Stale-Base Violation
-            Orc->>Orc: Record Telemetry (metrics.jsonl)
-            Orc-->>Trigger: Abort Execution (Exit 3)
-            break Fatal Security or Base Error
-                Orc->>Git: Teardown Worktree Sandbox
-            end
-        else Static Scope & Base Passed
-            Gate->>Gate: Classify Risk Tier (R0 Cosmetic, R1 Routine, R2 Consequential, R3 Restricted)
-            Gate->>+Git: Run Integrity Checks (Asset Magic-Bytes, Rules Budget, testCmd & buildCmd)
-            Git-->>-Gate: Execution & Integrity Proof (stdout/stderr)
-        end
-
-        alt 100% Verification Suite & Integrity Passed
-            Gate-->>-Orc: Verification Success + Risk Tier Metadata
-            Orc->>+Git: Commit & Push to Remote Branch / PR
-            Git-->>-Orc: PR Ready (Attached Execution Receipts)
-            Orc->>Orc: Record Telemetry (metrics.jsonl)
-            Orc-->>Trigger: Dispatch Succeeded (Exit 0)
-            break Task Completed
-                Orc->>Git: Teardown Worktree Sandbox
-            end
-        else Verification Failed
-            Gate-->>Orc: Verification Failed (Stderr Trace output)
-            Orc->>Orc: Record Failure Telemetry
-            
-            alt Retries Remaining (< 3)
-                Orc->>Orc: Construct Repair Prompt with Stderr Trace
-            else Max Retries Exceeded (3/3)
-                Orc-->>-Trigger: Abort & Log Diagnostic Feedback (Exit 4)
-                Orc->>Git: Teardown Worktree Sandbox
-            end
-        end
-    end
+<details>
+<summary><b>🤖 Specialist Agent Prompt Presets (.agent/prompts/)</b></summary>
+
+<br/>
+
+Specialized prompt presets enforcement payload limits (< 75 KB) and domain guardrails out of the box:
+
+| Preset | Role & Domain | Primary Focus |
+| :--- | :--- | :--- |
+| **`Overseer.md`** | **Architect & Supervisor** | System-wide refactoring, linearizable state, and structural integrity. |
+| **`Bolt.md`** | **Performance Engineer** | Bottleneck elimination, streaming optimization, and low-latency execution. |
+| **`Sentinel.md`** | **Security Auditor** | Vulnerability patching, secret sanitization, and TOCTOU defense. |
+| **`Janitor.md`** | **Technical Debt & Cleanup** | Dead code elimination, unused import pruning, and zero-dependency compliance. |
+
+```bash
+# Example: Dispatch a cleanup task using the Janitor preset
+npx agentctl dispatch \
+  --prompt "$(cat .agent/prompts/Janitor.md) Prune unused helper methods in src/utils.mjs"
 ```
 
-> 💡 **Core Architectural Invariants**:
-> - **Task Envelope Premise Validation**: Pre-flight checks verify referenced paths and base freshness before dispatching tasks to prevent session burnout.
-> - **Risk Tier Classification Engine (R0–R3)**: Classifies changes by blast radius to route auto-merge vs mandatory human review.
-> - **Zero-Trust Base-Branch Security**: Security rules (`forbidden_paths`) are fetched exclusively from `origin/main` (never untrusted PR branches).
-> - **Asset & Rules Integrity**: Guards binary assets against HTML corruption and enforces character/line budgets on rule files.
-> - **Automatic PII & Secret Redaction**: Outbound task prompts are automatically sanitized to redact API secrets and mask sensitive PII (emails, IPs, phone numbers).
-> - **Ledger Hash-Chain Integrity**: Hashing over JSONL event streams detects unauthorized log tampering or record deletions.
->
-> 🔍 For a deep dive into the execution protocol, see the [Architecture & Pipeline Flow](docs/architecture.md).
+</details>
 
----
+<details>
+<summary><b>⚡ GitHub Actions Composite Action (.github/actions/setup-jules)</b></summary>
+
+<br/>
+
+Integrate `jules-orchestrator-kit` into any GitHub Actions workflow with 3 lines of YAML:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: FullThrottle83/jules-orchestrator-kit/.github/actions/setup-jules@main
+    with:
+      action: 'gate'
+      base_branch: 'main'
+      tier: 'ultra'
+    env:
+      JULES_API_KEY: ${{ secrets.JULES_API_KEY }}
+```
+
+</details>
+
+<details>
+<summary><b>🛠️ CLI Command Reference (`agentctl`)</b></summary>
+
+<br/>
+
+| Command | Usage Example | Description |
+| :--- | :--- | :--- |
+| **`init`** | `npx agentctl init` | Initializes `.agent/` configuration, workflows, and task queue directory |
+| **`dispatch`** | `agentctl dispatch --title "Fix Bug" --prompt "..."` | Dispatches an autonomous task to Google Jules |
+| **`gate`** | `agentctl gate [--fix] [--base main]` | Runs 4-phase safety gatekeeper audit against workspace |
+| **`queue`** | `agentctl queue` | Processes pending task queue sequentially from `.agent/jules-queue/` |
+| **`swarm`** | `agentctl swarm` | Launches parallel multi-agent swarm in isolated git worktrees |
+| **`merge-swarm`** | `agentctl merge-swarm` | Performs 3-way structural merge on completed swarm PRs |
+| **`mcp`** | `agentctl mcp` | Starts stdio Model Context Protocol (MCP) JSON-RPC 2.0 server |
+| **`doctor`** | `agentctl doctor` | Verifies stack configuration, environment keys, and daily token budget |
+| **`scan`** | `agentctl scan` | Scans codebase for `TODO` and `FIXME` comments and generates task queue |
+| **`cleanup`** | `agentctl cleanup` | Audits and cleans up stale git worktrees and temporary state files |
+
+</details>
+
+<details>
+<summary><b>💳 Subscription Tier Presets (Free / Pro / Ultra)</b></summary>
+
+<br/>
 
-## Configuration
+![Subscription Tier Presets Matrix](docs/assets/tier-presets.svg?v=3)
 
-The orchestrator automatically detects your tech stack, but you can edit `.agent/jules.yml` for fine-grained control:
+<br/>
+
+Tailor session limits and rate-limiting behavior to your Google Jules API subscription tier:
+
+| Tier | `dailyTasks` | `repairAttempts` | `concurrency` | `staggerMs` | Target Usage |
+| :--- | :---: | :---: | :---: | :---: | :--- |
+| **`free`** | `15` | `1` | `1` | `3000 ms` | **Hobby / Free Tier:** Conserves quota, prevents HTTP 429 rate limits. |
+| **`pro`** | `100` | `2` | `2` | `1500 ms` | **Developer Pro:** Balanced throughput for everyday work. |
+| **`ultra`** *(default)* | `300` | `3` | `3` | `1000 ms` | **Swarm / Enterprise:** Maximum parallel throughput & CI/CD. |
+
+**How to activate:**
+- **Environment Variable:** `export JULES_TIER=free` (or set in `.env`)
+- **Config File (`.agent/jules.yml`):** Set `tier: free`
+
+</details>
+
+<details>
+<summary><b>📝 Configuration Reference (`.agent/jules.yml`)</b></summary>
+
+<br/>
+
+Auto-generated by `agentctl init` at the root of your project:
 
 ```yaml
-# Google Jules Repository Configuration (Version 2)
 version: 2
+tier: "pro" # Options: free, pro, ultra (default: ultra)
 test_cmd: "npm test"
 build_cmd: "npm run build"
 forbidden_paths:
-  - ".github/**"
-  - "**/secrets/**"
-  - "**/*.pem"
-  - "**/lock-manager/**"
-  - "scripts/jules-*"
+  - ".github/"
+  - "package.json"
   - ".agent/jules.yml"
 allow_paths: []
+limits:
+  dailyTasks: 300
+  repairAttempts: 3
+  diffKb: 75
 ```
 
----
+</details>
 
-## Expand with MCP
+<details>
+<summary><b>🚦 Exit Code Registry & Troubleshooting</b></summary>
 
-All task dispatches dynamically inject `<MCP_DIRECTIVE>` envelopes into task prompts. This forces Jules to adhere to strict read-before-write invariants.
+<br/>
 
-You can supercharge Jules with external MCP servers by connecting them to your environment, granting Jules direct access to your infrastructure and real-time documentation. Examples:
-* **SaaS APIs & Tooling:** Context 7, Linear, and v0.
-* **Databases & Cloud:** Render, Neon, Supabase, Stitch.
-* **Framework Documentation:** Astro Docs, Cloudflare Docs, Next.js Docs.
+Standardized exit codes enforced across all CLI utilities:
 
----
+| Exit Code | Status | Description & Immediate Action |
+| :---: | :--- | :--- |
+| `0` | **Success** | Task completed cleanly; PR opened or verification passed. |
+| `1` | **Pre-Dispatch / Arg Error** | Invalid arguments, prompt > 50 KB, or pre-dispatch validation error. |
+| `2` | **API / Network Failure** | Jules API rate-limit (HTTP 429), `FAILED_PRECONDITION` quota, or timeout. |
+| `3` | **Scope Violation** | Attempted modification of restricted files (`.github/`, command files, agent rules). |
+| `4` | **OODA Exhausted / Thrash** | Verification suite failed after 3 repair attempts or hit deterministic regression. |
+| `5` | **Diff Payload Limit** | Post-change git diff exceeds payload budget (`limits.diffKb`, default 75 KB). |
+| `6` | **Secret Detected** | High-confidence secret or private key detected in patch diff. |
+| `7` | **Budget Exhausted** | Daily task session quota limit reached (`limits.dailyTasks`, default 300). |
 
-## Integration Interfaces
+</details>
 
-The orchestrator supports three primary integration channels:
+<details>
+<summary><b>🔐 Environment Variables Reference</b></summary>
 
-**1. Direct REST API Mode (`jules.googleapis.com`)**
-When `JULES_API_KEY` and `JULES_REPO` are present in your environment, payloads are dispatched directly to the official Google Jules REST API endpoint. Handles HTTP 429 rate limits gracefully.
+<br/>
 
-**2. Native Jules CLI Fallback**
-If no API key is configured, the kit seamlessly falls back to invoking your local `jules` CLI binary via standard streams.
+| Variable | Description | Default |
+| :--- | :--- | :--- |
+| `JULES_API_KEY` | Google Jules REST API key | *(none)* |
+| `JULES_REPO` | Target GitHub Repository (`owner/repo`) | Auto-detected from `git remote` |
+| `JULES_TIER` | Subscription tier preset (`free`, `pro`, `ultra`) | `ultra` |
+| `JULES_DRY_RUN` | Set to `1` or `true` for dry-run simulation mode | `false` |
+| `JULES_DAILY_BUDGET` | Custom daily session budget limit | `300` |
+| `JULES_MAX_DIFF_KB` | Custom git diff payload limit in KB | `75` |
+| `JULES_ALLOW_COMMAND_FILE_CHANGES` | Allow PR changes to command files (`package.json`, etc.) | `false` |
+| `JULES_ALLOW_AGENT_RULE_CHANGES` | Allow PR changes to agent rule files (`AGENTS.md`, etc.) | `false` |
+| `BASE_BRANCH` | Base branch for PR Audits & Merge-Base checks | `main` |
+| `NO_COLOR` | Set to `true` to disable ANSI color output | `false` |
 
-**3. Programmatic Node.js SDK (`index.mjs`)**
-Downstream Node.js tools, MCP servers, and LLM orchestrators can import kit functions directly:
-```js
-import { gate, dispatch, validateEnvelope, classifyRiskTier, checkAssetIntegrity, checkRulesBudget, redactSecrets } from "jules-orchestrator-kit";
+</details>
 
-// Anonymize sensitive PII (emails, IPs, phone numbers) before sending prompts
-const cleanPrompt = anonymizePii("Contact support at john@example.com");
+<details>
+<summary><b>🌐 Supported Tech Stacks & Auto-Detection</b></summary>
 
-// Programmatically dispatch tasks
-await dispatch({ title: "Refactor Auth", prompt: cleanPrompt });
+<br/>
 
-// Run 4-phase safety gate audit
-const audit = await gate({ base: "main" });
-```
+The orchestrator automatically infers verification and build commands across ecosystems:
 
----
+| Stack / Ecosystem | Manifest File | Inferred Test Command | Inferred Build Command |
+| :--- | :--- | :--- | :--- |
+| **Turborepo** | `turbo.json` | `npx turbo run test` | `npx turbo run build` |
+| **pnpm Workspace** | `pnpm-workspace.yaml` | `pnpm test` | `pnpm build` |
+| **Nx Workspace** | `nx.json` | `npx nx run-many -t test` | `npx nx run-many -t build` |
+| **JavaScript / TypeScript** | `package.json` | `npm test` | `npm run build` |
+| **Rust** | `Cargo.toml` | `cargo test --workspace` | `cargo build` |
+| **Go** | `go.mod` | `go test ./...` | `go build ./...` |
+| **Python** | `pyproject.toml` | `pytest` | *(none)* |
+| **Bun / Deno** | `bunfig.toml` / `deno.json` | `bun test` / `deno test` | `bun run build` |
+| **Elixir / Ruby** | `mix.exs` / `Gemfile` | `mix test` / `rake test` | *(standard build)* |
+| **Java / C / C++** | `pom.xml` / `Makefile` | `mvn test` / `make test` | `mvn compile` / `make` |
 
-## Known Limitations
+</details>
 
-**Code Suggestions (Web UI Only)**
-Currently, there is no way to automatically extract "Suggestions" (the inline code review comments Jules sometimes proposes instead of direct commits) via the CLI or API. Suggestions can only be read directly inside the **Jules Web UI**.
+---
 
-*Workaround for Local LLM Users:* If you are tinkering with Jules alongside a local LLM and Jules leaves a Suggestion, the easiest workflow is to open the Jules Web UI, copy the suggestion block, and paste it back into your local LLM.
+## 🤝 Contributing & Standards
 
----
+We welcome community contributions! Please adhere to our core engineering invariants:
 
-## Supported Tech Stacks
-
-| Stack / Ecosystem           | Manifest / Workspace File             | Test Command                             | Build Command                            |
-| --------------------------- | ------------------------------------- | ---------------------------------------- | ---------------------------------------- |
-| **Turborepo**               | `turbo.json`                          | `npx turbo run test --filter=...`        | `npx turbo run build --filter=...`       |
-| **pnpm Workspace**          | `pnpm-workspace.yaml`                 | `pnpm --filter=... test`                 | `pnpm --filter=... build`                |
-| **Nx Workspace**            | `nx.json`                             | `npx nx run-many -t test -p ...`         | `npx nx run-many -t build -p ...`        |
-| **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 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`                             |
+1. **Zero External Runtime Dependencies**: Use ONLY native Node.js ESM built-in modules (`node:fs`, `node:path`, `node:crypto`, `node:child_process`, `node:os`).
+2. **100% Verification Suite**: All test suites must pass cleanly with 0 errors.
+3. **Cross-Platform Compatibility**: Always normalize Windows backslashes (`\`) to POSIX slashes (`/`).
 
----
+### Running Tests Locally
 
-## Reference Material
-
-### CLI Commands
-All commands are registered in `package.json` and can be run via `npm run <command>`.
-
-| Command | Description |
-| ------- | ----------- |
-| `npm run init` | Initializes the orchestrator and `.agent/` directory |
-| `npm run test` | Runs the orchestrator kit's own unit tests |
-| `npm run jules:dispatch` | Dispatches a single task directly to Jules |
-| `npm run jules:queue` | Runs the local queue processor (picks up tasks from `.agent/jules-queue`) |
-| `npm run jules:create` | Scaffolds a new boilerplate task markdown file |
-| `npm run jules:status` | Shows real-time 3-bucket status (Action Required, In Progress, Completed) |
-| `npm run jules:audit` | Runs the self-audit gatekeeper (verifies tests, forbidden paths, and scope) |
-| `npm run jules:cleanup` | Audits and closes merged or stale REST sessions |
-| `npm run jules:scan` | Scans the codebase for TODO/FIXME comments and generates a suggested tasks file |
-| `npm run jules:swarm` | Launches a multi-agent swarm in parallel across isolated worktrees |
-| `npm run jules:merge-swarm` | Autonomous PR merge engine with Safety Gate lock verification |
-| `npm run jules:nightly` | Nightly maintenance job (usually triggered in CI) |
-
-### Specialist Agent Prompts & Templates (`.agent/prompts/`)
-The kit includes pre-configured single-responsibility prompt presets in `.agent/prompts/`:
-- **`Overseer.md`**: Codebase architecture auditor & technical debt mapper.
-- **`Bolt.md`**: Performance micro-optimizer and payload governor (enforces < 75 KB payload diff limits).
-- **`Sentinel.md`**: Security audit specialist for input sanitization and secret scanning.
-- **`Task_Template.md`**: Machine-readable master task prompt template schema.
-
-### Environment Variables
-
-| Variable | Description |
-| -------- | ----------- |
-| `JULES_API_KEY` | Your Google Jules REST API key (required for API mode) |
-| `GEMINI_API_KEY` | Alias for `JULES_API_KEY` (fallback) |
-| `JULES_API_URL` | Override the Jules REST API URL |
-| `JULES_REPO` | Target GitHub Repository (Format: `owner/repo`) |
-| `JULES_REPOLESS` | Set to `true` or `1` to run in repoless/serverless mode |
-| `JULES_DRY_RUN` | Set to `true` or `1` to simulate dispatching without making API calls |
-| `JULES_DAILY_BUDGET` | Daily max session budget for autonomous dispatches (Default: `300`) |
-| `JULES_MAX_DIFF_KB` | Maximum git diff payload size in KB before aborting with Exit Code 5 (Default: `50`) |
-| `JULES_ALLOW_COMMAND_FILE_CHANGES` | Set to `true` to allow PR changes to command/config files like `package.json`, `tsconfig.json`, `vite.config.ts` (Default: `false`) |
-| `JULES_ALLOW_AGENT_RULE_CHANGES` | Set to `true` to allow PR changes to agent rule files like `AGENTS.md`, `JULES_RULES_TEMPLATE.md` (Default: `false`) |
-| `BASE_BRANCH` | Base branch for PR Audits & Merge-Base calculations (Default: `main`) |
-| `GITHUB_HEAD_REF` | PR Head Branch (Used dynamically by CI during OODA repair) |
-| `JULES_PROJECT_ROOT` | Root directory of the project (Auto-assigned during swarm executions) |
-| `JULES_SWARM_CONCURRENCY` | Maximum parallel dispatches for swarm runs (Default: `3`) |
-| `JULES_SWARM_STAGGER_MS` | Dispatch stagger interval in milliseconds (Default: `1500`) |
-| `JULES_PACE_MS` | Rate-limit for the `jules:queue` command (Default: `500`) |
-| `JULES_USE_WORKTREES` | Use Git Worktrees instead of cloning for swarm isolation (Default: `false`) |
-| `JULES_SLOT_INDEX` | Current slot index for partitioning tasks (Swarm mode) |
-| `JULES_SLOT_TOTAL` | Total number of slots for partitioning tasks (Swarm mode) |
-| `CI` | Set to `true` to change log output and fail-fast behaviors for CI environments |
-| `ALLOW_AUTO_REPAIR` | Set to `true` to allow OODA Auto-Repair even when running in CI |
-| `GITHUB_STEP_SUMMARY` | GitHub Actions Step Summary File Path |
-| `NO_COLOR` | Set to `true` to disable ANSI color output |
+```bash
+# Clone the repository
+git clone https://github.com/FullThrottle83/jules-orchestrator-kit.git
+cd jules-orchestrator-kit
 
-> [!NOTE]
-> **Scope Enforcement via `allow_paths`**
-> In `.agent/jules.yml`, defining `allow_paths` acts as a strict allowlist (deny-by-default). When non-empty, any file modified outside `allow_paths` will trigger a security violation (Exit Code 3). `forbidden_paths` always take absolute precedence and cannot be overridden.
-
-### Exit Codes
-The Gatekeeper (`jules-self-audit.mjs` and related scripts) uses standard exit codes to signal status to CI systems.
-
-| Code | Meaning | Action Taken |
-| ---- | ------- | ------------ |
-| `0`  | **Success** | All tests and security checks passed. |
-| `1`  | **Pre-Dispatch / Arg Error** | Missing dependencies, prompt > 50 KB, syntax error, or pre-dispatch failure. |
-| `2`  | **API / Network / Quota Error** | REST API HTTP 429 rate limit, HTTP 400 `FAILED_PRECONDITION` quota (~30 active limit), or connection timeout. |
-| `3`  | **Security / Scope Violation** | Modified file breached `forbidden_paths` or changed command-defining files (`package.json`, `Cargo.toml`). Fails closed immediately. |
-| `4`  | **Verification Exhausted** | Tests failed and the OODA Auto-Repair loop either exhausted its max retries (3) or is disabled. |
-| `5`  | **Diff Payload Limit** | Diff payload size exceeded payload governor budget (`JULES_MAX_DIFF_KB`, default 50 KB). Split task. |
-| `6`  | **Secret Leak Prevented** | High-confidence secret or private key pattern detected in diff. Aborted immediately. |
-| `7`  | **Budget Exhausted** | Daily session budget limit reached or budget state locked. |
+# Run ESLint & node unit test suite (100% zero external runtime deps)
+npm run lint
+npm test
+```
 
 ---
 
-## Contributing
-We welcome contributions! Please follow these core principles:
-1. **Zero Runtime Dependencies**: 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 prefixes (`feat:`, `fix:`, `docs:`, `test:`, `chore:`).
-4. **Cross-Platform Compatibility**: Normalize Windows backslashes (`\`) to POSIX slashes (`/`) for glob patterns and paths.
-
-Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating.
+## 📄 License
 
-## License
-MIT License - feel free to use, modify, and share!
+Distributed under the [MIT License](LICENSE).

package/bin/agentctl.mjs

@@ -13,7 +13,7 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.9.4 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.21.0 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -43,7 +43,7 @@ async function main() {
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
-    console.log("agentctl v0.9.4");
+    console.log("agentctl v0.21.0");
     process.exit(0);
   }
 
@@ -223,7 +223,7 @@ async function main() {
     }
 
     case "doctor": {
-      console.log(`\n🔍 agentctl System Diagnostics (v0.9.0)`);
+      console.log(`\n🔍 agentctl System Diagnostics (v0.21.0)`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Config File      : ${config._file || "None (Using defaults)"}`);

package/bin/init.js

@@ -145,11 +145,26 @@ const rulesDir = path.join(agentDir, "rules");
 const queueDir = path.join(agentDir, "jules-queue");
 const completedQueueDir = path.join(queueDir, "completed");
 const workflowsDir = path.join(agentDir, "workflows");
+const promptsDir = path.join(agentDir, "prompts");
 
-[agentDir, rulesDir, queueDir, completedQueueDir, workflowsDir].forEach((d) => {
+[agentDir, rulesDir, queueDir, completedQueueDir, workflowsDir, promptsDir].forEach((d) => {
   if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
 });
 
+// Scaffold .agent/prompts files
+const sourcePromptsDir = path.join(kitRoot, ".agent/prompts");
+if (fs.existsSync(sourcePromptsDir)) {
+  const promptFiles = fs.readdirSync(sourcePromptsDir);
+  promptFiles.forEach((file) => {
+    const srcPrompt = path.join(sourcePromptsDir, file);
+    const destPrompt = path.join(promptsDir, file);
+    if (!fs.existsSync(destPrompt) || isForce) {
+      fs.copyFileSync(srcPrompt, destPrompt);
+    }
+  });
+  console.log("✅ Created: .agent/prompts presets (Overseer, Bolt, Sentinel, Janitor, Task_Template)");
+}
+
 // Scaffold .agent/jules.yml
 const yamlConfigPath = path.join(agentDir, "jules.yml");
 if (!fs.existsSync(yamlConfigPath) || isForce) {