sampx/agent-orchestration
skills/backup/agent-orchestration/SKILL.md
Orchestrate OpenCode agent with OpenSpec-driven workflows and worktree isolation. Use when you need to: (1) Drive OpenCode with OpenSpec artifacts (proposal/design/specs/tasks), (2) Execute tasks in background with process-adapter, (3) Monitor and interact with background agent sessions, (4) Use worktree for isolated development. This skill is for Wopal to coordinate OpenCode as an execution unit.
$ install --global
skillsauthnpx skillsauth add sampx/agent-tools agent-orchestrationInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 24, 2026, 8:46 PM1.8s1 file scanned
SKILL.md
- name:
- agent-orchestration
- description:
- >
- Use when you need to:
- (1) Drive OpenCode with OpenSpec artifacts (proposal/design/specs/tasks),
Agent Orchestration (OpenCode)
编排 OpenCode 代理，通过 OpenSpec 驱动的工作流和 Worktree 隔离实现高效开发。
前置要求
- ✅
process-adapter（@wopal/processnpm 包，全局安装） - ✅
opencode命令行工具 - ✅
git-worktrees技能（可选，用于 Worktree 集成）
安装 @wopal/process：
cd projects/ontology/tools/process && npm install && npm link
检查所有依赖：
.agents/skills/agent-orchestration/scripts/check-dependencies.sh
快速开始
1. 简单任务（无 Worktree）
# 启动后台任务
SESSION=$(process-adapter start \
"OPENCODE_PERMISSION='{\"bash\":{\"*\":\"allow\"},\"edit\":{\"*\":\"allow\"},\"write\":{\"*\":\"allow\"}}' \
opencode run 'Read AGENTS.md and summarize project architecture.'" \
--name my-task \
--cwd projects/ontology | awk '{print $3}')
# 查看进度
process-adapter log $SESSION
2. OpenSpec 工作流（带 Worktree）
WORKSPACE_ROOT="/Users/sam/coding/wopal/wopal-workspace"
CHANGE="add-auth"
# 1. 创建 worktree
.agents/skills/git-worktrees/scripts/worktree.sh create ontology feature/auth
# 2. 清理标记文件
rm -f /tmp/opencode-done-$CHANGE
# 3. 启动 OpenCode（使用绝对路径）
SESSION=$(process-adapter start \
"PROCESS_ADAPTER_SESSION_ID=$CHANGE \
OPENCODE_PERMISSION='{\"bash\":{\"*\":\"allow\"},\"edit\":{\"*\":\"allow\"},\"write\":{\"*\":\"allow\"}}' \
opencode run 'Read $WORKSPACE_ROOT/openspec/changes/$CHANGE/tasks.md and implement all tasks. Run tests.'" \
--name $CHANGE \
--cwd .worktrees/ontology-feature-auth | awk '{print $3}')
# 4. 监控完成
.agents/skills/agent-orchestration/scripts/wait-for-opencode.sh $CHANGE 300
# 5. 查看结果
process-adapter log $SESSION
3. 一键启动（推荐）
.agents/skills/agent-orchestration/scripts/quick-start.sh \
ontology feature/auth add-auth 300
核心概念
process-adapter 会话管理
process-adapter list # 列出所有会话
process-adapter log <session-id> # 查看输出（最后 200 行）
process-adapter log <session-id> --limit 100 # 限制行数
process-adapter poll <session-id> # 检查状态
process-adapter kill <session-id> # 终止进程
process-adapter remove <session-id> # 清理会话
OpenCode 权限配置
非交互模式下，权限请求会被自动拒绝。必须通过环境变量预授权：
# 完整权限（OpenSpec 实现任务）
OPENCODE_PERMISSION='{"bash":{"*":"allow"},"edit":{"*":"allow"},"write":{"*":"allow"}}'
# Worktree 模式（需要读取主仓库 OpenSpec 文件）
OPENCODE_PERMISSION='{
"bash": {"*": "allow"},
"edit": {"*": "allow"},
"write": {"*": "allow"},
"read": {"*": "allow"},
"external_directory": {"*": "allow"}
}'
详见 references/permission-configs.md。
完成通知机制
通过 task-notify.js 插件监听 OpenCode 任务完成：
- 启动时设置
PROCESS_ADAPTER_SESSION_ID=<task-id> - 任务完成后插件创建标记文件
/tmp/opencode-done-<task-id> wait-for-opencode.sh轮询该文件直到存在或超时
重要：启动前必须清理残余标记文件，避免误判完成。
Worktree 隔离
新格式（create <project> <branch>）：
# 创建
.agents/skills/git-worktrees/scripts/worktree.sh create <project> <branch>
# 生成路径：.worktrees/<project>-<branch-dir>/
# 分支中的 / 自动转换为 -，如 feature/auth → ontology-feature-auth
# 清理
.agents/skills/git-worktrees/scripts/worktree.sh remove <project> <branch>
重要：OpenCode 运行在 worktree 目录，必须使用绝对路径读取主仓库的 OpenSpec 文件。
详见 examples/worktree-integration.md。
常见场景
并行执行多个任务
WORKSPACE_ROOT="/Users/sam/coding/wopal/wopal-workspace"
# 清理标记文件
rm -f /tmp/opencode-done-task-1 /tmp/opencode-done-task-2
# 并行启动
S1=$(process-adapter start \
"PROCESS_ADAPTER_SESSION_ID=task-1 OPENCODE_PERMISSION='...' \
opencode run 'Read $WORKSPACE_ROOT/openspec/changes/change-1/tasks.md and implement.'" \
--name task-1 --cwd .worktrees/project-branch-1 | awk '{print $3}')
S2=$(process-adapter start \
"PROCESS_ADAPTER_SESSION_ID=task-2 OPENCODE_PERMISSION='...' \
opencode run 'Read $WORKSPACE_ROOT/openspec/changes/change-2/tasks.md and implement.'" \
--name task-2 --cwd .worktrees/project-branch-2 | awk '{print $3}')
# 依次等待完成
.agents/skills/agent-orchestration/scripts/wait-for-opencode.sh task-1 300
.agents/skills/agent-orchestration/scripts/wait-for-opencode.sh task-2 300
会话监控
# 基础监控
python3 .agents/skills/agent-orchestration/scripts/monitor_session.py <session-id>
# 过滤输出
python3 .agents/skills/agent-orchestration/scripts/monitor_session.py <session-id> --filter "Error|Warning"
# 持续监控
python3 .agents/skills/agent-orchestration/scripts/monitor_session.py <session-id> --watch
常见错误排查
| 症状 | 原因 | 解决方案 |
|------|------|----------|
| Permission denied | 非交互模式未预授权 | 设置 OPENCODE_PERMISSION 环境变量 |
| 读不到 OpenSpec 文件 | Worktree 使用相对路径 | 改用绝对路径 + external_directory 权限 |
| 任务立即"完成" | 残余标记文件 | 启动前 rm -f /tmp/opencode-done-<task-id> |
| 任务超时无响应 | OpenCode 崩溃 | 使用 process-adapter log/poll 排查 |
详见 references/troubleshooting.md。
资源
脚本：
scripts/quick-start.sh— 一键启动 OpenSpec 任务scripts/check-dependencies.sh— 依赖检查scripts/wait-for-opencode.sh— 监控任务完成（支持超时）scripts/monitor_session.py— 会话输出监控scripts/prepare_openspec_context.sh— 生成 OpenSpec 执行摘要
示例：
examples/openspec-workflow.md— 完整 OpenSpec 驱动工作流examples/simple-task.md— 简单任务示例examples/worktree-integration.md— Worktree 集成详细指南examples/parallel-agents.md— 并行任务示例
参考：
references/permission-configs.md— 权限配置模式references/troubleshooting.md— 常见问题排查
Related Skills
sampx/ellamaka-config
tools
VerifiedTrustedCommunity
Configure ellamaka, a fork of OpenCode with wopal-space mode. MUST use for any task about ellamaka config, agent frontmatter, permission rules, model/provider selection, formatter settings, config loading order, or why config changes are ignored. Trigger on requests about ellamaka or opencode config files, agent permission overrides, restricting subagents, custom/plugin tool permissions (e.g. wopal_task_*), disabling tools, configuring providers or models, formatter setup, config precedence or layering, or debugging settings that do not take effect. Use this skill even when the user says "opencode" if the actual runtime, config path, or behavior is ellamaka. Prefer this skill whenever the answer depends on the difference between ellamaka and upstream opencode, including wopal-space config loading, plugin tool permissions, or agent frontmatter precedence.
1SKILL.mdUpdated May 31, 2026
sampx/df-plan-review
development
VerifiedTrustedCommunity
Plan quality verification for dev-flow. Goal-backward analysis ensures plans WILL achieve their stated goal before execution burns context. ⚠️ MUST use when: (1) Reviewing Plan quality before approve (2) Wopal completes Plan writing and needs quality gate (3) User asks to "check plan", "verify plan", "review plan" (4) Plan enters planning status and needs pre-execution validation 🔴 Trigger automatically when Plan is ready for review, even if user doesn't explicitly say "review". Agent: rook (read-only verification subagent) Mode: verification, not execution
1SKILL.mdUpdated May 31, 2026
sampx/df-implement-review
development
VerifiedTrustedCommunity
Review implementation results for goal achievement and code quality. Supports both Plan-backed review and planless diff review. ⚠️ MUST use when: (1) Wopal delegates rook to review fae implementation output, (2) Prompt contains "review_type: implementation", (3) Prompt contains changed code file list or Plan path + implementation scope, (4) Any code review request from Wopal. 🔴 Trigger even when user does not explicitly mention "review" if the task involves verifying implementation results. This skill is rook-exclusive (only rook agent can load it).
1SKILL.mdUpdated May 31, 2026
sampx/agents-collab
tools
VerifiedTrustedCommunity
Foundation rules for how Wopal collaborates with sub-agents such as fae and rook. ⚠️ MUST load before ANY delegation — covers delegation tool APIs, task lifecycle, notifications, status handling, and recovery. 🔴 Trigger: "delegate", "let fae implement", "fae task", "rook review", "check task status", "cancel task", "abort task", "agent collaboration", "委派", "让 fae 执行", "fae 任务", "rook 审查", "检查状态", or any intent to hand work to a sub-agent. 🔴 Never delegate without loading this skill first. Skipping it is serious negligence. Note: this skill does not include workflow-specific prompt templates such as dev-flow templates. Those belong to the corresponding workflow skills.
1SKILL.mdUpdated May 31, 2026