Skip to main content

Signal Files

Agents communicate stage completion via signal files.

Overview​

Signal files are created in .goblin/ within the worktree:

worktrees/{ISSUE_ID}/.goblin/
├── scope-complete
├── build-complete
├── review-approved
├── review-changes-requested
├── test-passed
└── test-failed

Signal File Reference​

scope-complete​

Created by: Scoper Triggers: BUILD stage

{
  "completed_at": "2024-01-15T10:30:00Z",
  "scope_result_hash": "abc123"
}

build-complete​

Created by: Builder Triggers: REVIEW stage

{
  "completed_at": "2024-01-15T11:00:00Z",
  "commits": 5,
  "files_changed": 8,
  "lines_added": 200,
  "lines_removed": 50
}

review-approved​

Created by: Reviewer Triggers: TEST stage

{
  "completed_at": "2024-01-15T11:30:00Z",
  "critical_issues": 0,
  "informational_issues": 2,
  "auto_fixes": 1
}

review-changes-requested​

Created by: Reviewer Triggers: BUILD stage (retry)

{
  "completed_at": "2024-01-15T11:30:00Z",
  "issues": [
    {
      "type": "critical",
      "category": "sql_injection",
      "file": "db.py",
      "line": 45,
      "fixed": false,
      "description": "String interpolation in query"
    }
  ],
  "summary": "2 critical issues require fixes"
}

test-passed​

Created by: Tester Triggers: DONE stage

{
  "completed_at": "2024-01-15T12:00:00Z",
  "qa_steps_total": 5,
  "qa_steps_passed": 5,
  "bugs_found": 2,
  "bugs_fixed": 2,
  "screenshots": [
    "01-initial.png",
    "02-action.png",
    "03-result.png"
  ]
}

test-failed​

Created by: Tester Triggers: REVIEW stage (retry)

{
  "completed_at": "2024-01-15T12:00:00Z",
  "failing_steps": ["QA-2", "QA-5"],
  "reason": "Error handling not working",
  "attempts": 1,
  "screenshots": [
    "01-initial.png",
    "02-error.png"
  ]
}

Detection​

The PipelineRunner watches for signal files:

# Polling interval
POLL_INTERVAL_SECONDS = 5

# Watched files
SIGNAL_FILES = [
    "scope-complete",
    "build-complete",
    "review-approved",
    "review-changes-requested",
    "test-passed",
    "test-failed",
]

Creating Signal Files​

Agents create signals using touch or write:

# Simple signal
touch .goblin/build-complete

# With content
echo '{"commits": 5}' > .goblin/build-complete

Cleanup​

Signal files are cleaned up:

  • When next stage starts
  • When pipeline completes
  • When pipeline is cancelled

Debugging​

# Check signal files
ls -la worktrees/ENG-123/.goblin/

# View signal content
cat worktrees/ENG-123/.goblin/build-complete

# Manually trigger stage
touch worktrees/ENG-123/.goblin/build-complete