Agents

Goblin uses Claude Code agents running in tmux sessions to perform development tasks.

Agent Types

Pipeline Agents

Agent	Stage	Purpose
Scoper	SCOPE	Analyzes issue, creates implementation plan
Builder	BUILD	Implements code, commits changes
Reviewer	REVIEW	Reviews diff, checks for issues
Tester	TEST	Runs tests, validates QA steps

Specialist Agents

Specialist	Trigger	Purpose
CEO	before_scope, manual	Product validation, scope decisions
DevOps	ci_failure, manual	CI/CD, Docker issues
Security	auth_changes, manual	Security audits
Performance	manual	Performance optimization
Docs	after_merge, manual	Documentation updates

See Specialists for details.

Agent Lifecycle

IDLE ──▶ WORKING ──▶ COMPLETE ──▶ ARCHIVED
  │         │
  │         ▼
  │      STALLED ──▶ RECOVERY
  │                     │
  └─────────────────────┘

State	Description
idle	Available for work
working	Actively processing a task
stalled	No heartbeat for threshold period
complete	Task finished successfully
failed	Task failed

tmux Sessions

Each agent runs in its own tmux session:

# List agent sessions
tmux list-sessions | grep goblin

# Attach to an agent session
goblin attach AGENT_ID

Agent Communication

Agents signal stage completion via files in .goblin/:

Signal File	Meaning
scope-complete	Scoper finished
build-complete	Builder finished
review-approved	Reviewer approved
review-changes-requested	Reviewer requested changes
test-passed	Tester passed
test-failed	Tester failed

See Signal Files for the complete reference.

Context Continuity

Agents maintain progress via GOBLIN_NOTES.md, enabling:

• Progress tracking across sessions
• Context handoffs between agents
• Recovery from crashes

Heartbeat Monitoring

The daemon monitors agent health:

• Checks for file modifications in worktree
• Detects stalled agents (no activity for threshold)
• Triggers recovery for stalled agents

Default stall threshold: 30 minutes.

Debugging

goblin status              # View agent status
goblin attach AGENT_ID     # Attach to session
goblin agent logs AGENT_ID # View logs
goblin agent kill AGENT_ID # Kill stuck agent

Next Steps

• Pipeline - How agents work together
• Context Engineering - Agent context strategies