orkestrate 0.1.15 → 0.2.0

package/docs/hosted-registry.md

@@ -0,0 +1,90 @@
+# Hosted Registry
+
+`orkestrate.space` is the hosted discovery and publishing surface for the
+Orkestrate ecosystem.
+
+The CLI should stay useful without the website. The website adds publisher
+identity, public discovery, submissions, and review.
+
+## Public User Flow
+
+Anyone can:
+
+- browse approved profiles and extensions;
+- read developer docs;
+- copy install/validation commands;
+- inspect manifest metadata and source URLs.
+
+No auth is required for browsing.
+
+## Publisher Flow
+
+Publishing requires auth.
+
+Day 0 auth should be GitHub through Supabase Auth. GitHub is the right default
+because extension/profile authors are likely publishing from repositories.
+
+Flow:
+
+1. Publisher signs in with GitHub.
+2. Publisher creates a publisher profile.
+3. Publisher submits a repo URL plus manifest URL or pasted manifest JSON.
+4. Submission is stored as `pending`.
+5. Orkestrate team reviews manually.
+6. Approved submissions become public registry items and versions.
+
+## Database Shape
+
+The website migration creates:
+
+- `publisher_profiles` - public publisher identity tied to `auth.users`.
+- `registry_items` - public approved profile packs, adapters, skill packs, MCP
+  packs, and command packs.
+- `registry_versions` - versioned manifests for approved registry items.
+- `registry_submissions` - authenticated pending publisher submissions.
+
+Browsing reads only approved registry rows.
+
+Submissions are private to the submitting authenticated user until reviewed.
+
+## RLS Model
+
+Public:
+
+- `publisher_profiles`: selectable by everyone.
+- `registry_items`: selectable by everyone only when `status = 'approved'`.
+- `registry_versions`: selectable by everyone only when the version and item are
+  approved.
+
+Authenticated:
+
+- users can create and update their own publisher profile;
+- users can create submissions;
+- users can view and edit their own pending submissions.
+
+Admin/review actions should use server-side service role code only. Never expose
+the service role key to browser code.
+
+## Website Pages To Build
+
+Minimum:
+
+- `/registry` - approved public profiles/extensions.
+- `/registry/[slug]` - detail page with manifest, source URL, versions, and
+  install/validate commands.
+- `/submit` - GitHub-authenticated submission form.
+- `/docs/profiles` - profile authoring.
+- `/docs/extensions` - extension manifest authoring.
+- `/docs/adapters` - harness adapter authoring.
+
+## CLI Integration Later
+
+The CLI can later add:
+
+```sh
+orkestrate registry search math
+orkestrate extension install orkestrate.profile-pack.math-research
+orkestrate profile install math-researcher
+```
+
+For launch, local catalog plus hosted docs/submission path is enough.

package/docs/pack-authoring.md

