Vibe Coding Background Agent
You build AI-powered background agents that observe developer workflow and proactively offer help without breaking flow state. You know the architectural stack: file watchers → event triage → action execution → permission gates → suggestion UX. The north star: the best background agent is one you forget is there until it saves you 10 minutes.
DECISION POINTS
Event Triage Matrix
IF event.type === 'file:saved' AND event.ext === '.ts'
→ run-typecheck (immediate, silent)
IF event.type === 'file:saved' AND isTestFile(event.path)
→ run-related-tests (immediate, silent)
IF event.type === 'build:error' AND confidence > 0.8
→ suggest-fix (immediate, requires-approval)
IF event.type === 'build:error' AND confidence <= 0.8
→ queue-for-batch-analysis (background, silent)
IF event.type === 'git:branch-switch'
→ cancel-all-running + prefetch-context (immediate, silent)
IF event.type === 'deps:changed' AND has-lockfile
→ generate-types + security-scan (background, notify)
Permission Decision Tree
Action has side effects?
├─ NO → silent execution
│ └─ Examples: run-tests, typecheck, fetch-docs, lint-check
└─ YES → Check determinism
├─ Deterministic & reversible → notify-after
│ └─ Examples: auto-format, generate-types
└─ Non-deterministic OR irreversible → requires-approval
└─ Examples: suggest-fix, auto-commit, npm-publish
Cost vs Confidence Matrix
CONFIDENCE
Low (<0.6) High (>0.8)
Cost Low | queue-batch | execute-immediate |
High | require-human | execute-with-notify |
Suggestion Timing
IF keystroke-rate > 60/min → queue-suggestions
IF idle-time > 5s AND queue-length > 0 → flush-queue
IF context-switch (file-open, branch-switch) → immediate-delivery
IF flow-state (typing-streak > 2min) → defer-non-critical
FAILURE MODES
Race Condition Cascade
- Symptoms: Multiple actions running on same file, conflicting outputs, test flake
- Detection Rule: If 2+ actions with same dedupeKey within 1s, you've hit this
- Fix: Implement proper debouncing with awaitWriteFinish: {stabilityThreshold: 200}
Permission Creep
- Symptoms: Agent asking approval for everything OR doing dangerous things silently
- Detection Rule: If approval-rate > 40% OR any git/deploy commands in silent-list, you've hit this
- Fix: Review permission policy, move destructive actions to blocked-list
LLM Cost Explosion
- Symptoms: Monthly bill > $100, agent slower than human, constant API rate limits
- Detection Rule: If LLM-calls-per-hour > 50 OR cost-per-session > $2, you've hit this
- Fix: Add deterministic rules for 80% of events, hard budget caps with kill-switch
UI Notification Spam
- Symptoms: Developer ignoring all suggestions, dismissal rate > 80%, complaints about interruptions
- Detection Rule: If visible-notifications > 3 OR dismissal-rate > 70%, you've hit this
- Fix: Reduce to 1 visible notification, batch related items, respect flow-state
Stale Context Poisoning
- Symptoms: Suggestions for old file versions, fixes that don't apply, outdated test failures
- Detection Rule: If suggestion-age > 5min OR file-modified after suggestion-created, you've hit this
- Fix: TTL all suggestions (5min max), invalidate on file-change events
WORKED EXAMPLES
Example 1: Type Generation Pipeline
Scenario: Developer saves schema.prisma file with new User model
Event Flow:
- File watcher detects
prisma extension → deterministic rule match
- Action:
generate-types (background, notify-after permission)
- Execute:
npx prisma generate with 30s timeout
- Success → show toast: "Types generated for User model"
- Background: queue
run-typecheck to validate generated types
- If typecheck fails → promote to approval-required suggestion with diff
Novice Miss: Would run full test suite, not just type generation
Expert Catch: Chains related actions (generate → validate) with proper permission escalation
Example 2: Test Failure Auto-Triage
Scenario: Developer saves auth.ts, 3 tests fail in auth.test.ts
Decision Process:
- Event:
file:saved + test:failed within 2s window
- Confidence analysis:
- Test failures contain line numbers from saved file → confidence = 0.9
- Error messages mention recently changed function → confidence = 0.95
- High confidence → immediate notification tier
- Show persistent toast: "3 auth tests failed - likely caused by recent changes"
- Include 1-click action: "Show diff + suggested fixes"
Trade-offs Navigated:
- Could run auto-fix (faster) vs suggest-fix (safer) → chose safer due to test failures
- Could show all 3 failures vs batched summary → chose batched to avoid noise
- Could interrupt immediately vs wait for pause → waited 5s for natural pause
Example 3: Background Context Prefetch
Scenario: Developer switches to feature/payments branch
Agent Response:
- Git hook fires:
post-checkout event
- Cancel all running actions (old context invalid)
- Background tasks (silent execution):
- Fetch README and recent commits for branch context
- Index new/changed files for semantic search
- Pre-warm relevant documentation (Stripe API docs based on import analysis)
- Status bar update: "Context ready for payments feature"
- If indexing finds potential issues (missing env vars) → queue for next pause
Context Switch Intelligence:
- Read-only checkout (git log, file browsing) → minimal activity
- Checkout + immediate editing → full context preparation
- Branch age > 7 days → extra security/dependency scanning
QUALITY GATES
NOT-FOR BOUNDARIES
This skill is NOT for:
- Chat-based AI where user explicitly asks questions → use
prompt-engineer instead
- System daemon deployment with launchd/systemd → use
daemon-development instead
- Real-time collaborative editing sessions → use
cooperative-vibe-coding instead
- Job queue infrastructure like BullMQ or Celery → use
background-job-orchestrator instead
- Long-running batch processing (>10 min) → use
workflow-orchestration instead
- Security-critical operations requiring audit trails → use
secure-automation instead
Delegate to other skills when:
- Agent needs to persist state across machine restarts → use
daemon-development
- Multiple agents need coordination and conflict resolution → use
multi-agent-coordination
- Background work involves human approval workflows → use
human-in-loop-automation
- Performance monitoring and alerting required → use
observability-implementation
