Skip to main content

BUILD Stage

The BUILD stage implements the code changes based on the scope plan.

Purpose​

The Builder agent:

  1. Reads the scope plan
  2. Creates an isolated worktree
  3. Implements code changes
  4. Commits incrementally
  5. Creates a draft PR

Process​

┌─────────────────────────────────────────────────────────────┐
│                      BUILD STAGE                             │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   1. Create Worktree                                         │
│      ├─ git worktree add                                     │
│      ├─ Isolated from main repo                              │
│      └─ Branch: {ISSUE_ID}-{title}                          │
│                                                              │
│   2. Read Scope Plan                                         │
│      ├─ Implementation steps                                 │
│      ├─ Files to modify/create                               │
│      └─ Dependencies to add                                  │
│                                                              │
│   3. Implement Code                                          │
│      ├─ Follow implementation steps                          │
│      ├─ Update GOBLIN_NOTES.md                              │
│      └─ Commit after each logical unit                       │
│                                                              │
│   4. Create Draft PR                                         │
│      ├─ Push branch to remote                                │
│      ├─ Create draft PR on GitHub                            │
│      └─ Include PR URL in pipeline                           │
│                                                              │
│   5. Signal Completion                                       │
│      └─ Create .goblin/build-complete                        │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Git Worktree​

Each issue gets an isolated worktree:

worktrees/
└── ENG-123-add-auth/
    ├── .git                   # Worktree git directory
    ├── .goblin/
    │   ├── GOBLIN_NOTES.md   # Progress tracking
    │   └── build-complete     # Signal file (when done)
    └── src/                   # Project files

Benefits​

  • Isolation: No interference between concurrent work
  • Clean Diffs: Compare against known base commit
  • Safe: Main repo stays clean
  • Parallel: Multiple agents work simultaneously

Commit Strategy​

The Builder makes incremental commits:

# One commit per logical unit
git commit -m "feat(auth): Add JWT token validation"
git commit -m "feat(auth): Add authentication middleware"
git commit -m "test(auth): Add unit tests for JWT"

Commit Message Format​

type(scope): description

[optional body]

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Types: feat, fix, refactor, test, docs, chore

Draft PR Creation​

When BUILD starts, Goblin:

  1. Pushes the branch to remote
  2. Creates a draft PR
  3. Stores PR URL in pipeline record
  4. Posts PR link to Linear
## BUILD Started: ENG-123

Branch: `ENG-123-add-auth`
PR: https://github.com/org/repo/pull/123

_Building implementation..._

Progress Tracking​

The Builder maintains GOBLIN_NOTES.md:

# GOBLIN_NOTES
Issue: ENG-123
Stage: BUILD
Last Updated: 2024-01-15T10:30:00Z

## Current Objective
Implement user authentication

## Progress Log
- [x] Created auth module
- [x] Added JWT validation
- [ ] Add password reset

## Key Decisions
- Using JWT over sessions for stateless auth

## Files Changed
- `src/auth.py` - New auth module
- `src/middleware.py` - Added auth middleware

## Context for Next Session
JWT implementation complete. Need password reset flow.

Handling Scope Plan​

The Builder follows the implementation steps:

{
  "implementation_steps": [
    {
      "order": 1,
      "description": "Create auth module",
      "files": ["src/auth.py"]
    },
    {
      "order": 2,
      "description": "Add middleware",
      "files": ["src/middleware.py"]
    }
  ]
}

Review Feedback Loop​

If REVIEW requests changes:

  1. Builder receives feedback
  2. Reads review comments
  3. Implements fixes
  4. Commits changes
  5. Returns to REVIEW

Completion Signal​

When done, the Builder creates:

.goblin/build-complete

Contents (optional):

{
  "commits": 3,
  "files_changed": 5,
  "lines_added": 150,
  "lines_removed": 20
}

Linear Updates​

## BUILD Complete: ENG-123

### Changes
- Created `src/auth.py` - JWT token handling
- Modified `src/middleware.py` - Auth middleware
- Added unit tests

### Stats
- 3 commits
- 5 files changed
- +150 / -20 lines

### PR
https://github.com/org/repo/pull/123

_Proceeding to REVIEW stage_

Next Steps​