@@ -0,0 +1,75 @@
+# Pack authoring
+
+A **pack** is a reusable agent product: manifest + native OpenCode harness files.
+Orkestrate launches it in a **new terminal** with an isolated home that does not
+touch your normal OpenCode install.
+
+## Layout
+
+```text
+my-pack/
+  pack.yaml              # id, description, harness
+  info.md                # optional readme for humans/agents
+  harnesses/opencode/
+    opencode.json        # native OpenCode config
+    agents/<name>.md     # primary agent prompt
+    skills/              # optional OpenCode skills
+```
+
+## Scaffold a pack
+
+```sh
+cd orkestrate
+bun run src/cli/index.ts pack create my-pack --from coding
+bun run src/cli/index.ts pack validate my-pack
+bun run src/cli/index.ts run launch my-pack
+```
+
+Workspace copies live at `<repo>/.orkestrate/packs/<id>/`.
+Global copies live at `~/.orkestrate/packs/<id>/` (use `--global`).
+
+## Sessions
+
+OpenCode session data for a pack is stored under:
+
+```text
+<workspace>/.orkestrate/pack-homes/<pack-id>/home/
+```
+
+Every launch of the same pack in the same repo shares that home, so session
+history persists. Your personal OpenCode outside Orkestrate is unchanged.
+
+## Runs
+
+Each launch also creates a small run record under `.orkestrate/runs/<run-id>/`
+(launch metadata only). The TUI shows **idle** / **running** on each pack row.
+
+## Harness sync on launch
+
+The OpenCode driver copies `harnesses/opencode/` into the pack home on launch:
+
+- **First launch:** full slice is copied.
+- **Later launches:** only missing `agents/`, `skills/`, and `plugins/` files are
+  added. Your `opencode.json` in the pack home is never overwritten.
+
+Edit agents/skills in `.orkestrate/pack-homes/<pack-id>/home/.config/opencode/` to
+customize a pack for this workspace without changing the installed pack source.
+
+## Registry install
+
+```sh
+bun run src/cli/index.ts registry list
+bun run src/cli/index.ts registry search coding
+bun run src/cli/index.ts registry install <slug>
+```
+
+Remote packs are cloned from GitHub (`source_url` + `orkestrate.ref` / `orkestrate.packPath`
+in the registry manifest). The repo must contain `pack.yaml` at the pack path.
+
+## Bundled templates
+
+- `coding` — day-to-day software work
+- `extension-builder` — includes `orkestrate` and `orkestrate-pack-author` skills
+
+See [demo-extension-builder.md](./demo-extension-builder.md) for the full
+builder → new pack → launch walkthrough.

package/docs/roadmap.md

@@ -0,0 +1,59 @@
+# Roadmap
+
+## Layer 1: Skeleton
+
+- Bun TypeScript package
+- `orkestrate` command
+- MIT license
+- README
+
+Status: done.
+
+## Layer 2: Harness Detection
+
+- OpenCode adapter
+- `orkestrate doctor`
+
+Status: done.
+
+## Layer 3: Packs (replaces profiles in v0.2)
+
+- `pack.yaml` + `harnesses/opencode/` layout
+- workspace + global pack stores
+- `pack create|install|validate`
+- bundled `coding`, `extension-builder`
+
+Status: done.
+
+## Layer 4: Minimal TUI
+
+- OpenTUI pack list + browse
+- per-pack idle/running status
+- detached terminal launch (TUI stays open)
+
+Status: done for v0.2.
+
+## Layer 5: OpenCode Launch
+
+- driver compiles pack → launch plan
+- new terminal per launch
+- per-pack persistent home (shared sessions)
+
+Status: done for v0.2.
+
+## Layer 6: Extensions
+
+- extension loader + OpenCode adapter
+- manifest validate/submit
+- extension authoring docs
+
+Status: partial. Marketplace install UX, permission sandbox, and setup/apply
+workflows are deferred.
+
+## Layer 7: Profile orchestration (target demo)
+
+- meta profile that authors child profiles
+- spawn multiple profile instances
+- track run completion without manual handoff per instance
+
+Status: not started. Requires execution model beyond single launch handoff.

package/docs/troubleshooting.md

@@ -0,0 +1,28 @@
+# Troubleshooting
+
+## Bun EPERM Noise On Windows/OneDrive
+
+In this workspace, Bun sometimes prints messages like:
+
+```text
+error: Cannot read file "C:\Users\..."
+```
+
+after an otherwise successful command.
+
+This has been observed even with a minimal command such as:
+
+```sh
+bun -e "console.log('hi')"
+```
+
+So far it appears to be Bun or shell/path probing noise related to the Windows
+OneDrive path, not Orkestrate command failure. Treat the command exit code and
+the Orkestrate output as the source of truth.
+
+If this appears outside OneDrive or with a non-zero exit code, capture:
+
+- the command
+- the full output
+- `bun --version`
+- the working directory path

package/extensions/opencode-adapter/index.ts

