Skip to main content

Context Engineering

Goblin uses context engineering techniques to maximize Claude agent effectiveness.

Philosophy​

Context is everything. Well-structured context enables:

  • Faster task completion
  • Fewer errors
  • Better handoffs between sessions
  • Improved decision making

Context Layers​

1. Issue Context​

Every agent receives comprehensive issue information from Linear:

  • Title and description
  • Acceptance criteria
  • Comments and discussion
  • State and priority

2. Codebase Context​

Agents understand the project structure:

  • Language and framework conventions
  • Relevant file paths
  • Architecture patterns
  • Testing approach

3. Progress Context​

GOBLIN_NOTES.md tracks progress across sessions:

  • Current objective
  • Completed steps
  • Key decisions
  • Files changed
  • Handoff context

Linear Updates​

Stage Completion​

Posted when each stage completes:

🔨 **BUILD Complete**

✅ Created auth module with JWT validation
✅ Added authentication middleware
✅ Implemented login/logout endpoints

_Completed in 15 minutes_

Blocker Notifications​

Posted immediately when questions arise, tagging relevant users:

🚨 **BUILD Needs Input** @john @sarah

**Question:**
Should we support refresh tokens, or is 24-hour expiration sufficient?

**Context:**
Implementing auth flow, need to decide token strategy.

_Please respond in this ticket._

Configuration​

# Stage completion updates (default: true)
goblin pipeline config -p PROJECT --config linear_stage_updates_enabled=true

# Tag users on blockers (default: true)
goblin pipeline config -p PROJECT --config linear_blocker_tagging=true

Best Practices​

Rich Issue Descriptions​

Write detailed issue descriptions with:

  • Clear problem statement
  • Acceptance criteria
  • Technical constraints
  • Related context

Meaningful Comments​

Add context via Linear comments:

  • Design decisions
  • Implementation hints
  • Links to relevant docs

Review Progress​

Check GOBLIN_NOTES.md to understand:

  • What's been done
  • What decisions were made
  • What's remaining