speexor 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,98 @@
+# Contributing to Speexor
+
+Thank you for considering contributing to Speexor! This document outlines our development workflow, standards, and expectations.
+
+## Code of Conduct
+
+All contributors must adhere to our [Code of Conduct](./CODE-OF-CONDUCT.md).
+
+## Getting Started
+
+### Prerequisites
+- Node.js >= 18.0.0
+- pnpm (recommended) or npm
+- TypeScript basic knowledge
+
+### Setup
+```bash
+# Clone the monorepo
+git clone https://github.com/superdevids/speexjs.git
+cd speexjs
+
+# Install dependencies
+pnpm install
+
+# Navigate to speexor
+cd packages/speexor
+
+# Build the package
+pnpm build
+
+# Run tests
+pnpm test
+```
+
+## Development Workflow
+
+### Branch Naming
+- `feat/<description>` — New features
+- `fix/<description>` — Bug fixes
+- `docs/<description>` — Documentation changes
+- `refactor/<description>` — Code refactoring
+- `chore/<description>` — Maintenance tasks
+
+### Commit Messages
+We follow conventional commits:
+- `feat:` — New feature
+- `fix:` — Bug fix
+- `docs:` — Documentation
+- `refactor:` — Code refactoring
+- `test:` — Test changes
+- `chore:` — Maintenance
+
+### Before Submitting
+1. Run `pnpm lint` — Biome will check code quality
+2. Run `pnpm typecheck` — TypeScript will verify types
+3. Run `pnpm test` — Vitest will run tests
+4. Run `pnpm build` — tsup will build the package
+
+## Code Standards
+
+### TypeScript
+- Strict mode enabled
+- ESM only (`import`/`export`)
+- No `any` types (strict mode)
+- Use interfaces over type aliases for object types
+- All public APIs must have JSDoc comments
+
+### Plugin Architecture
+When adding a new plugin:
+1. Define interface in `src/core/types.ts` (if new slot) or implement existing interface
+2. Create implementation in `src/plugins/<slot>/`
+3. Add to `src/plugins/index.ts` `loadAllPlugins()` function
+4. Write unit tests for the plugin contract
+
+### Testing
+- Unit tests with Vitest
+- Integration tests for plugin contracts
+- Aim for >80% coverage
+- Tests go in `tests/` directory
+
+### Documentation
+- Keep README.md and docs up to date
+- Document new features in the appropriate docs file
+- Add JSDoc comments to public APIs
+
+## Pull Request Process
+1. Create a feature branch from `dev`
+2. Implement your changes
+3. Run the full CI suite locally
+4. Push and create a PR against `dev`
+5. Ensure CI passes on GitHub
+6. Request review from maintainers
+
+## Plugin Development Guide
+...
+
+## Questions?
+Open an issue at https://github.com/superdevids/speexjs/issues

package/FAQ.md

