Real-World Use Cases

See how teams use ULPI Hooks to coordinate agents, prevent conflicts, and preserve context

Real-World Use Cases for ULPI Hooks

Theory is great. Real-world results are better.

This guide shows how actual development teams use ULPI Hooks to solve coordination problems, eliminate merge conflicts, and preserve critical context.

Each use case includes: the problem, the solution using hooks, and measurable results.

---

Use Case 1: Multi-Agent Development Team

The Problem

Team Setup:

• 3 developers (Alice, Bob, Charlie)
• All using AI coding assistants (Claude Code, Cursor, Windsurf)
• Working on same repository simultaneously
• Microservices architecture with shared code

Pain Points Before Hooks:

• 15-20 merge conflicts per week
• 3-4 hours weekly spent resolving conflicts
• Duplicate work (two people implementing same feature)
• Communication overhead (constant “are you editing X?” messages)
• Frustration and context switching

---

The Solution with Hooks

session-start Hook: Team Awareness

Every morning when team members start their AI sessions:

╔══════════════════════════════════════════════════════╗
║  🤖 ULPI Coordination Dashboard                      ║
╠══════════════════════════════════════════════════════╣
║  📬 Messages: 2 unread (1 from Alice)                ║
║                                                      ║
║  👥 Online Agents:                                   ║
║  ├─ Alice (Cursor) - working on auth module         ║
║  ├─ Bob (Claude Code) - refactoring API endpoints   ║
║  └─ You (Windsurf) - just joined                    ║
║                                                      ║
║  🔒 Active Reservations:                             ║
║  ├─ src/auth/login.ts (Alice, exclusive, 1h left)   ║
║  ├─ src/api/routes.ts (Bob, shared, 2h left)        ║
║  └─ database/migrations/007.sql (Alice, exclusive)   ║
╚══════════════════════════════════════════════════════╝

Benefit: Instant visibility into who’s working on what

---

pre-edit Hook: Automatic Conflict Prevention

Scenario: Charlie tries to edit src/auth/login.ts while Alice is working on it

Without hooks:

• Charlie edits the file
• Alice also edits the file
• Both commit locally
• Merge conflict when syncing
• 15 minutes lost to resolution

With hooks:

⛔ Edit Blocked - File Reserved

File: src/auth/login.ts
Reserved by: Alice (Cursor)
Mode: Exclusive
Expires: 1 hour 15 minutes

Alice is implementing OAuth login. Estimated completion: 1.5 hours

Coordination Options:
1. [Message Alice] - "When will you be done?"
2. [Check her progress] - View Alice's commits
3. [Work on related file] - auth/middleware.ts available
4. [Set reminder] - Notify when file is available

[Choose Option]

Charlie chooses option 1 (Message Alice):

📨 Message to Alice

Charlie: "Hey Alice, I need to add rate limiting to the login function.
         When will you be done with login.ts?"

Alice: "I'm adding OAuth, should be done in 30 min. But rate limiting
        can go in middleware/rateLimiter.ts and I'll call it from login.
        Want to pair on the integration?"

Charlie: "Perfect! I'll build the middleware now."

Result:

• Zero conflict
• Better architecture (middleware separation)
• Collaboration opportunity
• Both make progress

---

Results After 3 Months

Merge Conflicts

Before: 15-20/week After: 0-1/week (99% reduction)

The 1 remaining conflict was a force override for emergency hotfix

Time Saved

Before: 3-4 hours/week resolving conflicts After: 0 hours (15 minutes monthly)

Annual savings: 150 hours per developer

Communication

Before: Constant “are you editing X?” Slack messages After: Coordination through ULPI messaging

Benefit: Async, contextual, automated

Team Morale

Before: Frustration with conflicts After: “We never think about conflicts anymore”

Quote: “Hooks just work. We forget they’re there.” — Alice

---

Use Case 2: Parallel Task Execution with Subagents

The Problem

Scenario:

• Main agent orchestrating a large refactor
• Needs to update 20 files across 5 modules
• Sequential execution would take 6 hours
• Want to parallelize using subagents

Challenges:

• Subagents might edit same files (conflicts)
• Main agent loses subagent learnings after they stop
• No visibility into subagent progress
• File locks orphaned if subagent crashes

---

The Solution with Hooks

Task Orchestration with Hooks

Main agent spawns 5 subagents:

// Main agent distributes work
const tasks = [
  { subagent: 1, files: ['auth/login.ts', 'auth/logout.ts'] },
  { subagent: 2, files: ['api/users.ts', 'api/posts.ts'] },
  { subagent: 3, files: ['database/schema.ts', 'database/migrations/008.sql'] },
  { subagent: 4, files: ['tests/auth.test.ts', 'tests/api.test.ts'] },
  { subagent: 5, files: ['docs/api.md', 'docs/auth.md'] },
];

