Skip to main content

GOBLIN_NOTES.md

GOBLIN_NOTES.md is a structured progress file maintained by agents for context continuity.

Purpose​

  • Track progress across sessions
  • Enable handoffs between agents
  • Document key decisions
  • Provide context for recovery

Location​

worktrees/{ISSUE_ID}/.goblin/GOBLIN_NOTES.md

Structure​

# GOBLIN_NOTES
Issue: {ISSUE_ID}
Stage: {STAGE}
Last Updated: {TIMESTAMP}

## Current Objective
{What we're trying to accomplish}

## Progress Log
- [x] Completed: {step description}
- [x] Completed: {step description}
- [ ] In Progress: {current step}
- [ ] Pending: {next step}

## Key Decisions
- {Decision}: {Reason}
- {Decision}: {Reason}

## Files Changed
- `path/to/file.py` - {description}
- `path/to/other.py` - {description}

## Context for Next Session
{Compact summary for handoff - what the next agent needs to know}

Example​

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

## Current Objective
Implement JWT-based user authentication

## Progress Log
- [x] Completed: Created auth module with token validation
- [x] Completed: Added authentication middleware
- [x] Completed: Implemented login endpoint
- [ ] In Progress: Adding password reset flow
- [ ] Pending: Write unit tests

## Key Decisions
- JWT over sessions: Stateless authentication for horizontal scaling
- 24-hour expiration: Balance security and UX
- Refresh tokens: Deferred to v2

## Files Changed
- `src/auth/jwt.py` - JWT token handling
- `src/auth/middleware.py` - Auth middleware
- `src/routes/auth.py` - Login/logout endpoints

## Context for Next Session
Core auth flow is complete. Login/logout working. Need to:
1. Implement password reset (email flow)
2. Add unit tests for token validation
3. Integration tests for auth middleware

Usage by Agents​

Initialization (Start of Stage)​

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

## Current Objective
Implement user authentication based on scope plan

## Progress Log
- [ ] Pending: Create auth module
- [ ] Pending: Add middleware
- [ ] Pending: Write tests

## Key Decisions
(None yet)

## Files Changed
(None yet)

## Context for Next Session
Starting BUILD stage. Following scope plan.

During Work​

Agents update as they progress:

## Progress Log
- [x] Completed: Created auth module
- [ ] In Progress: Adding middleware

Completion​

Before signaling completion:

## Context for Next Session
BUILD complete. All code implemented:
- Auth module with JWT
- Middleware for protected routes
- Login/logout endpoints

Ready for REVIEW. No open questions.

Reading GOBLIN_NOTES​

Agents should read notes at session start:

cat .goblin/GOBLIN_NOTES.md

This provides:

  • Current state
  • What's been done
  • What needs doing
  • Key decisions made

Limits​

  • Completed Steps: Limited to last 5 entries
  • Files Changed: Limited to last 10 files
  • Key Decisions: Limited to last 5 decisions

Older entries are summarized in "Context for Next Session".

NotesManager API​

from goblin.core.notes import NotesManager

# Read notes
notes = NotesManager.read(worktree_path)

# Update notes
notes.current_objective = "Implement password reset"
notes.add_completed_step("Created auth module")
notes.add_decision("Using JWT", "Stateless auth")
notes.add_file_changed("src/auth.py", "JWT handling")

# Write notes
NotesManager.write(worktree_path, notes)