@@ -0,0 +1,105 @@
+# Frequently Asked Questions
+
+## General
+
+### What is Speexor?
+Speexor is an Agent Orchestrator that spawns and manages multiple AI coding agents in parallel across one or more git repositories. Each agent runs in an isolated git worktree, handles one task autonomously, and can automatically respond to CI failures and PR comments.
+
+### Why not just use AgentWrapper (AO)?
+Speexor was inspired by AO but rebuilt to be:
+- **Agent-agnostic** — not tied to Claude Code; supports OpenCode, Aider, Codex equally
+- **Multi-provider** — route tasks to different AI providers per project
+- **Native OpenCode support** — first-class integration with your vibe coding workflow
+- **Built for solo devs** — dashboard, auto-reactions, cost tracking out of the box
+
+### Is Speexor production-ready?
+Version 0.1.0 is a foundation release. The core architecture is solid, but we recommend:
+- Testing with non-critical repositories first
+- Keeping auto-merge disabled (`approved-and-green.auto: false`)
+- Reviewing agent output before merging PRs
+
+## Installation & Setup
+
+### What are the prerequisites?
+- Node.js >= 18.0.0
+- Git >= 2.30 (for worktree support)
+- GitHub CLI (`gh`) — for GitHub integration
+- tmux >= 3.0 — for tmux runtime (Unix only)
+- At least one AI coding agent CLI (OpenCode, Claude Code, Aider, or Codex)
+
+### How do I install Speexor?
+```bash
+npm install -g @speexjs/speexor
+# or
+pnpm add -g @speexjs/speexor
+```
+
+### Can I use Speexor on Windows?
+Yes! On Windows, the Process runtime is used automatically (tmux is not available). All features work except live terminal streaming in the dashboard.
+
+## Configuration
+
+### Where is the config file?
+Speexor looks for `speexor.config.yaml` in the current directory. Run `speexor start <repo-url>` to generate one automatically.
+
+### Can I manage multiple projects?
+Yes. The config supports multiple projects under the `projects` array. Each project can have its own provider routing and reaction rules.
+
+### What happens if CI fails?
+By default, Speexor automatically spawns a fix agent when CI fails (up to 3 retries). If it still fails after 3 retries, it escalates for human attention.
+
+## Usage
+
+### How do I spawn an agent?
+```bash
+speexor agent spawn --task 42 --agent opencode
+```
+This creates a worktree, starts a runtime session, and launches the agent.
+
+### How do I check agent status?
+```bash
+speexor list
+# Or open the dashboard at http://localhost:3000
+```
+
+### Can I run multiple agents in parallel?
+Yes. Each agent gets its own git worktree and runtime session. Configure `concurrentLimit` in the project config to limit parallel agents.
+
+### How do I stop an agent?
+```bash
+speexor stop <session-id>
+```
+This kills the agent process, cleans up the worktree, and removes the session.
+
+## Troubleshooting
+
+### "speexor.config.yaml not found"
+Run `speexor start <repo-url>` first to initialize the project, or manually create the config file.
+
+### "tmux not available"
+Install tmux (`brew install tmux` on macOS, `sudo apt install tmux` on Linux). On Windows, Speexor uses Process runtime automatically.
+
+### "GitHub CLI (gh) not found"
+Install from https://cli.github.com/ and authenticate with `gh auth login`.
+
+### Dashboard not loading?
+Check if port 3000 is available. Use `speexor start --port 4000` to use a different port.
+
+## Development
+
+### How do I add a new agent adapter?
+1. Create a file in `src/plugins/agent/`
+2. Implement the `AgentPlugin` interface
+3. Add it to `src/plugins/index.ts` `loadAllPlugins()`
+
+### How do I create a new plugin?
+1. Define the interface in `src/core/types.ts` (if new slot)
+2. Create the implementation in `src/plugins/<slot>/`
+3. Add to plugin loader
+
+### How do I run tests?
+```bash
+pnpm test        # Run all tests
+pnpm test:watch  # Watch mode
+pnpm test:coverage  # With coverage
+```

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya (@superdevids)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PUBLISH.md

