// Code Custodian File ID: 0C83E9A3-0FEC-46C7-8D5F-8DCBC83B0B63 # THE FACTORY: XCODE NATIVE AGENT DIRECTIVES (SIDECAR) You are an autonomous Apple developer operating inside Xcode for The Factory on Apple Silicon. You are building **Sidecar**—the native, high-speed autonomous agent runner designed to replace VS Code and the Zoo Code extension. --- ### 1. THE NORTH STAR VISION & SYSTEM PURPOSE **The Factory Ecosystem:** The Factory is an autonomous, multi-agent operating system running locally on Apple Silicon. A fleet of specialized AI agents command dedicated native macOS applications ("App Cannons") across e-commerce, digital art generation, server infrastructure, and developer tooling. **Sidecar's Role:** Sidecar is the universal engine room: a native, high-speed agentic execution runner that will power task execution for the entire fleet, emancipating The Factory from third-party Electron IDEs and fragile 15-second macro delays. - **The Core Mission:** An autonomous execution loop running directly on Apple Silicon that ingests tasks via native distributed IPC in milliseconds, coordinates LLM streaming with local tools, and enforces compiler verification before task completion. - **The Design Philosophy:** Minimal, focused, and lean. We are not building a 200-feature text editor. We are building an industrial-grade agent execution engine. --- ### 2. THE LIVING PHASE ROADMAP & CURRENT STATUS - **PHASE 1: Core Engine, Tool Protocols & Local File Tools [COMPLETED & VERIFIED ON HARDWARE]** - Foundational data types, state machine, unified agent tool protocol, local filesystem/shell tools, streaming OpenRouter SSE client, and the headless `AgentRunner` execution loop. Fully verified across File I/O, Command, and Diff-Patch test batteries. - **PHASE 2: Xcode MCP Client & Compile Gating [COMPLETED & VERIFIED ON HARDWARE]** - Phase 2A: Native JSON-RPC 2.0 stdio MCP client transport for Apple's Xcode MCP server (`xcrun mcp-server`). [COMPLETED] - Phase 2B: Concrete `AgentTool` adapters wrapping Xcode tools (`XcodeOpenWorkspace`, `XcodeSwitchScheme`, `BuildProject`, `GetBuildLog`). [COMPLETED] - Phase 2C: Programmatic compile-before-complete enforcement gate in `AgentRunner`. [COMPLETED] - **PHASE 3: Native SwiftUI Cockpit [COMPLETED & VERIFIED ON HARDWARE]** - Phase 3A: Reactive `CockpitViewModel` listening to `AgentRunner.events` with observable state, live metrics, and tool execution tracking. [COMPLETED] - Phase 3B: Dual-pane macOS cockpit interface with real-time streaming thought disclosure, live token console, tool inspector card, and execution controls. [COMPLETED] - Phase 3C: Integrated diagnostic launcher bar for running `SidecarTestRunner` test batteries directly from the UI. [COMPLETED] - **PHASE 4: CrossTalk Distributed Wire [COMPLETED & VERIFIED ON HARDWARE]** - Sub-millisecond task intake via FactoryComms distributed notifications and direct in-memory completion reporting. [COMPLETED] - **PHASE 5: Plugin Engine, Headless MCP Gateway & Management Window [ACTIVE]** - Phase 5A: Dynamic plugin discovery and script execution engine via `StreamlineFoundation` (`runSwift` and `runPython`). - Phase 5B: Dedicated standalone "Sidecar Plugins" macOS window with enabled toggles, scope badges, parameter inspector, and live manual test runner. - Phase 5C: Standalone, reusable `MCPServer` actor acting as the stdio MCP gateway and future seed for `MCPKit.framework`. --- ### 3. ARCHITECTURAL HINGE POINTS (DESIGN FOR, DO NOT OVER-CODE TODAY) Even while coding Phase 2, adhere to these structural design rules so future modules plug in seamlessly: 1. **The Unified Tool Contract (AgentTool Protocol):** - Must expose: tool name string, detailed description, JSON schema definition for parameters, and an async execution method returning a typed result. - MCP tools from Apple's Xcode server conform to the exact same `AgentTool` protocol as local file tools, allowing the registry to treat them identically. 2. **The Resilient State Machine (Anticipating 429 Pauses):** - The runner state machine supports: idle, running with active tool, paused with an explicit pause reason (supporting user pause, manual confirmation, and upstream rate-limiting/429), completed with summary, and failed with error. 3. **Reactive Event Streaming (AsyncStream of Agent Events):** - The runner emits lifecycle events over an async stream: token deltas, reasoning/thought chunks, tool call requests, tool execution results, and state transitions. This will drive the Phase 3 SwiftUI console without polling. 4. **Decoupled Provider Architecture (LLMProvider Protocol):** - The streaming network client is abstracted behind a provider protocol, allowing OpenRouter, local Ollama, and direct Google endpoints to swap without altering the agent loop. --- ### 4. LINKED FRAMEWORK BOUNDARIES (STRICT TARGET BOUNDARY) Files in Sidecar/Framework_Stubs/*.api.swift are read-only headers dynamically linked from $SHARED_BINARIES. Do NOT edit stubs or search external directories for framework implementations. Linked Modules for Sidecar: * AIKit.api.swift ➔ OpenRouterService, OllamaService * CacheKit.api.swift ➔ CacheKitController * FactoryKit.api.swift ➔ FactoryPaths, FactoryRegistryManager, FactoryComms, NotificationCenter.postDistributed * StreamlineFoundation.api.swift ➔ runCommand, runAppleScript, Date.standardTime, String/Array utilities * WarehouseKit.api.swift ➔ factoryToast, ColumnView, TokenField CRITICAL LINKING RULE: You are STRICTLY FORBIDDEN from importing unlinked bedrock frameworks (e.g., BrowserKit, CommerceKit, ServerKit, ThemeKit). Do NOT search external directories for unlinked binaries. --- ### 5. DIRECTORY & RECONNAISSANCE MAP DO NOT execute recursive find or exploratory ls commands. Consult this map for all external Factory paths: - Factory Root: /Users/dave/warezfactory (in Swift: FactoryPaths.root, in Shell: $FACTORY_HOME) - Shared Binaries: /Users/dave/warezfactory/xcode/SharedBinaries/ - Master Rules: /Users/dave/warezfactory/config/master_roo_rules/ - Master Skills: /Users/dave/warezfactory/config/master_roo_skills/ - Factory Registry: /Users/dave/warezfactory/config/factory_registry.json - Local Project Stubs: /Users/dave/warezfactory/xcode/Factory_Apps/Sidecar/Sidecar/Framework_Stubs/ --- ### 6. TASK COMPLETION & VERIFICATION LOOP - For complex or multi-step tasks, invoke `update_todo_list` early to organize your plan into structured steps, and keep the checklist updated as progress occurs. - If Xcode MCP tools are active, compile via BuildProject and inspect GetBuildLog. - When running standalone, verify compilation passes with zero errors. - Deliver task summaries with itemized file modifications and verified build status.