Configuration Guide

# Genericized orchestrator command (key excerpts)
# Full command is ~300 lines; this shows the essential structure.

# === IDENTITY ===
# Create sentinel file so hooks know this is an orchestrator session
touch "$HOME/.claude/.orchestrator-active-$SESSION_ID"

# === PRE-FLIGHT ===
# 1. Read CLAUDE.md and AGENTS.md for project conventions
# 2. Identify architecture docs relevant to current epic
# 3. Load orchestration state from loopctl
mcp__loopctl__get_progress({project_id: "<uuid>"})

# === AUTONOMOUS LOOP ===
# Repeat until no stories remain in ready state:

# 1. Find next ready story
STORY=$(mcp__loopctl__list_stories({status: "ready", limit: 1}))

# 2. Contract the story (commit to acceptance criteria count)
mcp__loopctl__contract_story({
story_id: "$STORY_ID",
story_title: "...",
ac_count: 12
})

# 3. Build implementation context
#    - Read the story JSON for full requirements
#    - Identify which architecture docs apply
#    - Check for dependency stories that inform this one

# 4. Dispatch implementation agent (NEVER write code directly)
#    The orchestrator coordinates. Agents write code.
claude --agent implementation-agent \
--message "Implement US-X.Y: $STORY_TITLE ..."

# 5. Implementation agent finishes — request review
mcp__loopctl__request_review({story_id: "$STORY_ID"})

# 6. Dispatch review agents (different identity than implementer)
#    Team review: 3 agents in parallel
#    Then: VCA (Verify, Classify, Aggregate)
#    Then: Adversarial review: 4 agents in parallel
#    Then: VCA again

# 7. Review agent reports completion
mcp__loopctl__report_story({story_id: "$STORY_ID"})
mcp__loopctl__review_complete({
story_id: "$STORY_ID",
findings_count: 14,
fixes_count: 12,
disproved_count: 2
})

# 8. Orchestrator verifies (third identity)
mcp__loopctl__verify_story({story_id: "$STORY_ID"})

# === RULES ===
# - MCP tools over curl (typed, validated, discoverable)
# - One story at a time — never parallelize stories
# - Chain of custody: implementer != reviewer != verifier
# - Never write code directly — dispatch sub-agents
# - Fix ALL review findings — no deferrals

---
name: implementation-agent
description: Primary development agent for feature implementation
permissionMode: bypassPermissions
model: sonnet
effort: high
skills:
- patterns-elixir
- patterns-ecto
- patterns-phoenix-web
---

---
name: business-analyst
description: Requirements analysis, AC validation, and story quality review
permissionMode: bypassPermissions
model: opus
effort: high
skills:
- patterns-elixir
- patterns-ecto
- patterns-phoenix-web
---

---
name: systems-architect
description: Architecture review, OTP compliance, fault tolerance, scalability
permissionMode: bypassPermissions
model: opus
effort: high
skills:
- patterns-elixir
- patterns-ecto
- patterns-phoenix-web
- patterns-elixir-otp
- patterns-elixir-integration
---

---
name: security-adversary
description: Adversarial security and resilience reviewer (READ-ONLY)
permissionMode: bypassPermissions
model: opus
effort: high
skills:
- owasp-security
- patterns-elixir
---

Team Review (3 agents)  ──>  VCA  ──>  Fix
      │                                  │
      ▼                                  ▼
Adversarial Review (4 agents)  ──>  VCA  ──>  Fix  ──>  Summary

# Findings math is API-enforced:
fixes_count + disproved_count == findings_count

# Example: 14 findings found
{
"findings_count": 14,
"fixes_count": 12,      # Bugs actually fixed
"disproved_count": 2     # False positives with justification
}
# 12 + 2 == 14  ✓  (accepted by API)
# 12 + 1 == 13  ✗  (rejected — math doesn't add up)

#!/bin/bash
# .claude/hooks/PreToolUse/orchestrator-guardrail.sh
# Blocks Edit/Write/MultiEdit when orchestrator sentinel is active.
# Orchestrator coordinates — agents write code.

input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name // ""')
session_id=$(echo "$input" | jq -r '.session_id // ""')

if [ -f "$HOME/.claude/.orchestrator-active-$session_id" ]; then
case "$tool_name" in
  Edit|Write|MultiEdit|NotebookEdit)
    echo "BLOCKED: Orchestrator cannot write code. Dispatch a sub-agent." >&2
    exit 2 ;;
esac
fi
exit 0

#!/bin/bash
# .claude/hooks/Stop/keep-working.sh
# Prevents orchestrator from stopping when stories remain.
# Queries loopctl API for pending work.

INPUT=$(cat)
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // ""')

if [ ! -f "$HOME/.claude/.orchestrator-active-$SESSION_ID" ]; then
exit 0  # Not an orchestrator session
fi

# Check for remaining work
PENDING=$(curl -s -H "Authorization: Bearer $LOOPCTL_ORCH_KEY" \
"$LOOPCTL_SERVER/api/v1/stories/ready?limit=1" | jq '.data | length')

if [ "$PENDING" -gt 0 ]; then
exit 2  # Force continuation — stories remain
fi
exit 0

# My Project

Stack: Elixir 1.18 / Phoenix 1.8, PostgreSQL, Oban

## CRITICAL: Load Orchestration State
mcp__loopctl__get_progress({project_id: "<uuid>"})

## Chain-of-Custody Enforcement
- POST /stories/:id/report — 409 if caller == assigned_agent
- POST /stories/:id/review-complete — 409 if caller == assigned_agent
- POST /stories/:id/verify — 409 if caller == assigned_agent

{
"mcpServers": {
  "loopctl": {
    "command": "npx",
    "args": ["loopctl-mcp-server"],
    "env": {
      "LOOPCTL_SERVER": "https://loopctl.com",
      "LOOPCTL_ORCH_KEY": "lc_your_orchestrator_key",
      "LOOPCTL_AGENT_KEY": "lc_your_agent_key"
    }
  }
}
}