Shared References

This directory contains shared reference documents used by multiple skills:

• validation-contract.md

  - Verification requirements for accepting spawned work

• references/claude-code-latest-features.md

  - Claude Code feature contract (slash commands, agent isolation, hooks, settings)

• references/backend-claude-teams.md

  - Concrete examples for Claude native teams (

  TeamCreate

  +

  SendMessage

  )

• references/backend-codex-subagents.md

  - Concrete examples for Codex CLI and Codex sub-agents

• references/backend-background-tasks.md

  - Fallback:

  Task(run_in_background=true)

• references/backend-inline.md

  - Degraded single-agent mode (no spawn)

• references/claude-cli-verified-commands.md

  - Verified Claude CLI command shapes and caveats

• references/codex-cli-verified-commands.md

  - Verified Codex CLI command shapes and caveats

• references/cli-command-failures-2026-02-26.md

  - Dated failure log and mitigations from live runs

These are not directly invocable skills. They are loaded by other skills (council, crank, swarm, research, implement) when needed.

CLI Availability Pattern

All skills that reference external CLIs MUST degrade gracefully when those CLIs are absent.

Check Pattern

# Before using any external CLI, check availability
if command -v bd &>/dev/null; then
  # Full behavior with bd
else
  echo "Note: bd CLI not installed. Using plain text tracking."
  # Fallback: use TaskList, plain markdown, or skip
fi

Fallback Table

bd

ao

.agents/learnings/

gt

codex

which codex

--mixed

cass

.agentops/config.yaml

Required Multi-Agent Capabilities

Council, swarm, and crank require a runtime that provides these capabilities. If a capability is missing, the corresponding feature degrades.

--quick

Every runtime maps these capabilities to its own API. Skills describe WHAT to do, not WHICH tool to call.

After detecting your backend (see Backend Detection below), load the matching reference for concrete tool call examples:

skills/shared/references/claude-code-latest-features.md

skills/shared/references/backend-claude-teams.md

skills/shared/references/backend-codex-subagents.md

skills/shared/references/backend-background-tasks.md

skills/shared/references/backend-inline.md

Backend Detection

Use capability detection at runtime, not hardcoded tool names. The same skill must work across any agent harness that provides multi-agent primitives. If no multi-agent capability is detected, degrade to single-agent inline mode (

--quick

Selection policy (runtime-native first):

1. If running in a Claude session and

   TeamCreate

   /

   SendMessage

   are available, use Claude Native Teams as the primary backend.
2. If running in a Codex session and

   spawn_agent

   is available, use Codex sub-agents as the primary backend.
3. If both are technically available, pick the backend native to the current runtime unless the user explicitly requests mixed/cross-vendor execution.
4. Only use background tasks when neither native backend is available.

spawn_agent(message=...)

TeamCreate

Task(team_name=...)

task(subagent_type="general", prompt=...)

spawn_agent(message=...)

Task(subagent_type="Explore")

task(subagent_type="explore", prompt=...)

wait(ids=[...])

SendMessage

send_input(id=..., message=...)

SendMessage(type="message", ...)

task(task_id="<prior>", prompt=...)

close_agent(id=...)

shutdown_request

TeamDelete()

send_input

SendMessage

OpenCode limitations:

• No inter-agent messaging — workers run as independent sub-sessions
• No debate mode (

  --debate

  ) — requires messaging between judges

• --quick

  (inline) mode works identically across all backends

Backend Capabilities Matrix

Prefer native teams over background tasks. Native teams provide messaging, redirect, and graceful shutdown. Background tasks are fire-and-forget with no steering — only a speedometer and emergency brake.

wait()

SendMessage

TaskOutput

send_input

SendMessage

SendMessage

close_agent

shutdown_request

send_input

SendMessage

send_input

SendMessage

git worktree

isolation: worktree

When to use each:

Skill Invocation Across Runtimes

Skills that chain to other skills (e.g.,

/rpi

/research

/vibe

/council

Skill(skill="X", args="...")

Skill(skill="council", args="--quick validate recent")

Skill

skill

<skill_content>

skill(skill="council")

OpenCode skill chaining rules:

1. Call the

   skill

   tool to load the target skill's content into context
2. Read and follow the loaded instructions directly — do NOT expect automatic execution
3. NEVER use slashcommand syntax (e.g.,

   /council

   ) in OpenCode — it triggers a command lookup, not skill loading
4. If the loaded skill references tools by Claude Code names, use OpenCode equivalents (see tool mapping below)

Cross-runtime tool mapping:

Task(subagent_type="...")

task(subagent_type="...")

Skill(skill="X")

skill

AskUserQuestion

question

TaskCreate

TaskUpdate

TaskList

TaskGet

todo

Read

Write

Edit

Bash

Glob

Grep

Rules

1. Never crash — missing CLI = skip or fallback, not error
2. Always inform — tell the user what was skipped and how to enable it
3. Preserve core function — the skill's primary purpose must still work without optional CLIs
4. Progressive enhancement — CLIs add capabilities, their absence removes them cleanly

Reference Documents

• references/content-hash-cache.md
• references/compaction-signals.md
• references/backend-background-tasks.md
• references/backend-claude-teams.md
• references/backend-codex-subagents.md
• references/backend-inline.md
• references/claude-code-latest-features.md
• references/claude-cli-verified-commands.md
• references/codex-cli-verified-commands.md
• references/cli-command-failures-2026-02-26.md
• references/ralph-loop-contract.md
• references/orchestration-as-prompt.md
• references/stale-scope-validation.md — planning rule loaded by plan + pre-mortem: re-validate inherited scope against HEAD before acting on deferred beads or handoff docs.
• references/strict-delegation-contract.md — canonical contract loaded by /rpi, /discovery, /validation: strict sub-skill delegation is the default for top-level orchestrators.