opencode-skills-collection 4.0.67 → 4.0.69

package/bundled-skills/resumable-implementation-contracts/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: resumable-implementation-contracts
+description: "Create repository-based execution contracts for multi-session implementation work, with stable task IDs, evidence, checkpoints, and exact resume state."
+category: project-management
+risk: safe
+source: self
+source_type: self
+date_added: "2026-09-19"
+author: ShianMike
+tags: [project-management, execution-contracts, checkpoints, verification, agent-workflows]
+tools: [claude, cursor, gemini, codex, antigravity]
+---
+
+# Resumable Implementation Contracts
+
+## Overview
+
+Turn a large, mostly defined implementation request into a repository contract
+that a fresh agent can read, update, verify, and resume without reconstructing
+the project from chat history. Keep stable intent separate from mutable
+execution state, and require evidence before any task is called complete.
+
+This is a tool-neutral document pattern. It does not depend on, replace, or
+configure any agent platform's built-in goal, task, plan, or project feature.
+
+This skill fills the layer between planning and execution. It does not replace
+product discovery, detailed technical design, project-wide state governance,
+or retrospective auditing.
+
+## When to Use This Skill
+
+Use it when work:
+
+- spans multiple sessions, agents, branches, or context windows;
+- has dependencies or acceptance criteria that must survive interruption;
+- needs an exact resume point rather than a narrative handoff;
+- can appear complete before runtime, artifact, UI, or test evidence exists;
+- must preserve partial work and unrelated repository changes.
+
+Skip it for a small task that can be completed and verified in one session.
+If requirements are still unsettled, resolve them before freezing the
+implementation contract.
+
+## Reuse Existing Project Documents
+
+Inspect the repository before creating files. Reuse equivalent documents and
+the project's established names when their ownership is clear. For substantial
+multi-session work, the minimum logical document set is:
+
+| Document | Owns | Must not become |
+| --- | --- | --- |
+| `IMPLEMENTATION_CONTRACT.md` | stable intent, scope, tasks, acceptance, definition of done | a live activity log |
+| `TASKS.md` | current task/subtask status, dependencies, evidence links | a second copy of the contract |
+| `CHECKPOINT.md` | authoritative current position and exact next action | a vague progress summary |
+| `DECISIONS.md` | material decisions, alternatives, and reasons | a transcript |
+| `VALIDATION.md` | checks actually run, results, evidence, and unresolved gates | a list of planned tests |
+
+These may live together under `docs/<contract-slug>/` or follow an existing
+repo layout. An existing `GOAL.md`, specification, or execution brief may own
+the contract role; do not rename it or create parallel files solely to match
+this skill.
+
+## Define Document Authority
+
+- Current owner instructions and applicable repository instructions govern
+  authorization and scope.
+- `IMPLEMENTATION_CONTRACT.md`, or its existing repository equivalent, owns
+  the implementation contract. Do not silently change it to fit the current
+  code.
+- The working tree, branch, commit, produced artifacts, and executed checks are
+  truth for implementation state.
+- The tracker files summarize that state; they do not override contrary
+  evidence on disk.
+
+When documents and reality disagree, reconcile status from evidence while
+preserving the contract's intent. Escalate any conflict that would materially
+change scope, behavior, or acceptance.
+
+## Write a Self-Contained Contract
+
+A new agent should be able to understand the work from the contract without
+the original conversation. Include only what is needed to execute correctly:
+
+1. objective and observable outcomes;
+2. current baseline and important constraints;
+3. in-scope work, exclusions, and authorization boundaries;
+4. operating rules, including interruption and validation policy;
+5. tasks with stable IDs, dependencies, acceptance, and breakpoints;
+6. final definition of done and handoff requirements.
+
+Use stable task and subtask IDs such as `T03` and `T03.2`. Never renumber them
+after execution starts; add new IDs or mark obsolete work explicitly.
+
+Each task should use this compact form:
+
+```markdown
+### T03 - <observable task outcome>
+
+- [ ] T03.1 <first implementation slice>
+- [ ] T03.2 <second implementation slice>
+
+Dependencies: T01
+
+Acceptance:
+- <observable behavior or artifact>
+- <required focused check and evidence>
+
+Breakpoint:
+- Update TASKS.md, VALIDATION.md, and CHECKPOINT.md after the accepted slice.
+```
+
+Write acceptance in pass/fail terms. File creation, code presence, or an
+agent's completion claim is not acceptance unless that is genuinely the whole
+requirement.
+
+## Read Before Acting
+
+At the start of a session or after interruption, read in this order:
+
+1. applicable repository instructions;
+2. the implementation contract;
+3. `TASKS.md`, `CHECKPOINT.md`, `DECISIONS.md`, and `VALIDATION.md`;
+4. current branch, `HEAD`, status, and relevant diff;
+5. only the code, tests, and artifacts needed for the active task.
+
+Reconcile the checkpoint with the working tree before editing. Preserve partial
+and unrelated changes. Resume the exact unfinished subtask when it is still
+valid; otherwise record why the next action changed.
+
+## Keep Writes Narrow and Durable
+
+- Change the implementation contract only when the owner changes intent or an
+  ambiguity is deliberately resolved.
+- Update `TASKS.md` when work starts, blocks, or becomes evidence-backed done.
+- Replace `CHECKPOINT.md` with the latest authoritative resume state; Git owns
+  its detailed history.
+- Add to `DECISIONS.md` only for choices that constrain later work.
+- Add to `VALIDATION.md` only after a check is actually run or explicitly
+  recorded as not run.
+- Update the checkpoint after a meaningful increment and before stopping.
+
+Do not duplicate the same mutable status across every document. Link to the
+owning record instead.
+
+## Use Evidence-Gated Status
+
+Use a small status vocabulary: `pending`, `in_progress`, `blocked`, and `done`.
+A task may become `done` only when its acceptance criteria have supporting
+evidence.
+
+For each validation record, capture:
+
+- timestamp and relevant commit or working-tree state;
+- exact command or manual procedure;
+- environment when it affects the result;
+- result, including failures and skipped checks;
+- artifact, log, screenshot, route, or report path when applicable;
+- unresolved caveats or gates.
+
+Run the smallest check that proves the current slice during implementation.
+Run broader integration or release suites at defined milestones or when the
+change's risk requires them. Never present a planned, mocked, or nominally
+successful check as observed behavior.
+
+## Make the Checkpoint Executable
+
+`CHECKPOINT.md` must let another agent continue immediately. Record:
+
+```markdown
+# Checkpoint
+
+Updated: <UTC timestamp>
+Branch / HEAD: <branch> / <commit>
+Active task: T03
+Active subtask: T03.2
+Status: in_progress
+
+Completed behavior:
+- <verified result and evidence link>
+
+Work in progress:
+- <files and partial state that must be preserved>
+
+Validation performed:
+- `<exact command>` -> <result>
+
+Blockers or uncertainties:
+- <blocker, owner, and condition for clearing it>
+
+Pre-existing or unrelated changes:
+- <paths or explicit none observed>
+
+Next exact action:
+- <one concrete edit, inspection, or command>
+
+Next verification:
+- <focused check that should follow that action>
+```
+
+Avoid next steps such as "continue implementation" or "finish tests." If the
+next agent must decide what those words mean, the checkpoint is incomplete.
+
+## Execution Loop
+
+1. Select the smallest dependency-ready task.
+2. Mark it `in_progress` and state the intended slice.
+3. Inspect the real path that owns the behavior.
+4. Make the minimum scoped change.
+5. Run focused verification and record the actual outcome.
+6. Update task status only from that evidence.
+7. Refresh the checkpoint with one exact next action.
+8. Repeat until every definition-of-done item is verified or explicitly
+  blocked.
+
+At final handoff, report completed outcomes, evidence, unresolved blockers,
+branch and commit state, and the exact next action if anything remains. Do not
+promote partial task completion into overall contract completion.
+
+## Limitations
+
+- This structure preserves execution state but cannot resolve unclear product
+  intent or choose among materially different outcomes for the owner.
+- Evidence quality depends on running checks that exercise the real behavior;
+  complete-looking documents do not prove implementation correctness.
+- Concurrent writers still need repository-level coordination to avoid
+  conflicting checkpoints and status updates.
+- The five-document layout is unnecessary overhead for small, single-session
+  tasks; reuse fewer existing documents when they provide the same ownership.
+
+## Common Failure Modes
+
+- Rewriting or renumbering task IDs after work has begun.
+- Treating checked boxes as evidence instead of linking the proof.
+- Recording only happy-path checks and losing failed attempts that constrain
+  the next decision.
+- Replaying all history instead of loading the authoritative current state.
+- Allowing implementation discoveries to silently expand the contract.
+- Running an expensive full suite after every small edit while skipping the
+  focused check that would isolate the defect.
+- Persisting credentials, tokens, private data, or sensitive command output in
+  tracking documents.
+
+## Relationship to Other Skills
+
+- Use `spec-driven-loop` when product requirements and technical design still
+  need structured discovery, freezing, and approval.
+- Use `planning-and-task-breakdown` when only an executable plan is needed.
+- Use `project-state-governor` when the need is canonical state across the
+  whole project rather than one scoped implementation effort.
+- Use `audit-agent-run-evidence` for a read-only retrospective audit of an
+  already completed run.
+
+This skill owns the compact execution contract that connects those concerns:
+stable intent, mutable progress, verification evidence, and exact resume state.

