flywheel: Instructions file for Claude Code

Flywheel — claude.md

This repo develops the Flywheel plugin for Claude Code and OpenCode. Source lives in flywheel/ (plugin contents); integration tests live in tests/integration/. Architectural philosophy: @docs/adrs/0001-skill-design-as-negotiation.md

Running integration tests

The end-to-end test (tests/integration/cases/03-pipeline-end-to-end.test.sh) drives the full /yolo autonomous flow against the real Anthropic API. Prerequisites:

• ANTHROPIC_API_KEY set
• tmux, claude, jq, bunx on PATH
• The plugin installed via bash install_claude_code.sh < /dev/null (stdin redirected to skip the Context7 prompt)

A typical run takes 25–45 minutes. Cost: real API tokens.

# Reinstall plugin first if any plugin file changed
bash install_claude_code.sh < /dev/null 2>&1 | tail -3

# Run e2e test in background, capture output
bash tests/integration/cases/03-pipeline-end-to-end.test.sh \
  > /tmp/yolo-test.log 2>&1; echo "TEST EXITED: $?" >> /tmp/yolo-test.log

Smaller tests:

• 00-plugin-loads.test.sh — palette discovery, no model call (~30s)
• 01-fly-work-resumes.test.sh — work skill against seeded session (~1–3min)
• 02-fly-plan-creates-spec.test.sh — plan skill end-to-end (~3–10min)

Monitoring a long-running test

Don't sit and watch the log. Use the Monitor tool with a script that emits events on milestones, deadlocks, and silent stops. Skeleton:

last_log=0; last_prompt=0; last_log_time=$(date +%s); stall_warned=0
while true; do
  now=$(date +%s)

  # 1. Test progress: emit each new PASS/FAIL/INFO line
  cur_log=$(wc -l < /tmp/yolo-test.log 2>/dev/null || echo 0)
  if [ "$cur_log" -gt "$last_log" ]; then
    tail -n $((cur_log - last_log)) /tmp/yolo-test.log \
      | grep --line-buffered -E "^(PASS|FAIL|INFO|Summary|TEST EXITED):" || true
    last_log=$cur_log
    last_log_time=$now
    stall_warned=0
  fi

  # 2. Deadlock detection: AskUserQuestion prompt visible in tmux
  pane=$(tmux capture-pane -t flywheel-int-yolo -p 2>/dev/null || echo "")
  prompt=$(echo "$pane" | grep -cE "Enter to select|Submit answers|Ready to submit" 2>/dev/null || echo 0)
  if [ "$prompt" -gt 0 ] && [ "$last_prompt" -eq 0 ]; then
    echo "DEADLOCK_DETECTED: AskUserQuestion in pane"
    echo "$pane" | tail -12
  fi
  last_prompt=$prompt

  # 3. Silent-stop detection: log idle >5min while test still running
  log_idle=$((now - last_log_time))
  if [ "$log_idle" -gt 300 ] && [ "$stall_warned" -eq 0 ] && [ "$last_log" -gt 0 ]; then
    echo "STALL_DETECTED: log idle ${log_idle}s — agent may have silent-stopped"
    echo "$pane" | tail -10
    stall_warned=1
  fi

  # 4. Completion: break on test exit (Summary OR TEST EXITED)
  if grep -q "^Summary:\|^TEST EXITED:" /tmp/yolo-test.log 2>/dev/null; then
    grep "^Summary:\|^TEST EXITED:" /tmp/yolo-test.log | tail -3
    break
  fi
  sleep 30
done