speexor 0.1.1 → 0.2.1

package/CONTRIBUTING.md

@@ -1,98 +1,93 @@
-# 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
+# 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 Speexor repository
+# Note: speexor = product package (this repo), speexjs = monorepo umbrella org
+git clone https://github.com/superdevids/speexor.git
+cd speexor
+
+# Install dependencies
+pnpm install
+
+# Build the package
+pnpm build
 ```
-
-## 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
+
+## 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

@@ -1,105 +1,132 @@
-# 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 speexor
-# or
-pnpm add -g 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
-```
+# 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 speexor
+# or
+pnpm add -g 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 submit a high-level task for decomposition?
+```bash
+speexor task submit "Build a user authentication system"
+```
+This sends the task to the Planner Engine, which decomposes it into a DAG of sub-tasks with automatic dependency resolution.
+
+### 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 manage extensions?
+```bash
+speexor ext search <query>       # Search the extension marketplace
+speexor ext install <name>       # Install an extension
+speexor ext list                 # List installed extensions
+speexor ext update [name]        # Update extension(s)
+speexor ext remove <name>        # Remove an extension
+```
+
+### How do I validate my config?
+```bash
+speexor config validate
+```
+This checks your `speexor.config.yaml` against the current schema and reports any issues.
+
+### How do I evaluate decision quality?
+```bash
+speexor eval decisions
+```
+This runs a calibration analysis on the Decision Log, comparing confidence scores against actual outcomes.
+
+### 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 `maxConcurrentAgents` in the config to limit parallel agents. The scheduler automatically respects resource constraints.
+
+### 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/GLOSSARY.md