// Each subagent claims its files via pre-edit hooks

---

pre-edit Hook: File Claiming

Subagent 1 starts editing auth/login.ts:

🎣 Pre-Edit Hook (Subagent-1)

File: auth/login.ts
Action: Reserve (exclusive mode for subagent)

✓ File reserved successfully
Reservation ID: res_sub1_abc123

Subagent 2 starts editing api/users.ts:

✓ File reserved (no conflict with Subagent 1)

No subagent can edit another’s claimed files.

---

subagent-stop Hook: Learning Consolidation

Subagent 1 completes its task:

🎣 Subagent-Stop Hook Fired

Subagent: Subagent-1
Task: Refactor auth module
Duration: 18 minutes
Files edited: 2 (login.ts, logout.ts)

Consolidating learnings to shared memory:
✓ Stored: OAuth implementation pattern (salience: 0.85)
✓ Stored: Error handling approach (salience: 0.80)
✓ Stored: JWT token validation logic (salience: 0.75)

Releasing file reservations:
✓ Released: auth/login.ts
✓ Released: auth/logout.ts

Reporting to Main Agent:
✓ Task completed
✓ 2 files refactored
✓ 12 tests passing

Main agent receives:

📊 Subagent-1 Report

Status: Completed
Files: 2/2 ✓
Tests: 12/12 passing ✓
Learnings: 3 patterns stored to memory

Available for Main Agent to review and other subagents to use.

---

session-start Hook: Cross-Subagent Learning

Subagent 4 (working on tests) starts and loads memories from Subagent 1:

🚀 Subagent-4 Session Start

🧠 Loading relevant memories from other subagents:
✓ Loaded: OAuth implementation pattern (from Subagent-1)
✓ Loaded: Error handling approach (from Subagent-1)

Subagent-4 can now write tests that match the patterns used
in the auth refactor, even though it didn't do that work.

---

Results

Performance

Sequential execution (without subagents):

• 20 files × 18 minutes/file = 6 hours

Parallel with subagents (without hooks):

• 5 subagents × 1.2 hours = 1.2 hours + 45 min conflict resolution = 2 hours

Parallel with hooks:

• 5 subagents × 1.2 hours = 1.2 hours (zero conflicts)

Speedup: 5x faster than sequential, 40% faster than unhook parallel

---

Use Case 3: Context Preservation for Long Projects

The Problem

Scenario:

• 6-month project building a new platform
• Multiple AI sessions over months
• Critical architecture decisions made early on
• New features added monthly

Challenges:

• Context compacted every few hours
• Architecture decisions forgotten
• New AI sessions start from scratch
• Re-explaining project context daily

Time waste:

• 15 minutes/session re-explaining context
• 3 sessions/day = 45 minutes daily
• 225 minutes/week = 3.75 hours weekly

---

The Solution with Hooks

Month 1: Architecture Planning

Conversation with Claude:

User: "We're building a social platform. PostgreSQL or MongoDB?"

Claude: "For your use case, PostgreSQL because:
1. Strong relationships (users, posts, comments)
2. ACID compliance for financial data (premium subscriptions)
3. Full-text search built-in
4. Your team knows SQL"

User: "Agreed. This is critical for the whole project architecture."

Pre-compact hook fires (context approaching limit):

💾 Saving Architecture Decision

Content: "PostgreSQL chosen over MongoDB for social platform.
         Rationale: Relational data model, ACID compliance for
         payments, full-text search, team expertise."
Type: architecture_decision
Importance: 0.98
Tags: ["database", "architecture", "postgresql"]

✓ Stored to memory

---

Month 2: New Feature (Payments)

New AI session starts:

🧠 Loading Relevant Memories

Project: social-platform
Loading high-importance memories...

✓ Loaded 23 architecture decisions
✓ Loaded 15 code conventions
✓ Loaded 8 key insights

Including:
- PostgreSQL database choice and rationale
- Microservices architecture decisions
- API design patterns
- ...

Conversation:

User: "We're adding payments. What database should we use?"

Claude: "Based on our architecture decision from Month 1, we're using
        PostgreSQL for the whole platform. For payments specifically,
        PostgreSQL is ideal because we need ACID compliance for
        transactions.

        I recommend:
        - payments table in main PostgreSQL database
        - Use transactions for payment operations
        - Leverage PostgreSQL's ACID guarantees"

User: "Perfect!" [Claude remembered without re-explanation]

Time saved: 15 minutes (didn’t re-explain DB choice)

---

Month 4: New Team Member

New developer (David) joins:

# David searches project memories
ulpi memory search --project social-platform --limit 50