package/bundled-skills/reverse-proxy/SKILL.md

@@ -0,0 +1,420 @@
+---
+name: reverse-proxy
+description: Configure nginx and Traefik as reverse proxies. Implement SSL termination
+  and routing. Use when setting up application gateways.
+category: devops
+risk: critical
+source: https://github.com/BagelHole/DevOps-Security-Agent-Skills
+source_repo: BagelHole/DevOps-Security-Agent-Skills
+source_type: community
+date_added: '2026-09-20'
+license: MIT
+license_source: https://github.com/BagelHole/DevOps-Security-Agent-Skills/blob/main/LICENSE
+compatibility: Requires the relevant OS/platform tooling and privileged access where
+  noted. Docs-only; helper scripts and templates not bundled.
+metadata:
+  author: devops-skills
+  version: '1.0'
+---
+
+# Reverse Proxy
+
+Configure reverse proxies to route traffic, terminate TLS, enforce rate limits, and serve as the gateway between clients and backend services.
+
+## When to Use
+
+- Routing traffic from a public domain to one or more backend services.
+- Terminating TLS at the edge and forwarding plain HTTP to backends.
+- Adding rate limiting, CORS, security headers, and access control.
+- Consolidating multiple services under a single domain with path-based routing.
+- Handling WebSocket upgrades, gRPC proxying, or HTTP/2 passthrough.
+
+## Prerequisites
+
+- Backend service(s) running on known host:port.
+- TLS certificate (Let's Encrypt, ACM, or self-signed for development).
+- nginx 1.25+ or Traefik 3.x installed.
+- DNS record pointing the domain to the proxy server.
+
+## nginx Reverse Proxy
+
+### Basic HTTPS Proxy with Redirect
+
+```nginx
+# /etc/nginx/sites-available/app.example.com
+server {
+    listen 80;
+    server_name app.example.com;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name app.example.com;
+
+    # TLS configuration
+    ssl_certificate     /etc/letsencrypt/live/app.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;
+    ssl_protocols       TLSv1.2 TLSv1.3;
+    ssl_ciphers         ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384;
+    ssl_prefer_server_ciphers on;
+    ssl_session_cache   shared:SSL:10m;
+    ssl_session_timeout 10m;
+
+    # Security headers
+    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
+    add_header X-Frame-Options DENY always;
+    add_header X-Content-Type-Options nosniff always;
+    add_header Referrer-Policy strict-origin-when-cross-origin always;
+
+    # Proxy to backend
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # Timeouts
+        proxy_connect_timeout 5s;
+        proxy_read_timeout 60s;
+        proxy_send_timeout 60s;
+
+        # Buffering
+        proxy_buffering on;
+        proxy_buffer_size 4k;
+        proxy_buffers 8 4k;
+    }
+}
+```
+
+### Path-Based Routing to Multiple Services
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name app.example.com;
+
+    ssl_certificate     /etc/letsencrypt/live/app.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;
+
+    # Frontend SPA
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_set_header Host $host;
+    }
+
+    # API backend
+    location /api/ {
+        proxy_pass http://127.0.0.1:8080/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_read_timeout 120s;
+    }
+
+    # WebSocket endpoint
+    location /ws/ {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_read_timeout 86400s;  # 24h for long-lived connections
+    }
+
+    # Static assets with caching
+    location /static/ {
+        alias /var/www/static/;
+        expires 30d;
+        add_header Cache-Control "public, immutable";
+    }
+}
+```
+
+### Rate Limiting
+
+```nginx
+# Define rate limit zones in http block
+http {
+    # 10 requests/second per IP
+    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;
+
+    # 1 request/second for login
+    limit_req_zone $binary_remote_addr zone=login_limit:10m rate=1r/s;
+
+    # Connection limit per IP
+    limit_conn_zone $binary_remote_addr zone=conn_limit:10m;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name app.example.com;
+
+    # Apply rate limit to API
+    location /api/ {
+        limit_req zone=api_limit burst=20 nodelay;
+        limit_req_status 429;
+        proxy_pass http://127.0.0.1:8080;
+    }
+
+    # Strict rate limit on auth endpoints
+    location /api/auth/ {
+        limit_req zone=login_limit burst=5;
+        limit_req_status 429;
+        proxy_pass http://127.0.0.1:8080;
+    }
+
+    # Connection limit
+    location / {
+        limit_conn conn_limit 100;
+        proxy_pass http://127.0.0.1:3000;
+    }
+}
+```
+
+### Gzip and Brotli Compression
+
+```nginx
+http {
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript text/xml application/xml image/svg+xml;
+    gzip_min_length 256;
+    gzip_vary on;
+    gzip_proxied any;
+    gzip_comp_level 5;
+
+    # Brotli (requires ngx_brotli module)
+    # brotli on;
+    # brotli_types text/plain text/css application/json application/javascript text/xml application/xml image/svg+xml;
+    # brotli_comp_level 6;
+}
+```
+
+### Let's Encrypt with Certbot
+
+```bash
+# Install certbot with nginx plugin
+sudo apt install certbot python3-certbot-nginx
+
+# Obtain and install certificate
+sudo certbot --nginx -d app.example.com -d www.example.com
+
+# Auto-renewal is configured via systemd timer
+sudo systemctl status certbot.timer
+
+# Manual renewal test
+sudo certbot renew --dry-run
+```
+
+## Traefik Reverse Proxy
+
+### Static Configuration
+
+```yaml
+# traefik.yml
+entryPoints:
+  web:
+    address: ":80"
+    http:
+      redirections:
+        entryPoint:
+          to: websecure
+          scheme: https
+  websecure:
+    address: ":443"
+
+certificatesResolvers:
+  letsencrypt:
+    acme:
+      email: admin@example.com
+      storage: /letsencrypt/acme.json
+      httpChallenge:
+        entryPoint: web
+
+providers:
+  docker:
+    exposedByDefault: false
+  file:
+    directory: /etc/traefik/dynamic/
+
+api:
+  dashboard: true
+  insecure: false
+
+log:
+  level: INFO
+
+accessLog:
+  filePath: /var/log/traefik/access.log
+```
+
+### Dynamic Configuration (File Provider)
+
+```yaml
+# /etc/traefik/dynamic/services.yml
+http:
+  routers:
+    app:
+      rule: "Host(`app.example.com`)"
+      entryPoints:
+        - websecure
+      service: app
+      tls:
+        certResolver: letsencrypt
+      middlewares:
+        - security-headers
+        - rate-limit
+
+    api:
+      rule: "Host(`app.example.com`) && PathPrefix(`/api`)"
+      entryPoints:
+        - websecure
+      service: api
+      tls:
+        certResolver: letsencrypt
+
+  services:
+    app:
+      loadBalancer:
+        servers:
+          - url: "http://127.0.0.1:3000"
+        healthCheck:
+          path: /health
+          interval: 10s
+          timeout: 3s
+
+    api:
+      loadBalancer:
+        servers:
+          - url: "http://127.0.0.1:8080"
+        healthCheck:
+          path: /api/health
+          interval: 10s
+          timeout: 3s
+
+  middlewares:
+    security-headers:
+      headers:
+        stsSeconds: 63072000
+        stsIncludeSubdomains: true
+        frameDeny: true
+        contentTypeNosniff: true
+        browserXssFilter: true
+        referrerPolicy: strict-origin-when-cross-origin
+
+    rate-limit:
+      rateLimit:
+        average: 100
+        burst: 50
+        period: 1m
+```
+
+### Traefik with Docker Labels
+
+```yaml
+# docker-compose.yml
+version: "3.8"
+
+services:
+  traefik:
+    image: traefik:v3.0
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - ./traefik.yml:/etc/traefik/traefik.yml:ro
+      - letsencrypt:/letsencrypt
+
+  frontend:
+    image: my-frontend:latest
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.frontend.rule=Host(`app.example.com`)"
+      - "traefik.http.routers.frontend.tls.certresolver=letsencrypt"
+      - "traefik.http.services.frontend.loadbalancer.server.port=3000"
+
+  api:
+    image: my-api:latest
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.api.rule=Host(`app.example.com`) && PathPrefix(`/api`)"
+      - "traefik.http.routers.api.tls.certresolver=letsencrypt"
+      - "traefik.http.services.api.loadbalancer.server.port=8080"
+      - "traefik.http.routers.api.middlewares=api-ratelimit"
+      - "traefik.http.middlewares.api-ratelimit.ratelimit.average=50"
+      - "traefik.http.middlewares.api-ratelimit.ratelimit.burst=25"
+
+volumes:
+  letsencrypt:
+```
+
+## nginx Testing and Management
+
+```bash
+# Test configuration syntax
+sudo nginx -t
+
+# Reload without downtime
+sudo nginx -s reload
+
+# View active connections
+sudo nginx -s status
+
+# Check which config file is active
+nginx -V 2>&1 | grep -o '\-\-conf-path=[^ ]*'
+
+# Monitor access logs
+tail -f /var/log/nginx/access.log
+
+# Monitor error logs
+tail -f /var/log/nginx/error.log
+```
+
+## IP Allowlisting and Geoblocking
+
+```nginx
+# Allow only specific IPs (admin panel)
+location /admin/ {
+    allow 203.0.113.0/24;
+    allow 198.51.100.5;
+    deny all;
+    proxy_pass http://127.0.0.1:3000;
+}
+
+# Block by country (requires GeoIP2 module)
+# geoip2 /usr/share/GeoIP/GeoLite2-Country.mmdb {
+#     auto_reload 60m;
+#     $geoip2_data_country_iso_code country iso_code;
+# }
+# if ($geoip2_data_country_iso_code = "XX") {
+#     return 403;
+# }
+```
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| 502 Bad Gateway | Backend not running or unreachable | Verify backend is listening; check `proxy_pass` URL |
+| 504 Gateway Timeout | Backend too slow | Increase `proxy_read_timeout`; check backend performance |
+| Mixed content warnings | `X-Forwarded-Proto` not set | Add `proxy_set_header X-Forwarded-Proto $scheme` |
+| WebSocket disconnects after 60s | Default proxy timeout expires | Set `proxy_read_timeout 86400s` for WebSocket locations |
+| Rate limit hits legitimate users | Zone rate too aggressive | Increase `rate` or `burst` values; use different zones per endpoint |
+| Let's Encrypt renewal fails | Port 80 blocked or wrong server block | Ensure `.well-known/acme-challenge/` is accessible |
+| Traefik shows 404 for all routes | Docker labels not detected | Verify Docker socket is mounted; check `exposedByDefault` setting |
+| TLS handshake failure | Certificate chain incomplete | Include intermediate certificates in `ssl_certificate` |
+
+## Related Skills
+
+- load-balancing (`load-balancing`) - Multi-backend traffic distribution
+- cdn-setup (`cdn-setup`) - CDN in front of reverse proxy
+- dns-management (`dns-management`) - DNS records for proxy domains
+- service-mesh (`service-mesh`) - Service-level routing in Kubernetes
+
+## Limitations
+
+- Infrastructure commands can disrupt services: confirm target host/scope and have backups/snapshots before mutating state.
+- Docs-only import: upstream scripts and templates not bundled.
+