# CLAUDE.md — Zyquo Agent

## Project Identity

**Zyquo Agent** is the autonomous-agent member of the **Zyquo** family: a legendary, native macOS app written in **Swift + SwiftUI**, built **without the Xcode IDE** (Swift Package Manager + command-line toolchain). Where **Zyquo Cloud** is a chat client and **Zyquo Local** runs models on-device, **Zyquo Agent** turns those same cloud models into a **deeply agentic assistant that can actually operate the user's Mac** — running `shell`/`bash` commands and `AppleScript`/`osascript`, reading and writing files, and iterating in a real agentic loop until a task is done.

This is not a toy. Zyquo Agent must be an **ultra-advanced agent**: a robust plan→act→observe→reflect loop, a rich tool layer, memory/context compression for long tasks, per-task working directories ("workspaces"), streaming visibility into everything the agent thinks and does, and strong safety controls (approvals, sandboxable command policies, dry-run, full audit log). It reuses **exactly the same providers and models as Zyquo Cloud** — specifically the subset capable of deep agentic/tool-use work — by studying the Zyquo Cloud repository first.

**Naming conventions (use consistently everywhere):**
- Display name / product name: `Zyquo Agent`
- App bundle: `Zyquo Agent.app`
- Bundle identifier: `com.zyquo.agent`
- Executable / SPM target: `ZyquoAgent` (no space)
- Data folder: `~/Library/Application Support/ZyquoAgent/`
- Workspaces root: `~/Library/Application Support/ZyquoAgent/Workspaces/`
- Repo module prefix in file headers: `Zyquo Agent`

---

## 📋 MANDATORY FILE HEADER — EVERY CODE FILE

**Every single code file you write** (all `.swift` files, plus `Makefile`, shell scripts, `Package.swift`, verification scripts — anything containing code) **MUST begin with this header comment**, adapted to the file's comment syntax:

```swift
//
//  <FileName>.swift
//  Zyquo Agent
//
//  Author: Simon-Pierre Boucher
//  Mail: contact@spboucher.ai
//
```

For shell scripts / Makefiles:

```bash
#
#  <filename>
#  Zyquo Agent
#
#  Author: Simon-Pierre Boucher
#  Mail: contact@spboucher.ai
#
```

No exceptions. If you ever create or refactor a file and the header is missing, add it. Before declaring the project done, run a sweep over the repository to verify every code file carries the header.

---

## 🧭 METHODOLOGY — WORK METHODICALLY, KEEP EVERYTHING COHERENT

You must execute this project **strictly in phase order (0 → 8)**. Do not jump ahead, do not interleave phases, do not build the agent loop before the provider layer streams tool calls, and do not write any code before Phase 0 research + Zyquo Cloud study are complete.

**Working rules:**

1. **One phase at a time.** At the start of each phase, write a checklist into `docs/PLAN.md`; check items off as you go. At the end of each phase, run a **phase checkpoint**: build (`swift build`), run what's runnable, fix all warnings/errors, write a 3–5 line phase summary in `docs/PLAN.md` before moving on.
2. **Phase gates:** Phase 0 is complete only when `docs/AGENT-RESEARCH.md` and `docs/PROVIDER-REUSE.md` are complete (see Phase 0). Phase 3 is complete only when a minimal loop can call a model, receive a tool call, execute a real `bash` command, feed the result back, and reach a final answer — proven in a CLI POC. Phase 4 spec is the contract for all UI in Phase 6. Phase 7 is complete only when the multi-scenario agent evaluation passes AND every reused model performs tool-calling correctly with real keys. Phase 8 is complete only when `spctl` says "Notarized Developer ID".
3. **Single source of truth, everywhere:**
   - Provider/model behavior → ported from Zyquo Cloud's client layer (see Phase 0.B); never re-invent request formats.
   - Colors, fonts, spacing, radii → only from `ZyquoTheme` design tokens. Zero raw hex values or magic numbers in views.
   - Tool definitions, the agent loop, and command execution → only in the `Agent/` and `Tools/` layers; never leak shell execution into Views or ViewModels.
   - Product naming → per the conventions above. Never `Zyquo` alone, never `ZyquoAgent` in user-facing text.