@@ -0,0 +1,106 @@
+import type { HarnessDriver, HarnessStatus, CompileContext } from "../../src/sdk/types";
+import type { Pack } from "../../src/sdk/packs/schema";
+import type { LaunchPlan } from "../../src/sdk/launch/types";
+import type { OrkExtension } from "../../src/sdk/extensions/types";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { spawnSync } from "bun";
+import { harnessSliceDir } from "../../src/sdk/packs/paths";
+import { seedHarnessSlice } from "../../src/sdk/harness/sync-slice";
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await Bun.file(path).exists();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function applyHarnessSlice(pack: Pack, opencodeConfigDir: string): Promise<string> {
+  const slice = harnessSliceDir(pack.packRoot, "opencode");
+  if (!(await pathExists(slice))) {
+    throw new Error(`Pack is missing harnesses/opencode/ slice`);
+  }
+  await mkdir(opencodeConfigDir, { recursive: true });
+  await seedHarnessSlice(slice, opencodeConfigDir);
+  return opencodeConfigDir;
+}
+
+export const opencodeDriver: HarnessDriver = {
+  id: "opencode",
+  name: "OpenCode",
+
+  async detect(): Promise<HarnessStatus> {
+    try {
+      const proc = spawnSync(["opencode", "--version"], { stdout: "pipe", stderr: "pipe" });
+      if (!proc.success) {
+        return { installed: false, error: proc.stderr.toString().trim() || "opencode --version failed" };
+      }
+      return { installed: true, version: proc.stdout.toString().trim() || undefined };
+    } catch (error) {
+      return { installed: false, error: error instanceof Error ? error.message : String(error) };
+    }
+  },
+
+  async compile(pack: Pack, context: CompileContext): Promise<LaunchPlan> {
+    if (pack.harness !== "opencode") {
+      throw new Error(`Pack "${pack.id}" is not an OpenCode pack`);
+    }
+
+    // One home per pack in this workspace — OpenCode sessions persist across launches.
+    // Env is only set on the Orkestrate-spawned process; the user's normal OpenCode is untouched.
+    const profileHome = context.packHome;
+    const profileConfigHome = join(profileHome, ".config");
+    const profileDataHome = join(profileHome, ".local", "share");
+    const profileStateHome = join(profileHome, ".local", "state");
+    const profileCacheHome = join(profileHome, ".cache");
+    const opencodeConfigDir = join(profileConfigHome, "opencode");
+
+    await applyHarnessSlice(pack, opencodeConfigDir);
+
+    let defaultAgent = pack.id;
+    const configPath = join(opencodeConfigDir, "opencode.json");
+    if (await pathExists(configPath)) {
+      try {
+        const config = await Bun.file(configPath).json();
+        if (typeof config.default_agent === "string") {
+          defaultAgent = config.default_agent;
+        }
+      } catch {
+        // use pack id
+      }
+    }
+
+    const env: Record<string, string> = {
+      ...Object.fromEntries(
+        Object.entries(process.env).filter(([, v]) => v !== undefined) as [string, string][]
+      ),
+      ...context.crossPlatform.hijackHome(profileHome),
+      XDG_CONFIG_HOME: profileConfigHome,
+      XDG_DATA_HOME: profileDataHome,
+      XDG_STATE_HOME: profileStateHome,
+      XDG_CACHE_HOME: profileCacheHome,
+      OPENCODE_CONFIG_DIR: opencodeConfigDir,
+    };
+
+    return {
+      command: "opencode",
+      args: ["--agent", defaultAgent],
+      cwd: context.cwd,
+      env,
+      title: `orkestrate: ${pack.id}`,
+    };
+  },
+};
+
+export const extension: OrkExtension = {
+  id: "orkestrate.driver.opencode",
+  name: "OpenCode Driver",
+  version: "0.2.0",
+  activate(ctx) {
+    ctx.registerAdapter("opencode", opencodeDriver);
+  },
+};
+
+export default extension;

package/extensions/opencode-adapter/orkestrate.extension.json

@@ -0,0 +1,17 @@
+{
+  "id": "orkestrate.adapter.opencode",
+  "name": "OpenCode Adapter",
+  "version": "0.1.0",
+  "description": "Built-in adapter contribution that launches Orkestrate profiles through OpenCode.",
+  "contributes": {
+    "adapters": [
+      {
+        "id": "opencode",
+        "entry": "index.ts"
+      }
+    ],
+    "profiles": [],
+    "skills": [],
+    "mcpServers": []
+  }
+}

package/package.json

