docs: salvage homelab network readiness skill

Rebuild the useful homelab VLAN, DNS, and VPN planning surface from stale PR #1413 as a safety-first readiness checklist instead of raw router/firewall commands. Sync the catalog count from 202 to 203 skills and include the skill in the devops-infra install module and npm publish surface.
2026-05-12 15:47:27 +08:00 · 2026-05-11 13:14:28 -04:00
parent fd820d6306
commit de217ef910
10 changed files with 185 additions and 14 deletions
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -11,7 +11,7 @@
    {
      "name": "ecc",
      "source": "./",
-      "description": "The most comprehensive Claude Code plugin — 53 agents, 202 skills, 69 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning",
+      "description": "The most comprehensive Claude Code plugin — 53 agents, 203 skills, 69 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning",
      "version": "2.0.0-rc.1",
      "author": {
        "name": "Affaan Mustafa",
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
  "name": "ecc",
  "version": "2.0.0-rc.1",
-  "description": "Battle-tested Claude Code plugin for engineering teams — 53 agents, 202 skills, 69 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use",
+  "description": "Battle-tested Claude Code plugin for engineering teams — 53 agents, 203 skills, 69 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use",
  "author": {
    "name": "Affaan Mustafa",
    "url": "https://x.com/affaanmustafa"
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
 # Everything Claude Code (ECC) — Agent Instructions

-This is a **production-ready AI coding plugin** providing 53 specialized agents, 202 skills, 69 commands, and automated hook workflows for software development.
+This is a **production-ready AI coding plugin** providing 53 specialized agents, 203 skills, 69 commands, and automated hook workflows for software development.

 **Version:** 2.0.0-rc.1

@@ -146,7 +146,7 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat

 ```
 agents/          — 53 specialized subagents
-skills/          — 202 workflow skills and domain knowledge
+skills/          — 203 workflow skills and domain knowledge
 commands/        — 69 slash commands
 hooks/           — Trigger-based automations
 rules/           — Always-follow guidelines (common + per-language)
--- a/README.md
+++ b/README.md
@@ -89,7 +89,7 @@ This repo is the raw code only. The guides explain everything.
 ### v2.0.0-rc.1 — Surface Refresh, Operator Workflows, and ECC 2.0 Alpha (Apr 2026)

 - **Dashboard GUI** — New Tkinter-based desktop application (`ecc_dashboard.py` or `npm run dashboard`) with dark/light theme toggle, font customization, and project logo in header and taskbar.
- **Public surface synced to the live repo** — metadata, catalog counts, plugin manifests, and install-facing docs now match the actual OSS surface: 53 agents, 200 skills, and 69 legacy command shims.
+- **Public surface synced to the live repo** — metadata, catalog counts, plugin manifests, and install-facing docs now match the actual OSS surface: 53 agents, 203 skills, and 69 legacy command shims.
 - **Operator and outbound workflow expansion** — `brand-voice`, `social-graph-ranker`, `connections-optimizer`, `customer-billing-ops`, `ecc-tools-cost-audit`, `google-workspace-ops`, `project-flow-ops`, and `workspace-surface-audit` round out the operator lane.
 - **Media and launch tooling** — `manim-video`, `remotion-video-creation`, and upgraded social publishing surfaces make technical explainers and launch content part of the same system.
 - **Framework and product surface growth** — `nestjs-patterns`, richer Codex/OpenCode install surfaces, and expanded cross-harness packaging keep the repo usable beyond Claude Code alone.
@@ -351,7 +351,7 @@ If you stacked methods, clean up in this order:
 /plugin list ecc@ecc
 ```

-**That's it!** You now have access to 53 agents, 202 skills, and 69 legacy command shims.
+**That's it!** You now have access to 53 agents, 203 skills, and 69 legacy command shims.

 ### Dashboard GUI

@@ -1341,7 +1341,7 @@ The configuration is automatically detected from `.opencode/opencode.json`.
 |---------|-------------|----------|--------|
 | Agents | PASS: 53 agents | PASS: 12 agents | **Claude Code leads** |
 | Commands | PASS: 69 commands | PASS: 31 commands | **Claude Code leads** |
-| Skills | PASS: 202 skills | PASS: 37 skills | **Claude Code leads** |
+| Skills | PASS: 203 skills | PASS: 37 skills | **Claude Code leads** |
 | Hooks | PASS: 8 event types | PASS: 11 events | **OpenCode has more!** |
 | Rules | PASS: 29 rules | PASS: 13 instructions | **Claude Code leads** |
 | MCP Servers | PASS: 14 servers | PASS: Full | **Full parity** |
@@ -1446,7 +1446,7 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e
 |---------|------------|------------|-----------|----------|
 | **Agents** | 53 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 |
 | **Commands** | 69 | Shared | Instruction-based | 31 |
-| **Skills** | 202 | Shared | 10 (native format) | 37 |
+| **Skills** | 203 | Shared | 10 (native format) | 37 |
 | **Hook Events** | 8 types | 15 types | None yet | 11 types |
 | **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks |
 | **Rules** | 34 (common + lang) | 34 (YAML frontmatter) | Instruction-based | 13 instructions |
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -160,7 +160,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"
 /plugin list ecc@ecc
 ```

-**完成！** 你现在可以使用 53 个代理、202 个技能和 69 个命令。
+**完成！** 你现在可以使用 53 个代理、203 个技能和 69 个命令。

 ### multi-* 命令需要额外配置

--- a/docs/zh-CN/AGENTS.md
+++ b/docs/zh-CN/AGENTS.md
@@ -1,6 +1,6 @@
 # Everything Claude Code (ECC) — 智能体指令

-这是一个**生产就绪的 AI 编码插件**，提供 53 个专业代理、202 项技能、69 条命令以及自动化钩子工作流，用于软件开发。
+这是一个**生产就绪的 AI 编码插件**，提供 53 个专业代理、203 项技能、69 条命令以及自动化钩子工作流，用于软件开发。

 **版本:** 2.0.0-rc.1

@@ -147,7 +147,7 @@

 ```
 agents/          — 53 个专业子代理
-skills/          — 202 个工作流技能和领域知识
+skills/          — 203 个工作流技能和领域知识
 commands/        — 69 个斜杠命令
 hooks/           — 基于触发的自动化
 rules/           — 始终遵循的指导方针（通用 + 每种语言）
--- a/docs/zh-CN/README.md
+++ b/docs/zh-CN/README.md
@@ -224,7 +224,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"
 /plugin list ecc@ecc
 ```

-**搞定！** 你现在可以使用 53 个智能体、202 项技能和 69 个命令了。
+**搞定！** 你现在可以使用 53 个智能体、203 项技能和 69 个命令了。

 ***

@@ -1134,7 +1134,7 @@ opencode
 |---------|-------------|----------|--------|
 | 智能体 | PASS: 53 个 | PASS: 12 个 | **Claude Code 领先** |
 | 命令 | PASS: 69 个 | PASS: 31 个 | **Claude Code 领先** |
-| 技能 | PASS: 202 项 | PASS: 37 项 | **Claude Code 领先** |
+| 技能 | PASS: 203 项 | PASS: 37 项 | **Claude Code 领先** |
 | 钩子 | PASS: 8 种事件类型 | PASS: 11 种事件 | **OpenCode 更多！** |
 | 规则 | PASS: 29 条 | PASS: 13 条指令 | **Claude Code 领先** |
 | MCP 服务器 | PASS: 14 个 | PASS: 完整 | **完全对等** |
@@ -1242,7 +1242,7 @@ ECC 是**第一个最大化利用每个主要 AI 编码工具的插件**。以
 |---------|------------|------------|-----------|----------|
 | **智能体** | 53 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 |
 | **命令** | 69 | 共享 | 基于指令 | 31 |
-| **技能** | 202 | 共享 | 10 (原生格式) | 37 |
+| **技能** | 203 | 共享 | 10 (原生格式) | 37 |
 | **钩子事件** | 8 种类型 | 15 种类型 | 暂无 | 11 种类型 |
 | **钩子脚本** | 20+ 个脚本 | 16 个脚本 (DRY 适配器) | N/A | 插件钩子 |
 | **规则** | 34 (通用 + 语言) | 34 (YAML 前页) | 基于指令 | 13 条指令 |
--- a/manifests/install-modules.json
+++ b/manifests/install-modules.json
@@ -550,6 +550,7 @@
        "skills/cisco-ios-patterns",
        "skills/deployment-patterns",
        "skills/docker-patterns",
+        "skills/homelab-network-readiness",
        "skills/homelab-network-setup",
        "skills/netmiko-ssh-automation",
        "skills/network-bgp-diagnostics",
--- a/package.json
+++ b/package.json
@@ -160,6 +160,7 @@
    "skills/google-workspace-ops/",
    "skills/healthcare-phi-compliance/",
    "skills/hipaa-compliance/",
+    "skills/homelab-network-readiness/",
    "skills/homelab-network-setup/",
    "skills/hookify-rules/",
    "skills/inventory-demand-planning/",
--- a/skills/homelab-network-readiness/SKILL.md
+++ b/skills/homelab-network-readiness/SKILL.md
@@ -0,0 +1,169 @@
+---
+name: homelab-network-readiness
+description: Readiness checklist for homelab VLAN segmentation, local DNS filtering, and WireGuard-style remote access before changing router, firewall, DHCP, or VPN configuration.
+origin: community
+---
+
+# Homelab Network Readiness
+
+Use this skill before changing a home or small-lab network that mixes VLANs,
+Pi-hole or another local DNS resolver, firewall rules, and remote VPN access.
+
+This is a planning and review skill. Do not turn it into copy-paste router,
+firewall, or VPN configuration unless the target platform, current topology,
+rollback path, console access, and maintenance window are all known.
+
+## When to Use
+
+- Preparing to split a flat network into trusted, IoT, guest, server, or
+  management VLANs.
+- Moving DHCP clients to Pi-hole, AdGuard Home, Unbound, or another local DNS
+  resolver.
+- Adding WireGuard, Tailscale, ZeroTier, OpenVPN, or router-native VPN access.
+- Reviewing whether a homelab change can lock the operator out of the gateway,
+  switch, access point, DNS server, or VPN server.
+- Turning an informal home-network idea into a staged migration plan with
+  validation evidence.
+
+## Safety Rules
+
+- Keep the first answer read-only: inventory, risks, staged plan, validation,
+  and rollback.
+- Do not expose gateway admin panels, DNS resolvers, SSH, NAS consoles, or VPN
+  management UIs directly to the public internet.
+- Do not provide firewall, NAT, VLAN, DHCP, or VPN commands without a confirmed
+  platform and a rollback procedure.
+- Require out-of-band or same-room console access before changing management
+  VLANs, trunk ports, firewall default policies, or DHCP/DNS settings.
+- Keep a working path back to the internet before pointing the whole network at
+  a new DNS resolver or VPN route.
+- Treat IoT, guest, camera, and lab-server networks as different trust zones
+  until the operator explicitly chooses otherwise.
+
+## Required Inventory
+
+Collect this before giving implementation steps:
+
+| Area | Questions |
+| --- | --- |
+| Internet edge | What is the modem or ONT? Is the ISP router bridged or still routing? |
+| Gateway | What routes, firewalls, handles DHCP, and terminates VPNs? |
+| Switching | Which switch ports are uplinks, access ports, trunks, or unmanaged? |
+| Wi-Fi | Which SSIDs map to which networks, and are APs wired or mesh? |
+| Addressing | What subnets exist today, and which ranges conflict with VPN sites? |
+| DNS/DHCP | Which service currently hands out leases and resolver addresses? |
+| Management | How will the operator reach the gateway, switch, and AP after changes? |
+| Recovery | What can be reverted locally if DNS, DHCP, VLANs, or VPN routes break? |
+
+## VLAN And Trust-Zone Plan
+
+Start with intent rather than vendor syntax.
+
+| Zone | Typical contents | Default policy |
+| --- | --- | --- |
+| Trusted | Laptops, phones, admin workstations | Can reach shared services and management only when needed |
+| Servers | NAS, Home Assistant, lab hosts, DNS resolver | Accepts narrow inbound flows from trusted clients |
+| IoT | TVs, smart plugs, cameras, speakers | Internet access plus explicit exceptions only |
+| Guest | Visitor devices | Internet-only, no LAN reachability |
+| Management | Gateway, switches, APs, controllers | Reachable only from trusted admin devices |
+| VPN | Remote clients | Same or narrower access than trusted clients |
+
+Before recommending VLAN IDs or subnets, confirm:
+
+1. The gateway supports inter-VLAN routing and firewall rules.
+2. The switch supports the required tagged and untagged port behavior.
+3. The APs can map SSIDs to VLANs.
+4. The operator knows which port they are connected through during the change.
+5. The management network remains reachable after trunk and SSID changes.
+
+## DNS Filtering Readiness
+
+Pi-hole or another local resolver should be introduced as a dependency, not as a
+single point of failure.
+
+1. Give the resolver a reserved address before using it in DHCP options.
+2. Confirm it can resolve public DNS and local `home.arpa` names.
+3. Keep the gateway or a second resolver available as a temporary fallback.
+4. Test one client or one VLAN before changing every DHCP scope.
+5. Document which networks may bypass filtering and why.
+6. Check that blocking rules do not break captive portals, work VPNs, firmware
+   updates, or medical/security devices.
+
+Useful validation evidence:
+
+```text
+Client gets expected DHCP lease
+Client receives expected DNS resolver
+Public DNS lookup succeeds
+Local home.arpa lookup succeeds
+Blocked test domain is blocked only where intended
+Gateway and DNS admin interfaces are not reachable from guest or IoT networks
+```
+
+## Remote Access Readiness
+
+For WireGuard-style access, decide what the VPN is allowed to reach before
+generating keys or opening ports.
+
+| Mode | Use when | Risk notes |
+| --- | --- | --- |
+| Split tunnel to one subnet | Remote admin for NAS or lab hosts | Keep route list narrow |
+| Split tunnel to trusted services | Access selected apps by IP or DNS | Requires precise firewall rules |
+| Full tunnel | Untrusted networks or travel | More bandwidth and DNS responsibility |
+| Overlay VPN | Simpler remote access with identity controls | Still needs ACL review |
+
+Do not recommend port forwarding until the operator confirms:
+
+- The VPN endpoint is patched and actively maintained.
+- The forwarded port goes only to the VPN service, not an admin UI.
+- Dynamic DNS, public IP behavior, and ISP CGNAT status are understood.
+- Peer keys can be revoked without rebuilding the whole network.
+- Logs or connection status can verify who connected and when.
+
+## Change Sequence
+
+Prefer small, reversible changes:
+
+1. Snapshot the current topology, IP plan, DHCP settings, DNS settings, and
+   firewall rules.
+2. Reserve infrastructure addresses for gateway, DNS, controller, APs, NAS, and
+   VPN endpoint.
+3. Create the new zone or VLAN without moving critical devices.
+4. Move one test client and validate DHCP, DNS, routing, internet, and block
+   behavior.
+5. Add narrow firewall exceptions for required flows.
+6. Move one low-risk device group.
+7. Add VPN access with the narrowest route and firewall policy that satisfies
+   the use case.
+8. Document final state, known exceptions, and rollback commands or UI steps.
+
+## Review Checklist
+
+- Each network has a reason to exist and a clear trust boundary.
+- No management interface is reachable from guest, IoT, or the public internet.
+- DNS failure does not take down the operator's ability to recover locally.
+- DHCP scope changes were tested on one client before broad rollout.
+- VPN clients receive only the routes and DNS settings they need.
+- Firewall rules are default-deny between zones, with named exceptions.
+- The operator can still reach gateway, switch, AP, DNS, and VPN admin surfaces.
+- Rollback is documented in the same vocabulary as the chosen platform UI or
+  CLI.
+
+## Anti-Patterns
+
+- Segmenting networks before knowing which switch ports and SSIDs carry which
+  VLANs.
+- Moving the admin workstation off the only reachable management network.
+- Pointing all DHCP scopes at a Pi-hole before testing fallback DNS.
+- Publishing NAS, DNS, router, or hypervisor management directly to the
+  internet.
+- Treating VPN access as equivalent to full trusted-LAN access.
+- Adding allow-all firewall rules temporarily and forgetting to remove them.
+- Copying commands from another vendor or firmware version without checking the
+  exact platform syntax.
+
+## See Also
+
+- Skill: `homelab-network-setup`
+- Skill: `network-config-validation`
+- Skill: `network-interface-health`