kevinslin/gen-notifier

Task Completion Notifier

This skill sends desktop notifications using terminal-notifier to alert the user when a job has reached its final terminal state.

When to Use This Skill

Use this skill in the following scenarios:

1. User explicitly requests notification - When the user says "notify me when done", "let me know when this finishes", etc.
2. Long-running tasks - Jobs that take significant time (builds, deployments, large refactors, test suites)
3. Background tasks - When the user might context-switch while waiting
4. Default behavior - By default, assume all jobs assigned to you will require one notification unless the user specifies otherwise

Core Rule

Use this skill only once per job, at the very end, after the work is finalized and immediately before you generate the final user-facing report.

• Do not notify during intermediate steps
• Do not notify when you are still investigating or iterating
• Do not notify before verification, cleanup, or finalization is complete
• If the user explicitly asks for different timing, follow the user's instruction instead

How to Notify

When a job reaches a finalized terminal state (completed, needs_input, or errors), send a notification using:

terminal-notifier -title "{DESCRIPTION OF JOB}" -message "{STATUS_OF_JOB}" -sound default

The -sound default parameter makes a beeping sound to alert the user audibly.

Status Values

Use one of these status values in the message:

• completed - Task finished successfully
• needs_input - Task requires user input to proceed
• errors - Task encountered errors and cannot proceed

Title Format

The title should be a concise description of the job (3-8 words):

Good examples:

• "Build and Test Suite"
• "API Integration Implementation"
• "Database Migration"
• "Code Refactoring Complete"

Bad examples:

• "Task" (too vague)
• "The implementation of the new authentication system with JWT tokens and refresh token rotation" (too long)

Notification Examples

Successful Completion

terminal-notifier -title "API Integration Implementation" -message "completed" -sound default

Needs User Input

terminal-notifier -title "Database Migration Setup" -message "needs_input" -sound default

Encountered Errors

terminal-notifier -title "Build and Test Suite" -message "errors" -sound default

Notification Timing

Send the notification only when both conditions are true:

1. The job is finalized - Implementation, verification, cleanup, and any final checks are done, or you have reached a definitive blocked/error state
2. You are about to report out - The next step is the final user-facing response

Order of operations:

1. Finish the work
2. Verify and finalize the outcome
3. Send exactly one notification
4. Generate the final report to the user

When NOT to Send Notifications

Don't send notifications for:

• Quick tasks (< 30 seconds)
• Intermediate steps of a larger task
• Minor clarifying questions
• Every tool execution
• Tasks where user is actively watching
• Cases where the job is not yet finalized

Best Practices

1. One notification per task - Don't spam multiple notifications
2. Wait until final handoff - Only notify when the job is fully finalized and you are about to produce the final report
3. Be specific in title - User should understand what completed
4. Use appropriate status - Accurately reflect the outcome
5. Default timing can be overridden - If the user explicitly asks for a different moment, follow that instead

Example Workflows

Successful Completion

User: "Implement the new authentication feature and notify me when done"

Assistant steps:

1. Implements authentication feature
2. Adds tests
3. Runs tests (all pass)
4. Finalizes the result and prepares the handoff
5. Sends notification: terminal-notifier -title "Authentication Feature" -message "completed" -sound default
6. Generates the final user-facing report

Needs User Input

User: "Set up the database migration"

Assistant steps:

1. Creates migration files
2. Discovers multiple valid approaches for schema design
3. Determines it cannot proceed without a user decision
4. Finalizes the blocked state and prepares the handoff
5. Sends notification: terminal-notifier -title "Database Migration Setup" -message "needs_input" -sound default
6. Generates the final user-facing report

Encountered Errors

User: "Run the full test suite and notify me"

Assistant steps:

1. Runs test suite
2. Encounters 5 failing tests
3. Attempts to fix but determines the task cannot be completed within scope
4. Finalizes the error state and prepares the handoff
5. Sends notification: terminal-notifier -title "Test Suite Execution" -message "errors" -sound default
6. Generates the final user-facing report

Implementation Notes

Timing

Always send the notification after the job is finalized and immediately before the final user-facing report:

Assistant: I've completed implementing the authentication feature...

[Details of what was done]

[Runs terminal-notifier command]

[Final report to the user]

Error Handling

If terminal-notifier is not installed, gracefully inform the user:

I attempted to send a notification but terminal-notifier is not installed. 
You can install it with: brew install terminal-notifier

Multiple Tasks

For multiple sub-tasks within a larger job, only send ONE notification for the entire job:

❌ Bad - multiple notifications:

- Notification: "User model created"
- Notification: "API endpoint created"  
- Notification: "Tests written"
- Notification: "Authentication complete"

✅ Good - single notification:

- Notification: "Authentication Feature" -message "completed" -sound default

Requirements

This skill requires terminal-notifier to be installed:

brew install terminal-notifier

Check if installed:

which terminal-notifier