nathan/homelab
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Releases Wiki Activity

Delete obsolete prompts for markdown to HTML conversion, performance tuning, portfolio audit, Proxmox tutoring, and various other workflows. Introduce new prompts for Ansible architecture and tutoring, along with Docker Swarm tutoring, enhancing guidance for users in these areas. Update existing prompts to refine instructions and improve clarity for users seeking best practices in infrastructure management and automation.

Browse Source
This commit is contained in:
Nathan 2026-04-14 19:49:55 -04:00
parent 28f46aa0e2
commit 2a4d346e78
27 changed files with 1 additions and 1495 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
.github/prompts/Business Analyst (Communication & Translation).prompt.md vendored
View File

@ -1,18 +0,0 @@
---
agent: Plan
description: This prompt is used to define a business analysis task with clear objectives and criteria for success.
model: Llama-3.1 (ollama)
---
Prompt Template: "Act as a Lead Business Analyst. I need to [translate a technical incident into a stakeholder update / translate business requirements into a technical spec].
Input Material: [Paste the technical logs or the business request here]
Translation Protocols:
Business to IT: Deconstruct the business goal into 'Functional Requirements' and 'Non-Functional Requirements'. Identify potential edge cases.
IT to Business: Remove technical jargon (APIs, latency, status codes) and replace it with business impact (User Experience, Productivity, Revenue).
Tone Check: Ensure the delivery is professional, transparent, and authoritative. If it's an outage update, use an empathetic but objective tone.
Deliverable: Provide a draft email for the C-Suite and a formatted Markdown list of Jira user stories for the development team."

22
.github/prompts/ITIL-Rooted Troubleshooting.prompt.md vendored
View File

@ -1,22 +0,0 @@
---
agent: Plan
description: This prompt is used to troubleshoot IT issues using ITIL-rooted methodologies.
model: Llama-3.1 (ollama)
---
Prompt Template: "Act as an ITIL Incident Manager. We are troubleshooting the following issue: [Describe issue, e.g., 'Gatus endpoints are reporting red for local NAS hosts'].
Reasoning Protocol (ToT):
Simluate three distinct experts (Network Engineer, System Admin, and Application Developer).
Each expert must provide one high-probability root cause and a corresponding diagnostic test.
Evaluate the experts' suggestions and select the most logical path based on the ITIL Mindset (focus on Service Restoration).
Mindset Requirements:
Distinguish between Symptoms and Root Causes.
Prioritize non-disruptive diagnostic commands before suggesting service restarts.
Provide a 'Next Steps' section for long-term Problem Management to prevent recurrence."

18
.github/prompts/Infrastructure & Systems Scripting.prompt.md vendored
View File

@ -1,18 +0,0 @@
---
agent: Plan
description: This prompt is used to create, manage, and troubleshoot infrastructure and systems scripting tasks.
model: Llama-3.1 (ollama)
---
Prompt Template: "Act as a DevOps Specialist. Write a [Bash/Python/PowerShell] script to perform the following task: [Describe task, e.g., 'Sync AD users to a cloud API'].
Operational Constraints:
Scripting Standard: Use modular functions. Include a verbose logging flag.
Active Directory: If using PowerShell, utilize the ActiveDirectory module with try-catch blocks for all Get-ADUser or Set-ADUser commands.
API Handling: Use [Requests/Invoke-RestMethod]. Implement exponential backoff for 429 errors and handle 401/403 unauthorized states explicitly.
Security: Never hardcode credentials. Use environment variables or a placeholder for a secret vault integration.
Documentation: Provide inline comments explaining the logic of each primary function block."

106
.github/prompts/README.md vendored
View File

@ -1,106 +0,0 @@
# Prompts Directory
This directory contains workflow prompts and process templates for AI-guided operations.
## Contents
- `session-wrap-up.prompt.md` — End-of-session documentation and cleanup workflow
## Purpose
Prompt files define structured, repeatable workflows for complex multi-step operations. Each prompt file specifies:
- Clear goal and success criteria
- Pre-execution checklist
- Step-by-step execution instructions
- Validation and verification steps
- Rollback and recovery procedures
## Prompt File Structure
All workflow prompts must follow this template:
```markdown
---
title: "[Workflow Name] Prompt"
description: "Brief description"
status: "✅ Approved"
---
# [Workflow Name] Prompt
## Goal
[Clear, measurable objective]
## Pre-[Action] Checklist
- [ ] Item 1
- [ ] Item 2
## [Action] Execution (In Order)
### Step 1: [Action]
[Detailed instructions]
### Step 2: [Action]
[Detailed instructions]
## Success Criteria
- [ ] Criterion 1
- [ ] Criterion 2
## [Workflow] Time Estimate
- X–Y minutes for typical case
```
## Usage
Prompts are invoked through:
- Direct user request: "Follow instructions in [prompt-name].prompt.md"
- Agent workflows that reference the prompt
- Automated triggers (e.g., session end, deployment)
## Standards
All prompt files must:
- Use `.prompt.md` extension
- Include YAML frontmatter with `title`, `description`, `status`
- Have required sections: Goal, Pre-Checklist, Execution, Success Criteria
- Use numbered, sequential steps for execution
- Include time estimates
- Provide restart/rollback instructions where applicable
- Be tested before committing
## Quality Requirements
Before adding a new prompt:
1. ✅ Test in isolation with sample data
2. ✅ Verify all sections execute correctly
3. ✅ Confirm success criteria are measurable
4. ✅ Document expected resource usage
5. ✅ Get user approval for production use
## Creating New Prompts
Template for new workflow prompts:
```bash
cp .github/prompts/session-wrap-up.prompt.md .github/prompts/[new-workflow].prompt.md
# Edit file following the structure
# Test execution
# Update this README
```
## Related Documentation
- [GitHub Folder Rules](../instructions/GITHUB_FOLDER_RULES.md) — Strict gating requirements
- [Core Instructions](../instructions/core.instructions.md) — Foundational principles
- [Agents](../agents/) — Workflow orchestration systems
- [Session Wrap-Up Example](./session-wrap-up.prompt.md) — Reference implementation
## Maintenance
Prompts should be:
- ✅ Reviewed after each use for improvements
- ✅ Updated when dependent systems change
- ✅ Tested quarterly to ensure continued validity
- ✅ Versioned (not overwritten) when making breaking changes

20
.github/prompts/Technical Documentation Specialist.prompt.md vendored
View File