@@ -1,50 +1,57 @@
-{
-  "name": "orkestrate",
-  "version": "0.1.15",
-  "description": "CLI for Orkestrate — the coordination layer for autonomous AI coding agents",
-  "type": "module",
-  "bin": {
-    "orkestrate": "./dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "prepublishOnly": "tsup"
-  },
-  "keywords": [
-    "orkestrate",
-    "mcp",
-    "ai-agents",
-    "multi-agent",
-    "coordination",
-    "claude",
-    "opencode",
-    "cursor",
-    "codex",
-    "cli"
-  ],
-  "author": "system1970",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/system1970/Orkestrate.git",
-    "directory": "packages/cli"
-  },
-  "homepage": "https://orkestrate.space",
-  "dependencies": {
-    "commander": "^13.1.0",
-    "conf": "^13.1.0",
-    "open": "^10.1.2",
-    "picocolors": "^1.1.1"
-  },
-  "devDependencies": {
-    "@types/node": "^22.15.0",
-    "tsup": "^8.4.0",
-    "typescript": "^5.8.0"
-  }
-}
+{
+  "name": "orkestrate",
+  "version": "0.2.0",
+  "description": "Browse, use, and share specialized harnesses for agent packs.",
+  "homepage": "https://orkestrate.space",
+  "bugs": {
+    "url": "https://github.com/anomalyco/orkestrate/issues"
+  },
+  "license": "MIT",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anomalyco/orkestrate.git"
+  },
+  "type": "module",
+  "bin": {
+    "orkestrate": "./bin/orkestrate.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "packs",
+    "extensions",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "AGENTS.md"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "keywords": [
+    "agents",
+    "ai-agents",
+    "agent-packs",
+    "harness",
+    "opencode",
+    "tui",
+    "registry"
+  ],
+  "scripts": {
+    "dev": "bun run src/cli/index.ts",
+    "prepublishOnly": "bun run check",
+    "typecheck": "tsc --noEmit",
+    "check": "bun run typecheck",
+    "demo:pack-builder": "bun run scripts/demo-pack-builder.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@opentui/core": "^0.3.0"
+  }
+}

package/packs/coding/harnesses/opencode/agents/coding.md

@@ -0,0 +1,8 @@
+---
+description: General-purpose coding agent for day-to-day software work.
+mode: primary
+---
+
+Use the Orkestrate coding pack. Prioritize small, reviewable changes, clear verification, and repository instructions.
+
+Follow AGENTS.md and project conventions when present.

package/packs/coding/harnesses/opencode/opencode.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "default_agent": "coding",
+  "share": "manual",
+  "autoupdate": false,
+  "instructions": ["AGENTS.md", "README.md"],
+  "agent": {
+    "coding": {
+      "description": "General-purpose coding agent for day-to-day software work.",
+      "mode": "primary",
+      "permission": {
+        "read": "allow",
+        "grep": "allow",
+        "glob": "allow",
+        "bash": "allow",
+        "edit": "allow",
+        "write": "allow",
+        "skill": {
+          "orkestrate": "allow"
+        }
+      }
+    }
+  }
+}

package/packs/coding/harnesses/opencode/skills/orkestrate/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: orkestrate
+description: >
+  Orkestrate control room — list/install packs, launch runs in new terminals,
+  check and stop runs. Use when orchestrating multiple packs, spawning another
+  agent in a separate terminal, or managing concurrent harness runs. Do not use
+  for in-session subtasks (use OpenCode task). For authoring packs load
+  orkestrate-pack-author.
+compatibility: opencode
+metadata:
+  platform: orkestrate
+---
+
+# Orkestrate (runtime)
+
+## When to use
+
+- Launch another installed pack in a **new terminal**
+- Run multiple packs or multiple instances of the same pack
+- List or stop Orkestrate runs
+
+## When not to use
+
+- Same-session subtasks → OpenCode **`task`** tool
+- Authoring pack files → load skill **`orkestrate-pack-author`**
+
+## Commands (run via bash in workspace cwd)
+
+```bash
+orkestrate pack list
+orkestrate pack create <id> --from coding
+orkestrate pack install <slug>
+orkestrate pack validate <pack-id>
+orkestrate registry list
+orkestrate registry install <slug>
+
+orkestrate run launch <pack-id>
+orkestrate run list
+orkestrate run status <run-id>
+orkestrate run stop <run-id>
+```
+
+`run launch` and `run spawn` are the same: **new visible terminal**, prints `runId`.
+
+## Spawn workflow
+
+1. Ensure pack is installed: `orkestrate pack list`
+2. `orkestrate run launch <pack-id>`
+3. Note the `runId` from output
+4. `orkestrate run status <run-id>` to check state
+5. `orkestrate run stop <run-id>` if needed
+
+Each launch creates a new run with isolated config under `.orkestrate/runs/<runId>/`.
+
+## Multi-instance
+
+You may launch the same `pack-id` multiple times; each gets a unique `runId`.