4. **Coherence sweeps:** after Phases 3, 6, and 8, do a consistency pass over the whole codebase (uniform naming — one term per concept, always `ToolCall`, `AgentStep`, `ProviderClient`; no dead code; headers present; folders match Phase 2).
5. **Compile early, compile often.** Never accumulate more than one file of unbuilt changes.
6. **Commit discipline:** one logical unit per commit, message prefixed by phase. Never commit secrets or anything from a user workspace.
7. **Safety is not optional and cannot be "phased later":** from the very first command-executing code in Phase 3, the approval/policy/audit machinery (Phase 3.C) must be wired in. There is never a code path that runs a shell command without going through the policy gate.

---

## ⚠️ PHASE 0 — MANDATORY RESEARCH + ZYQUO CLOUD STUDY (DO THIS FIRST, BEFORE ANY CODE)

Two mandatory research tracks. Both produce documents. No Swift until both are done.

### 0.A — `docs/AGENT-RESEARCH.md` — how modern agents actually work (INTENSIVE WEB RESEARCH)

Do NOT rely on training data. Perform **several intensive web research sessions** and synthesize, with citations, a thorough understanding of production agent design. You must research and document at minimum:

1. **The core agentic loop.** How real coding/computer-use agents structure plan → act (tool call) → observe (tool result) → reflect → repeat until done. Study concrete, documented systems and patterns: **the Anthropic tool-use / agent loop**, **ReAct**, **Reflexion / self-critique**, **Plan-and-Execute**, and the way tools are surfaced to the model (native function/tool calling vs. structured output). Document the anatomy of one loop iteration end-to-end, including how the model signals "I'm done."
2. **Tool design.** How tools are defined and exposed to models (JSON schema for parameters, names, descriptions), how tool_use/tool_result blocks are threaded back into the conversation for each provider, parallel vs. sequential tool calls, and best practices for writing tool descriptions the model won't misuse. Research how leading agents design a **shell/bash tool**, a **file-edit tool**, and OS-automation tools.
3. **Memory & context compression.** This is critical for long tasks. Research: sliding-window context management, **summarization/compaction of old turns**, hierarchical memory (short-term scratchpad vs. long-term notes file), "memory files" the agent maintains on disk, retrieval of past steps, and how agents avoid blowing the context window during long autonomous runs. Document concrete compaction strategies (e.g., summarize completed sub-tasks into a compact record, keep the plan + recent N steps verbatim, offload detail to files).
4. **Working repositories / workspaces.** How agents get a scratch working directory, why isolation matters, how they track created/modified files, checkpoints, and how a "project" or "session" maps to a folder on disk. Research how agentic coding tools create and manage their working repo/sandbox.
5. **Planning & task decomposition.** Todo lists / task trees, how agents create and update a plan mid-run, sub-agents/delegation patterns, and when to re-plan after failures.
6. **Reliability & control.** Loop-guarding (max steps, budgets, stall/no-progress detection, repetition detection), error recovery, timeouts, and human-in-the-loop approval gates. How agents decide an action is risky.
7. **Evaluation.** How agentic systems are tested (task suites, success criteria, trajectory inspection).

Write it all into `docs/AGENT-RESEARCH.md`. The architecture in later phases must trace back to findings here.

### 0.B — `docs/PROVIDER-REUSE.md` — study the Zyquo Cloud repo and reuse its providers