@@ -0,0 +1,77 @@
+# Publishing Speexor
+
+This document describes the process for publishing `@speexjs/speexor` to npm.
+
+## Prerequisites
+- npm account with access to `@speexjs` organization
+- GitHub repository write access
+- Clean working tree (no uncommitted changes)
+
+## Version Bumping
+
+We follow [Semantic Versioning](https://semver.org/):
+- **Patch** (`0.1.0` → `0.1.1`): Bug fixes, minor changes
+- **Minor** (`0.1.0` → `0.2.0`): New features, backwards compatible
+- **Major** (`0.1.0` → `1.0.0`): Breaking changes
+
+## Pre-Publish Checklist
+
+- [ ] All tests pass: `pnpm test`
+- [ ] TypeScript compiles: `pnpm typecheck`
+- [ ] Linter passes: `pnpm lint`
+- [ ] Build succeeds: `pnpm build`
+- [ ] CHANGELOG.md updated
+- [ ] Version bumped in package.json
+- [ ] Git tag created
+- [ ] Docs updated (README, architecture, etc.)
+
+## Publishing Steps
+
+### 1. Update Version
+```bash
+# From the speexor package directory
+pnpm version patch  # or minor, or major
+```
+
+### 2. Update Changelog
+Update `CHANGELOG.md` with the new version, date, and changes.
+
+### 3. Build
+```bash
+pnpm build
+```
+
+### 4. Publish to npm
+```bash
+pnpm publish --access public
+```
+
+### 5. Tag and Push
+```bash
+git tag speexor-v0.1.0
+git push --tags
+git push origin main
+```
+
+### 6. Create GitHub Release
+- Go to https://github.com/superdevids/speexjs/releases
+- Draft a new release
+- Use the git tag as version
+- Copy changelog entry as release notes
+- Attach any relevant binaries
+
+## npm Package Contents
+
+The published package includes:
+- `dist/` — Compiled ESM + type declarations
+- `schema/` — JSON Schema for config
+- `examples/` — Example configurations
+- `speexor.config.yaml.example` — Config template
+- `*.md` — Documentation files
+
+## CI/CD
+
+Publishing can also be automated via GitHub Actions:
+- Trigger: pushing a tag matching `speexor-v*`
+- Steps: install → build → test → publish
+- Secrets: `NPM_TOKEN` must be configured in GitHub repository secrets

package/README.md

@@ -0,0 +1,179 @@
+# @speexjs/speexor
+
+**Agent Orchestrator for multi-AI coding agents across repositories**
+
+[![npm version](https://img.shields.io/npm/v/@speexjs/speexor.svg)](https://www.npmjs.com/package/@speexjs/speexor)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/%3C/%3E-TypeScript-3178C6)](https://www.typescriptlang.org/)
+
+---
+
+## Overview
+
+Speexor is an **agent orchestrator** purpose-built for teams and solo developers running multiple AI coding agents across several repositories. Inspired by the architecture of AgentWrapper AO but designed to be **agent-agnostic** and **multi-provider** from day one, Speexor lets you dispatch, monitor, and manage sessions from OpenCode, Claude Code, Aider, and Codex — all through a single CLI and YAML config.
+
+Coordinating multiple coding agents manually is error-prone and slow. Speexor solves this with a **7-plugin slot architecture** that separates agent adapters, runtime backends, workspace management, issue tracking, SCM operations, notifications, and terminal I/O into clean, swappable modules. Git worktree isolation keeps each agent session on its own branch without polluting your working tree.
+
+Speexor ships with a built-in **HTTP dashboard**, a **reaction engine** for automated CI-fix loops, JSON-file session persistence, and two runtime backends — `tmux` on Unix and `Process` on Windows — so it works wherever you do.
+
+> **Status:** v0.1.0 — Early release. The plugin API and core commands are stable; breaking changes are possible before 1.0.
+
+---
+
+## Key Features
+
+- **Parallel Agent Dispatch** — Spawn multiple coding agents (OpenCode, Claude Code, Aider, Codex) across different repositories simultaneously
+- **Multi-Provider Routing** — Configure primary and fallback AI providers per project with concurrent-limit controls
+- **Git Worktree Isolation** — Every agent task operates on its own isolated `git worktree` branch — zero interference with your main workspace
+- **Reaction Engine** — Automatically detect CI failures, PR review changes, and approvals; trigger fix, notify, or escalate actions with configurable retries
+- **Built-in HTTP Dashboard** — Monitor sessions, worktrees, and agent status in real time (Node.js built-in `http` module, no external dependencies)
+- **7-Plugin Slot Architecture** — Swap or extend every layer: agent adapters, runtimes, workspace, tracker, SCM, notifier, and terminal
+- **Cross-Platform Runtimes** — `tmux` for Unix, `Process` for Windows — pick the backend that matches your OS
+- **JSON-File Persistence** — Session state, worktrees, and runtimes persist to `.speexor/state.json` automatically
+- **Zod-Validated Config** — YAML configuration validated at load with clear error messages for every field
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install globally
+npm install -g @speexjs/speexor
+
+# 2. Initialize a project (creates speexor.config.yaml + starts dashboard)
+speexor start https://github.com/your-org/your-repo --port 3000
+
+# 3. (Optional) Edit speexor.config.yaml to set provider, reactions, etc.
+
+# 4. Spawn an agent for a GitHub issue
+speexor agent spawn --task 42
+
+# 5. Monitor progress
+speexor list
+speexor logs <session-id> --follow
+```
+
+**Prerequisites:**
+- Node.js >= 18.0.0
+- `git` installed and authenticated
+- One or more AI coding agents installed (`opencode`, `claude-code`, `aider`, `codex`)
+- `gh` CLI (GitHub CLI) authenticated — required for tracker and SCM plugins
+- `tmux` installed on Unix (optional — falls back to Process runtime)
+
+---
+
+## Configuration
+
+Speexor is configured via `speexor.config.yaml` (or `.speexor.yaml`, `speexor.yaml`) in your project root.
+
+Create one with `speexor start <repo>` or manually:
+
+```yaml
+version: "1"
+
+projects:
+  - name: my-app
+    repository: https://github.com/your-org/my-app
+    provider:
+      primary: opencode
+      fallback:
+        - claude-code
+        - aider
+      concurrentLimit: 3
+
+    reactions:
+      ci-failed:
+        auto: true
+        action: fix
+        retries: 3
+        escalateAfter: 30
+      changes-requested:
+        auto: true
+        action: fix
+        retries: 2
+        escalateAfter: 60
+      approved-and-green:
+        auto: false
+        action: notify
+        retries: 0
+        escalateAfter: 0
+
+  - name: my-lib
+    repository: https://github.com/your-org/my-lib
+    provider:
+      primary: claude-code
+      concurrentLimit: 2
+```
+
+See the full schema with `speexor config-help`.
+
+---
+
+## Plugin Architecture
+
+Speexor defines **7 plugin slots**. Each slot can have multiple implementations registered at startup.
+
+| Slot | Interface | Built-in Implementations |
+|------|-----------|--------------------------|
+| `agent` | `spawn()`, `sendInput()`, `getStatus()`, `kill()` | OpenCode, Claude Code, Aider, Codex |
+| `runtime` | `createSession()`, `sendInput()`, `getOutput()`, `getLiveStream()` | `tmux` (Unix), `Process` (Windows) |
+| `workspace` | `createWorktree()`, `removeWorktree()`, `cleanupStale()` | `GitWorktreeWorkspace` |
+| `tracker` | `fetchIssues()`, `getIssue()`, `onEvent()` | `GitHubTracker` |
+| `scm` | `createBranch()`, `commitAndPush()`, `createPR()`, `mergePR()` | `GitHubSCM` (via `gh` CLI) |
+| `notifier` | `notify(level, title, message)` | `DesktopNotifier` |
+| `terminal` | `attach()`, `write()`, `onData()` | _(interface defined, implementation optional)_ |
+
+Plugins implement `PluginModule` with a standard lifecycle (`initialize` / `destroy`) and receive typed access to the config, event bus, and logger through `PluginContext`.
+
+---
+
+## CLI Reference
+
+```
+speexor <command> [options]
+```
+
+| Command | Description |
+|---------|-------------|
+| `start [repo]` | Initialize a project config and start the HTTP dashboard. Options: `--port`, `--name`, `--no-dashboard` |
+| `agent spawn --task <id>` | Spawn an agent for a GitHub issue. Options: `--agent` (opencode, claude-code, aider, codex) |
+| `list` | List all projects and active agent statuses |
+| `stop <session-id>` | Stop an agent session safely |
+| `logs <session-id>` | Tail logs for an agent session. Options: `--follow`, `--lines` |
+| `config-help` | Print the full YAML config schema reference |
+
+---
+
+## Examples
+
+A complete multi-project configuration with reaction rules is available in [`examples/basic.yaml`](./examples/basic.yaml).
+
+---
+
+## Documentation
+
+- [Architecture & Design (PRD 01)](./docs/PRD01.md)
+- [Technical Spec (PRD 02)](./docs/PRD02.md)
+- [Behavior Spec (PRD 03)](./docs/PRD03.md)
+- [Design Docs (PRD 04)](./docs/PRD04.md)
+- [Specification (PRD 05)](./docs/PRD05.md)
+- [Setup Guide](./docs/SETUP.md)
+- [Troubleshooting](./docs/TROUBLESHOOTING.md)
+
+---
+
+## Why Speexor?
+
+Speexor was created because existing agent orchestration tools were either tied to a single AI provider or required complex infrastructure. Speexor is:
+
+- **Agent-agnostic** — run OpenCode, Claude Code, Aider, or Codex with the same CLI
+- **Lightweight** — zero external runtime dependencies beyond your agents and git
+- **Repository-native** — works with your existing GitHub repos, issues, and PR workflows
+- **Extensible** — swap any plugin slot with your own implementation
+
+---
+
+## License
+
+[MIT](LICENSE) © SuperDevIds

package/REFACTOR-LOG.md

@@ -0,0 +1,40 @@
+# Refactoring Log
+
+> Tracking significant architectural changes and refactoring decisions for Speexor.
+
+## [2026-06-30] — Initial Implementation (v0.1.0)
+
+### Context
+Initial implementation of the Agent Orchestrator based on PRD01.md. Built from scratch as `packages/speexor` in the speexjs monorepo.
+
+### Decisions
+1. **Plugin Architecture**: 7 fixed plugin slots (agent, runtime, workspace, tracker, scm, notifier, terminal) — inspired by AgentWrapper AO but with cleaner interface segregation
+2. **Monorepo as Single Package**: Unlike AO's multi-package structure, v1 lives in a single `@speexjs/speexor` package with internal module separation. This reduces initial complexity while maintaining clean module boundaries via `src/` directories.
+3. **TypeScript ESM Only**: No CJS support. The rest of speexjs ecosystem is ESM-first.
+4. **Built-in HTTP Dashboard**: Using Node.js built-in `http` module instead of Express/NestJS to keep dependencies minimal for v1.
+5. **No Dynamic Plugin Loading**: All built-in plugins are hardcoded in `loadAllPlugins()`. Dynamic loading from external packages is deferred to v2.
+6. **Synchronous File I/O for State**: `SessionStore` uses `readFileSync`/`writeFileSync` for simplicity. Will migrate to async when performance requires it.
+
+### Rebrand: Konduktor → Speexor
+The project was initially codenamed "Konduktor" internally. After initial implementation, renamed to "Speexor" to align with the SpeexJS brand ecosystem. All code identifiers, CLI names, config files, and documentation were updated.
+
+### Patterns Established
+- `PluginModule` base interface with `initialize()`/`destroy()` lifecycle
+- Debug namespace pattern: `speexor:<module>:<submodule>`
+- Session ID format: `<prefix>-<task-id>-<timestamp>`
+- Worktree branch format: `speexor/<task-id>`
+- Config directory: `.speexor/` at project root
+
+### Technical Debt
+- No test files yet (vitest configured but no tests written)
+- `getLiveStream()` throws "not implemented" in both runtime plugins
+- Terminal plugin has no implementation
+- Dashboard HTML is inline (hard to maintain)
+- Session store uses synchronous I/O
+- No dynamic plugin discovery mechanism
+
+### What Worked Well
+- TypeScript strict mode caught several type errors during initial build
+- Event bus pattern cleanly decouples lifecycle from dashboard
+- Zod validation provides clear error messages for misconfigured YAML
+- Plugin interface design allows adding new providers without touching core

package/ROADMAP.md

@@ -0,0 +1,78 @@
+# Roadmap
+
+> Development roadmap for Speexor — Agent Orchestrator.
+
+## Current Release: v0.1.0 (Foundation)
+
+Completed milestones:
+- M0: Monorepo setup, core lifecycle, plugin contract types
+- M1: Single-agent E2E (OpenCode + tmux/process + git worktree)
+- M2: GitHub integration (tracker + SCM + reaction engine)
+- M3: Multi-agent adapters (Claude Code, Aider, Codex)
+- M4: Dashboard MVP (REST API + HTML frontend)
+
+## Upcoming Milestones
+
+### M5 — Cost & Provider Panel (Target: Q3 2026)
+- Multi-provider routing config
+- Cost tracking per provider per project
+- Usage analytics dashboard panel
+- Provider fallback configuration UI
+
+### M6 — Polish & Documentation (Target: Q3 2026)
+- Comprehensive test suite (Vitest + integration tests)
+- CI/CD pipeline setup
+- Open-source readiness review
+- Performance benchmarking
+
+### M7 — Recursive Task Decomposition (Target: Q4 2026)
+- DAG-based task breakdown
+- Parallel sub-agent spawning
+- Task dependency resolution
+- Progress tracking across sub-tasks
+- Context window management
+
+### M8 — Real-Time Terminal (Target: Q4 2026)
+- WebSocket-based live terminal streaming
+- xterm.js integration in dashboard
+- Terminal resize and interactive input
+- Session recording and replay
+
+### M9 — Extension Marketplace (Target: Q1 2027)
+- Extension manifest format
+- Plugin SDK (@speexor/sdk)
+- Marketplace index (GitHub-based registry)
+- Extension install/update/remove lifecycle
+- Permission system for extensions
+
+### M10 — Advanced Security & Compliance (Target: Q1 2027)
+- End-to-end encryption for cross-device sync
+- Secret scanning in agent output
+- Audit logging for all agent actions
+- Air-gapped mode
+- SBOM generation
+
+### M11 — Multi-Host Distribution (Target: Q2 2027)
+- Docker runtime support
+- Remote agent execution
+- Load balancing across hosts
+- Agent pool management
+
+## Themes
+
+### 🎯 Short-term (Q3 2026)
+- Polish existing features
+- Test coverage >80%
+- Documentation completion
+- Cost tracking
+
+### 🚀 Medium-term (Q4 2026)
+- Recursive task decomposition
+- Real-time terminal streaming
+- Advanced observability
+
+### 🌟 Long-term (2027)
+- Extension marketplace
+- Plugin SDK for community
+- Multi-host distributed execution
+- Enterprise security features

package/SECURITY.md

@@ -0,0 +1,79 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.1.x   | ✅ Active development |
+
+## Reporting a Vulnerability
+
+Speexor handles API tokens (GitHub tokens, AI provider keys) and executes AI-generated code. Security is a top priority.
+
+**To report a vulnerability:**
+1. **Do NOT** open a public GitHub issue
+2. Email: opensource@superdevids.com (or use GitHub's private vulnerability reporting)
+3. Include a detailed description, steps to reproduce, and potential impact
+
+You can expect:
+- **Acknowledgment** within 48 hours
+- **Initial assessment** within 5 business days
+- **Fix timeline** depending on severity
+
+## Security Practices
+
+### Credential Management
+- API tokens are stored in environment variables or the system keychain
+- Secrets are never logged in plaintext
+- GitHub tokens are reused from `gh` CLI when possible
+- `.speexor/` directory is git-ignored (add to `.gitignore`)
+
+### Code Execution
+- AI agents generate and execute code in isolated git worktrees
+- Each agent runs in its own process/tmux session
+- Process runtime has resource limits (SIGTERM → SIGKILL after 5s)
+- Worktrees are cleaned up on session stop or package destroy
+
+### Network Security
+- Dashboard server listens on localhost by default
+- CORS is enabled (configurable in production)
+- No telemetry or tracking
+- No cloud dependency — fully local-first
+
+### Data Protection
+- Session state stored in `.speexor/state.json` (local only)
+- Logs stored in `.speexor/logs/` (local only)
+- No data sent to external servers except configured AI providers and GitHub API
+- Users control which API endpoints are called
+
+### Supply Chain Security
+- All dependencies are pinned with exact versions
+- pnpm lockfile for deterministic installs
+- Regular dependency audits via `pnpm audit`
+- Minimal runtime dependencies (12 packages)
+
+## Security Checklist for Deployments
+
+- [ ] AI provider API keys stored in environment variables (not config files)
+- [ ] GitHub tokens use minimal scopes (repo, issues, pull requests)
+- [ ] Dashboard port not exposed to public internet
+- [ ] `.speexor/` directory added to `.gitignore`
+- [ ] Regular dependency updates (`pnpm audit`)
+- [ ] Agent output reviewed before auto-merge (auto-merge disabled by default)
+
+## Third-Party Security
+
+Speexor relies on:
+- **GitHub CLI (`gh`)** — user's existing authentication
+- **AI agent CLIs** — OpenCode, Claude Code, Aider, Codex — each with their own security models
+- **tmux** (Unix) / **Process** (Windows) — for runtime isolation
+
+Review the security documentation for each tool you use.
+
+## Incident Response
+
+1. **Detection** — Monitoring for unusual agent behavior or unauthorized access
+2. **Containment** — `speexor stop <session>` to halt affected agents
+3. **Analysis** — Review logs in `.speexor/logs/` and session state
+4. **Recovery** — Rotate affected credentials, clean up worktrees
+5. **Postmortem** — Document findings, update security practices