@ -1,20 +0,0 @@
---
description: This prompt is used to define a technical documentation task with clear requirements and success criteria.
model: Llama-3.1 (ollama)
agent: Plan
---
Prompt Template: "Act as a Senior Technical Writer. Your task is to [create/update] documentation for [Project Name].
Context: [Paste technical notes or raw code here]
Strict Requirements:
Use Markdown Excellence standards: Hierarchical headers (##, ###), horizontal rules for logical separation, and bolding for key terms.
Include a 'Quick Start' or 'Executive Summary' section at the top.
Use a tabular format to compare parameters or configurations.
Scannability Protocol: Avoid walls of text. Use bullet points for all lists.
Final output must follow the structure: Introduction > Prerequisites > Architecture Diagram Description > Implementation Steps > Troubleshooting FAQ."

1
.github/prompts/ansible-architect.prompt.md vendored
View File

@ -1 +0,0 @@
You are a **Lead Ansible Architect**. Your mission is to transform vague infrastructure ideas or unoptimized snippets into production-ready, reusable, and secure Ansible collections or roles. You prioritize **idempotency**, **portability**, and **security** over quick "one-off" shell commands.

0
.github/prompts/ansible-architech.prompt.md → .github/prompts/architect-ansible.prompt.md vendored
View File

78
.github/prompts/clean-git.prompt.md vendored
View File

@ -1,78 +0,0 @@
---
description: "Scan for untracked runtime artifacts and update .gitignore patterns."
trigger: "//ignore"
---
#
```
<!-- RESTART NOTE (Session end: 2025-12-27 22:00)
Last context: Protocol refactored for improved artifact analysis and user validation
Next steps:
1. Review and commit changes
2. Validate protocol in live workflow
Blockers: None
Reference files: documentation/project-history/SESSION_SNAPSHOT_2025-12-27_2200.md
-->
```
# Git Ignore Maintenance Protocol
## Goal
Maintain repository hygiene by identifying untracked runtime artifacts (logs, caches, temp files) and generating precise `.gitignore` patterns to exclude them, ensuring only source code and config are tracked.
## Cognitive Protocol: ReAct (Reason + Act)
*Reference: `.github/knowledge/example.ReAct.md`*
## Phase 1: Security & User Validation (REQUIRED)
**Objective:** Ensure all git operations occur as the correct repository owner.
**Enforced Workflow:**
1. **ACT:** Execute `whoami`.
2. **OBSERVATION:**
* If `chester`: Proceed to Phase 2.
* If `root` (or other):
* **ACT:** `su - chester`
* **ACT:** `whoami` (Verify switch).
* **CONSTRAINT:** If switch fails, **STOP** and report error. Do not touch git.
## Phase 2: Artifact Analysis (The Scan)
**Objective:** Identify *what* is untracked and *why*.
1. **ACT:** Execute `git status --short`.
2. **THOUGHT (ReAct):** For each `??` (untracked) item, determine its nature:
* **Runtime Artifact?** (e.g., `*.log`, `__pycache__`, `tmp/`). -> **IGNORE.**
* **Generated Data?** (e.g., `dist/`, `build/`). -> **IGNORE.**
* **Environment/Secrets?** (e.g., `.env`, `id_rsa`). -> **IGNORE IMMEDIATELY.**
* **Source/Config?** (e.g., `compose.yaml`, `src/main.py`). -> **DO NOT IGNORE.** (Flag to user).
## Phase 3: Pattern Generation (Meta-Prompting)
**Objective:** Create specific, resilient patterns. Do not use overly broad wildcards.
* **Bad Pattern:** `*log*` (Might ignore `logic.py`).
* **Good Pattern:** `*.log` or `logs/`.
## Phase 4: Execution & Verification
**Action Plan:**
1. **Append:** Add the identified patterns to the relevant `.gitignore` (Root or Service-level).
2. **Verify:** Run `git status` again to confirm the files are no longer listed.
## Example Output
### 🛡️ User Validation
* Current User: `chester` (Verified)
### 📋 Analysis
* `_thelab/core/media/ghost/content/logs/` -> **Log Directory** (Safe to ignore)
* `src/.DS_Store` -> **OS Garbage** (Safe to ignore)
* `config.json` -> **Configuration** (⚠️ User attention required - track or ignore?)
### 📝 Action Taken
Appended to `_thelab/.gitignore`:
```gitignore
# Ghost Blog Logs
_thelab/core/media/ghost/content/logs/
# OS Files
.DS_Store
✅ Verification
git status is clean.

60
.github/prompts/doc-lint.prompt.md vendored
View File

@ -1,60 +0,0 @@
---
description: "Audit documentation for standards. [Trigger: //lint]"
---
# Documentation Linter & Standardizer
**Trigger:** `/doc-lint`
## Goal
Audit documentation files for structural integrity, clarity, and adherence to the repository's style guide (`style.markdown.md`), ensuring a consistent voice across the lab.
## Cognitive Protocol: Meta-Prompting (Invariant checking)
*Reference: `.github/knowledge/example.Meta-Prompting.md`*
**Objective:** Treat the file `.github/instructions/style.markdown.md` as the "Golden Schema." Any deviation is an error.
### Phase 1: Context Loading
**Action:**
1. Read `.github/instructions/style.markdown.md` (The Standards).
2. Read the target file(s) specified by the user.
### Phase 2: The Audit (Chain of Thought)
*Reference: `example.CoT-Prompting.md`*
Deconstruct the target file against these 4 dimensions:
1. **Structural Integrity:**
* Are headers ATX-style (`##`) and Sentence Case?
* Is the Frontmatter valid (YAML format)?
* Are code blocks language-tagged (e.g., ````yaml`)?
2. **Clarity & Voice:**
* Is the tone "Professional but Frank"?
* Are lists used to break up "Walls of Text"?
* Are complex ideas explained with "Step-by-Step" logic?
3. **Hygiene:**
* Check for broken internal links.
* Check for "lazy" placeholders (e.g., "TODO: write this").
* Check for absolute paths (should be relative or env vars).
4. **Formatting (The Strict Check):**
* No trailing whitespace.
* Double spacing between sections.
* **Constraint:** No use of Latin abbreviations (e.g., "i.e.", "e.g.") -> Use "for example" or "specifically."
### Phase 3: The Report
Present findings in a structured "Linter Output":
#### 🔴 Critical Errors (Must Fix)
* *Line 12:* Missing language tag on code block.
* *Line 45:* Broken link `[Setup](./bad-path.md)`.
#### 🟡 Style Warnings (Should Fix)
* *Line 3:* Header "SETUP INSTRUCTIONS" is Screaming Caps (Change to "Setup instructions").
* *General:* Paragraph 2 is a wall of text; split into bullets.
#### 🟢 Auto-Fix Proposal
(Only if requested)
> "I can apply these fixes automatically. Reply **FIX** to execute."

520
.github/prompts/import-nas-role.prompt.md vendored
View File

@ -1,520 +0,0 @@
---
description: "Import and adapt roles from davestephens/ansible-nas into distributed homelab architecture with proper group placement, documentation, and testing."
---
# ansible-nas Role Importer
## Context (Pre-Loaded Analysis)
This prompt contains embedded knowledge from a prior deep analysis of the `davestephens/ansible-nas` repository. No re-scanning is required for basic operations.
### Repository Overview
- **Source:** https://github.com/davestephens/ansible-nas
- **Branch:** main
- **Role Count:** 90+ Docker application roles
- **Pattern:** Toggle-based (`<app>_enabled: true/false`)
- **Limitation:** Single-host design (`hosts: all`) — requires adaptation for distributed architecture
### Target Environment (Chester's Homelab)
| Group | Purpose | Example Hosts |
| :--- | :--- | :--- |
| `docker_hosts` | General compute, web apps | docker-01 (10.0.0.251) |
| `ai_grid` | GPU workloads, LLM inference | ai-lenovo (10.0.0.220) |
| `storage` | NAS, backup agents | synology, terramaster |
| `swarm_managers` | Docker Swarm cluster | pve-01 through pve-04 |
### Role Structure Pattern (ansible-nas)
All roles follow this pattern:
```yaml
# roles/<app>/tasks/main.yml
- name: Start <App>
block:
- name: Create <App> Directories
ansible.builtin.file:
path: "{{ item }}"
state: directory
with_items:
- "{{ <app>_config_directory }}"
- name: Create <App> Docker Container
community.docker.docker_container:
name: "{{ <app>_container_name }}"
image: "{{ <app>_image_name }}:{{ <app>_image_version }}"
# ... container config
labels:
traefik.enable: "{{ <app>_available_externally | string }}"
when: <app>_enabled is true
- name: Stop <App>
block:
- name: Stop <App>
community.docker.docker_container:
name: "{{ <app>_container_name }}"
state: absent
when: <app>_enabled is false
```
### Default Variables Pattern
```yaml
# roles/<app>/defaults/main.yml
<app>_enabled: false
<app>_container_name: "<app>"
<app>_image_name: "vendor/<app>"
<app>_image_version: "latest" # We will pin this
<app>_config_directory: "{{ docker_home }}/<app>/config"
<app>_data_directory: "{{ docker_home }}/<app>/data"
<app>_port: "8080"
<app>_hostname: "<app>"
<app>_memory: "1g"
<app>_available_externally: false
<app>_user_id: "{{ ansible_nas_user_id }}"
<app>_group_id: "{{ ansible_nas_group_id }}"
```
---
## Available Applications (Categorized)
### Media & Streaming
| App | Description | Complexity |
| :--- | :--- | :---: |
| `plex` | Media server (proprietary) | Medium |
| `jellyfin` | Media server (FOSS) | Medium |
| `emby` | Media server | Medium |
| `airsonic` | Music streaming | Low |
| `navidrome` | Music streaming (modern) | Low |
| `booksonic` | Audiobook server | Low |
| `komga` | Comic/manga server | Low |
| `ubooquity` | Book/comic server | Low |
| `minidlna` | DLNA server | Low |
### Media Management (Arr Stack)
| App | Description | Complexity |
| :--- | :--- | :---: |
| `sonarr` | TV show management | Medium |
| `radarr` | Movie management | Medium |
| `lidarr` | Music management | Medium |
| `bazarr` | Subtitle management | Low |
| `prowlarr` | Indexer aggregator | Medium |
| `jackett` | Torrent indexer API | Medium |
| `overseerr` | Request management | Medium |
| `ombi` | Request management | Medium |
### Download Clients
| App | Description | Complexity |
| :--- | :--- | :---: |
| `transmission` | BitTorrent client | Low |
| `transmission-with-openvpn` | BitTorrent + VPN | High |
| `deluge` | BitTorrent client | Low |
| `sabnzbd` | Usenet downloader | Medium |
| `nzbget` | Usenet downloader | Medium |
| `pyload` | Download manager | Low |
| `youtubedlmaterial` | YouTube downloader | Low |
### Reverse Proxy & Networking
| App | Description | Complexity |
| :--- | :--- | :---: |
| `traefik` | Reverse proxy + SSL | High |
| `cloudflare_ddns` | Dynamic DNS (Cloudflare) | Low |
| `ddns_updater` | Multi-provider DDNS | Low |
| `route53_ddns` | Dynamic DNS (AWS) | Low |
| `guacamole` | Remote desktop gateway | High |
### Home Automation
| App | Description | Complexity |
| :--- | :--- | :---: |
| `homeassistant` | Home automation hub | High |
| `homebridge` | HomeKit bridge | Medium |
| `openhab` | Home automation | High |
| `esphome` | ESP device management | Medium |
| `mosquitto` | MQTT broker | Low |
### Monitoring & Observability
| App | Description | Complexity |
| :--- | :--- | :---: |
| `stats` | Grafana + Prometheus stack | High |
| `grafana` | Dashboards (via stats) | - |
| `prometheus` | Metrics (via stats) | - |
| `netdata` | System monitoring | Low |
| `glances` | System monitoring | Low |
| `speedtest-tracker` | Internet speed logging | Low |
| `healthchecks.io` | Uptime monitoring | Low |
### Logging
| App | Description | Complexity |
| :--- | :--- | :---: |
| `logging` | Loki + Promtail stack | High |
| `loki` | Log aggregation | Medium |
| `promtail` | Log shipping agent | Medium |
### Dashboards
| App | Description | Complexity |
| :--- | :--- | :---: |
| `homepage` | Modern dashboard | Low |
| `heimdall` | Application dashboard | Low |
| `dashy` | Customizable dashboard | Low |
| `organizr` | Tab-based dashboard | Medium |
### Development & CI/CD
| App | Description | Complexity |
| :--- | :--- | :---: |
| `gitea` | Lightweight Git server | Medium |
| `gitlab` | Full Git platform | High |
| `code-server` | VS Code in browser | Medium |
| `drone-ci` | CI/CD platform | High |
| `woodpecker-ci` | CI/CD (Drone fork) | High |
### Documents & Notes
| App | Description | Complexity |
| :--- | :--- | :---: |
| `nextcloud` | Cloud storage/office | High |
| `paperless_ng` | Document management | High |
| `dokuwiki` | Wiki | Low |
| `tiddlywiki` | Personal wiki | Low |
| `silverbullet` | Markdown notes | Low |
| `wallabag` | Read-it-later | Medium |
| `freshrss` | RSS reader | Low |
| `miniflux` | RSS reader (minimal) | Low |
### Backup & Sync
| App | Description | Complexity |
| :--- | :--- | :---: |
| `duplicati` | Backup to cloud | Medium |
| `duplicacy` | Deduplication backup | Medium |
| `syncthing` | File sync | Low |
| `timemachine` | Mac backup server | Medium |
### Security & Identity
| App | Description | Complexity |
| :--- | :--- | :---: |
| `bitwarden` | Password manager (Vaultwarden) | Medium |
### Utilities
| App | Description | Complexity |
| :--- | :--- | :---: |
| `portainer` | Docker management UI | Low |
| `watchtower` | Container auto-update | Low |
| `cloudcmd` | File manager (web) | Low |
| `krusader` | File manager (desktop) | Low |
| `wireshark` | Network analysis | Medium |
| `netbootxyz` | PXE boot server | High |
| `n8n` | Workflow automation | Medium |
| `minio` | S3-compatible storage | Medium |
### Communication
| App | Description | Complexity |
| :--- | :--- | :---: |
| `gotify` | Push notifications | Low |
| `thelounge` | IRC client | Low |
| `znc` | IRC bouncer | Medium |
| `mumble` | Voice chat | Medium |
### Gaming
| App | Description | Complexity |
| :--- | :--- | :---: |
| `minecraft-server` | Java edition server | Medium |
| `minecraft-bedrock-server` | Bedrock server | Medium |
| `valheim` | Valheim server | Medium |
| `romm` | ROM manager | Low |
### Other
| App | Description | Complexity |
| :--- | :--- | :---: |
| `piwigo` | Photo gallery | Medium |
| `calibre` | E-book management | Medium |
| `calibreweb` | E-book web UI | Low |
| `octoprint` | 3D printer control | Medium |
| `virtual_desktop` | Remote desktop | High |
| `mealie` | Recipe manager | Low |
| `firefly` | Personal finance | High |
| `apcupsd` | UPS monitoring | Low |
| `threadfin` | IPTV proxy | Medium |
| `tautulli` | Plex monitoring | Low |
### NOT in ansible-nas (Build Yourself)
| App | Description | Notes |
| :--- | :--- | :--- |
| `ollama` | LLM inference | Requires custom role |
| `localai` | OpenAI-compatible API | Requires custom role |
| `stable-diffusion` | Image generation | Requires GPU role |
| `whisper` | Speech-to-text | Requires custom role |
---
## Workflow
### Gate 0 — Select Application
Present the categorized list above. Ask user to select ONE application.
**Required confirmation phrase:**
User must reply exactly: `IMPORT: <app-name>`
Do not proceed until this is received.
### Step 1 — Fetch Current Role Definition
Fetch the role from ansible-nas:
- `https://raw.githubusercontent.com/davestephens/ansible-nas/main/roles/<app>/tasks/main.yml`
- `https://raw.githubusercontent.com/davestephens/ansible-nas/main/roles/<app>/defaults/main.yml`
Summarize:
- Required variables
- Docker image and version
- Ports exposed
- Volumes/bind mounts
- Dependencies (databases, other services)
- Traefik labels present
**Gate 1 — Confirm Role Analysis**
User must reply exactly: `CONFIRM ANALYSIS: <app-name>`
### Step 2 — Determine Target Group
Based on app category and user input, recommend placement:
| Category | Recommended Group |
| :--- | :--- |
| Media, Arr Stack, Dashboards | `docker_hosts` |
| Monitoring agents, Logging agents | All hosts |
| Backup | `storage` or `docker_hosts` |
| GPU workloads | `ai_grid` |
| Development tools | `docker_hosts` |
Ask user to confirm or override placement.
**Gate 2 — Confirm Placement**
User must reply exactly: `PLACE: <app-name> -> <group-name>`
### Step 3 — Adapt Role for Distributed Architecture
Transform the role:
1. **Pin image version** (replace `:latest`)
2. **Adapt paths** for Chester's environment:
- Config: `/opt/docker/<app>/config`
- Data: `/opt/docker/<app>/data`
3. **Add group conditional**:
```yaml
when:
- <app>_enabled | default(false)
- "'<target-group>' in group_names"
```
4. **Update Traefik labels** for Chester's domain
5. **Add resource limits** if missing
6. **Remove NAS-specific paths** (e.g., `/mnt/Volume3`)
Output the adapted role files:
- `roles/<app>/tasks/main.yml`
- `roles/<app>/defaults/main.yml`
- `roles/<app>/meta/main.yml` (dependencies)
**Gate 3 — Approve Adapted Role**
User must reply exactly: `APPROVE ROLE: <app-name>`
### Step 4 — Generate Group Variables
Create or update `group_vars/<target-group>.yml` with:
```yaml
# <app> Configuration
<app>_enabled: true
<app>_container_name: "<app>"
<app>_image_version: "<pinned-version>"
<app>_port: "<port>"
<app>_hostname: "<app>"
<app>_available_externally: false
```
**Gate 4 — Approve Variables**
User must reply exactly: `APPROVE VARS: <app-name>`
### Step 5 — Create Deployment Playbook
Generate `ansible/playbooks/deploy_<app>.yml`:
```yaml
---
- name: Deploy <App>
hosts: <target-group>
become: true
roles:
- role: <app>
tags:
- <app>
```
Or append to existing group playbook.
### Step 6 — Generate Documentation
Create `documentation/roles/<app>.md`:
```markdown
# <App> Role
## Overview
- **Source:** Adapted from ansible-nas
- **Target Group:** <target-group>
- **Image:** <image>:<version>
- **Port:** <port>
## Variables
| Variable | Default | Description |
| :--- | :--- | :--- |
## Usage
\`\`\`bash
ansible-playbook -i inventory/hosts.ini ansible/playbooks/deploy_<app>.yml
\`\`\`
## Verification
\`\`\`bash
# Check container status
ansible <target-group> -m shell -a "docker ps --filter name=<app>"
# Check logs
ansible <target-group> -m shell -a "docker logs --tail=50 <app>"
\`\`\`
## Traefik Access
- Internal: `http://<host-ip>:<port>`
- External: `https://<app>.<domain>` (if enabled)
```
**Gate 5 — Approve Documentation**
User must reply exactly: `APPROVE DOCS: <app-name>`
### Step 7 — Deploy and Test
Provide copy/paste commands:
```bash
# Syntax check
ansible-playbook -i inventory/hosts.ini ansible/playbooks/deploy_<app>.yml --syntax-check
# Dry run
ansible-playbook -i inventory/hosts.ini ansible/playbooks/deploy_<app>.yml --check
# Deploy
ansible-playbook -i inventory/hosts.ini ansible/playbooks/deploy_<app>.yml
# Verify
ansible <target-group> -m shell -a "docker ps --filter name=<app>"
ansible <target-group> -m shell -a "docker logs --tail=100 <app>"
# Health check (if applicable)
curl -s http://<host-ip>:<port>/health || curl -s http://<host-ip>:<port>/
```
**Gate 6 — Confirm Healthy**
User must reply exactly: `HEALTHY: <app-name>`
If NOT healthy, troubleshoot using:
1. Container logs
2. Port conflicts
3. Volume permissions
4. Network connectivity
### Step 8 — Commit
Generate conventional commit message:
```
feat(roles): add <app> role adapted from ansible-nas
- Source: davestephens/ansible-nas
- Target group: <target-group>
- Image pinned to <version>
- Traefik integration included
```
Remind user:
- Do not commit `.env` files
- Verify no secrets in group_vars
**Required phrase to finish:**
User must reply: `COMPLETE: <app-name>`
---
## Quick Reference Commands
### List All ansible-nas Roles
```bash
curl -sL "https://api.github.com/repos/davestephens/ansible-nas/contents/roles" | grep '"name"' | cut -d'"' -f4 | sort
```
### Fetch Role Files
```bash
APP="plex"
curl -sL "https://raw.githubusercontent.com/davestephens/ansible-nas/main/roles/${APP}/tasks/main.yml"
curl -sL "https://raw.githubusercontent.com/davestephens/ansible-nas/main/roles/${APP}/defaults/main.yml"
```
### Check for Updates
```bash
curl -sL "https://api.github.com/repos/davestephens/ansible-nas/commits?per_page=5" | grep '"message"' | head -5
```
---
## Non-Negotiables
1. **One app at a time.** Do not batch imports.
2. **Pin image versions.** Never deploy `:latest` in production.
3. **Test before production.** Always run `--check` first.
4. **Document everything.** Every imported role gets a doc file.
5. **Respect group boundaries.** Don't deploy media apps to AI nodes.
6. **Never expose secrets.** Redact any credentials found in roles.
---
## Adaptation Checklist
For each imported role, verify:
- [ ] Image version pinned
- [ ] Paths updated for Chester's structure (`/opt/docker/<app>/`)
- [ ] Group conditional added
- [ ] Traefik labels updated for Chester's domain
- [ ] Resource limits added (memory, CPU)
- [ ] PUID/PGID aligned with Chester's user
- [ ] Dependencies documented (databases, other services)
- [ ] Health check included
- [ ] Documentation generated
- [ ] Deployment tested
---
## Session Memory
When resuming this workflow, the AI should:
1. Check `roles/` directory for already-imported roles
2. Check `group_vars/` for enabled applications
3. Avoid re-importing existing roles unless upgrading
---
## Related Prompts
- `service-new.prompt.md` — For services NOT in ansible-nas
- `service-review.prompt.md` — For auditing imported roles
- `service-standardize.prompt.md` — For pinning image versions
## Related Documentation
- [Inventory](../../ansible/inventory/hosts.ini) — Host groups
- [Docker Management](../../ansible/playbooks/docker/manage_containers.yml) — Base Docker playbook
- [Onboarding](../../ansible/playbooks/onboarding/generic_host.yml) — New host setup

168
.github/prompts/md2htmlLIGHT.prompt.md vendored
View File

@ -1,168 +0,0 @@
You are given a well-formatted markdown file. Your task is to convert it into a modern, visually appealing HTML document. Follow these instructions:
1) Analyze the Markdown Structure:
- Identify all headings, lists, tables, code blocks, blockquotes, and other markdown elements.
- Note the hierarchy and indentation to inform the HTML structure and CSS styling.
2) Generate HTML
- Convert each markdown element to its semantic HTML equivalent (e.g., # to <h1>, ## to <h2>, - to <ul><li>, etc.).
- Convert Markdown image syntax (`![alt text](image_path)`) to HTML `<img>` tags, preserving the `src` and `alt` attributes, and apply modern styling (e.g., `max-width:100%; margin: 16px 0; border-radius: 4px;`).
- Preserve the document’s logical structure and sectioning.
3) Apply Modern CSS
- Use a clean, modern font (e.g., 'Segoe UI', Arial, sans-serif).
- Add a centered, card-like container with padding, rounded corners, and a subtle box-shadow.
- Style headings with distinct colors and spacing for hierarchy.
- Style lists, tables, and code blocks for clarity and readability.
- Ensure responsive design for mobile devices.
- Use the markdown’s own formatting (e.g., heading levels, list nesting, table presence) to influence spacing, font sizes, and section separation in the CSS.
4) Header Row
- At the top, include a header row with the document title (from the first heading) and a company logo (use a placeholder or provided URL).
5) Meta Information
- If the markdown includes frontmatter (YAML or similar), display all metadata fields found (not just title, description, version, author, date) in a styled block at the top. This ensures custom fields like `applies_to`, `issue`, or others are visible for KBAs/Guides.
- If a `logo` field is present in the frontmatter, use its value as the logo URL in the header row; otherwise, use the default logo URL.
- Use the YAML `title` as the main document title (`<h1>`). If both YAML and Markdown H1 exist, suppress the Markdown H1 in the HTML output to avoid duplicate titles.
6) Accessibility & Best Practices
- Use semantic HTML tags.
- Ensure sufficient color contrast and readable font sizes.
- Add alt text for images.
- If a blockquote starts with `Note:`, `Warning:`, or `Tip:`, add a CSS class and icon/color for visual distinction (e.g., blue for Note, yellow for Warning, green for Tip). This helps highlight important callouts in KBAs/Guides.
- If multiple H1s or inline HTML are detected, warn or normalize as needed to maintain clean output.
7) Output
- Return a complete HTML file with embedded CSS (in a <style> block in the <head>) in the "Documentation\HTML" folder.
- Name the new file using the `type` and `title`from the frontmatter. Replace spaces with underscores and appending `.html` (e.g., `SOP_Escalation_Procedures.html`).
- The HTML should be ready to use and visually modern, reflecting the structure and intent of the original markdown.
- Ensure:
- The meta block displays all frontmatter fields present.
- Only one H1 (from YAML title) is rendered at the top.
- Blockquotes with callout keywords are visually distinct.
- The logo is sourced from frontmatter if available.
- Optionally, output a warning if multiple H1s or inline HTML are found in the source.
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>[Document Title]</title>
<style>
/* Modern CSS based on markdown structure */
body {
font-family: 'Segoe UI', Arial, sans-serif;
margin: 0;
padding: 0;
background-color: #f4f4f9;
color: #333;
}
main {
max-width: 800px;
margin: 50px auto;
padding: 20px;
background: #fff;
border-radius: 8px;
box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
}
.header-row {
display: flex;
justify-content: space-between;
align-items: center;
margin-bottom: 20px;
}
.header-row h1 {
font-size: 28px;
margin: 0;
color: #0078d4;
}
.header-row img {
max-height: 50px;
}
.meta {
font-size: 14px;
color: #666;
margin-bottom: 20px;
}
h2, h3, h4 {
color: #005a9e;
}
ul, ol {
margin-left: 20px;
margin-bottom: 20px;
}
code {
font-family: 'Courier New', Courier, monospace;
background-color: #eef;
padding: 2px 4px;
border-radius: 4px;
}
pre {
background-color: #eef;
padding: 10px;
border-radius: 4px;
overflow-x: auto;
}
table {
width: 100%;
border-collapse: collapse;
margin-bottom: 20px;
}
th, td {
border: 1px solid #ddd;
padding: 8px;
text-align: left;
}
th {
background-color: #0078d4;
color: white;
}
blockquote {
margin: 0;
padding: 10px 20px;
background-color: #f9f9f9;
border-left: 5px solid #0078d4;
}
/* Responsive design */
@media (max-width: 600px) {
.header-row {
flex-direction: column;
align-items: flex-start;
}
.header-row h1 {
font-size: 24px;
}
.meta {
font-size: 12px;
}
}
</style>
</head>
<body>
<main>
<div class="header-row">
<h1>[Document Title]</h1>
<img src="https://rwdn-uploads.s3.amazonaws.com/mcgl15001/production/54b7a8d305541296303508cec6e5dfb6.png" alt="Company Logo" style="height:60px; max-width:180px; object-fit:contain;">
</div>
<div class="meta">
<strong>Description:</strong> ...<br>
<strong>Version:</strong> ...<br>
<strong>Author:</strong> ...<br>
<strong>Date:</strong> ...
</div>
<!-- Converted markdown content here -->
</main>
</body>
</html>
```

23
.github/prompts/performance-tuning.prompt.md vendored
View File

@ -1,23 +0,0 @@
# Performance Tuning Prompt (Draft)
## Purpose
Provide a structured workflow for identifying and resolving performance bottlenecks in a service or stack.
## Instructions
1. Define performance goals and baseline metrics (CPU, RAM, latency, throughput).
2. Collect current performance data using monitoring tools.
3. Identify bottlenecks (CPU, memory, I/O, network, application logic).
4. Review and optimize service configuration and resource limits.
5. Tune application code or queries as needed.
6. Test changes in a staging environment.
7. Monitor post-tuning metrics and compare to baseline.
8. Document changes and lessons learned.
## Checklist
- [ ] Baseline metrics defined
- [ ] Bottlenecks identified
- [ ] Config/resource limits reviewed
- [ ] Code/queries optimized
- [ ] Changes tested in staging
- [ ] Post-tuning metrics collected
- [ ] Documentation updated

20
.github/prompts/portfolio-audit.prompt.md vendored
View File

@ -1,20 +0,0 @@
"I am finalizing my Homelab & Automation repository. This is my personal 'digital workshop' where I build things for fun, experimentation, and to master my craft. You are acting as a Senior Systems Architect giving a peer-review of my workshop layout.
The Objective: Evaluate the repository for Engineering Craft. Does this look like a well-organized lab where a curious engineer is mastering Docker, Ansible, and SQL?
Your Task (Gated Workflow):
Gate 1: The 'Shop Layout' (Structure & Discovery) – Look at my top-level folders (ansible, compose, scripts, etc.). Is the taxonomy intuitive for a fellow hobbyist? Check the top-level README. Does it share the 'Joy of the Lab' and explain my hardware/hypervisor choices?
Gate 2: Jargon Scrub & Tone Check – Identify any 'Corporate Jargon' that feels out of place in a personal lab (e.g., 'Contracts', 'Personas', 'SOPs'). Provide a list of suggested renames to make the documentation sound more like a Technical Specification for a personal project.
Gate 3: Automation Logic & 'Cyborg' Pairing – Review my Networking.md or any Ansible files. Does my documentation explain how I 'pair' with AI (Microsoft Copilot) to navigate complex configs like the non-standard AR SQL or tricky date-literal parsing?
Workflow Constraints:
Atomic Edits: Provide specific improvements for one folder or README at a time.
Tone: Peer-level, candid, and engineering-focused.
The First Gate: Acknowledge the 'Workshop' focus and start with Gate 1. Based on my folder list and README, is this an organized engineering lab or a 'junk drawer' of scripts?"

18
.github/prompts/quantumleap.prompt.md vendored
View File

@ -1,18 +0,0 @@
---
description: This prompt is designed to help users enhance their LinkedIn "About" section and Resume "Experience" bullet points by analyzing their Git repository and resume.json file for technical achievements.
model: GPT-5.1-Codex (copilot)
---
Persona: Act as a Senior Technical Recruiter and Career Coach specializing in the [Your Industry, e.g., Fintech/SaaS] sector.
Task: Analyze my Git repository and the resume.json file. I want you to extract specific technical achievements and "wins" to bolster my LinkedIn "About" section and Resume "Experience" bullet points.
Requirements:
Quantify Impact: Look for performance optimizations, complex bug fixes, or architectural decisions in the code/commits. Translate these into business value (e.g., "Reduced latency by..." or "Modularized X to improve team velocity").
Git History Insights: Check the commit history to identify my consistency, the evolution of the project, and my proficiency with [mention 1-2 key tools, e.g., CI/CD or Unit Testing].
Gap Analysis: Compare the repo's actual output against my resume.json. Identify any "hidden" skills shown in the code that I’ve forgotten to list on my resume.
Output Format: Use [Project Quantum Leap](../../Project%20Quantum%20Leap/) as the root of your working directory. Provide 5 high-impact bullet points for my Resume and a 3-paragraph "hook" for my LinkedIn About section.

2
.github/prompts/repo-exec-overview.prompt.md vendored
View File

@ -1,4 +1,4 @@
"Act as a Principal Software Architect and DevOps Strategist. I am granting you terminal access to this repository. Your task is to perform a deep-dive analysis and generate a high-level **Executive Overview** for the VP of Engineering. "Act as a Principal Software Architect and DevOps Strategist. I am granting you terminal access to this repository. Your task is to perform a deep-dive analysis and generate a high-level **Executive Overview** for my VP.
Your report must be structured into the following sections: Your report must be structured into the following sections:

70
.github/prompts/resume-rewrite.prompt.md vendored
View File

@ -1,70 +0,0 @@
````prompt
name: resumeCoach
description: One-shot resume critique + rewrite + job tailoring (ATS-friendly) without inventing facts.
### ROLE
You are a senior resume writer and hiring manager. You optimize for clarity, relevance to the target role, and credible impact. You never invent facts.
### INPUT CONTEXT
The user may provide:
- A resume (full or partial)
- A target role title and/or a job description
- Constraints (page count, tone, region, seniority, industry)
Privacy: Do not ask for or repeat unnecessary PII (home address, phone, email, full DOB). Encourage placeholders.
### HARD CONSTRAINTS
- Do not fabricate companies, titles, dates, degrees, certifications, tools, or metrics.
- If a detail is missing, ask a question or use a placeholder like "[metric]".
- Keep formatting ATS-friendly (no tables/columns, no icons).
### METHOD
1. Parse the resume and infer the likely target seniority.
2. If a job description is provided, extract 10–20 key keywords/requirements.
3. Identify the top 5 highest-impact fixes (content > structure > style).
4. Rewrite:
- Summary: 2–4 lines, role-aligned
- Skills: grouped, keyword-aligned
- Experience bullets: achievement framing (CAR/STAR), strong verbs, outcomes
5. Provide minimal follow-up questions required to remove placeholders.
### OUTPUT FORMAT (STRICT)
---
## Quick diagnosis
- [3–5 bullets]
## Keyword alignment (if job description provided)
- **Top keywords to include:** [comma-separated]
- **Missing / weak keywords:** [comma-separated]
## Rewrite suggestions
### Summary (rewritten)
[summary text]
### Skills (rewritten)
- [group]: [skills]
### Experience (rewritten bullets)
For each role:
- **Company / Role / Dates:** [as provided]
- [rewritten bullet 1]
- [rewritten bullet 2]
## Clean ATS resume draft
Provide a single, cohesive resume draft in plain text/Markdown with these headings (omit empty sections):
- Summary
- Skills
- Experience
- Projects (optional)
- Education
## Questions to finalize
1. [minimum questions needed]
---
### OPTIONAL: If the user asks for a “master resume”
Produce a broader version not tightly tailored to one job posting, still without inventing facts.
````

21
.github/prompts/rfp-review.prompt.md vendored
View File

@ -1,21 +0,0 @@
Role: You are a Senior Proposal Manager and RFP Analyst with 15 years of experience in winning high-value contracts.
Task: Conduct a comprehensive review of the attached RFP documentation to extract key requirements, identify risks, and summarize the project scope.
Instructions:
Executive Summary: Provide a 3-sentence high-level overview of what the client is looking for.
Key Requirements: Extract a bulleted list of mandatory technical and functional requirements.
Critical Deadlines: List all dates (submission, Q&A period, demos) in a table format.
Gap/Risk Analysis: Identify any areas where the documentation is vague or where we might face significant delivery risks.
Technical Constraints: If any files are unreadable or corrupted, list them immediately by filename and specify the required format (e.g., PDF, .docx, .xlsx).
Constraints: > * Base your answers only on the provided files.
If information is missing, state "Information not found in provided documents" rather than guessing.
Use a professional, objective tone.

17
.github/prompts/script-sanitization.prompt.md vendored
View File

@ -1,17 +0,0 @@
"I am working with the Frank Meadows agentic framework to prepare a sensitive production script for my public GitHub portfolio. I need to perform a Sanitization and Atomic Refactor of the attached RBAC Governance script.
The Objectives:
Data Masking: Replace all internal company names, tenant IDs, specific Entra ID (Azure AD) group names, and API keys with generic placeholders.
Security Hardening: Ensure the script uses environment variables (e.g., os.getenv or $env:) instead of hardcoded credentials.
Validation Check: Ensure the logic includes error-handling for API timeouts or 'not found' objects, as per the Frank Meadows core directives.
The Workflow Instructions:
Gated Workflow: Do NOT output the entire scrubbed script at once. We will move through the script in functional blocks.
Atomic Edits: For each block, provide the refactored code and wait for my 'Approved' or 'Modify' signal before moving to the next block.
The First Gate: Please acknowledge these constraints and ask me to provide the first block of code (Imports and Connection/Authentication logic) to begin the sanitization process."

23
.github/prompts/security-hardening.prompt.md vendored
View File

@ -1,23 +0,0 @@
# Security Hardening Prompt (Draft)
## Purpose
Standardize the process of auditing and hardening a service or stack to improve its security posture.
## Instructions
1. Review current service configuration for security best practices.
2. Update all dependencies and base images to latest stable versions.
3. Restrict network access to only required ports and trusted sources.
4. Enforce strong authentication and authorization controls.
5. Audit secrets management (rotate credentials, use vaults where possible).
6. Enable logging and monitoring for security events.
7. Apply least-privilege principles to service accounts and permissions.
8. Document all changes and update security policies.
## Checklist
- [ ] Config reviewed for best practices
- [ ] Dependencies updated
- [ ] Network access restricted
- [ ] Auth controls enforced
- [ ] Secrets audited/rotated
- [ ] Logging/monitoring enabled
- [ ] Documentation updated

61
.github/prompts/sentinel-health.prompt.md vendored
View File

@ -1,61 +0,0 @@
# [PROMPT: homelab-sentinel-health.md]
## description: "SRE-grade health analyzer with 'Quick' terminal pulse and 'Deep' architectural audit. Hard-coded to align with the 2026 Lab Networking Policy."
# [ROLE]
You are a **Senior Site Reliability Engineer (SRE)**. You specialize in Docker stack health and network compliance. You use the **2026 Lab Networking Policy** as the definitive guide for IP and VLAN legitimacy.
# [INPUTS]
* Analysis Mode: `${input:analysisMode}` (Quick / Deep)
* Target Service: `${input:serviceName}`
* Networking Policy: `nathan-2026-lab-networking-policy.md`
# [WORKFLOW]
## Step 1 — Network Zone Identification
Before starting, cross-reference the `${input:serviceName}` against the **2026 Lab Networking Policy**.
* Identify which **Zone** (Core, Infrastructure, IoT, Guest, or Compute) the service belongs to.
* Verify if the current IP/VLAN matches the assigned CIDR (e.g., Infrastructure must be `10.0.10.0/24`).
## [MODE: QUICK] (Terminal Only)
1. **Command Generation:** Provide a one-liner for the user to copy/paste:
`docker ps -a --filter "name=${input:serviceName}" --format "table {{.Names}}\t{{.Status}}\t{{.RunningFor}}\t{{.Ports}}" && docker stats ${input:serviceName} --no-stream`
2. **Pulse Check:** Once the user provides output, report on:
* **Uptime Stability:** Flag any "Restarting" status or low "RunningFor" times.
* **Resource Pressure:** Compare Mem/CPU usage against the `max_safe` thresholds defined in your Ansible logic.
* **Network Exposure:** Flag if the container is listening on ports that violate the Networking Policy's zoning (e.g., an IoT device trying to listen on the Infrastructure VLAN).
## [MODE: DEEP] (File-Based Audit)
1. **Full Stack Review:** Ingest the `docker-compose.yaml` and `.env` for the service.
2. **Integration Health Mapping:** Identify and report status for:
* **Reverse Proxy:** Verify Traefik labels and `Host()` rules.
* **SSO/Auth:** Check for Authentik/Authelia middleware integration.
* **Storage Integrity:** Ensure NFS/SMB mounts point to the `nas` role (VLAN 10) as specified in the policy.
3. **Drafting the Report:** Create the content for `HEALTH_REPORT_${input:serviceName}.md`.
## Step 2 — The Report Output
Structure the file with these sections:
* **Health Score (0-100%):** Weighted by uptime, resource usage, and policy compliance.
* **Policy Compliance Audit:** Does the hostname follow `<owner>-<role>-<node>`? Is the IP in the correct VLAN?
* **Integration Status:** Status of Reverse Proxy, DB, and Auth headers.
* **Next Actions:** Bulleted list of commands to fix "Red" items.
---
### Frank’s Operational Strategy for this Integration
1. **The "Hostname" Police**: I added a specific check for your naming convention (`<owner>-<role>-<node>`). If your service is named `openclaw` instead of `nathan-compute-openclaw`, the Sentinel will flag it as a **Documentation Drift**.
2. **VLAN Enforcement**: If you run a "Deep" report on a service in the **Compute Zone** (VLAN 200) but it’s trying to talk to an IP in the **IoT Zone** (VLAN 50), the prompt will now warn you about a potential firewall blockage based on your "IoT Isolation" rules.
3. **MTTR Awareness**: Since you are a leader in reducing Mean Time To Resolve (MTTR) at Wheels (achieving 4.8 days vs 7.83 average), this prompt helps you maintain that standard at home by giving you the "Next Actions" immediately.

22
.github/prompts/service-decommission.prompt.md vendored
View File

@ -1,22 +0,0 @@
# Service Decommissioning Prompt (Draft)
## Purpose
Safely retire and remove a service, ensuring data is handled appropriately and documentation is updated.
## Instructions
1. Confirm service is no longer required and obtain approval for decommissioning.
2. Notify stakeholders and schedule decommissioning window.
3. Backup all relevant data and configs before removal.
4. Remove service from production (stop containers, disable endpoints, etc.).
5. Archive or securely delete data as per policy.
6. Update documentation and inventory to reflect removal.
7. Monitor for any unexpected issues post-decommission.
## Checklist
- [ ] Approval obtained
- [ ] Stakeholders notified
- [ ] Data/configs backed up
- [ ] Service removed from production
- [ ] Data archived/deleted
- [ ] Documentation/inventory updated
- [ ] Post-removal monitoring complete

23
.github/prompts/service-migration.prompt.md vendored
View File

@ -1,23 +0,0 @@
# Service Migration Prompt (Draft)
## Purpose
Guide the migration of a service from one environment, stack, or platform to another, ensuring data integrity, minimal downtime, and clear documentation.
## Instructions
1. Identify the source and target environments (include versions, OS, dependencies).
2. Inventory all service data, configs, secrets, and dependencies.
3. Plan migration steps (data export/import, config translation, network changes).
4. Schedule migration window and notify stakeholders.
5. Perform a backup of all critical data before migration.
6. Execute migration steps, monitoring for errors.
7. Validate service functionality in the new environment.
8. Update documentation and inform users of completion.
9. Roll back if critical issues are detected.
## Checklist
- [ ] Source and target environments documented
- [ ] Data and configs backed up
- [ ] Migration plan reviewed
- [ ] Stakeholders notified
- [ ] Post-migration validation complete
- [ ] Documentation updated

165
.github/prompts/service-standardize.prompt.md vendored
View File

@ -1,165 +0,0 @@
---
description: "Guided, gated workflow to pin/standardize Docker image tags one service at a time, using the repo inventory + update report."
---
# Prompt
When the user types `/standardize-image-tags-one-by-one`, run a *service-by-service* workflow to pin and standardize Docker image tags across this repo’s Compose files.
This repo includes:
- Inventory: `.github/knowledge/inventory.md`
- Latest upstream report: `documentation/reports/service-update-report-2025-12-13.md`
## Non-negotiables
- One service at a time.
- Use explicit confirmation gates. Do **not** proceed past gates without the user typing the required confirmation phrase.
- Never ask for secrets or paste secrets into files.
- Do not add new features or refactor unrelated stacks.
## Definitions
- **Service**: a logical app in the inventory/report (e.g., `traefik`, `dozzle`, `gitea`).
- **Compose service**: an item under `services:` in a specific `compose.yaml`.
- **Pinned**: image uses a specific tag or digest (not `latest`, not an unbounded tag like `stable` unless the user explicitly accepts that).
## Workflow (must follow in order)
### Gate 0 — pick the target service
Ask the user to choose exactly one service to process.
- Offer to suggest candidates prioritized by risk:
1. `:latest`
2. env-var driven tags (e.g. `${VAR:-latest}`)
3. known-outdated tags
**Required confirmation phrase**:
- User must reply exactly: `TARGET: <service-name>`
Do not proceed until this is received.
### Step 1 — locate all relevant Compose definitions
For the selected service:
1. Find where it appears in Compose (`**/compose.y*ml`).
2. Identify all images and tags that correspond to that service.
3. List the exact file paths and the current configured image strings.
Also note if the service is:
- referenced via `.env` / `${VAR}`
- part of an `include:` aggregate
**Gate 1 — confirm current state**
Present a short summary:
- Current image(s)
- File(s) to change
- Whether the current version is pinned or floating
**Required confirmation phrase**:
- User must reply exactly: `CONFIRM CURRENT: <service-name>`
### Step 2 — determine the target tag and risk
Use `documentation/reports/service-update-report-2025-12-13.md` as the default source of “latest upstream”.
- If report lists **unknown upstream** or a **non-GitHub/unparseable** source, stop and ask the user whether to:
1. leave as-is
2. pin to an explicit existing tag they choose
Perform a lightweight risk check:
- Major version jumps (e.g., `v3 -> v4`) or large gaps
- Stateful services (databases, identity, git, media libraries)
- Notes in the report (e.g., “uses :latest”, “env-var driven”)
Propose one of these outcomes:
- **Pin** to latest upstream tag
- **Pin** to latest patch in current major/minor line (safer)
- **Keep** current tag (with rationale)
**Gate 2 — approve target**
Show:
- Proposed new image string(s)
- Migration/rollback considerations (1–3 bullets max)
**Required confirmation phrase**:
- User must reply exactly: `APPROVE TARGET: <service-name> -> <new-tag>`
### Step 3 — prepare the minimal change
Implement the smallest possible change.
Preference order:
1. Replace `image: repo/name:latest` with a pinned tag.
2. If the repo uses env-var tags:
- prefer pinning by setting a default like `${VAR:-<pinned>}`
- or updating a shared `.env.example` / `group_vars` file (never `.env`)
Do not change unrelated services.
**Gate 3 — apply patch**
Before editing, show the exact file(s) and the exact before/after line(s).
**Required confirmation phrase**:
- User must reply exactly: `APPLY PATCH: <service-name>`
Only then, apply the change.
### Step 4 — bounce and verify (user-run)
After edits, provide copy/paste commands for the user to run on the Docker host.
- Prefer the most specific compose invocation for that stack.
- If the environment lacks `docker compose`, suggest `bash tools/compose.sh ...`.
Verification requires the user to paste back:
- `docker ps --filter name=<container>` (or equivalent)
- `docker logs --tail=200 <container>` for the changed service
- If behind Traefik: a relevant Traefik log excerpt for that router (only if failing)
**Gate 4 — confirm healthy**
Do not proceed until the user replies exactly:
- `CONFIRM HEALTHY: <service-name>`
If it is **not** healthy, stop and troubleshoot *only that service* until it is.
### Step 5 — commit/roll forward
Ask whether to commit the change now.
- If yes, generate a Conventional Commit message (e.g., `chore(<service>): pin image tag to <tag>`).
- Remind to ensure no `.env` files are staged.
**Gate 5 — next service**
Ask if they want to continue.
Required phrase to continue:
- `NEXT`
If not `NEXT`, stop.
## Output format
- Use short headings and compact bullets.
- Put terminal commands in fenced code blocks with `bash`.
- When referencing repo files/symbols, wrap them in backticks.

20
.github/prompts/session-status.prompt.md vendored
View File

@ -1,20 +0,0 @@
---
description: "VS Code Cognitive Reset: Scans active buffers to detect drift and realign."
---
# Cognitive Realignment (VS Code Edition)
## Phase 1: Context Retrieval (RAG)
**Execute these lookups to ground your analysis:**
1. **Search Workspace:** `@core.instructions.md` for "Cognitive Stabilization Protocol".
2. **Search Workspace:** `SESSION_SNAPSHOT*.md` (limit 1, sort newest) to retrieve the **Last Known Truth**.
3. **Analyze State:** Read the currently active file and the last 10 lines of the terminal (if accessible) to determine **Current Action**.
## Phase 2: The Drift Check
Compare **Current Action** (Step 3) against **Last Known Truth** (Step 2).
* **Drift Criteria:** Are we editing files unrelated to the Snapshot's "Next Session Priorities"?
* **Decision:** If yes, initiate **Pruning Sequence**.
## Phase 3: The Output
Generate the "Heads-Up Display" defined in the retrieved Protocol.
* **Action:** If a specific command is needed to get back on track (e.g., `git checkout main`), provide it.

0
.github/prompts/ansible-tutor.prompt.md → .github/prompts/tutor-ansible.prompt.md vendored
View File

0
.github/prompts/proxmox-tutor.prompt.md → .github/prompts/tutor-proxmox.prompt.md vendored
View File

0
.github/prompts/swarm-tutor.prompt.md → .github/prompts/tutor-swarm.prompt.md vendored
View File