From de217ef910807aa7474addaaa9dd197de584009d Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Mon, 11 May 2026 13:14:28 -0400 Subject: [PATCH] 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. --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- AGENTS.md | 4 +- README.md | 8 +- README.zh-CN.md | 2 +- docs/zh-CN/AGENTS.md | 4 +- docs/zh-CN/README.md | 6 +- manifests/install-modules.json | 1 + package.json | 1 + skills/homelab-network-readiness/SKILL.md | 169 ++++++++++++++++++++++ 10 files changed, 185 insertions(+), 14 deletions(-) create mode 100644 skills/homelab-network-readiness/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index ef54409c..5b528f80 100644 --- 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", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 5d3dd78c..ad890730 100644 --- 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" diff --git a/AGENTS.md b/AGENTS.md index 30ec15e5..a957a1ab 100644 --- 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) diff --git a/README.md b/README.md index 3d5e5b80..1be727b8 100644 --- 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 | diff --git a/README.zh-CN.md b/README.zh-CN.md index ee847fc9..c154d042 100644 --- 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-* 命令需要额外配置 diff --git a/docs/zh-CN/AGENTS.md b/docs/zh-CN/AGENTS.md index 47c4a094..afbad184 100644 --- 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/ — 始终遵循的指导方针（通用 + 每种语言） diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md index 063e5593..31fa7543 100644 --- 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 条指令 | diff --git a/manifests/install-modules.json b/manifests/install-modules.json index bc7eb2da..51c7640b 100644 --- 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", diff --git a/package.json b/package.json index fedd09b6..5aef0179 100644 --- 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/", diff --git a/skills/homelab-network-readiness/SKILL.md b/skills/homelab-network-readiness/SKILL.md new file mode 100644 index 00000000..9c090cb4 --- /dev/null +++ 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`