@@ -0,0 +1,34 @@
+# Glossary
+
+> Canonical term definitions for Speexor. All terms from v4 §4 and v5 §6.
+
+| Term | Definition | Not to be confused with |
+|------|-----------|------------------------|
+| **Agent** | A single AI coding agent instance (OpenCode, Claude Code, Aider, Codex) spawned by the orchestrator to execute a task. | **Subagent** (child of an Agent), **Agent Backend** (the CLI/provider binary) |
+| **Agent Backend** | The underlying CLI binary or API that an Agent adapter wraps — e.g., `opencode`, `claude-code`, `aider`, `codex`. | **Agent** (the managed instance), **Provider** (the LLM model behind the CLI) |
+| **Approvals** | The single unified dashboard panel covering both Task Origin Gate (proposed tasks) and Action Risk Gate (high-stakes actions), per FR-87. Each item is tagged with its gate type, countdown timer, and default action. | **Decision Log** (read-only history), **Review Queue** (deprecated name) |
+| **Atomic Unit of Work** | The smallest in-progress chunk of an agent's current action (e.g., finishing one function edit, one file write, one commit) that must complete before a Graceful Handoff (pause/redirect/interrupt) takes effect. | **Task Node** (a full unit of decomposition), **Checkpoint** (saved state boundary) |
+| **Decision Log** | The read-only, searchable history of all autonomous decisions — both auto-executed and approved/rejected ones — including confidence scores and reasoning. Previously called "Decision Journal" / "Review Queue." | **Approvals** (actionable items), **Session Log** (raw agent I/O) |
+| **EventBus** | An EventEmitter3 wrapper through which all inter-module communication flows. Plugins and dashboard components subscribe to events without importing each other. | **Direct method call** (the alternative pattern we avoid for loose coupling) |
+| **Extension** | A third-party add-on installed via the Marketplace, declared by a `speexor.extension.json` manifest. Extensions can be skills (prompt/logic bundles), plugins (runtime adapters), or UI panels. | **Plugin** (built-in first-party adapter), **Skill** (a type of extension, not the container) |
+| **Library** | A versioned, installable Node.js package dependency used by an Extension (Plugin/Skill/Agent Backend adapter). Distributed via npm, resolved by the extension manager at install time following standard Node.js resolution rules. | **Plugin** (runtime adapter), **Skill** (prompt/logic bundle) |
+| **Graceful Handoff** | The protocol whereby an in-progress agent completes its current Atomic Unit of Work before pausing, redirecting, or being interrupted — ensuring no half-finished file edits. | **Hard kill** (immediate termination, used only for unresponsive agents) |
+| **MCP Server** | A Model Context Protocol server that provides tools, resources, and prompts to AI agents. Speexor extensions can expose MCP servers that agents discover and invoke at runtime. | **Plugin** (internal to Speexor), **Agent Backend** (the CLI being orchestrated) |
+| **Notifier Plugin** | One of the 7 plugin slots. Sends desktop notifications (macOS, Windows, Linux) for events like `approved-and-green` or stuck agents. | **Tracker Plugin** (fetches issues), **SCM Plugin** (git/PR operations) |
+| **Orchestrator** | The central Speexor lifecycle that manages plugin registration, session state, agent spawning, and the EventBus. The orchestrator does not execute code — it coordinates. | **Agent** (executes code), **Scheduler** (decides which agent runs when) |
+| **Plugin** | A built-in first-party adapter implementing one of the 7 plugin slot interfaces (agent, runtime, workspace, tracker, scm, notifier, terminal). | **Extension** (third-party, Marketplace-installed), **MCP Server** (external protocol) |
+| **Plugin Slot** | One of 7 typed interfaces (`AgentPlugin`, `RuntimePlugin`, `WorkspacePlugin`, `TrackerPlugin`, `SCMPlugin`, `NotifierPlugin`, `TerminalPlugin`) that plugins implement. | **Plugin** (the instance), **Extension** (third-party add-on) |
+| **Reaction Engine** | Subsystem that listens to Tracker/SCM events (ci-failed, changes-requested, approved-and-green) and executes configurable automated responses (fix, notify, escalate, skip) with retry tracking. | **EventBus** (transport layer), **Governance Engine** (approval gating) |
+| **Runtime Plugin** | One of the 7 plugin slots. Creates/destroys terminal sessions for agent execution. Implementations: tmux (Unix) and Process (Windows). | **Agent Plugin** (spawns the AI), **Workspace Plugin** (manages worktrees) |
+| **SCM Plugin** | One of the 7 plugin slots. Handles git operations: branch creation, commit/push, PR creation, CI status checks. | **Tracker Plugin** (issue management), **Workspace Plugin** (worktree management) |
+| **Session** | A running instance of an agent, bound to a specific worktree and runtime session. Created by `spawnAgent()`, tracked in the in-memory session map and persisted in `state.json`. | **Agent** (the CLI binary), **Task** (what the agent is working on) |
+| **Skill** | An extension type (`type: "skill"` in `speexor.extension.json`) that bundles prompt templates and logic for a specific capability (e.g., code review, test writing). | **Plugin** (runtime adapter), **Extension** (the container format) |
+| **Subagent** | An agent spawned by another agent during recursive task decomposition. Operates in its own worktree forked from the parent agent's branch at a pinned commit hash (per Worktree Hierarchy Protocol). | **Agent** (top-level), **Worker Agent** (generic term) |
+| **Task Graph** | A directed acyclic graph (DAG) representing decomposed work items. Each Task Node has dependencies (edges), and nodes with no inter-dependency execute in parallel. | **Task List** (flat, no dependency ordering) |
+| **Task Node** | A single unit of decomposed work within the Task Graph. Has a description, depth, status, assigned agent, and optional parent task ID. | **Atomic Unit of Work** (runtime granularity), **Issue** (from tracker, mapped to a root task) |
+| **Task Origin Gate** | Axis 1 of the unified Approval Model (FR-86). Applies once when a task is first proposed by an agent (not the user). Governed by `governance.autoApproveProposedTasks`. | **Action Risk Gate** (Axis 2 — runtime action gating) |
+| **Action Risk Gate** | Axis 2 of the unified Approval Model (FR-86). Applies every time any task executes a high-stakes action. Governed by `riskPolicy`. | **Task Origin Gate** (Axis 1 — task proposal gating) |
+| **Terminal Plugin** | One of the 7 plugin slots. Provides interactive terminal attach/detach for live session viewing in the dashboard. | **Runtime Plugin** (creates the session), **Dashboard** (renders the terminal) |
+| **Tracker Plugin** | One of the 7 plugin slots. Fetches issues and subscribes to tracker events (issue-opened, issue-closed, CI events). | **SCM Plugin** (PR/CI operations), **Notifier Plugin** (desktop alerts) |
+| **Worktree Hierarchy Protocol** | The formal protocol (FR-88) for subagent branch management: subagent worktrees are pinned to the parent's spawn-time commit hash, merges are serialized (never concurrent), and merge conflicts escalate to Axis-2 approval. | **Git worktree** (the underlying git primitive), **Workspace Plugin** (manages worktrees) |
+| **Workspace Plugin** | One of the 7 plugin slots. Creates and removes isolated git worktrees for each agent task. | **Runtime Plugin** (terminal session), **SCM Plugin** (branch/PR operations) |

package/LICENSE.md

@@ -1,21 +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.
+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.