speexor 0.1.1 → 0.2.0

package/docs/SETUP.md

@@ -1,94 +1,94 @@
-# Speexor Setup Guide
-
-## Prerequisites
-
-- **Node.js** >= 18.0.0
-- **pnpm** (recommended) or npm
-- **Git** >= 2.30 (for `git worktree` support)
-- **GitHub CLI** (`gh`) — for tracker & SCM plugins (optional for local-only mode)
-- **tmux** >= 3.0 — for tmux runtime (macOS/Linux, optional with process fallback)
-- One or more AI coding agent CLIs:
-  - [OpenCode CLI](https://github.com/superdevids/opencode)
-  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
-  - [Aider](https://aider.chat/)
-  - [Codex CLI](https://github.com/openai/codex)
-
-## Installation
-
-```bash
-# Via npm
-npm install -g speexor
-
-# Or via pnpm
-pnpm add -g speexor
-
-# Or run from the monorepo
-cd speexjs
-pnpm install
-pnpm --filter speexor build
-```
-
-## Quick Start
-
-### 1. Initialize a project
-
-```bash
-cd /path/to/your/project
-speexor start https://github.com/username/repo.git
-```
-
-This will:
-- Create `speexor.config.yaml` with default configuration
-- Create `.speexor/` directory for worktrees and logs
-- Start the dashboard at `http://localhost:3000`
-
-### 2. Spawn an agent for a task
-
-```bash
-# Using a GitHub issue ID
-speexor agent spawn --task 42 --agent opencode
-
-# Using a custom task ID
-speexor agent spawn --task "feature-auth" --agent claude-code
-```
-
-### 3. Monitor progress
-
-```bash
-# Open dashboard in browser
-open http://localhost:3000
-
-# List active sessions
-speexor list
-
-# View agent logs
-speexor logs <session-id>
-```
-
-### 4. Stop a session
-
-```bash
-speexor stop <session-id>
-```
-
-## Configuration
-
-See `speexor config-help` for full schema reference, or refer to `examples/basic.yaml` in the package.
-
-## Plugin Architecture
-
-Speexor uses a 7-slot plugin architecture:
-
-| Slot | Purpose | Default Plugin |
-|------|---------|---------------|
-| **Agent** | AI coding agent adapter | OpenCode, Claude Code, Aider, Codex |
-| **Runtime** | Process execution environment | tmux (Unix), Process (Windows) |
-| **Workspace** | Code isolation strategy | Git Worktree |
-| **Tracker** | Task/issue source | GitHub Issues |
-| **SCM** | Git/PR operations | GitHub (gh CLI) |
-| **Notifier** | Alert channel | Desktop notifications |
-| **Terminal** | Live session viewer | Web (dashboard) |
-
-## Troubleshooting
-
-See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for common issues.
+# Speexor Setup Guide
+
+## Prerequisites
+
+- **Node.js** >= 18.0.0
+- **pnpm** (recommended) or npm
+- **Git** >= 2.30 (for `git worktree` support)
+- **GitHub CLI** (`gh`) — for tracker & SCM plugins (optional for local-only mode)
+- **tmux** >= 3.0 — for tmux runtime (macOS/Linux, optional with process fallback)
+- One or more AI coding agent CLIs:
+  - [OpenCode CLI](https://github.com/superdevids/opencode)
+  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+  - [Aider](https://aider.chat/)
+  - [Codex CLI](https://github.com/openai/codex)
+
+## Installation
+
+```bash
+# Via npm
+npm install -g speexor
+
+# Or via pnpm
+pnpm add -g speexor
+
+# Or run from the monorepo
+cd speexjs
+pnpm install
+pnpm --filter speexor build
+```
+
+## Quick Start
+
+### 1. Initialize a project
+
+```bash
+cd /path/to/your/project
+speexor start https://github.com/username/repo.git
+```
+
+This will:
+- Create `speexor.config.yaml` with default configuration
+- Create `.speexor/` directory for worktrees and logs
+- Start the dashboard at `http://localhost:3000`
+
+### 2. Spawn an agent for a task
+
+```bash
+# Using a GitHub issue ID
+speexor agent spawn --task 42 --agent opencode
+
+# Using a custom task ID
+speexor agent spawn --task "feature-auth" --agent claude-code
+```
+
+### 3. Monitor progress
+
+```bash
+# Open dashboard in browser
+open http://localhost:3000
+
+# List active sessions
+speexor list
+
+# View agent logs
+speexor logs <session-id>
+```
+
+### 4. Stop a session
+
+```bash
+speexor stop <session-id>
+```
+
+## Configuration
+
+See `speexor config-help` for full schema reference, or refer to `examples/basic.yaml` in the package.
+
+## Plugin Architecture
+
+Speexor uses a 7-slot plugin architecture:
+
+| Slot | Purpose | Default Plugin |
+|------|---------|---------------|
+| **Agent** | AI coding agent adapter | OpenCode, Claude Code, Aider, Codex |
+| **Runtime** | Process execution environment | tmux (Unix), Process (Windows) |
+| **Workspace** | Code isolation strategy | Git Worktree |
+| **Tracker** | Task/issue source | GitHub Issues |
+| **SCM** | Git/PR operations | GitHub (gh CLI) |
+| **Notifier** | Alert channel | Desktop notifications |
+| **Terminal** | Live session viewer | Web (dashboard) |
+
+## Troubleshooting
+
+See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for common issues.

package/docs/TROUBLESHOOTING.md

@@ -1,113 +1,113 @@
-# Speexor Troubleshooting Guide
-
-## Common Issues
-
-### "speexor.config.yaml not found"
-
-**Cause:** You ran `speexor list` or `speexor agent spawn` without initializing a project first.
-
-**Fix:** Run `speexor start <repo-url>` to create the config file, or manually create `speexor.config.yaml` in your project root.
-
-### "Not a git repository"
-
-**Cause:** You're running `speexor` outside a git repository.
-
-**Fix:** Navigate to a git repository or run `git init` first.
-
-### "tmux not available"
-
-**Cause:** tmux is not installed on your system.
-
-**Fix (macOS):**
-```bash
-brew install tmux
-```
-
-**Fix (Linux):**
-```bash
-sudo apt install tmux  # Debian/Ubuntu
-sudo dnf install tmux  # Fedora
-```
-
-**Fix (Windows):** Speexor will automatically fall back to the Process runtime on Windows.
-
-### "GitHub CLI (gh) not found"
-
-**Cause:** The `gh` CLI is not installed but required for GitHub tracker/SCM plugins.
-
-**Fix:**
-```bash
-# macOS
-brew install gh
-
-# Linux (Debian/Ubuntu)
-sudo apt install gh
-
-# Windows (winget)
-winget install GitHub.cli
-
-# Or manual: https://cli.github.com/
-```
-
-### Agent spawn fails
-
-**Cause:** The specified agent CLI is not installed or not in PATH.
-
-**Fix:** Ensure the agent CLI is installed and accessible:
-```bash
-# Verify
-opencode --version
-claude --version
-aider --version
-codex --version
-```
-
-### "Worktree already exists"
-
-**Cause:** A worktree for the same branch already exists, possibly from a previous interrupted session.
-
-**Fix:**
-```bash
-# List worktrees
-git worktree list
-
-# Remove stale worktree
-speexor stop <session-id>
-# Or manually:
-git worktree remove --force .speexor/worktrees/<task-id>
-```
-
-### Dashboard not showing
-
-**Cause:** Port 3000 might be in use, or the dashboard was not started.
-
-**Fix:**
-```bash
-# Specify a different port
-speexor start --port 4000
-
-# Or start dashboard only (if already initialized)
-speexor start
-```
-
-## Windows-Specific Issues
-
-### ConPTY Fallback
-
-On Windows, tmux is not available. Speexor automatically uses the Process runtime instead. This works for most cases but lacks live terminal streaming.
-
-### Shell Path
-
-If you use PowerShell, the default shell path detection should work. To customize:
-
-```yaml
-# In speexor.config.yaml
-plugins:
-  runtime: process
-```
-
-## Getting Help
-
-- Open an issue: https://github.com/superdevids/speexjs/issues
-- Check the PRD: [PRD01.md](./PRD01.md)
-- Ask in the SpeexJS community
+# Speexor Troubleshooting Guide
+
+## Common Issues
+
+### "speexor.config.yaml not found"
+
+**Cause:** You ran `speexor list` or `speexor agent spawn` without initializing a project first.
+
+**Fix:** Run `speexor start <repo-url>` to create the config file, or manually create `speexor.config.yaml` in your project root.
+
+### "Not a git repository"
+
+**Cause:** You're running `speexor` outside a git repository.
+
+**Fix:** Navigate to a git repository or run `git init` first.
+
+### "tmux not available"
+
+**Cause:** tmux is not installed on your system.
+
+**Fix (macOS):**
+```bash
+brew install tmux
+```
+
+**Fix (Linux):**
+```bash
+sudo apt install tmux  # Debian/Ubuntu
+sudo dnf install tmux  # Fedora
+```
+
+**Fix (Windows):** Speexor will automatically fall back to the Process runtime on Windows.
+
+### "GitHub CLI (gh) not found"
+
+**Cause:** The `gh` CLI is not installed but required for GitHub tracker/SCM plugins.
+
+**Fix:**
+```bash
+# macOS
+brew install gh
+
+# Linux (Debian/Ubuntu)
+sudo apt install gh
+
+# Windows (winget)
+winget install GitHub.cli
+
+# Or manual: https://cli.github.com/
+```
+
+### Agent spawn fails
+
+**Cause:** The specified agent CLI is not installed or not in PATH.
+
+**Fix:** Ensure the agent CLI is installed and accessible:
+```bash
+# Verify
+opencode --version
+claude --version
+aider --version
+codex --version
+```
+
+### "Worktree already exists"
+
+**Cause:** A worktree for the same branch already exists, possibly from a previous interrupted session.
+
+**Fix:**
+```bash
+# List worktrees
+git worktree list
+
+# Remove stale worktree
+speexor stop <session-id>
+# Or manually:
+git worktree remove --force .speexor/worktrees/<task-id>
+```
+
+### Dashboard not showing
+
+**Cause:** Port 3000 might be in use, or the dashboard was not started.
+
+**Fix:**
+```bash
+# Specify a different port
+speexor start --port 4000
+
+# Or start dashboard only (if already initialized)
+speexor start
+```
+
+## Windows-Specific Issues
+
+### ConPTY Fallback
+
+On Windows, tmux is not available. Speexor automatically uses the Process runtime instead. This works for most cases but lacks live terminal streaming.
+
+### Shell Path
+
+If you use PowerShell, the default shell path detection should work. To customize:
+
+```yaml
+# In speexor.config.yaml
+plugins:
+  runtime: process
+```
+
+## Getting Help
+
+- Open an issue: https://github.com/superdevids/speexjs/issues
+- Check the PRD: [PRD01.md](./PRD01.md)
+- Ask in the SpeexJS community

package/docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,44 @@
+# ADR-0001: Use Architecture Decision Records
+
+## Status
+
+Accepted
+
+## Context
+
+Speexor is a plugin-based, agent-agnostic orchestrator for multi-AI coding agents. As the project grows, contributors and maintainers need a clear historical record of why architectural choices were made. Without this, future developers may reverse decisions without understanding the original rationale, leading to inconsistent architecture.
+
+## Decision
+
+We will use Architecture Decision Records (ADRs) in `docs/adr/` to document all significant architectural decisions. Each ADR follows this template:
+
+```markdown
+# ADR-NNNN: Title
+
+## Status
+
+[Proposed | Accepted | Deprecated | Superseded by ADR-NNNN]
+
+## Context
+
+The background, constraints, and forces that led to this decision.
+
+## Decision
+
+The architectural choice we made and how it addresses the context.
+
+## Consequences
+
+The trade-offs, benefits, and costs of this decision.
+```
+
+- ADRs are numbered sequentially (0001, 0002, ...).
+- ADRs are written in the present tense as of the decision date.
+- ADRs are never deleted; deprecated ADRs link to their replacement.
+- ADRs are committed alongside the code changes they describe.
+
+## Consequences
+
+- **Positive:** Clear rationale trail for future contributors; easier onboarding; architectural consistency enforced by explicit record-keeping.
+- **Negative:** Overhead of writing and maintaining ADRs; risk of falling behind if decisions are not documented promptly.
+- **Neutral:** ADRs become a permanent part of the codebase in `docs/adr/`.

package/docs/adr/0002-plugin-architecture.md

@@ -0,0 +1,53 @@
+# ADR-0002: 7-Slot Plugin Architecture with EventBus
+
+## Status
+
+Accepted
+
+## Context
+
+Speexor must support diverse capabilities — agent adapters, runtime backends, workspace management, issue tracking, SCM operations, notifications, and terminal I/O — without coupling these concerns in the core lifecycle. The architecture must allow:
+
+1. New plugins to be added without modifying core code.
+2. Multiple implementations per slot (e.g., tmux and Process for runtime).
+3. Loose communication between plugins and the dashboard.
+4. Graceful degradation when a plugin dependency (e.g., `tmux`, `gh` CLI) is unavailable.
+
+## Decision
+
+### Seven Plugin Slots
+
+We define exactly seven plugin slots, each with a dedicated TypeScript interface:
+
+| Slot       | Interface          | Purpose                              |
+|------------|---------------------|---------------------------------------|
+| agent      | `AgentPlugin`       | Spawn, communicate with, kill agents |
+| runtime    | `RuntimePlugin`     | Create/destroy terminal sessions     |
+| workspace  | `WorkspacePlugin`   | Manage isolated git worktrees        |
+| tracker    | `TrackerPlugin`     | Fetch issues, subscribe to events    |
+| scm        | `SCMPlugin`         | Branch, commit, PR, CI operations    |
+| notifier   | `NotifierPlugin`    | Desktop notifications                |
+| terminal   | `TerminalPlugin`    | Interactive terminal attach/detach   |
+
+### EventBus over Direct Calls
+
+All inter-module communication flows through an EventBus (EventEmitter3 wrapper) rather than direct method calls. This means:
+
+- The dashboard subscribes to lifecycle events without lifecycle knowing about the dashboard.
+- Plugins emit events (e.g., `session:created`, `worktree:created`) without importing other modules.
+- New observers (e.g., logging, metrics) can be added without modifying existing code.
+
+### getFirstPlugin() Resolution
+
+When the lifecycle needs a plugin for a slot, it calls `getFirstPlugin<T>(slot)` which returns the first registered implementation. This allows:
+
+- Multiple implementations per slot (e.g., both TmuxRuntime and ProcessRuntime).
+- Implicit priority ordering by registration order.
+- Graceful fallback: if the primary plugin fails initialization, the next in the list serves.
+
+## Consequences
+
+- **Positive:** Loose coupling; plugins are independently testable; new capabilities slot in without core changes.
+- **Positive:** The `getFirstPlugin()` pattern enables natural fallback (ProcessRuntime when tmux is absent).
+- **Negative:** Event-based flow is harder to trace than direct calls during debugging.
+- **Negative:** Seven slots are a fixed set — adding a new slot requires a core type change and a new interface definition.

package/docs/adr/0003-recursive-task-decomposition.md

@@ -0,0 +1,57 @@
+# ADR-0003: DAG-Based Recursive Task Decomposition with LLM Planner
+
+## Status
+
+Accepted
+
+## Context
+
+Speexor must decompose complex tasks (e.g., "implement feature X across the full stack") into smaller, parallel-executable units that can be distributed across multiple agents. Two core design questions arise:
+
+1. **Representation:** Should the task structure be a flat list, a tree, or a directed acyclic graph (DAG)?
+2. **Planner:** Should the decomposition algorithm be rule-based (deterministic) or LLM-driven (probabilistic)?
+
+The representation must handle dependency ordering (task B depends on task A, task C depends on both) and allow parallel execution of independent sub-tasks. The planner must adapt to arbitrary repo structures and technologies without hardcoded rules.
+
+## Decision
+
+### DAG-Based Task Graph
+
+We represent decomposed tasks as a **directed acyclic graph (DAG)** where:
+
+- Each **Task Node** represents one atomic unit of work.
+- Edges represent **depends-on** relationships (a node cannot execute until all predecessors complete).
+- Nodes with no edges between them are eligible for parallel execution.
+- The graph supports dynamic refinement: a node in progress can be further decomposed into sub-DAGs at runtime.
+
+This choice over a flat list (which cannot express dependencies) or a tree (which cannot express cross-branch dependencies like "both frontend and backend depend on the shared schema change").
+
+### LLM-Based Planner over Algorithmic Decomposition
+
+We use an LLM-based planner (configurable per project, defaulting to `deepseek-reasoner`) to decompose tasks rather than a rule-based algorithm. Rationale:
+
+- **Arbitrary tech stacks:** The planner reads the repo structure and task description, then generates a decomposition customized to the actual codebase — no hardcoded "microservice decomposition" rules needed.
+- **Context-aware granularity:** The LLM decides how fine-grained each sub-task should be based on complexity, rather than a fixed heuristic.
+- **Adaptive refinement:** If the initial decomposition is too coarse, the planner can further decompose a node mid-execution using the same LLM.
+- **Human-readable plans:** The LLM generates natural language descriptions for each node, which feed into the approval UI and decision log.
+
+### Configuration
+
+```yaml
+decomposition:
+  maxTaskGraphDepth: 3      # Max depth of the Task Graph (node depth)
+  maxAgentSpawnDepth: 3     # Max levels of subagent spawning
+  maxNodesPerGraph: 50      # Safety limit on graph size
+  plannerProvider: opencode # Which agent backend to use for planning
+  plannerModel: deepseek-reasoner  # Model for the planner LLM call
+```
+
+The two depth limits (`maxTaskGraphDepth` and `maxAgentSpawnDepth`) are tracked separately — a deep task graph does not force deep agent spawning if the planner assigns shallow agents to deep nodes.
+
+## Consequences
+
+- **Positive:** DAG enables maximum parallelism — independent sub-tasks execute concurrently.
+- **Positive:** LLM planner adapts to any codebase without rule maintenance.
+- **Negative:** LLM planner calls add latency and cost to the decomposition phase.
+- **Negative:** DAG complexity requires a scheduler with dependency resolution (no simple FIFO queue).
+- **Neutral:** The `maxTaskGraphDepth`/`maxAgentSpawnDepth` split prevents confusion between graph depth and agent hierarchy depth (per FR-89).

package/docs/adr/0004-local-first-security.md

@@ -0,0 +1,58 @@
+# ADR-0004: Local-First Security with Two-Layer Defense
+
+## Status
+
+Accepted
+
+## Context
+
+Speexor manages AI agents that write code, execute commands, and interact with git providers. This introduces two distinct security surfaces:
+
+1. **Third-party extensions** (installed via the future Marketplace) that can access the file system, shell, and network.
+2. **Runtime agent actions** — file edits, git operations, PR creation, CI interactions — some of which are irreversible (e.g., force-push to main).
+
+The architecture must ensure that a malicious or buggy extension cannot compromise the host system, and that high-risk agent actions require explicit human approval.
+
+## Decision
+
+### Local-First Architecture
+
+All data, credentials, and execution remain on the user's machine. There is no cloud relay, no telemetry by default, and no remote control plane. This means:
+
+- Secrets are stored in the OS keychain (via `conf` with `encryptionKey`), never in plaintext config files.
+- The dashboard runs on localhost only (`127.0.0.1`) by default.
+- The decision log and session state never leave the `~/.speexor/` directory.
+
+### Two-Layer Defense: Extension Permissions + Action Risk Tiers
+
+These are two independent, complementary layers documented in `SECURITY-DEFAULTS.md`:
+
+**Layer 1 — Extension Permissions (install-time capability gating):**
+
+Defined by `extensions.permissionsMode` in config (`strict` | `permissive`). Each extension declares capabilities (`shell`, `network`, `fileSystem`, `clipboard`) at install time. In `strict` mode, the user must explicitly approve each capability; in `permissive` mode, all declared capabilities are auto-granted. This layer gates what an extension *can ever do* — set once, at install.
+
+Extensions with `shell: none` and `network: none` run in `isolated-vm` (true V8 isolate, no access to Node built-ins). Extensions requiring `fileSystem`/`shell`/`network` run as separate OS processes with minimum privileges and a permission-enforcing proxy layer intercepting `fs`/`net`/`child_process` calls.
+
+`worker_threads` is explicitly **not** used as a security boundary — it is a performance-only primitive for orchestrator-internal CPU-bound work (per FR-85).
+
+**Layer 2 — Action Risk Tiers (runtime action gating):**
+
+Defined by `riskPolicy` in config. Every action an agent or extension takes is classified into a risk tier. Actions in `requireApproval` tiers (e.g., `irreversible-high-stakes`) block until the user approves. Actions in `autoApprove` tiers (e.g., `reversible-low`) execute autonomously. Unknown actions default to `high-stakes` (safe default).
+
+This layer gates what *any* action (from any already-permitted extension or core agent) *does right now* — evaluated every time, separate from the install-time capability grant.
+
+### Sandboxing: isolated-vm over worker_threads
+
+| Mechanism       | Security Boundary | Use Case                         |
+|-----------------|-------------------|----------------------------------|
+| `isolated-vm`   | True V8 isolate   | Extensions with no shell/network |
+| OS process      | OS-level          | Extensions with shell/network    |
+| `worker_threads`| None (same proc)  | Orchestrator-internal CPU work   |
+
+## Consequences
+
+- **Positive:** Two layers provide defense-in-depth — an extension with "write files" capability still cannot force-push to main without risk-tier approval.
+- **Positive:** Local-first ensures no external dependency for security; no cloud outage can leak secrets.
+- **Negative:** `isolated-vm` is a native dependency that complicates cross-platform builds and installs.
+- **Negative:** Two-layer model requires clear documentation (covered by `SECURITY-DEFAULTS.md`).
+- **Neutral:** `worker_threads` reclassification from v4's proposal removes a false sense of security.