diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..0008941
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,142 @@
+# gocron: Go Job Scheduling Library
+
+Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
+
+## Working Effectively
+
+### Bootstrap and Build Commands
+- Install dependencies: `go mod tidy`
+- Build the library: `go build -v ./...`
+- Install required tools:
+  - `go install go.uber.org/mock/mockgen@latest` 
+  - `export PATH=$PATH:$(go env GOPATH)/bin` (add to shell profile)
+- Generate mocks: `make mocks`
+- Format code: `make fmt`
+
+### Testing Commands  
+- Run all tests: `make test` -- takes 50 seconds. NEVER CANCEL. Set timeout to 90+ seconds.
+- Run CI tests: `make test_ci` -- takes 50 seconds. NEVER CANCEL. Set timeout to 90+ seconds.
+- Run with coverage: `make test_coverage` -- takes 50 seconds. NEVER CANCEL. Set timeout to 90+ seconds.
+- Run specific tests: `go test -v -race -count=1 ./...`
+
+### Linting Commands
+- Format verification: `grep "^func [a-zA-Z]" example_test.go | sort -c`
+- Full linting: `make lint` -- MAY FAIL due to golangci-lint config compatibility issues. This is a known issue.
+- Alternative basic linting: `go vet ./...` and `gofmt -d .`
+
+## Validation
+
+### Required Validation Steps
+- ALWAYS run `make test` before submitting changes. Tests must pass.
+- ALWAYS run `make fmt` to ensure proper formatting.
+- ALWAYS run `make mocks` if you change interface definitions.
+- ALWAYS verify examples still work by running them: `cd examples/elector && go run main.go`
+
+### Manual Testing Scenarios
+Since this is a library, not an application, testing involves:
+1. **Basic Scheduler Creation**: Verify you can create a scheduler with `gocron.NewScheduler()`
+2. **Job Creation**: Verify you can create jobs with various `JobDefinition` types
+3. **Scheduler Lifecycle**: Verify Start() and Shutdown() work correctly
+4. **Example Validation**: Run examples in `examples/` directory to ensure functionality
+
+Example validation script:
+```go
+package main
+import (
+    "fmt"
+    "time"
+    "github.com/go-co-op/gocron/v2"
+)
+func main() {
+    s, err := gocron.NewScheduler()
+    if err != nil { panic(err) }
+    j, err := s.NewJob(
+        gocron.DurationJob(2*time.Second),
+        gocron.NewTask(func() { fmt.Println("Working!") }),
+    )
+    if err != nil { panic(err) }
+    fmt.Printf("Job ID: %s\n", j.ID())
+    s.Start()
+    time.Sleep(6 * time.Second)
+    s.Shutdown()
+}
+```
+
+### CI Requirements
+The CI will fail if:
+- Tests don't pass (`make test_ci`)
+- Function order in `example_test.go` is incorrect
+- golangci-lint finds issues (though config compatibility varies)
+
+## Common Tasks
+
+### Repository Structure
+```
+.
+├── README.md              # Main documentation
+├── CONTRIBUTING.md        # Contribution guidelines  
+├── SECURITY.md           # Security policy
+├── Makefile              # Build automation
+├── go.mod               # Go module definition
+├── .github/             # GitHub workflows and configs
+├── .golangci.yaml       # Linting configuration
+├── examples/            # Usage examples
+│   └── elector/         # Distributed elector example
+├── mocks/               # Generated mock files
+├── *.go                # Library source files
+└── *_test.go           # Test files
+```
+
+### Key Source Files
+- `scheduler.go` - Main scheduler implementation
+- `job.go` - Job definitions and scheduling logic
+- `executor.go` - Job execution engine
+- `logger.go` - Logging interfaces and implementations  
+- `distributed.go` - Distributed scheduling support
+- `monitor.go` - Job monitoring interfaces
+- `util.go` - Utility functions
+- `errors.go` - Error definitions
+
+### Dependencies and Versions
+- Requires Go 1.23.0+
+- Key dependencies automatically managed via `go mod`:
+  - `github.com/google/uuid` - UUID generation
+  - `github.com/jonboulle/clockwork` - Time mocking for tests
+  - `github.com/robfig/cron/v3` - Cron expression parsing
+  - `github.com/stretchr/testify` - Testing utilities
+  - `go.uber.org/goleak` - Goroutine leak detection
+
+### Testing Patterns
+- Uses table-driven tests following Go best practices
+- Extensive use of goroutine leak detection (may be skipped in CI via TEST_ENV)
+- Mock-based testing for interfaces
+- Race condition detection enabled (`-race` flag)
+- 93.8% test coverage expected
+
+### Build and Release
+- No application to build - this is a library
+- Version managed via Git tags (v2.x.x)
+- Distribution via Go module system
+- CI tests on Go 1.23 and 1.24
+
+## Troubleshooting
+
+### Common Issues
+1. **mockgen not found**: Install with `go install go.uber.org/mock/mockgen@latest`
+2. **golangci-lint config errors**: Known compatibility issue - use `go vet` instead
+3. **Test timeouts**: Tests can take 50+ seconds, always set adequate timeouts
+4. **PATH issues**: Ensure `$(go env GOPATH)/bin` is in PATH
+5. **Import errors in examples**: Run `go mod tidy` to resolve dependencies
+
+### Expected Timings
+- `make test`: ~50 seconds
+- `make test_coverage`: ~50 seconds  
+- `make test_ci`: ~50 seconds
+- `go build`: ~5 seconds
+- `make mocks`: ~2 seconds
+- `make fmt`: <1 second
+
+### Known Limitations
+- golangci-lint configuration may have compatibility issues with certain versions
+- Some tests are skipped in CI environments (controlled by TEST_ENV variable)
+- Examples directory has no tests but should be manually validated
\ No newline at end of file