orkestrate 0.1.14 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,56 @@
+# Orkestrate — agent instructions
+
+Help the user **browse, use, and share specialized harnesses** for **agent packs**.
+
+## What it is
+
+| Term | Meaning |
+|------|---------|
+| Agent pack | `pack.yaml` + `harnesses/opencode/` — installable agent product |
+| Harness slice | Task-specific runtime (tools, prompts, skills) inside the pack |
+| Orkestrate | CLI + TUI: install packs, launch OpenCode in a **new terminal**, persist sessions in `.orkestrate/pack-homes/<packId>/` |
+
+v0 is **OpenCode only**. Orkestrate does not replace OpenCode.
+
+## Install
+
+```bash
+npm install -g orkestrate
+# Bun 1.3+ — or: bun install -g orkestrate
+
+orkestrate doctor
+orkestrate registry install coding
+orkestrate run launch coding
+```
+
+## Commands (trust only these)
+
+```text
+orkestrate                          # TUI workbench
+orkestrate doctor
+orkestrate pack list|install|create|validate
+orkestrate run launch|list|status|stop <pack-id>
+orkestrate registry list|search|install
+orkestrate extension validate
+```
+
+## Paths
+
+```text
+<workspace>/.orkestrate/packs/<id>/
+<workspace>/.orkestrate/pack-homes/<id>/home/
+```
+
+Bundled packs: `coding`, `extension-builder`. Registry: `https://orkestrate.space/api/registry`.
+
+## Rules
+
+1. Say **pack**, not legacy **profile**.
+2. Launch = **new terminal**; sessions live in the pack home.
+3. Do not promise Pi/Claude adapters, CLI registry submit, or agent-generated slices (roadmap).
+4. Windows launch needs **Windows Terminal** (`wt` on PATH).
+
+## More context
+
+- Index: https://orkestrate.space/llms.txt
+- Docs: https://orkestrate.space/docs

package/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+Orkestrate is early. Keep contributions small and aligned with the OpenCode-first
+profile workbench.
+
+Roadmap: [../plan.md](../plan.md) (work phase-by-phase with maintainers).
+
+## Setup
+
+From this directory (`orkestrate/`):
+
+```sh
+bun install
+bun run check
+```
+
+Use Bun only unless a maintainer explicitly approves another package manager.
+
+## Product boundary
+
+```text
+specialized agent = profile + harness adapter + extensions
+```
+
+- OpenCode is the only supported harness today.
+- Profiles are the main user-facing primitive.
+- Extensions can register adapters; marketplace flows are partial.
+- Do not add fake harness support or undocumented CLI commands.
+
+## Pull requests
+
+- Keep changes focused.
+- Update docs when behavior changes.
+- Run `bun run typecheck`.
+- Do not commit `.orkestrate/`, `node_modules/`, `.env*`, or local session artifacts.

package/README.md

@@ -1,79 +1,59 @@
-# orkestrate
+# Orkestrate
 
