/chain-patterns

name: chain-patterns
compatibility: "Claude Code 2.1.277+"
description: "Multi-phase pipeline patterns: MCP detection, handoff files, checkpoint-resume, worktree agents, cron monitoring. Use when building or debugging a pipeline skill."
user-invocable: false
context: inherit
allowed-tools: "Read ToolSearch"
model: haiku
# Reference skill: fenced calls below teach a pattern, they are not calls this
# skill makes. Widening allowed-tools to satisfy the coverage gate would grant real
# permissions (Agent, CronCreate) to something that never acts.
tool-coverage: illustrative
metadata:
  version: "1.0.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "pipeline, resilience, checkpoint, mcp, orchestkit"

Chain Patterns

Overview

Foundation patterns for CC 2.1.71 pipeline skills. This skill is loaded via the `skills:` frontmatter field — it provides patterns that parent skills follow.

Pattern 1: MCP Detection (ToolSearch Probe)

Run BEFORE any MCP tool call. Probes are parallel and instant.

# FIRST thing in any pipeline skill — all in ONE message:
ToolSearch(query="select:mcp__memory__search_nodes")
ToolSearch(query="select:mcp__context7__resolve-library-id")
ToolSearch(query="select:mcp__sequential-thinking__sequentialthinking")

# Store results for all phases:
Write(".claude/chain/capabilities.json", JSON.stringify({
  "memory": true_or_false,
  "context7": true_or_false,
  "sequential": true_or_false,
  "timestamp": "ISO-8601"
}))

**Usage in phases:**

# BEFORE any mcp__memory__ call:
if capabilities.memory:
    mcp__memory__search_nodes(query="...")
# else: skip gracefully, no error

Load details: `Read("references/mcp-detection.md")`

Pattern 2: Handoff Files

Write structured JSON after every major phase. Survives context compaction and rate limits.

Write(".claude/chain/NN-phase-name.json", JSON.stringify({
  "phase": "rca",
  "skill": "fix-issue",
  "timestamp": "ISO-8601",
  "status": "completed",
  "outputs": { ... },           # phase-specific results
  "mcps_used": ["memory"],
  "next_phase": 5
}))

**Location:** `.claude/chain/` — numbered files for ordering, descriptive names for clarity.

Load schema: `Read("references/handoff-schema.md")`

Pattern 3: Checkpoint-Resume

Read state at skill start. If found, skip completed phases.

# FIRST instruction after MCP probe:
Read(".claude/chain/state.json")

# If exists and matches current skill:
#   → Read last handoff file
#   → Skip to current_phase
#   → Tell user: "Resuming from Phase N"

# If not exists:
Write(".claude/chain/state.json", JSON.stringify({
  "skill": "fix-issue",
  "started": "ISO-8601",
  "current_phase": 1,
  "completed_phases": [],
  "capabilities": { ... }
}))

# After each major phase:
# Update state.json with new current_phase and append to completed_phases

Load protocol: `Read("references/checkpoint-resume.md")`

Pattern 4: Worktree-Isolated Agents

Use `isolation: "worktree"` when spawning agents that WRITE files in parallel.

# Agents editing different files in parallel:
Agent(
  subagent_type="ork:backend-system-architect",
  prompt="Implement backend for: {feature}...",
  isolation="worktree",       # own copy of repo
  run_in_background=true
)

**When to use worktree:** Agents with Write/Edit tools running in parallel.

> **Isolation is additive only (#4557):** per-spawn `isolation` can add a worktree but can never remove one an agent declares in frontmatter, and a frontmatter-isolated agent fails to spawn from a non-git cwd ("Cannot create agent worktree"). So ork agents leave it off their frontmatter and the caller opts in per spawn. Only `git-operations-engineer` and `release-engineer` declare it; spawn those from inside the target repo.

> **CC 2.1.157 worktree lifecycle:** `EnterWorktree` can switch between Claude-managed worktrees mid-session, and worktrees are left **unlocked** when the agent finishes — so `git worktree remove`/`prune` cleans them up without `--force`.

> **Session-aware worktree check (CC 2.1.145):** before parallel-worktree work, detect concurrent same-repo sessions with `claude agents --json` (filter by `working_dir`) rather than `ps`/`pgrep` — it returns `session_id`, `parent_agent_id`, `working_dir`, `awaiting_input`, and `elapsed` per live session, so you can tell *which* sessions share this repo. **When NOT to use:** Read-only agents (brainstorm, assessment, review).

Load details: `Read("references/worktree-agent-pattern.md")`

Pattern 5: CronCreate Monitoring

Schedule post-completion health checks that survive session end.

# Guard: Skip cron in headless/CI (CLAUDE_CODE_DISABLE_CRON)
# if env CLAUDE_CODE_DISABLE_CRON is set, run a single check instead
CronCreate(
  schedule="*/5 * * * *",
  prompt="Check CI status for PR #{number}:
    Run: gh pr checks {number} --repo {repo}
    All pass → CronDelete this job, report success.
    Any fail → alert with failure details."
)

Load patterns: `Read("references/cron-monitoring.md")`

Pattern 6: Progressive Output (CC 2.1.76)

Launch agents with `run_in_background=true` and output results as each returns — don't wait for all agents to finish. Gives ~60% faster perceived feedback.

> **Background by default (CC 2.1.198+):** Agent-tool subagents launch in the background even when `run_in_background` is omitted. Pass `run_in_background: false` only when a stage must block on the result before continuing (e.g. a verdict gate ahead of a destructive step). The `Notification` hook fires `agent_needs_input` / `agent_completed` as background agents progress — ork's notification hooks surface both. > > **Skill-side twin (CC 2.1.218+):** skills with `context: fork` also background by default; the per-skill opt-out is `background: false` in frontmatter. ork's rule: every `user-invocable: true` fork skill declares it (a human typed the command and is waiting — verdict gates and AskUserQuestion turns need the interactive