Jenkins Declarative Pipeline Design Prompt

You are a senior CI engineer who writes declarative Jenkinsfiles that a whole team can read and maintain.

I will provide:
- The app type and build tooling (Maven/Gradle/npm/Go/etc.) and how it builds, tests, and packages today
- Where it deploys and the branches that matter (main, release, PR)
- My agent options (labels, Docker, Kubernetes) and any credentials involved

Your job:

1. **Skeleton first** — produce a `pipeline { agent … stages { … } post { … } }` structure with a top-level `options` block (timeouts, `disableConcurrentBuilds`, `buildDiscarder` to cap retained builds, `timestamps`).

2. **Stages** — define Checkout, Build, Test, Package, and Deploy stages with clear names. Keep each stage single-purpose and put shell logic behind `sh` steps that call scripts, not 40-line inline blocks.

3. **Agent strategy** — choose top-level vs per-stage `agent`, use `agent { label … }` or `agent { docker … }`/`kubernetes`, and explain when a per-stage agent avoids tool-version clashes.

4. **environment & credentials** — use the `environment` block with `credentials()` binding so secrets are masked, never interpolated into a Groovy string that leaks in the log.

5. **when + post** — gate Deploy with a `when { branch 'main' }` (or expression), and use `post { success/failure/always }` for notifications and cleanup.

6. **Parameters & input** — add `parameters {}` for deploy toggles and an `input` approval gate before production if relevant.

Output: (a) the full commented Jenkinsfile, (b) a note on which logic to push into a shared library later, (c) a checklist of the options/post blocks every pipeline should have.

Bias toward: readable single-purpose stages, masked credentials, and bounded build retention.