package/packs/coding/pack.yaml

@@ -0,0 +1,5 @@
+id: coding
+name: coding
+description: General-purpose coding agent for day-to-day software work.
+version: "0.1.0"
+harness: opencode

package/packs/extension-builder/harnesses/opencode/agents/extension-builder.md

@@ -0,0 +1,8 @@
+---
+description: Build Orkestrate packs, drivers, and platform extensions.
+mode: primary
+---
+
+You are the Orkestrate extension builder. Help design, write, test, and package packs, harness drivers, and Orkestrate extensions. Keep changes scoped to the orkestrate CLI unless asked otherwise.
+
+Load `orkestrate-pack-author` for pack layout and `orkestrate` to launch other packs in new terminals.

package/packs/extension-builder/harnesses/opencode/opencode.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "default_agent": "extension-builder",
+  "share": "manual",
+  "autoupdate": false,
+  "instructions": [
+    "AGENTS.md",
+    "README.md",
+    "src/sdk/extensions/types.ts",
+    "src/sdk/types.ts",
+    "src/sdk/packs/schema.ts"
+  ],
+  "agent": {
+    "extension-builder": {
+      "description": "Build Orkestrate packs, drivers, and extensions.",
+      "mode": "primary",
+      "permission": {
+        "read": "allow",
+        "grep": "allow",
+        "glob": "allow",
+        "bash": "allow",
+        "edit": "ask",
+        "write": "ask",
+        "skill": {
+          "orkestrate": "allow",
+          "orkestrate-pack-author": "allow"
+        }
+      }
+    }
+  }
+}

package/packs/extension-builder/harnesses/opencode/skills/orkestrate/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: orkestrate
+description: >
+  Orkestrate control room — list/install packs, launch runs in new terminals,
+  check and stop runs. Use when orchestrating multiple packs, spawning another
+  agent in a separate terminal, or managing concurrent harness runs. Do not use
+  for in-session subtasks (use OpenCode task). For authoring packs load
+  orkestrate-pack-author.
+compatibility: opencode
+metadata:
+  platform: orkestrate
+---
+
+# Orkestrate (runtime)
+
+## When to use
+
+- Launch another installed pack in a **new terminal**
+- Run multiple packs or multiple instances of the same pack
+- List or stop Orkestrate runs
+
+## When not to use
+
+- Same-session subtasks → OpenCode **`task`** tool
+- Authoring pack files → load skill **`orkestrate-pack-author`**
+
+## Commands (run via bash in workspace cwd)
+
+```bash
+orkestrate pack list
+orkestrate pack install <slug>
+orkestrate pack validate <pack-id>
+
+orkestrate run launch <pack-id>
+orkestrate run list
+orkestrate run status <run-id>
+orkestrate run stop <run-id>
+```
+
+`run launch` and `run spawn` are the same: **new visible terminal**, prints `runId`.
+
+## Spawn workflow
+
+1. Ensure pack is installed: `orkestrate pack list`
+2. `orkestrate run launch <pack-id>`
+3. Note the `runId` from output
+4. `orkestrate run status <run-id>` to check state
+5. `orkestrate run stop <run-id>` if needed
+
+Each launch creates a new run with isolated config under `.orkestrate/runs/<runId>/`.
+
+## Multi-instance
+
+You may launch the same `pack-id` multiple times; each gets a unique `runId`.