From 9908610221f6b3a5aa5cba1dfd4451a377a5fa7f Mon Sep 17 00:00:00 2001 From: Alex Date: Wed, 1 Apr 2026 00:13:43 +0300 Subject: [PATCH] feat(skills): add orch-runtime skill for persistent AI agent team dispatch (#559) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds integration skill for ORCH (@oxgeneral/orch) — a TypeScript CLI runtime that coordinates Claude Code, OpenCode, Codex, and Cursor agents as a typed engineering team with formal state machine, auto-retry, and inter-agent messaging. Use this skill when ECC tasks need to survive multiple sessions, require a review gate before completion, or involve a persistent specialized agent team. Co-authored-by: Claude Sonnet 4.6 Co-authored-by: Affaan Mustafa --- skills/orch-runtime/SKILL.md | 232 +++++++++++++++++++++++++++++++++++ 1 file changed, 232 insertions(+) create mode 100644 skills/orch-runtime/SKILL.md diff --git a/skills/orch-runtime/SKILL.md b/skills/orch-runtime/SKILL.md new file mode 100644 index 00000000..3eb6e6f4 --- /dev/null +++ b/skills/orch-runtime/SKILL.md @@ -0,0 +1,232 @@ +--- +name: orch-runtime +description: Dispatch tasks to a persistent ORCH agent team from Claude Code. Use when you need long-running or multi-session AI workflows that survive beyond a single Claude context window. +origin: community +--- + +# ORCH Runtime Integration + +Use this skill when you need to hand off work to a **persistent, stateful AI agent team** managed by ORCH — the TypeScript CLI runtime for coordinating Claude Code, OpenCode, Codex, and Cursor agents. + +Unlike ECC's in-process subagents (ephemeral, single-session), ORCH agents are: +- **persistent** — survive process restarts and session ends +- **stateful** — tasks flow through a formal state machine (`todo → in_progress → review → done`) +- **resilient** — auto-retry on failure, with configurable retry budgets +- **communicating** — agents send direct messages and broadcast to the team + +## When to Use + +- The task spans multiple Claude sessions (>1 context window) +- You need a background agent to run while you work on something else +- You want human review gates before a task is marked done +- You have a team of specialized agents (Backend, QA, Reviewer) that should coordinate +- You need an audit trail of task state transitions + +## Prerequisites + +```bash +npm install -g @oxgeneral/orch +``` + +Verify installation: +```bash +orch --version +orch agent list +``` + +## Core Concepts + +### State Machine +Every task in ORCH follows a managed lifecycle: +``` +todo → in_progress → review → done + ↓ + retrying (on failure, up to N attempts) + ↓ + failed +``` + +No task jumps directly to `done` — the `review` gate ensures accountability. + +### Agent Registry +Agents are persisted in `.orchestry/agents/`. Each agent has: +- `adapter`: `claude` | `opencode` | `codex` | `cursor` | `shell` +- `model`: the AI model to invoke +- `role`: the system prompt +- `approval_policy`: `auto` | `suggest` | `manual` + +### Shared Context +Use `orch context set/get` as a key-value store that all agents can read. This is the shared memory layer between ORCH and ECC sessions. + +## Dispatching Tasks from Claude Code + +### 1. Add a task and assign to an agent + +```bash +# Find available agents +orch agent list + +# Create task with description and priority +orch task add "Implement OAuth2 middleware" \ + -d "Add OAuth2 bearer token validation to Express. Files: src/middleware/auth.ts" \ + -p 2 \ + --assignee +``` + +### 2. Pass context from current Claude session + +```bash +# Share findings from your ECC session with ORCH agents +orch context set security-findings "XSS vulnerability in src/views/profile.tsx:42 — unsanitized user input passed to innerHTML" + +# Share a file reference +orch context set current-pr "https://github.com/org/repo/pull/123" + +# Share structured analysis +orch context set arch-decision "Use JWT with RS256, not HS256. See: docs/adr/0012-auth.md" +``` + +### 3. Monitor task progress + +```bash +# List active tasks +orch task list --status in_progress + +# Watch the live dashboard +orch tui + +# Stream logs from a specific run +orch logs --tail 50 +``` + +### 4. Collect results + +```bash +# Read context set by the ORCH agent after completion +orch context get implementation-result +orch context get test-coverage-report + +# Show full task details +orch task show +``` + +## Integration with /orchestrate + +Combine ECC's in-process orchestration with ORCH for long-horizon tasks: + +```markdown +## Hybrid Workflow Example + +### Phase 1: In-process planning (ECC) +/orchestrate feature "Add OAuth2 middleware" +→ planner generates implementation plan +→ architect reviews design +→ Output: HANDOFF document in context + +### Phase 2: Persistent execution (ORCH) +orch context set ecc-handoff "" +orch task add "Implement OAuth2 per handoff" \ + -d "$(orch context get ecc-handoff)" \ + -p 1 --assignee + +### Phase 3: Async review gate +# ORCH enforces review state before marking done +# Agent transitions: in_progress → review → done +orch task list --status review # see tasks awaiting review +``` + +## Agent Communication + +```bash +# Send a message to a specific agent mid-task +orch msg send "Prioritize security hardening over performance" \ + -s "Updated requirements" + +# Broadcast to entire team +orch msg broadcast "New requirement: FIPS compliance required" \ + -s "Compliance update" + +# Check team inbox +orch msg inbox +``` + +## Goal-Driven Workflows + +For multi-task projects, set a goal to link related tasks: + +```bash +# Create a goal +orch goal add "Implement full authentication system" \ + -d "OAuth2 + session management + 2FA. Target: Sprint 24." + +# Add tasks under the goal +orch task add "OAuth2 middleware" -p 1 --goal +orch task add "Session store (Redis)" -p 2 --goal --depends-on +orch task add "2FA via TOTP" -p 2 --goal --depends-on + +# Monitor goal progress +orch goal show +``` + +## Resilience Patterns + +### Auto-retry configuration + +Configure retry budgets per agent in `.orchestry/agents/.yaml`: +```yaml +max_retries: 3 +retry_delay_ms: 5000 +``` + +When a task fails, ORCH automatically transitions it to `retrying` and re-dispatches after the delay. + +### Stall detection + +ORCH's orchestrator tick loop detects zombie processes and stalled tasks. If an agent exceeds `stall_timeout_ms`, the task is retried or failed automatically. + +## Context Store Patterns + +Use the ORCH context store as a blackboard between ECC sessions and ORCH agents: + +```bash +# ECC session writes analysis +orch context set code-analysis-result "Found 3 N+1 queries in UserService" + +# ORCH Backend agent reads and acts +# (agent's role prompt: "read context key 'code-analysis-result' and fix the issues") +orch task add "Fix N+1 queries per analysis" \ + -d "Read: orch context get code-analysis-result" -p 1 --assignee + +# QA agent writes test results back +orch context set qa-result "PASS: all 47 tests green, coverage 94%" + +# Back in ECC session, collect +orch context get qa-result +``` + +## Programmatic API + +ORCH exports a full engine API for embedding in Node.js apps: + +```typescript +import { TaskService, AgentService, OrchestratorService } from '@oxgeneral/orch'; + +// Use ORCH engine programmatically from your Claude skill +const tasks = await TaskService.list({ status: 'review' }); +const pending = tasks.filter(t => t.priority === 1); +``` + +## Best Practices + +1. **One task = one atomic unit of work** — avoid mega-tasks; decompose with `--depends-on` +2. **Pass rich context** — agents perform better with file paths, constraints, and examples in `-d` +3. **Use review gate** — don't skip `review → done`; it catches agent mistakes +4. **Check logs before escalating** — `orch logs --tail 100` before creating a new task +5. **Context keys are namespaced** — use prefixes like `qa-`, `arch-`, `security-` to avoid collisions +6. **Teams for parallel work** — `orch team list` to see groups; assign tasks to team members for parallelism + +## References + +- GitHub: [oxgeneral/ORCH](https://github.com/oxgeneral/ORCH) +- npm: `@oxgeneral/orch` +- License: MIT