# Results:

📚 Project Memory Archive

Architecture Decisions (12):
1. PostgreSQL database (importance: 0.98, month 1)
   Rationale: Relational model, ACID, full-text search
2. Microservices architecture (importance: 0.95, month 1)
   Rationale: Team size, scalability, deployment flexibility
3. REST over GraphQL (importance: 0.90, month 2)
   Rationale: Simpler, team familiarity, caching
...

Code Conventions (15):
1. Error handling pattern (importance: 0.85)
2. API response format (importance: 0.80)
3. Testing strategy (importance: 0.85)
...

Key Insights (24):
1. N+1 query optimization pattern (importance: 0.75)
2. Caching strategy for user feeds (importance: 0.80)
...

David’s onboarding:

• Before hooks: 2 weeks to understand architecture
• With hooks: 3 days (reads memory archive, asks clarifying questions)

---

Results After 6 Months

Context Re-Explanation Time

Before: 3.75 hours/week After: 0 hours

Total saved: 90 hours over 6 months

Architecture Consistency

Before: Decisions forgotten, inconsistent approaches After: 100% consistency with original architecture

New features align with month 1 decisions

Onboarding Speed

Before: 2 weeks for new developers After: 3 days

Memory archive serves as living documentation

Knowledge Retention

Before: 40% of decisions remembered after compaction After: 100% of important decisions preserved

Nothing lost to context compaction

---

Use Case 4: Emergency Code Freeze

The Problem

Scenario:

• Friday 4 PM: Security vulnerability discovered in production
• Need immediate code freeze (no deploys until patched)
• 5 developers actively working with AI assistants
• Need to alert all agents instantly

Challenges:

• Agents don’t know about security issue
• Might deploy vulnerable code
• Need instant coordination across all agents

---

The Solution with Hooks

1. Send Urgent Message to All Agents

# Security team sends urgent broadcast
ulpi coordination broadcast \
  --priority urgent \
  --subject "SECURITY: Code freeze - SQL injection vulnerability" \
  --body "Critical SQL injection found in user auth. CODE FREEZE until patched. Do not deploy. Do not modify auth module." \
  --all-agents

---

2. user-prompt-submit Hook Alerts

Every agent sees alert before next response:

Alice (Cursor):

🚨 URGENT COORDINATION MESSAGE

From: Security Team
Priority: CRITICAL
Subject: Code freeze - SQL injection vulnerability

Critical SQL injection found in user auth.

⛔ CODE FREEZE:
- Do not deploy any code
- Do not modify auth module
- Wait for security patch

[Acknowledge] [View Details]

Alice clicks [Acknowledge] → Can continue non-auth work

---

Bob (Claude Code):

Bob is about to modify auth/login.ts when:

🚨 URGENT MESSAGE + PRE-EDIT HOOK BLOCK

⛔ Edit Blocked

File: auth/login.ts
Reason: Emergency code freeze (security issue)

You have unacknowledged urgent message about this file.
You must acknowledge before editing auth-related files.

[View Urgent Message] [Acknowledge]

Bob views message → Understands → Works on different module

---

3. Pre-Edit Hook: Enforce Freeze

Configuration update (instant):

# Security team adds auth module to blocked files
ulpi coordination block-files \
  --pattern "src/auth/**" \
  --reason "Emergency security patch in progress" \
  --duration 2h

Now pre-edit hooks block ALL auth file edits:

⛔ Edit Blocked - Emergency Freeze

File: src/auth/middleware.ts
Reason: Emergency security patch in progress
Duration: 1 hour 45 minutes remaining

Security team is patching SQL injection vulnerability.
Auth module is frozen until patch is deployed.

[Contact Security Team] [View Details] [OK]

---

Results

Alert Speed

Traditional: Email/Slack (5-30 min to reach everyone) With hooks: Instant (next user prompt)

All 5 agents alerted within 2 minutes

Prevented Deploys

Without hooks: 2 agents deployed vulnerable code With hooks: 0 deploys during freeze

Security maintained

Coordination Time

Traditional: 30 min of Slack messages to coordinate With hooks: 2 minutes (auto-alerts + acknowledgments)

93% faster coordination

Incident Resolution

Total time: 45 minutes (patch + deploy) Zero conflicting changes during freeze

Smooth, coordinated response

---

Use Case 5: Multi-Codebase Development

The Problem

Scenario:

• Microservices architecture (8 services)
• Developer works across multiple repos daily
• Each service has different conventions
• Each repo has different AI context

Challenges:

• Context doesn’t transfer between repos
• Conventions forgotten when switching repos
• Re-explain architecture for each service

---

The Solution with Hooks

session-start Hook: Load Repo-Specific Context

Switch to auth-service repo:

