feat(skills): add orch-runtime — persistent AI agent team dispatch from Claude Code#559
Conversation
…patch 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 <noreply@anthropic.com>
📝 WalkthroughWalkthroughA new documentation file for the ORCH Runtime Integration skill that describes a persistent, stateful agent-based workflow system. It defines task state management, agent registry, context store, communication primitives, and service APIs for orchestrating work across multiple Claude Code sessions. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment Tip CodeRabbit can use your project's `biome` configuration to improve the quality of JS/TS/CSS/JSON code reviews.Add a configuration file to your project to customize how CodeRabbit runs |
Greptile SummaryThis PR adds
Confidence Score: 5/5Safe to merge; all remaining findings are documentation quality/usability suggestions (P2) that do not block correctness. The only new finding introduced in this review round is a P2 usability note about multi-line shell quoting in the hybrid workflow example. All other items from prior rounds (state machine diagram, orch init, orch team list) are pre-existing open threads. P2-only findings do not reduce confidence below 5. skills/orch-runtime/SKILL.md — hybrid workflow shell-quoting example and the three open items from prior review threads should be addressed before or after merge. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[ECC Session\n/orchestrate] -->|generates HANDOFF doc| B[orch context set ecc-handoff]
B --> C[orch task add\nassignee: backend-agent]
C --> D{ORCH State Machine}
D --> E[todo]
E --> F[in_progress]
F -->|success| G[review]
F -->|failure| H[retrying]
H -->|retry budget exhausted| I[failed]
H -->|re-dispatch after retry_delay_ms| F
G -->|approved| J[done]
J --> K[orch context get result]
K --> L[Back in ECC Session\nCollect results]
Reviews (2): Last reviewed commit: "Merge branch 'main' into feat/skill-orch..." | Re-trigger Greptile |
![greptile-apps[bot]](https://cdn.github.com/in/867647?s=60&v=4){kind=small}
| ``` | ||
| todo → in_progress → review → done | ||
| ↓ | ||
| retrying (on failure, up to N attempts) | ||
| ↓ | ||
| failed | ||
| ``` |
There was a problem hiding this comment.
The ASCII diagram only shows a one-way path from retrying → failed, but the prose below it (and in the Resilience Patterns section on line 181) says the task is re-dispatched after the retry delay. The retry loop back to in_progress is missing, which makes the diagram misleading — it looks like every failure immediately terminates in failed with no recovery path.
| ``` | |
| todo → in_progress → review → done | |
| ↓ | |
| retrying (on failure, up to N attempts) | |
| ↓ | |
| failed | |
| ``` |
todo → in_progress → review → done
↓
retrying (on failure, up to N attempts)
↓↑ (re-dispatched after retry_delay_ms)
failed
| 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 |
There was a problem hiding this comment.
orch team list referenced but never introduced
The best practice mentions orch team list and the concept of agent teams/groups, but this concept is not introduced, explained, or referenced anywhere else in the skill. A reader encountering this command for the first time has no context for what "teams" are, how they differ from individual agents, or how to create them. Either add a brief ## Teams section covering orch team list, orch team add, etc., or remove this reference to avoid confusion.
| ## Prerequisites | ||
|
|
||
| ```bash | ||
| npm install -g @oxgeneral/orch | ||
| ``` | ||
|
|
||
| Verify installation: | ||
| ```bash | ||
| orch --version | ||
| orch agent list | ||
| ``` |
There was a problem hiding this comment.
The Prerequisites section goes straight from npm install -g @oxgeneral/orch to orch agent list, but there is no mention of how to initialize an ORCH project (creating the .orchestry/ directory and registering agents). Without an orch init command (or equivalent), running orch agent list on a fresh install will likely fail or return an empty result with no guidance on what to do next.
Consider adding an initialization step, e.g.:
npm install -g @oxgeneral/orch
# Initialize a new ORCH project in your repo
orch init
# Verify installation and see pre-configured agents
orch --version
orch agent listIf orch init is not required (e.g., the tool works without it), a note explaining how the first agent is created/registered would be helpful here.
![coderabbitai[bot]](https://cdn.github.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
skills/orch-runtime/SKILL.md (2)
226-226: Document theorch team listcommand.Line 226 references
orch team listto see groups and assign tasks to team members, but this command isn't documented anywhere else in the skill.Consider adding a section on team management or removing this reference to avoid confusion about features that aren't explained.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/orch-runtime/SKILL.md` at line 226, The mention of the command orch team list is undocumented; either add a short "Team management" section in SKILL.md that documents the orchestration team commands (at minimum describe orch team list: purpose, usage/syntax, example output, and how to assign tasks to team members) or remove the reference on line 226 if team features are not supported; update any related sections (e.g., task assignment examples) to reference the documented command names such as orch team list or the alternative approach you choose.
207-217: Clarify how to use the programmatic API within Claude Code context.The section shows TypeScript imports from
@oxgeneral/orch, but doesn't explain:
- Where would this code run? (In a Node.js script? In a Claude skill? In a custom ECC extension?)
- How to install the dependency in the appropriate context
- Whether ECC skills can import and use external npm packages
- How authentication/configuration for ORCH would work in programmatic usage
The comment "Use ORCH engine programmatically from your Claude skill" suggests this could be embedded in ECC skills, but there's no guidance on setup or examples of other skills using external packages this way.
Consider adding a subsection explaining the setup and context for programmatic usage, or providing a complete example with installation steps.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/orch-runtime/SKILL.md` around lines 207 - 217, Clarify the Programmatic API usage by explaining that the example using TaskService, AgentService, OrchestratorService is intended to run in a Node.js runtime (e.g., a backend service or a custom ECC extension process), not directly inside Claude's hosted execution sandbox; add a short subsection that (1) lists installation steps (npm install `@oxgeneral/orch`) and where to place that dependency (your backend or custom ECC extension package.json), (2) states whether ECC skills can import external npm packages (only if you deploy a custom extension or host server-side code the skill can call — hosted Claude code cannot install npm packages), and (3) shows how to configure/authenticate the SDK (mention relevant env vars or config object used by OrchestratorService/TaskService constructors or init function and an example flow: set env vars → initialize OrchestratorService with API key/URL → call TaskService.list). Include references to the symbols TaskService, AgentService, OrchestratorService and suggest linking to a minimal end-to-end example in the repo or docs.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@skills/orch-runtime/SKILL.md`:
- Line 37: Replace or add the required "How It Works" section header in the
SKILL.md by renaming the existing "Core Concepts" header to "How It Works" (or
insert a new "## How It Works" section above the core concepts) and move or
rewrite the explanatory content under that header so the file contains the
required "When to Use", "How It Works", and "Examples" sections; locate the
current "Core Concepts" heading in SKILL.md and update it to the exact "How It
Works" title and ensure the core-concept text sits beneath it.
- Around line 113-136: The "Integration with /orchestrate" section misleads
readers into thinking there's programmatic integration; change the section title
to something like "Using ORCH alongside /orchestrate" or "Manual Coordination
with /orchestrate", and add a short explicit note under the Hybrid Workflow
Example stating this is manual copy-paste coordination: describe steps that
/orchestrate runs in-process, the user must copy the HANDOFF document, then run
external orch CLI commands (orch context set, orch task add, orch task list),
and that ORCH is an independent external tool rather than part of ECC's
orchestration system.
---
Nitpick comments:
In `@skills/orch-runtime/SKILL.md`:
- Line 226: The mention of the command orch team list is undocumented; either
add a short "Team management" section in SKILL.md that documents the
orchestration team commands (at minimum describe orch team list: purpose,
usage/syntax, example output, and how to assign tasks to team members) or remove
the reference on line 226 if team features are not supported; update any related
sections (e.g., task assignment examples) to reference the documented command
names such as orch team list or the alternative approach you choose.
- Around line 207-217: Clarify the Programmatic API usage by explaining that the
example using TaskService, AgentService, OrchestratorService is intended to run
in a Node.js runtime (e.g., a backend service or a custom ECC extension
process), not directly inside Claude's hosted execution sandbox; add a short
subsection that (1) lists installation steps (npm install `@oxgeneral/orch`) and
where to place that dependency (your backend or custom ECC extension
package.json), (2) states whether ECC skills can import external npm packages
(only if you deploy a custom extension or host server-side code the skill can
call — hosted Claude code cannot install npm packages), and (3) shows how to
configure/authenticate the SDK (mention relevant env vars or config object used
by OrchestratorService/TaskService constructors or init function and an example
flow: set env vars → initialize OrchestratorService with API key/URL → call
TaskService.list). Include references to the symbols TaskService, AgentService,
OrchestratorService and suggest linking to a minimal end-to-end example in the
repo or docs.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 9caaeb4b-702d-4a33-92af-eac9dc726bc0
📒 Files selected for processing (1)
skills/orch-runtime/SKILL.md
| orch agent list | ||
| ``` | ||
|
|
||
| ## Core Concepts |
There was a problem hiding this comment.
Missing required "How It Works" section header.
The coding guidelines require skills to have clear sections for "When to Use, How It Works, and Examples." This file has "Core Concepts" instead of "How It Works."
Consider renaming this section to "How It Works" or adding a dedicated "How It Works" section that explains the mechanism before diving into core concepts.
As per coding guidelines: Skills should be formatted as Markdown with clear sections for When to Use, How It Works, and Examples.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/orch-runtime/SKILL.md` at line 37, Replace or add the required "How It
Works" section header in the SKILL.md by renaming the existing "Core Concepts"
header to "How It Works" (or insert a new "## How It Works" section above the
core concepts) and move or rewrite the explanatory content under that header so
the file contains the required "When to Use", "How It Works", and "Examples"
sections; locate the current "Core Concepts" heading in SKILL.md and update it
to the exact "How It Works" title and ensure the core-concept text sits beneath
it.
| ## 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 "<paste HANDOFF document>" | ||
| orch task add "Implement OAuth2 per handoff" \ | ||
| -d "$(orch context get ecc-handoff)" \ | ||
| -p 1 --assignee <backend-agent-id> | ||
|
|
||
| ### 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 | ||
| ``` |
There was a problem hiding this comment.
Clarify that this is manual coordination, not automated integration.
The section title "Integration with /orchestrate" suggests automated integration between ECC's /orchestrate command and the external ORCH tool, but the workflow shown is actually manual coordination:
- ECC's
/orchestrateruns in-process (per commands/orchestrate.md) - User manually copies HANDOFF document
- User runs separate
orchCLI commands - User manually retrieves results
The "integration" is just copying data between two independent tools. Consider:
- Retitling this section to "Using ORCH alongside /orchestrate" or "Manual Coordination with /orchestrate"
- Adding a note that this requires manual copy-paste steps
- Clarifying that ORCH is an external tool, not part of ECC's orchestration system
Based on learnings: The /orchestrate command uses handoff documents for sequential agent workflows (planner → tdd-guide → code-reviewer), which are in-process or tmux-based, not persistent agent systems.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/orch-runtime/SKILL.md` around lines 113 - 136, The "Integration with
/orchestrate" section misleads readers into thinking there's programmatic
integration; change the section title to something like "Using ORCH alongside
/orchestrate" or "Manual Coordination with /orchestrate", and add a short
explicit note under the Hybrid Workflow Example stating this is manual
copy-paste coordination: describe steps that /orchestrate runs in-process, the
user must copy the HANDOFF document, then run external orch CLI commands (orch
context set, orch task add, orch task list), and that ORCH is an independent
external tool rather than part of ECC's orchestration system.
![cubic-dev-ai[bot]](https://cdn.github.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
2 issues found across 1 file
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="skills/orch-runtime/SKILL.md">
<violation number="1" location="skills/orch-runtime/SKILL.md:28">
P2: User-facing docs introduce an unpinned global install of an external package and link to its external repo, which violates the team guidance against unvetted external dependencies in docs and increases supply‑chain risk.</violation>
<violation number="2" location="skills/orch-runtime/SKILL.md:127">
P2: The docs advise pasting arbitrary handoff content into a double-quoted shell argument, which allows shell expansion and can break on embedded quotes. This can corrupt the stored context or trigger local expansion; use a heredoc or file-based input instead.</violation>
</file>
Since this is your first cubic review, here's how it works:
- cubic automatically reviews your code and comments on bugs and improvements
- Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
- Add one-off context when rerunning by tagging
@cubic-dev-aiwith guidance or docs links (includingllms.txt) - Ask questions if you need clarification on any suggestion
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
| ## Prerequisites | ||
|
|
||
| ```bash | ||
| npm install -g @oxgeneral/orch |
There was a problem hiding this comment.
P2: User-facing docs introduce an unpinned global install of an external package and link to its external repo, which violates the team guidance against unvetted external dependencies in docs and increases supply‑chain risk.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At skills/orch-runtime/SKILL.md, line 28:
<comment>User-facing docs introduce an unpinned global install of an external package and link to its external repo, which violates the team guidance against unvetted external dependencies in docs and increases supply‑chain risk.</comment>
<file context>
@@ -0,0 +1,232 @@
+## Prerequisites
+
+```bash
+npm install -g @oxgeneral/orch
+```
+
</file context>
| → Output: HANDOFF document in context | ||
|
|
||
| ### Phase 2: Persistent execution (ORCH) | ||
| orch context set ecc-handoff "<paste HANDOFF document>" |
There was a problem hiding this comment.
P2: The docs advise pasting arbitrary handoff content into a double-quoted shell argument, which allows shell expansion and can break on embedded quotes. This can corrupt the stored context or trigger local expansion; use a heredoc or file-based input instead.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At skills/orch-runtime/SKILL.md, line 127:
<comment>The docs advise pasting arbitrary handoff content into a double-quoted shell argument, which allows shell expansion and can break on embedded quotes. This can corrupt the stored context or trigger local expansion; use a heredoc or file-based input instead.</comment>
<file context>
@@ -0,0 +1,232 @@
+→ Output: HANDOFF document in context
+
+### Phase 2: Persistent execution (ORCH)
+orch context set ecc-handoff "<paste HANDOFF document>"
+orch task add "Implement OAuth2 per handoff" \
+ -d "$(orch context get ecc-handoff)" \
</file context>
…patch (affaan-m#559) 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 <noreply@anthropic.com> Co-authored-by: Affaan Mustafa <me@affaanmustafa.com>
…team dispatch (affaan-m#559)" This reverts commit 9908610.
…patch (affaan-m#559) 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 <noreply@anthropic.com> Co-authored-by: Affaan Mustafa <me@affaanmustafa.com>
…team dispatch (affaan-m#559)" This reverts commit 2cd3258.
2 participants
Summary
Adds
skills/orch-runtime/SKILL.md— an integration skill for ORCH (@oxgeneral/orch), a TypeScript CLI runtime for coordinating persistent AI agent teams.Why this fits ECC:
/orchestrate,/multi-plan,/multi-execute)What the skill teaches:
orch task add)orch context set/get)/orchestratefor planning → ORCH for execution@oxgeneral/orchas npm library)Type
Testing
Tested against ORCH v0.3+ with Claude adapter:
All CLI commands in the skill are functional and verified.
Checklist
skills/orch-runtime/SKILL.mdname,description,origin: communitySummary by cubic
Adds
skills/orch-runtime/SKILL.md, a new skill that integrates ECC with ORCH to dispatch work to a persistent, stateful agent team. Enables long-running workflows across sessions with a formal state machine, auto-retry, team messaging, and a shared context bridge.@oxgeneral/orchand theorchCLI.orch task add/list/show,orch tui,orch logs.orch context set/get./orchestrate, execute asynchronously with ORCH review gates.orch msg send/broadcast, goals with dependencies.@oxgeneral/orchAPI for embedding in Node.js apps.Written for commit 66d874f. Summary will update on new commits.
Summary by CodeRabbit
Release Notes