feat: migrate commands to skills + background job system

[ojowwalker77]

Summary

• Commands to Skills Migration - All 10 Matrix commands now use the new skills format with hot-reload support
• Background Job System - Async operations with job polling to avoid timeouts
• once:true Hook Support - One-time hook execution tracking

Changes

Skills Migration

• Migrated all commands from commands/ to skills/*/SKILL.md format
• Added model delegation (agent: haiku for simple ops)
• Added context isolation (context: fork for review/deep-research)
• Added explicit allowed-tools permissions

Background Job System

• New matrix_job_status, matrix_job_cancel, matrix_job_list MCP tools
• matrix_reindex now supports async: true for background execution
• Job progress tracking in SQLite

One-Time Hooks

• hasRunThisSession() / markAsRun() helpers for hooks that should run once per session
• Database-backed tracking with auto-cleanup

Test Plan

• Build passes
• All 66 tests pass
• Verify skills load correctly
• Test async reindex with job polling

[greptile-apps]

Greptile Summary

This PR successfully migrates all commands to the new skills format and introduces a robust background job system with one-time hook execution support.

Key Changes:

• Background job system enables async operations (e.g., matrix_reindex with async: true) to avoid MCP timeouts
• New MCP tools (matrix_job_status, matrix_job_cancel, matrix_job_list) for job management with polling-based progress tracking
• One-time hook execution tracking via hasRunThisSession() and markAsRun() helpers, database-backed with automatic cleanup
• Database schema expanded with background_jobs and hook_executions tables, properly indexed
• All changes maintain backward compatibility

Implementation Quality:
The job management system is well-architected with clear separation between manager (state tracking), workers (business logic), and spawner (process management). Error handling is generally solid, with proper job state transitions and cleanup mechanisms. The one-time hook system is simple and effective with appropriate silent error handling.

Minor Concerns:

• Worker script errors may leave jobs stuck in queued state if the worker crashes before updating job status
• Detached background processes lack PID tracking for cleanup of orphaned processes on server restart

Confidence Score: 4/5

• This PR is safe to merge with minor improvements recommended
• Score reflects solid implementation with proper database schema, error handling, and backward compatibility. Two minor issues identified (worker error handling and orphaned process tracking) are edge cases that don't affect core functionality but should be addressed for production robustness.
• src/jobs/worker-entry.ts needs improved error handling to prevent stuck jobs

Important Files Changed

Filename	Overview
src/jobs/workers.ts	New background job worker implementation for async reindexing with progress tracking. Minor concern: spawned processes are detached without monitoring for orphaned processes.
src/jobs/manager.ts	Solid job management system with proper state tracking, timestamps, and cleanup functionality. Well-structured with clear separation of concerns.
src/jobs/worker-entry.ts	Simple worker entry point for background jobs. Minor issue: error handling doesn't update job status on worker script errors.
src/db/schema.ts	Added two new tables (hook_executions, background_jobs) with proper constraints, indexes, and foreign keys. Schema changes are backward compatible.

Sequence Diagram

sequenceDiagram
    participant User
    participant MCP as MCP Server
    participant Handler as handlers.ts
    participant Manager as Job Manager
    participant Spawner as workers.ts
    participant Worker as worker-entry.ts
    participant Indexer as indexRepository

    User->>MCP: matrix_reindex(async: true)
    MCP->>Handler: handleToolCall('matrix_reindex')
    Handler->>Manager: createJob('matrix_reindex', input)
    Manager->>Manager: generateJobId()
    Manager->>Manager: INSERT INTO background_jobs
    Manager-->>Handler: jobId
    Handler->>Spawner: spawnBackgroundJob('reindex', jobId, input)
    Spawner->>Worker: Bun.spawn([bun, run, worker-entry.ts])
    Note over Spawner,Worker: Detached process
    Handler-->>User: {jobId, status: 'queued', message}
    
    Worker->>Worker: Parse args (workerName, jobId, input)
    Worker->>Manager: updateJob(jobId, {status: 'running'})
    Worker->>Indexer: runReindexJob(jobId, input)
    
    loop Progress Updates
        Indexer->>Manager: updateJob(jobId, {progressPercent, progressMessage})
    end
    
    Indexer-->>Worker: result
    Worker->>Manager: updateJob(jobId, {status: 'completed', result})
    Worker->>Worker: process.exit(0)
    
    User->>MCP: matrix_job_status(jobId)
    MCP->>Handler: handleToolCall('matrix_job_status')
    Handler->>Manager: getJob(jobId)
    Manager->>Manager: SELECT FROM background_jobs
    Manager-->>Handler: job data
    Handler-->>User: {status, progress, result}

Loading

[greptile-apps]

_{12 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

style: Consider storing the process PID in the background_jobs table to enable cleanup of orphaned processes on restart. Detached processes without tracking could leak if the parent crashes. Have you considered storing the PID for cleanup of orphaned processes on restart?

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/jobs/workers.ts
Line: 112:116

Comment:
**style:** Consider storing the process PID in the `background_jobs` table to enable cleanup of orphaned processes on restart. Detached processes without tracking could leak if the parent crashes. Have you considered storing the PID for cleanup of orphaned processes on restart?

How can I resolve this? If you propose a fix, please make it concise.