**Before writing provider code, read and study the Zyquo Cloud repository** (the sibling project already built from its own CLAUDE.md). Locate it on disk (check the user's projects folder; if you cannot find it, ask the user for its path). From it, understand and document:

1. **Exactly how each provider's API is called** in Zyquo Cloud: base URLs, auth headers, request/response `Codable` models, the shared `OpenAICompatibleClient`, and the native `AnthropicClient` / `GeminiClient`. Zyquo Agent must call models **the exact same way** — port or, ideally, factor this code so it is identical to Cloud's.
2. **The full model catalog** Zyquo Cloud ships (`ModelCatalog` / `docs/PROVIDERS.md`), including which providers/models support **native tool/function calling** and streaming of tool calls. Reproduce that catalog here.
3. **Tool-calling capability per model.** From Cloud's data + fresh docs checks, determine the subset of models that are genuinely suitable for **deep agentic, multi-step tool use** (strong reasoning + reliable function calling + adequate context window). Zyquo Agent's model picker must **offer exactly the same models as Zyquo Cloud**, but clearly mark and default to this "agent-capable" subset. Document the subset and the reasoning in `docs/PROVIDER-REUSE.md`.
4. **The secure key vault approach** from Cloud (custom AES-256-GCM encryption, NO Keychain). Zyquo Agent reuses the **same `SecureKeyStore` design** and vault format so a user's keys and behavior feel consistent across the family. (Reuse the code; keep the "no Keychain" rule.)
5. Note any provider-specific tool-calling quirks (e.g., Anthropic tool_use blocks vs. OpenAI `tool_calls`, Gemini function calling, how each streams partial tool-call arguments) so the agent loop handles all of them uniformly behind a `ProviderClient` protocol.

**Outcome:** Zyquo Agent's provider layer is functionally identical to Zyquo Cloud's, exposes the same models, and adds a normalized tool-calling interface on top.

---

## PHASE 1 — Project Setup (No Xcode IDE)

- **Toolchain:** Swift Package Manager. `Package.swift`, executable target `ZyquoAgent`. Build `swift build -c release`.
- **App bundle:** `Makefile` that builds release, assembles `Zyquo Agent.app` (`Contents/MacOS/ZyquoAgent`, `Info.plist`, `Resources/AppIcon.icns`), signs (Phase 8; ad-hoc for `make dev`).
- **Info.plist:** `CFBundleDisplayName` = `Zyquo Agent`, bundle ID `com.zyquo.agent`, `LSMinimumSystemVersion` (macOS 13.0+), `NSHighResolutionCapable`, `LSApplicationCategoryType` (`public.app-category.developer-tools`), and **usage-description strings** for any Automation/AppleScript access (`NSAppleEventsUsageDescription`) and any other TCC-guarded capabilities the agent touches. Universal (arm64 + x86_64) for release.
- **Entry point:** `@main` SwiftUI `App`; proper activation from terminal launch.
- **Dependencies:** Foundation + SwiftUI + CryptoKit; Apple `swift-markdown` acceptable. Reuse Zyquo Cloud's networking (URLSession) — no external HTTP libs.

---

## PHASE 2 — Architecture

```
Sources/ZyquoAgent/
├── App/                   # @main, windows, menu bar extra
├── DesignSystem/          # ZyquoTheme — family token system, Agent palette
├── Models/                # Conversation/Task, Message, AgentStep, ToolCall, Provider, AIModel…
├── Providers/             # PORTED FROM ZYQUO CLOUD
│   ├── ProviderProtocol.swift          # + normalized tool-calling interface
│   ├── OpenAICompatibleClient.swift    # tool_calls streaming
│   ├── AnthropicClient.swift           # tool_use blocks
│   └── GeminiClient.swift              # function calling
├── Agent/
│   ├── AgentLoop.swift        # actor: the plan→act→observe→reflect engine
│   ├── AgentStep.swift        # one iteration: thought, tool call(s), tool result(s)
│   ├── Planner.swift          # task decomposition, todo list, re-planning
│   ├── MemoryManager.swift    # context compression / compaction, memory files
│   ├── LoopGuard.swift        # max steps, budgets, stall & repetition detection
│   └── Transcript.swift       # structured run history for UI + audit
├── Tools/
│   ├── Tool.swift             # protocol: name, JSON schema, execute(args) async throws -> ToolResult
│   ├── ToolRegistry.swift     # available tools, schemas handed to the model
│   ├── ShellTool.swift        # bash/sh command execution (via ExecutionService)
│   ├── AppleScriptTool.swift  # osascript / AppleScript execution
│   ├── FileTools.swift        # read, write, edit, list, search within workspace
│   └── (extensible: HTTP fetch, etc. — designed for easy addition)
├── Execution/
│   ├── ExecutionService.swift # runs Process (/bin/bash, /usr/bin/osascript), streams stdout/stderr, timeouts, cancellation
│   ├── PolicyEngine.swift     # SAFETY gate: allow/ask/deny per command (Phase 3.C)
│   └── AuditLog.swift         # append-only signed log of every executed action
├── Workspace/
│   └── WorkspaceManager.swift # per-task working directory, file tracking, checkpoints
├── Services/
│   ├── SecureKeyStore.swift   # reused from Zyquo Cloud (no Keychain)
│   └── PersistenceService.swift
├── ViewModels/
└── Views/
```

- **`AgentLoop` and `ExecutionService` are actors.** Structured concurrency throughout; every long operation cancellable.
- **All shell/AppleScript execution goes through `ExecutionService` → `PolicyEngine`.** No exceptions.

---

## PHASE 3 — THE AGENT ENGINE (THE CORE)

Build this in three tightly-linked parts. **PHASE GATE:** finish with a CLI POC (`ZyquoAgent --run "create a folder ~/zqtest and put a hello.txt in it, then list it"`) that plans, calls the model, executes real tools through the policy gate, compresses memory if needed, and produces a correct final result with a full printed transcript.

### 3.A — The agentic loop (`AgentLoop`)
- Implement the loop from `docs/AGENT-RESEARCH.md`: send system prompt + tools + conversation → receive assistant turn → if it contains tool call(s), execute them (respecting the policy gate), append tool_result(s), loop; if it's a final answer, stop.
- Support **native tool calling for every provider** via the normalized interface (OpenAI `tool_calls`, Anthropic `tool_use`, Gemini function calls). Stream the model's thinking/text AND tool-call arguments live to the UI.
- **Planner:** at task start, the agent drafts a plan / todo list (persisted, editable, shown in UI) and updates it as steps complete or fail; re-plans on repeated failure.
- **LoopGuard:** enforce max steps and a token/time budget; detect stalls (no state change), repetition (same failing command), and dead-ends; on trip, pause and ask the user rather than spinning.
- A strong **system prompt** that establishes the agent's role, the available tools, the workspace, safety expectations, and the "signal done" convention — grounded in the research.

### 3.B — Memory / context compression (`MemoryManager`)
- Implement compaction from the research: keep the plan + system prompt + most recent N steps verbatim; **summarize older completed steps** into a compact structured record; offload large tool outputs (long logs, file dumps) to files in the workspace and replace them in-context with a short reference + summary.
- Maintain a persistent **`MEMORY.md`** (and/or structured notes) in the workspace that the agent reads/writes to carry knowledge across compactions and sessions.
- Track context-window usage live; trigger compaction before hitting limits; never silently drop the plan or key facts.

### 3.C — Tools, execution & SAFETY (`Tools/`, `Execution/`) — WIRED FROM THE START
- **ShellTool:** runs commands via `/bin/bash -lc` (or `/bin/sh`) inside the current **workspace** as cwd; streams stdout/stderr line-by-line to the UI; enforces per-command timeout; captures exit code; cancellable.
- **AppleScriptTool:** runs AppleScript via `osascript` (and `osascript -e` / script files) to automate macOS apps (Finder, Notes, Mail, Calendar, System Events for UI scripting, etc.); same streaming/timeout/cancel; surfaces the Automation permission prompts gracefully and explains them.
- **FileTools:** read/write/edit/list/search — **scoped to the workspace by default**; escaping the workspace requires explicit user permission.
- **PolicyEngine (the safety gate every action passes through):**
  - Three modes, user-selectable per task: **Manual** (approve every action), **Auto with guardrails** (auto-run read-only/safe commands, ask for anything mutating or matching a risk rule), **YOLO/Autonomous** (run freely within budget — clearly labeled, off by default, still audited).
  - A **risk classifier** for commands: flag destructive patterns (`rm -rf`, `sudo`, disk/format ops, `mv`/overwrite outside workspace, network installs, `curl … | sh`, killing processes, writing to system paths, `defaults`/`launchctl`, anything needing elevated privileges). Risky actions ALWAYS require approval regardless of mode.
  - **Approval UI:** show the exact command / AppleScript, an explanation, the cwd, and predicted effect; buttons Approve / Approve & remember (for that safe class) / Edit / Deny; optional **dry-run** where supported.
  - **Never run `sudo` or request passwords silently.** Elevated actions are surfaced explicitly and require deliberate user confirmation.
- **AuditLog:** append-only record of every executed command/script with timestamp, cwd, exit code, and truncated output — viewable and exportable; nothing the agent does is invisible.

---

## PHASE 4 — DESIGN SYSTEM & UI SPECIFICATION (LIGHT THEME, PIXEL-PERFECT)

Same design DNA and `ZyquoTheme` token system as the rest of the family, with an **"Agent" identity**: focused, capable, a touch of "command center". Where Cloud is sky-blue and Local is emerald, **Agent is a confident violet/plum** — intelligent and operational.

### 4.1 — Light theme

| Token | Value (light) | Usage |
|---|---|---|
| `background` | `#FBFAFD` (cool off-white, faint violet undertone) | Main canvas |
| `surface` | `#FFFFFF` | Cards, bubbles, input, panels |
| `surfaceSecondary` | `#F4F2F8` | Hover, code/terminal blocks |
| `sidebar` | `NSVisualEffectView` `.sidebar` material | Sidebar |
| `accent` | `#7A5AF0` (confident violet) | Primary actions, selection, links, run button |
| `accentSubtle` | `#EFEBFD` | Selected rows, user bubble tint |
| `success` / `warning` / `danger` | `#2FA36B` / `#D9822B` / `#D64545` | Tool ok / approval needed / destructive & errors |
| `textPrimary` `#1B1A20` · `textSecondary` `#6E6B78` · `textTertiary` `#A09DAC` · `border` `#E7E4EE` | | |

Same global rules as the family: no pure black on pure white, 0.5pt hairlines, ultra-soft shadows on floating panels only, dark theme derived (deep plum-charcoal command-center feel), **light theme is the flagship**. Typography, spacing, radii identical to Zyquo Cloud/Local (`body` 13.5pt / line-height 1.45; scale 4–32; radii 6/10/14; content column 760pt for chat). Terminal/command output uses SF Mono at `code` size.

### 4.2 — Layout & screens (exact spec)

The window is a **command center**, not just a chat. Default 1320×860, min 1040×680.

- **Sidebar (260pt, translucent):** "Zyquo Agent" wordmark; **New Task** button (prominent, accent); task list grouped Pinned/Today/Yesterday/Previous 7 Days/Older — each row = task title + status pill (Planning / Running / Awaiting approval / Done / Failed) + model badge + relative time; running tasks show a subtle activity indicator. Footer: settings gear + safety-mode chip (Manual / Guarded / Autonomous) + active model chip.
- **Main detail = three coordinated regions:**
  1. **Conversation / task column (center, max 760pt):** the human↔agent dialogue with full Markdown. The agent's turns render as a **live transcript of steps**: each `AgentStep` is a card — a "thought" line, then tool call(s) shown as labeled chips (`bash`, `osascript`, `write_file`…) with the exact command in a monospace block, then the streamed **tool result** (stdout/stderr, exit code, truncated with expand). Approval-required steps render an inline **Approval card** (command + explanation + Approve/Edit/Deny) that blocks until resolved. Reasoning models' thinking goes in a collapsible section. The input bar (floating card, radius 14, violet **Run/Send** button ⌘↩, attach text files, Stop button while running) sits at the bottom.
  2. **Plan / Todo panel (right, collapsible ~300pt):** the live task plan as a checklist the agent maintains — items with states (pending/active/done/failed), editable by the user; a progress bar; step counter and token/time budget meters (from LoopGuard).
  3. **Activity / Terminal drawer (bottom, collapsible):** a live, streaming, color-coded feed of raw command execution (like a built-in terminal) — every stdout/stderr line as it happens, with the current cwd; tabs for **Live**, **Audit Log** (all executed actions), and **Files** (the workspace file tree with created/modified badges, click to preview, reveal in Finder).
- **Header (52pt):** editable task title; centered **model chip** (agent-capable models emphasized; same list as Zyquo Cloud); **safety-mode segmented control** (Manual / Guarded / Autonomous) always visible; workspace chip (name + reveal in Finder); export, info popover (system prompt, budgets, totals).
- **Empty state:** a beautiful "What should I do on your Mac?" hero with example task cards ("Organize my Downloads folder", "Batch-rename these files", "Set up a Python project and run the tests", "Export my Notes to Markdown"), the safety-mode selector, and the model chip. Must feel powerful and trustworthy.

**Settings** (native tabs, 760×560): 1. **Providers & Keys** (reused vault UI; per-provider test) 2. **Models** (same catalog as Cloud; mark agent-capable subset; set default agent model) 3. **Safety** (default mode; manage the allow/deny rule lists; the destructive-pattern list; require-approval-for-AppleScript toggle; workspace-escape policy) 4. **Agent** (max steps, token/time budgets, per-command timeout, parallel tool calls on/off, compaction thresholds) 5. **Appearance** (Light/Dark/System; accent: violet default + graphite, sky, emerald, amber) 6. **Shortcuts** 7. **Advanced** (reveal data/workspaces folder, export audit logs, import/export tasks).

**Quick Task panel** (⌥Space): floating Spotlight-style panel to fire a one-off agent task with the default model + Guarded mode; expands to show live steps; can be promoted to a full task.

### 4.3 — Motion & micro-interactions
Family standard (smooth streaming, blinking caret, 150ms fade+rise, 80ms hovers, 0.97 press, `.snappy` popovers, 60fps, lazy transcript). Agent-specific: step cards animate in as the agent acts; the plan panel check-offs animate; terminal lines stream without reflow jank; approval cards pulse gently to draw attention; status pills transition smoothly (Planning→Running→Done).

### 4.4 — Design quality gate
Before done, review every screen and every state: empty, planning, running, streaming stdout, awaiting approval, approval denied, tool error, loop-guard tripped, task done, task failed, no model/key configured. Consistent tokens, aligned baselines, no clipped text/commands, correct dark mode, clean font scaling. If it looks "developer-made" rather than "designed", iterate.

---

## PHASE 5 — APP ICON: ULTRA-LEGENDARY "AGENT" ICON, DESIGNED IN SVG

Designed in SVG first (`assets/icon/zyquo-agent.svg`) → `.icns`. Visual sibling of Cloud & Local: same squircle, same Z-monogram DNA, same premium quality — telling the **autonomous agent / command** story.

**Creative direction — the Z that acts.** Two directions (render both, keep the best):
1. *Z-command:* the bold Z monogram whose lower stroke resolves into a subtle **command-line prompt / cursor** motif (a refined `›` chevron or blinking-caret block integrated into the letterform) — reads instantly as "an agent that runs commands", elegant not literal.
2. *Z-orbit:* the Z at the center with a few small **satellite nodes on a thin orbit ring** (the agent dispatching tools/sub-tasks) glowing around it — autonomy and orchestration.

- **Canvas:** Big Sur–style rounded **squircle** (Apple curvature).
- **Palette (mirrors the app):** deep violet-to-plum vertical gradient (`#8B6CF5 → #7A5AF0 → #4B3A9E` territory, tune for richness), Z/cursor in white/near-white with a subtle inner luminosity and one restrained top highlight; if using the caret, give it a faint accent glow. Modern, confident, premium — beside Cloud (sky) and Local (silicon), the trio must read as one family, three characters.
- **Precision & iteration:** clean paths, `viewBox="0 0 1024 1024"`, optical centering, effects that survive downscaling. Render 16→1024, inspect, refine; simplified small-size variant (drop orbit/nodes, keep Z + caret) for 16/32px.

**Pipeline (Makefile):** SVG → PNGs (16→1024 incl. `@2x`) via `rsvg-convert` or a CoreGraphics rasterizer → `AppIcon.iconset` → `iconutil -c icns`. SVG stays as source of truth. Derive the monochrome **menu bar template icon** (18×18pt) and in-app wordmark/empty-state glyph from the same SVG.

---

## PHASE 6 — Features (This is where Zyquo Agent becomes LEGENDARY)

### Agentic core
- Full plan→act→observe→reflect loop over **all agent-capable models** (same set as Zyquo Cloud), native tool calling for every provider
- Live streaming of thoughts, tool calls, and command output; stop/cancel at any moment
- Editable live **plan/todo**; automatic re-planning on failure; sub-task decomposition
- **Memory compaction** for long autonomous runs + persistent workspace `MEMORY.md`
- **LoopGuard**: step/token/time budgets, stall & repetition detection, graceful pause-and-ask

### Tools
- `bash`/`sh` shell execution, `AppleScript`/`osascript` OS automation, and workspace file read/write/edit/list/search — all streaming, cancellable, timeout-bounded
- Extensible ToolRegistry (adding a new tool = conform to `Tool` + register); designed so an HTTP-fetch tool and others drop in cleanly
- Optional: allow the agent to write and run helper scripts it creates in the workspace

### Safety & trust (a headline feature, not an afterthought)
- Three safety modes (Manual / Guarded / Autonomous) with per-task selection
- Risk classifier + editable allow/deny rules; mandatory approval for destructive/elevated actions; never silent `sudo`
- Inline approval cards with command preview, explanation, edit, dry-run; full append-only **audit log**, exportable
- Everything scoped to a per-task **workspace** by default; explicit permission required to touch files outside it

### Workspaces
- Each task gets an isolated working directory under `Workspaces/`; file tree with created/modified tracking; checkpoints; reveal in Finder; reopen a past task with its workspace intact

### Productivity & polish
- Task library / templates (≥25 ready-made agent tasks) + user templates with variables
- Personas (system prompt + preferred agent model + safety default)
- Quick Task panel (⌥Space); Export task transcript → Markdown/PDF; full-text search across tasks
- Auto-generated task titles; reused encrypted key vault (no Keychain)
- Shortcuts: ⌘N new task, ⌘K model/command palette, ⌘⏎ run, ⌘. stop, ⌘F search, ⌘⇧A open audit log, ⌥Space Quick Task; toggleable menu bar extra showing running-task status

---

## PHASE 7 — VERIFICATION (MANDATORY)

The user will provide **real API keys** (same providers as Zyquo Cloud). You MUST:

1. **Provider/tool-calling verification:** for **every agent-capable model** in the shared catalog, run a scripted check that the model correctly (a) receives tool schemas, (b) emits a valid tool call for a trivial task (`"list the files in the workspace using the shell tool"`), (c) consumes the tool_result and produces a correct final answer, (d) streams properly. Produce a table: provider → model → tool-call ✅/❌ → notes. Fix every failure (schema format, tool_result threading, provider quirks) until green.
2. **Agent scenario evaluation:** define a suite of ≥8 real end-to-end tasks executed against a scratch workspace / temp directories (NEVER destructive to the user's real data), e.g.: create a folder structure and files; batch-rename files by pattern; write and run a small Python script and report its output; parse a CSV and summarize it; use AppleScript to create a Note or a Reminder (with approval); find and summarize the largest files in a temp dir; multi-step task requiring re-planning after an intentional failure; a long task that triggers memory compaction. For each: verify success criteria, inspect the trajectory, confirm the policy gate blocked/asked on risky steps, and confirm the audit log is complete. Iterate until all pass reliably.
3. **Safety tests:** confirm destructive patterns (`rm -rf`, `sudo`, writes outside workspace) ALWAYS require approval in every mode; confirm cancellation actually stops a running command; confirm no `sudo` ever runs silently.
4. Never commit, log, or embed the user's keys anywhere; keys live only in the encrypted vault or env vars during testing. Never run destructive test commands against real user data.

---

## PHASE 8 — SIGNING & NOTARIZATION (REAL, NOT AD-HOC)

The user has an existing, working signing/notarization setup for another project. **Before doing anything, read and inspect the folder:**

```
/Users/simon-pierreboucher/Desktop/other/OTHER/zyquo-term
```

Locate the **Developer ID Application identity name**, **Team ID**, **notarytool keychain profile (or Apple ID + app-specific password)**, entitlements, and any config there. **Reuse the exact same identity, Team ID, and notarytool credentials/profile for Zyquo Agent.** Never invent placeholders, never print secrets, never commit them.

Then implement `make release`:
1. Build universal release (arm64 + x86_64, `lipo`), assemble `Zyquo Agent.app`.
2. `entitlements.plist` with **Hardened Runtime**; include only what's needed. Because the app spawns `bash`/`osascript` child processes and sends Apple events, verify the correct posture: keep Hardened Runtime, ensure `NSAppleEventsUsageDescription` is present, and add `com.apple.security.automation.apple-events` if entitlement-gated automation requires it. Do NOT add App Sandbox (this app legitimately controls the Mac and would be crippled by it) unless the user explicitly wants a sandboxed variant. Test the minimal set.
3. `codesign --force --options runtime --timestamp --entitlements entitlements.plist --sign "Developer ID Application: <identity from zyquo-term>" "Zyquo Agent.app"` — sign nested code first.
4. `ditto -c -k --keepParent` → `xcrun notarytool submit "Zyquo Agent.zip" --keychain-profile "<profile from zyquo-term>" --wait`.
5. `xcrun stapler staple "Zyquo Agent.app"`; verify `spctl -a -vv` = "accepted, source=Notarized Developer ID" and `stapler validate`.
6. Optional signed+stapled DMG (`hdiutil`).
7. On failure: `notarytool log`, fix, resubmit until it passes. Keep `make dev` (ad-hoc) for iteration.

---

## Engineering Standards

- Swift 5.9+ (Swift 6 mode if the toolchain allows); zero warnings
- `AgentLoop` and `ExecutionService` as actors; all provider and tool types `Codable`
- Every executed action passes the PolicyEngine; every action is audited; cancellation everywhere (loop, command, download-of-nothing — every long op)
- Robust, human-readable errors for every failure class (tool failed, command timeout, model refused/looped, budget exceeded, permission denied by macOS TCC → explain how to grant Automation access in System Settings)
- Provider layer identical to Zyquo Cloud; tokens-only design system; UI strings centralized
- `README.md` (build) + `docs/` (AGENT-RESEARCH, PROVIDER-REUSE, PLAN); never commit secrets or workspace contents
- Commit in logical, phase-prefixed increments

## Definition of Done

- `make release` produces a **Developer ID–signed, notarized, stapled** `Zyquo Agent.app` (verified by `spctl`), built without the Xcode IDE
- The agent reliably runs a full plan→act→observe→reflect loop using **the same providers/models as Zyquo Cloud**, with native tool calling verified across the agent-capable subset (Phase 7 table green)
- `bash`, `AppleScript`, and workspace file tools work with live streaming output; every action passes the safety policy gate; destructive/elevated actions always require approval; full audit log present
- Memory compaction keeps long tasks within context; workspaces isolate and track task files
- The violet-themed SVG icon exists, is striking at all sizes, embedded as `.icns` + menu bar template icon; clearly a sibling of the Cloud and Local icons
- The violet light theme matches the Phase 4 spec exactly and passes the design quality gate; dark theme derived and correct
- Naming coherent everywhere: `Zyquo Agent` user-facing, `com.zyquo.agent`, `ZyquoAgent` target/data folder; keys in the reused encrypted vault (no Keychain)
- **Every code file starts with the mandatory Author/Mail header** (verified by a repo-wide sweep)
- `docs/PLAN.md` shows every phase completed with its checkpoint summary; `docs/AGENT-RESEARCH.md` and `docs/PROVIDER-REUSE.md` are complete and traceable to the implementation
- Zyquo Agent feels like a polished, legendary, and *trustworthy* native Mac agent — clearly the most capable of its kind