-**The CLI for [Orkestrate](https://orkestrate.space) — the coordination layer for autonomous AI coding agents.**
+Browse, use, and share **specialized harnesses** for **agent packs**. Install packs from the registry, launch OpenCode in a new terminal with an isolated pack home — your personal OpenCode config stays untouched.
 
-Connect your AI coding tools (Claude Code, OpenCode, Cursor, Windsurf, Codex) to Orkestrate in seconds.
-
----
-
-## Install
-
-```bash
-# Global install
-bun install -g orkestrate
-
-# Or run without installing
-bunx orkestrate login
+```text
+pack = pack.yaml + harnesses/opencode/
+launch = new terminal + .orkestrate/pack-homes/<packId>/
 ```
 
-## Quick Start
+## Install
 
-```bash
-# 1. Authenticate
-orkestrate login
+Requires [Bun](https://bun.sh) 1.3+.
 
-# 2. Connect your AI tool
-orkestrate connect claude
+```sh
+npm install -g orkestrate
+# or: bun install -g orkestrate
 
-# 3. Done. Start coding.
+orkestrate doctor
+orkestrate registry install coding
+orkestrate
 ```
 
 ## Commands
 
-| Command | Description |
-|---|---|
-| `orkestrate login` | Authenticate via browser OAuth |
-| `orkestrate logout` | Clear stored credentials |
-| `orkestrate connect <tool>` | Configure MCP for an AI tool |
-| `orkestrate status` | Show team coordination state |
-| `orkestrate workspace list` | List all workspaces |
-| `orkestrate workspace switch <name>` | Switch active workspace |
-| `orkestrate workspace create <name> <repo-url>` | Create new workspace |
-| `orkestrate init` | Initialize Orkestrate in current project |
-| `orkestrate whoami` | Show current auth & config |
+| Command | Purpose |
+|---------|---------|
+| `orkestrate` | OpenTUI workbench |
+| `orkestrate pack list\|install\|create\|validate` | Packs |
+| `orkestrate run launch <id>` | New terminal → OpenCode |
+| `orkestrate registry list\|search\|install` | Catalog |
+| `orkestrate doctor` | Harness health |
 
-### Supported Tools
+## For coding agents
 
-- **Claude Code** — `orkestrate connect claude`
-- **OpenCode** — `orkestrate connect opencode`
-- **Cursor** — `orkestrate connect cursor`
-- **Windsurf** — `orkestrate connect windsurf`
-- **Codex** — `orkestrate connect codex`
+- Machine index: [llms.txt](https://orkestrate.space/llms.txt)
+- Instructions: [AGENTS.md](./AGENTS.md) (also at https://orkestrate.space/agents.md)
 
-## How It Works
+## Publish to npm
 
-1. **`orkestrate login`** opens your browser for OAuth authentication, then stores credentials locally in `~/.config/orkestrate/`.
+From this directory, with `NPM_TOKEN` or `npm login`:
 
-2. **`orkestrate connect <tool>`** auto-detects your AI coding tool and writes the MCP server configuration pointing to `https://orkestrate.space/api/mcp`.
-
-3. Your AI tools can now coordinate — sharing state, claiming file scopes, and avoiding collisions — all through the Orkestrate MCP protocol.
-
-## What This CLI Does NOT Do
-
-- ❌ Not an AI agent — doesn't write or edit code
-- ❌ Not a task runner — doesn't execute prompts
-- ❌ Not a git wrapper — doesn't commit or push
-- ❌ Not a proxy — MCP traffic goes directly from your tool to Orkestrate
-
-The CLI is purely **setup, wiring, and observability**. The coordination magic happens through MCP.
+```sh
+bun run check
+npm publish --access public
+```
 
----
+CI: tag `orkestrate-v*` or run the **Publish npm** workflow (set repo secret `NPM_TOKEN`).
 
-## Links
+## Development
 
-- **Website**: [orkestrate.space](https://orkestrate.space)
-- **GitHub**: [github.com/system1970/Orkestrate](https://github.com/system1970/Orkestrate)
+```sh
+bun install
+bun run dev
+bun run check
+```
 
----
+Docs: [pack-authoring](docs/pack-authoring.md), [getting-started](docs/getting-started.md).
 
-© 2026 Orkestrate. Built for the autonomous age.
+MIT — see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,24 @@
+# Security
+
+Orkestrate launches local agent harnesses and may pass prompts, skills, MCP
+definitions, paths, and extension code into those harnesses.
+
+## Trust model (v0)
+
+- Intended for **local, trusted** use on your machine.
+- **OpenCode** is the executing harness for launch builds.
+- **Orkestrate extensions** load via dynamic `import()` in the same process as
+  the CLI — treat them as trusted code (no sandbox).
+- **OpenCode plugins** are separate; they run inside OpenCode per
+  [OpenCode plugin docs](https://opencode.ai/docs/plugins/).
+- Do not commit secrets. Keep `.env*` and `.orkestrate/` out of git.
+
+## Reporting
+
+Open a private security advisory or email maintainers with:
+
+- affected version or commit
+- reproduction steps
+- impact (data exposure, arbitrary execution, etc.)
+
+Do not post exploit details publicly before maintainers respond.

package/bin/orkestrate.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/cli/index.ts";

package/docs/concepts.md

@@ -0,0 +1,119 @@
+# Concepts
+
+Orkestrate is an open workbench for specialized AI agent profiles.
+
+The core loop is simple:
+
+```text
+browse profile -> install profile -> inspect requirements -> launch harness
+```
+
+## Profile
+
+A profile is a packaged agent identity.
+
+It defines:
+
+- what the agent does;
+- which harness it runs on;
+- model defaults;
+- prompt and operating workflow;
+- tools and permissions;
+- skills or other context resources;
+- harness-specific launch configuration.
+
+Profiles are the user-facing primitive. A user should be able to choose
+`math-researcher`, `proof-referee`, `coding`, or `frontend-polisher` without
+understanding every config file behind it.
+
+Current profiles are JSON files stored in:
+
+```text
+orkestrate/profiles/               bundled seed + catalog templates
+~/.orkestrate/profiles/            global installed profiles
+<workspace>/.orkestrate/profiles/  workspace installed profiles
+```
+
+## Harness
+
+A harness is the runtime that actually runs the agent.
+
+Examples:
+
+- OpenCode
+- Claude Code
+- Codex
+- future domain-specific harnesses
+
+The harness owns the agent loop, terminal UI, tool execution, model calls, and
+session behavior. Orkestrate does not replace the harness. It prepares a profile
+for the harness and launches it.
+
+## Adapter
+
+An adapter teaches Orkestrate how to launch profiles for one harness.
+
+An adapter can:
+
+- detect whether a harness is installed;
+- report version/status;
+- translate a profile into harness config;
+- prepare environment variables and launch args;
+- avoid mutating global harness configuration.
+
+Adapters are not a separate ecosystem category. An adapter is one contribution
+type inside an extension.
+
+For the launch build, the OpenCode adapter is built into the package. The
+future extension system should let harness makers ship adapter extensions.
+
+## Extension
+
+An extension is an installable package of contributions.
+
+It may contribute:
+
+- profiles;
+- harness adapters;
+- skills;
+- MCP server templates;
+- commands;
+- permission policies;
+- docs and examples.
+
+This is the ecosystem primitive. A profile pack, a Lean skill pack, a Supabase
+MCP pack, and an OpenCode adapter are all extensions with different
+contributions.
+
+## Skill
+
+A skill is reusable domain or workflow knowledge for an agent.
+
+In the current OpenCode adapter, profile skills are prototype local references:
+Orkestrate looks for matching `SKILL.md` files and injects their text into the
+profile prompt. Native OpenCode skills are disabled for the generated profile.
+
+That is enough for the launch demo, but not the final portability model. The
+future model should let extension packs contribute pinned or bundled skills.
+
+## Catalog
+
+The catalog merges:
+
+- bundled JSON under `orkestrate/profiles/`
+- approved items from `orkestrate.space/api/registry` when online
+
+Install copies a template into `~/.orkestrate/profiles/` or the workspace store.
+
+## Session And Config
+
+Orkestrate currently uses `.orkestrate/` for workspace-local profile installs
+and generated harness launch artifacts.
+
+For OpenCode launches, Orkestrate creates a temporary per-launch home/config
+inside `.orkestrate/sessions/...`, writes generated OpenCode config, launches
+OpenCode in the real current directory, and cleans the generated launch folder
+when the harness exits.
+
+This should be treated as isolated harness launch config, not long-lived
+Orkestrate-owned session management.

package/docs/demo-extension-builder.md

@@ -0,0 +1,82 @@
+# Demo: extension-builder → new pack → launch
+
+This is the v0 “agents build agents” path using only the CLI (no registry).
+
+## Prerequisites
+
+- Bun 1.3+
+- [OpenCode](https://opencode.ai) on `PATH` (`opencode --version`)
+- Windows Terminal recommended on Windows
+
+## Steps
+
+From the `orkestrate/` package:
+
+```sh
+bun install
+bun run src/cli/index.ts doctor
+```
+
+### 1. Install builder pack (if needed)
+
+```sh
+bun run src/cli/index.ts pack install extension-builder
+# or: bun run src/cli/index.ts pack install coding
+```
+
+### 2. Scaffold a new pack from template
+
+```sh
+bun run src/cli/index.ts pack create demo-agent \
+  --from coding \
+  --description "Demo pack created by the extension-builder flow"
+bun run src/cli/index.ts pack validate demo-agent
+```
+
+This writes `.orkestrate/packs/demo-agent/` in your current working directory.
+
+### 3. Launch from CLI
+
+```sh
+bun run src/cli/index.ts run launch demo-agent
+```
+
+A new terminal tab opens OpenCode. Create a session, then exit OpenCode.
+
+### 4. Prove session persistence
+
+```sh
+bun run src/cli/index.ts run launch demo-agent
+```
+
+The second window should list the session from step 3 (same pack home under
+`.orkestrate/pack-homes/demo-agent/`).
+
+### 5. Launch via TUI
+
+```sh
+bun run dev
+```
+
+Select `demo-agent` → **Enter**. Status should show **running**, then **idle**
+after you close the OpenCode window.
+
+## Optional: run the scripted check
+
+```sh
+bun run scripts/demo-pack-builder.ts
+```
+
+This runs steps 2–3 non-interactively (does not open OpenCode UI for you).
+
+## Using extension-builder in OpenCode
+
+For the full meta flow, launch the builder pack and ask it to author a pack:
+
+```sh
+bun run src/cli/index.ts run launch extension-builder
+```
+
+In that OpenCode session, use the bundled `orkestrate-pack-author` skill and CLI
+commands (`pack create`, `pack validate`, `run launch`) from a shell in your
+real repo cwd.

package/docs/extensions/adapters.md

@@ -0,0 +1,57 @@
+# Harness Adapters
+
+Harness Adapters are the runtime bridges that translate high-level Orkestrate agent profiles into execution configurations for external CLI or TUI engines. By building a harness adapter, you enable Orkestrate to launch and control entirely new agent environments.
+
+## The Harness Adapter Interface
+
+To register a new runtime engine, your extension must provide an implementation of the `HarnessAdapter` interface.
+
+```typescript
+export interface HarnessAdapter {
+  id: string;
+  name: string;
+  
+  capabilities: {
+    mcp: boolean;
+    systemPrompt: boolean;
+    skills: boolean;
+    modelSelection: boolean;
+  };
+  
+  detect(): Promise<HarnessStatus>;
+  
+  prepareLaunch(
+    profile: Profile,
+    context: LaunchContext
+  ): Promise<{
+    config: HarnessLaunchConfig;
+    cleanup: () => Promise<void>;
+  }>;
+}
+```
+
+## Core Responsibilities
+
+An adapter must handle three primary phases of the agent lifecycle: **Detection**, **Environment Preparation**, and **Cleanup**.
+
+### 1. Detection
+
+Before a profile can be launched, Orkestrate asks the adapter if the target harness is available on the user's system. The `detect()` method typically spawns a synchronous subprocess (e.g., `opencode --version`) to verify installation and report the status.
+
+### 2. Environment Preparation
+
+The `prepareLaunch()` method is where the heavy lifting occurs. When a user requests to run a profile, the adapter must convert the profile's declarative manifest into something the target harness understands.
+
+Common tasks in this phase include:
+- **Session Isolation**: Spawning unique session root folders (e.g., `.orkestrate/sessions/<uuid>`).
+- **Home Hijacking**: Redirecting environment variables like `USERPROFILE`, `HOME`, and `XDG_CONFIG_HOME` to prevent the agent from modifying the user's global settings.
+- **Dynamic Configuration**: Converting Orkestrate tool policies and MCP server definitions into the native configuration format of the harness (e.g., generating an `opencode.json` file).
+- **Prompt Construction**: Merging profile-scoped `SKILL.md` files into a unified system instruction set.
+
+### 3. Cleanup
+
+To prevent stale environments and dangling files, `prepareLaunch` must return an asynchronous `cleanup()` callback. Orkestrate guarantees that this callback is invoked recursively upon process exit, ensuring temporary session folders are properly removed.
+
+## Example: The OpenCode Adapter
+
+The bundled `opencode-adapter` demonstrates the full capability of the adapter contract. It handles deep session isolation, dynamically parses tool constraints into OpenCode permissions (`read`, `edit`, `bash`, `skill`), and manages temporary execution environments.

package/docs/extensions/architecture.md

@@ -0,0 +1,49 @@
+# Architecture
+
+The Orkestrate extension system is designed to dynamically discover, load, and activate modules during the CLI bootstrapping phase. This approach ensures that extensions are isolated and can be injected without modifying the core codebase.
+
+## Discovery and Load Paths
+
+When Orkestrate starts, the `loadExtensions()` routine scans specific directories for executable extensions. The resolution order is strictly prioritized:
+
+1. **Bundled Extensions**: `<package-root>/extensions/`
+   First-party extensions that ship with Orkestrate (e.g., `opencode-adapter`).
+2. **Global Extensions**: `~/.orkestrate/extensions/`
+   User-level extensions installed globally across all projects.
+3. **Workspace Extensions**: `<project-cwd>/.orkestrate/extensions/`
+   Repository-specific extensions designed for a particular workspace.
+
+If multiple extensions with the same ID are discovered, the loader currently prioritizes them based on the loading sequence, allowing workspace extensions to override global ones.
+
+## The Activation Hook
+
+During startup, Orkestrate filters the discovered directories for valid entry points (`index.ts`, `index.js`, or a valid `package.json` main entry). Once located, it dynamically imports the module and invokes its `activate` method.
+
+### The Extension Context
+
+The `activate` method receives an `ExtensionContext` object. This context acts as the bridge between your extension and the Orkestrate global registry. 
+
+```typescript
+export interface ExtensionContext {
+  registerAdapter(harness: string, adapter: HarnessAdapter): void;
+}
+```
+
+Through this context, your extension can safely register its capabilities into the runtime before any profiles are launched.
+
+### Registering an adapter
+
+The harness string in a profile JSON must match the key passed to
+`registerAdapter`:
+
+```typescript
+activate(ctx) {
+  ctx.registerAdapter("opencode", new OpenCodeAdapter());
+}
+```
+
+## Lifecycle Management & Security
+
+### Current Limitations
+- **Deactivation**: Currently, the system lacks a formal `deactivate()` hook. Extensions should avoid spawning orphaned background processes or leaving long-running listeners attached without explicit cleanup mechanisms provided during launch execution.
+- **Sandboxing**: Extensions are executed via native dynamic imports (`import()`) within the same V8 isolate as the Orkestrate CLI. As such, they inherit the exact same filesystem and network permissions as the host process. Always verify third-party extension code before installation.

package/docs/extensions/introduction.md

@@ -0,0 +1,26 @@
+# Extensions
+
+Extensions register runtime capabilities when the CLI starts. Today the main
+contribution type is a **harness adapter**.
+
+## OrkExtension
+
+```typescript
+export interface OrkExtension {
+  id: string;
+  name: string;
+  version: string;
+  activate(ctx: ExtensionContext): void | Promise<void>;
+}
+```
+
+## Discovery paths
+
+1. `<package>/extensions/` — bundled (e.g. `opencode-adapter`)
+2. `~/.orkestrate/extensions/`
+3. `<workspace>/.orkestrate/extensions/`
+
+## Docs
+
+- [Architecture & lifecycle](./architecture.md) — load order, `ExtensionContext`, security
+- [Harness adapters](./adapters.md) — `HarnessAdapter` contract and OpenCode example

package/docs/getting-started.md

@@ -0,0 +1,85 @@
+# Getting Started
+
+Orkestrate is a Bun CLI and OpenTUI workbench for **packs** (OpenCode-first).
+
+## Install
+
+```sh
+cd orkestrate
+bun install
+```
+
+## Run the workbench
+
+```sh
+bun run dev
+```
+
+On first launch with no packs installed, the welcome wizard installs `coding`.
+
+## Check harness status
+
+```sh
+bun run src/cli/index.ts doctor
+```
+
+## Create a pack
+
+```sh
+bun run src/cli/index.ts pack create my-agent --from coding
+bun run src/cli/index.ts pack validate my-agent
+```
+
+Templates: `coding`, `extension-builder` (use `--from <name>`).
+
+## Install packs
+
+Bundled:
+
+```sh
+bun run src/cli/index.ts pack install coding
+bun run src/cli/index.ts pack install extension-builder --global
+```
+
+Registry (GitHub-backed, requires network):
+
+```sh
+bun run src/cli/index.ts registry list
+bun run src/cli/index.ts registry search <query>
+bun run src/cli/index.ts registry install <slug>
+```
+
+In the TUI: `b` to browse bundled + registry, `Enter` to install.
+
+## Launch a pack
+
+CLI:
+
+```sh
+bun run src/cli/index.ts run launch coding
+```
+
+TUI: select a pack → `Enter` or `l`.
+
+Orkestrate opens a **new terminal** running OpenCode with:
+
+- Your real repo as `cwd`
+- Config from the pack harness slice
+- Session data under `.orkestrate/pack-homes/<pack-id>/home/`
+
+Your normal OpenCode config is not modified.
+
+## Where files live
+
+```text
+<workspace>/.orkestrate/packs/<id>/       # pack source
+<workspace>/.orkestrate/pack-homes/<id>/  # persistent OpenCode home
+~/.orkestrate/packs/<id>/                 # global install (optional)
+```
+
+Bundled catalog: `orkestrate/packs/`.
+
+## Next
+
+- [Pack authoring](pack-authoring.md)
+- [Extension-builder demo](demo-extension-builder.md)