🚀 Session Start: auth-service

🧠 Loading auth-service memories:
✓ Architecture: OAuth 2.0 with JWT tokens
✓ Convention: Winston logger for all errors
✓ Convention: Jest with 80% coverage minimum
✓ Active tasks: Rate limiting implementation (60% done)

Claude now has auth-service context.

15 minutes later, switch to payment-service repo:

🚀 Session Start: payment-service

🧠 Loading payment-service memories:
✓ Architecture: Stripe integration with webhook handling
✓ Convention: Pino logger (different from auth-service!)
✓ Convention: Supertest for API tests
✓ Active tasks: Subscription management (planning phase)

Claude now has payment-service context.

---

Context Isolation

Key benefit: Each repo’s context is separate

User (in payment-service): "Add error logging"

Claude: "I'll use Pino logger as per payment-service conventions:

logger.error({ err, userId }, 'Payment processing failed');
"

Claude used Pino (payment-service convention), not Winston (auth-service convention)

---

Results

Context Switching Time

Before: 10 min/switch (re-explain conventions) After: 0 min (auto-loaded memories)

5 switches/day × 10 min = 50 min saved daily

Convention Consistency

Before: Mixed conventions (used wrong logger in 3 repos) After: 100% consistent with each repo’s standards

No cross-contamination

Task Continuity

Before: Forgot which tasks active in which repo After: Active tasks loaded per repo

Resume exactly where you left off

Cognitive Load

Before: Mental effort to remember each repo’s patterns After: Zero effort (hooks handle it)

Developer focus on actual code, not conventions

---

Use Case 6: Compliance & Audit Trail

The Problem

Scenario:

• Financial services company (regulated industry)
• Must maintain audit trail of all code changes
• Need to prove who changed what and why
• AI-assisted development complicates attribution

Compliance requirements:

• Track every file modification
• Identify human developer and AI assistant used
• Record rationale for changes
• Demonstrate review process

---

The Solution with Hooks

post-edit Hook: Automatic Audit Logging

Every file edit automatically logged:

📝 Audit Log Entry Created

Timestamp: 2024-01-15T14:32:18Z
Developer: [e-mail]
AI Assistant: Claude Code (Claude Sonnet 4.5)
Agent ID: claude-code-alice

File: src/payments/processor.ts
Action: Edit
Lines changed: 45-67 (23 lines)
Diff size: +85, -42

Change summary: "Added fraud detection validation before payment processing"

Compliance metadata:
- Reservation ID: res_abc123
- Code review: Required (2 approvals pending)
- Security scan: Passed
- Test coverage: 92% (above 80% minimum)

✓ Logged to compliance database

---

session-start & session-end Hooks: Session Tracking

Session start:

📊 Session Started

Developer: [e-mail]
Agent: Claude Code
Project: payment-platform
Timestamp: 2024-01-15T09:00:00Z

Compliance requirements active:
✓ SOC 2 Type II
✓ PCI DSS Level 1
✓ GDPR

All actions will be logged for audit.

Session end:

📊 Session Summary

Duration: 3 hours 15 minutes
Files edited: 8
Total changes: +420, -185 lines
Code reviews initiated: 2
Security scans: 8 passed, 0 failed

All actions logged to compliance database.
Audit trail: audit_log_xyz789

---

Results

Audit Compliance

Before: Manual logging (inconsistent, often forgotten) After: 100% automated, complete audit trail

Passed SOC 2 audit with zero findings

Attribution Clarity

Before: Unclear if human or AI made change After: Perfect attribution (human + AI assistant tracked)

Regulators satisfied with transparency

Time Saved

Before: 30 min/day manual audit logging After: 0 min (fully automated)

125 hours saved annually per developer

Security Posture

Before: Some changes untracked (security risk) After: Every change tracked and logged

Zero unauthorized changes

---

Summary: Hooks ROI by Use Case

Use Case	Time Saved	Key Benefit	Difficulty
Multi-Agent Team	3-4 hrs/week	Zero merge conflicts	⭐ Easy
Parallel Subagents	5x speedup	Conflict-free parallelization	⭐⭐ Moderate
Context Preservation	3.75 hrs/week	No re-explanation needed	⭐ Easy
Emergency Freeze	93% faster	Instant team coordination	⭐ Easy
Multi-Codebase	50 min/day	Auto-context switching	⭐ Easy
Compliance	125 hrs/year	Perfect audit trail	⭐⭐⭐ Advanced

---

Next Steps

Getting Started

Install hooks in 5 minutes and start coordinating

File Conflict Prevention

Deep dive into zero-conflict file management

Memory Integration

Learn how to preserve 100% of critical context

Performance Metrics

Understand hook latency and optimization strategies