Infrastructure

---
name: claude-md-master
description: Master skill for CLAUDE.md lifecycle - create, update, improve with repo-verified content and multi-module support. Use when creating or updating CLAUDE.md files.
---

# CLAUDE.md Master (Create/Update/Improver)

## When to use
- User asks to create, improve, update, or standardize CLAUDE.md files.

## Core rules
- Only include info verified in repo or config.
- Never include secrets, tokens, credentials, or user data.
- Never include task-specific or temporary instructions.
- Keep concise: root <= 200 lines, module <= 120 lines.
- Use bullets; avoid long prose.
- Commands must be copy-pasteable and sourced from repo docs/scripts/CI.
- Skip empty sections; avoid filler.

## Mandatory inputs (analyze before generating)
- Build/package config relevant to detected stack (root + modules).
- Static analysis config used in repo (if present).
- Actual module structure and source patterns (scan real dirs/files).
- Representative source roots per module to extract:
  package/feature structure, key types, and annotations in use.

## Discovery (fast + targeted)
1. Locate existing CLAUDE.md variants: `CLAUDE.md`, `.claude.md`, `.claude.local.md`.
2. Identify stack and entry points via minimal reads:
   - `README.md`, relevant `docs/*`
   - Build/package files (see stack references)
   - Runtime/config: `Dockerfile`, `docker-compose.yml`, `.env.example`, `config/*`
   - CI: `.github/workflows/*`, `.gitlab-ci.yml`, `.circleci/*`
3. Extract commands only if they exist in repo scripts/config/docs.
4. Detect multi-module structure:
   - Android/Gradle: read `settings.gradle` or `settings.gradle.kts` includes.
   - iOS: detect multiple targets/workspaces in `*.xcodeproj`/`*.xcworkspace`.
   - If more than one module/target has `src/` or build config, plan module CLAUDE.md files.
5. For each module candidate, read its build file + minimal docs to capture
   module-specific purpose, entry points, and commands.
6. Scan source roots for:
   - Top-level package/feature folders and layer conventions.
   - Key annotations/types in use (per stack reference).
   - Naming conventions used in the codebase.
7. Capture non-obvious workflows/gotchas from docs or code patterns.

Performance:
- Prefer file listing + targeted reads.
- Avoid full-file reads when a section or symbol is enough.
- Skip large dirs: `node_modules`, `vendor`, `build`, `dist`.

## Stack-specific references (Pattern 2)
Read the relevant reference only when detection signals appear:
- Android/Gradle → `references/android.md`
- iOS/Xcode/Swift → `references/ios.md`
- PHP → `references/php.md`
- Go → `references/go.md`
- React (web) → `references/react-web.md`
- React Native → `references/react-native.md`
- Rust → `references/rust.md`
- Python → `references/python.md`
- Java/JVM → `references/java.md`
- Node tooling → `references/node.md`
- .NET/C# → `references/dotnet.md`
- Dart/Flutter → `references/flutter.md`
- Ruby/Rails → `references/ruby.md`
- Elixir/Erlang → `references/elixir.md`
- C/C++/CMake → `references/cpp.md`
- Other/Unknown → `references/generic.md` (fallback when no specific reference matches)

If multiple stacks are detected, read multiple references.
If no stack is recognized, use the generic reference.

## Multi-module output policy (mandatory when detected)
- Always create a root `CLAUDE.md`.
- Also create `CLAUDE.md` inside each meaningful module/target root.
  - "Meaningful" = has its own build config and `src/` (or equivalent).
  - Skip tooling-only dirs like `buildSrc`, `gradle`, `scripts`, `tools`.
- Module file must be module-specific and avoid duplication:
  - Include purpose, key paths, entry points, module tests, and module
    commands (if any).
  - Reference shared info via `@/CLAUDE.md`.

## Business module CLAUDE.md policy (all stacks)
For monorepo business logic directories (`src/`, `lib/`, `packages/`, `internal/`):
- Create `CLAUDE.md` for modules with >5 files OR own README
- Skip utility-only dirs: `Helper`, `Utils`, `Common`, `Shared`, `Exception`, `Trait`, `Constants`
- Layered structure not required; provide module info regardless of architecture
- Max 120 lines per module CLAUDE.md
- Reference root via `@/CLAUDE.md` for shared architecture/patterns
- Include: purpose, structure, key classes, dependencies, entry points

## Mandatory output sections (per module CLAUDE.md)
Include these sections if detected in codebase (skip only if not present):
- **Feature/component inventory**: list top-level dirs under source root
- **Core/shared modules**: utility, common, or shared code directories
- **Navigation/routing structure**: navigation graphs, routes, or routers
- **Network/API layer pattern**: API clients, endpoints, response wrappers
- **DI/injection pattern**: modules, containers, or injection setup
- **Build/config files**: module-specific configs (proguard, manifests, etc.)

See stack-specific references for exact patterns to detect and report.

## Update workflow (must follow)
1. Propose targeted additions only; show diffs per file.

2. Ask for approval before applying updates:

**Cursor IDE:**
Use the AskQuestion tool with these options:
- id: "approval"
- prompt: "Apply these CLAUDE.md updates?"
- options: [{"id": "yes", "label": "Yes, apply"}, {"id": "no", "label": "No, cancel"}]

**Claude Code (Terminal):**
Output the proposed changes and ask:
"Do you approve these updates? (yes/no)"
Stop and wait for user response before proceeding.

**Other Environments (Fallback):**
If no structured question tool is available:
1. Display proposed changes clearly
2. Ask: "Do you approve these updates? Reply 'yes' to apply or 'no' to cancel."
3. Wait for explicit user confirmation before proceeding

3. Apply updates, preserving custom content.

If no CLAUDE.md exists, propose a new file for approval.

## Content extraction rules (mandatory)
- From codebase only:
  - Extract: type/class/annotation names used, real path patterns,
    naming conventions.
  - Never: hardcoded values, secrets, API keys, business-specific logic.
  - Never: code snippets in Do/Do Not rules.

## Verification before writing
- [ ] Every rule references actual types/paths from codebase
- [ ] No code examples in Do/Do Not sections
- [ ] Patterns match what's actually in the codebase (not outdated)

## Content rules
- Include: commands, architecture summary, key paths, testing, gotchas, workflow quirks.
- Exclude: generic best practices, obvious info, unverified statements.
- Use `@path/to/file` imports to avoid duplication.
- Do/Do Not format is optional; keep only if already used in the file.
- Avoid code examples except short copy-paste commands.

## Existing file strategy
Detection:
- If `<!-- Generated by claude-md-editor skill -->` exists → subsequent run
- Else → first run

First run + existing file:
- Backup `CLAUDE.md` → `CLAUDE.md.bak`
- Use `.bak` as a source and extract only reusable, project-specific info
- Generate a new concise file and add the marker

Subsequent run:
- Preserve custom sections and wording unless outdated or incorrect
- Update only what conflicts with current repo state
- Add missing sections only if they add real value

Never modify `.claude.local.md`.

## Output
After updates, print a concise report:
```
## CLAUDE.md Update Report
- /CLAUDE.md [CREATED | BACKED_UP+CREATED | UPDATED]
- /<module>/CLAUDE.md [CREATED | UPDATED]
- Backups: list any `.bak` files
```

## Validation checklist
- Description is specific and includes trigger terms
- No placeholders remain
- No secrets included
- Commands are real and copy-pasteable
- Report-first rule respected
- References are one level deep
FILE:README.md
# claude-md-master

Master skill for the CLAUDE.md lifecycle: create, update, and improve files
using repo-verified data, with multi-module support and stack-specific rules.

## Overview
- Goal: produce accurate, concise `CLAUDE.md` files from real repo data
- Scope: root + meaningful modules, with stack-specific detection
- Safeguards: no secrets, no filler, explicit approval before writes

## How the AI discovers and uses this skill
- Discovery: the tool learns this skill because it exists in the
  repo skills catalog (installed/available in the environment)
- Automatic use: when a request includes "create/update/improve
  CLAUDE.md", the tool selects this skill as the best match
- Manual use: the operator can explicitly invoke `/claude-md-master`
  to force this workflow
- Run behavior: it scans repo docs/config/source, proposes changes,
  and waits for explicit approval before writing files

## Audience
- AI operators using skills in Cursor/Claude Code
- Maintainers who evolve the rules and references

## What it does
- Generates or updates `CLAUDE.md` with verified, repo-derived content
- Enforces strict safety and concision rules (no secrets, no filler)
- Detects multi-module repos and produces module-level `CLAUDE.md`
- Uses stack-specific references to capture accurate patterns

## When to use
- A user asks to create, improve, update, or standardize `CLAUDE.md`
- A repo needs consistent, verified guidance for AI workflows

## Inputs required (must be analyzed)
- Repo docs: `README.md`, `docs/*` (if present)
- Build/config files relevant to detected stack(s)
- Runtime/config: `Dockerfile`, `.env.example`, `config/*` (if present)
- CI: `.github/workflows/*`, `.gitlab-ci.yml`, `.circleci/*` (if present)
- Source roots to extract real structure, types, annotations, naming

## Output
- Root `CLAUDE.md` (always)
- Module `CLAUDE.md` for meaningful modules (build config + `src/`)
- Concise update report listing created/updated files and backups

## Workflow (high level)
1. Locate existing `CLAUDE.md` variants and detect first vs. subsequent run
2. Identify stack(s) and multi-module structure
3. Read relevant docs/configs/CI for real commands and workflow
4. Scan source roots for structure, key types, annotations, patterns
5. Generate root + module files, avoiding duplication via `@/CLAUDE.md`
6. Request explicit approval before applying updates
7. Apply changes and print the update report

## Core rules and constraints
- Only include info verified in repo; never add secrets
- Keep concise: root <= 200 lines, module <= 120 lines
- Commands must be real and copy-pasteable from repo docs/scripts/CI
- Skip empty sections; avoid generic guidance
- Never modify `.claude.local.md`
- Avoid code examples in Do/Do Not sections

## Multi-module policy (summary)
- Always create root `CLAUDE.md`
- Create module-level files only for meaningful modules
- Skip tooling-only dirs (e.g., `buildSrc`, `gradle`, `scripts`, `tools`)
- Business modules get their own file when >5 files or own README

## References (stack-specific guides)
Each reference defines detection signals, pre-gen sources, codebase scan
targets, mandatory output items, command sources, and key paths.

- `references/android.md` — Android/Gradle
- `references/ios.md` — iOS/Xcode/Swift
- `references/react-web.md` — React web apps
- `references/react-native.md` — React Native
- `references/node.md` — Node tooling (generic)
- `references/python.md` — Python
- `references/java.md` — Java/JVM
- `references/dotnet.md` — .NET (C#/F#)
- `references/go.md` — Go
- `references/rust.md` — Rust
- `references/flutter.md` — Dart/Flutter
- `references/ruby.md` — Ruby/Rails
- `references/php.md` — PHP (Laravel/Symfony/CI/Phalcon)
- `references/elixir.md` — Elixir/Erlang
- `references/cpp.md` — C/C++
- `references/generic.md` — Fallback when no stack matches

## Extending the skill
- Add a new `references/<stack>.md` using the same template
- Keep detection signals and mandatory outputs specific and verifiable
- Do not introduce unverified commands or generic advice

## Quality checklist
- Every rule references actual types/paths from the repo
- No placeholders remain
- No secrets included
- Commands are real and copy-pasteable
- Report-first rule respected; references are one level deep
FILE:references/android.md
# Android (Gradle)

## Detection signals
- `settings.gradle` or `settings.gradle.kts`
- `build.gradle` or `build.gradle.kts`
- `gradle.properties`
- `gradle/libs.versions.toml`
- `gradlew`
- `gradle/wrapper/gradle-wrapper.properties`
- `app/src/main/AndroidManifest.xml`

## Multi-module signals
- Multiple `include(...)` or `includeBuild(...)` entries in `settings.gradle*`
- More than one module dir with `build.gradle*` and `src/`
- Common module roots like `feature/`, `core/`, `library/` (if present)

## Before generating, analyze these sources
- `settings.gradle` or `settings.gradle.kts`
- `build.gradle` or `build.gradle.kts` (root and modules)
- `gradle/libs.versions.toml`
- `gradle.properties`
- `config/detekt/detekt.yml` (if present)
- `app/src/main/AndroidManifest.xml` (or module manifests)

## Codebase scan (Android-specific)
- Source roots per module: `*/src/main/java/`, `*/src/main/kotlin/`
- Package tree for feature/layer folders (record only if present):
  `features/`, `core/`, `common/`, `data/`, `domain/`, `presentation/`,
  `ui/`, `di/`, `navigation/`, `network/`
- Annotation usage (record only if present):
  Hilt (`@HiltAndroidApp`, `@AndroidEntryPoint`, `@HiltViewModel`,
  `@Module`, `@InstallIn`, `@Provides`, `@Binds`),
  Compose (`@Composable`, `@Preview`),
  Room (`@Entity`, `@Dao`, `@Database`),
  WorkManager (`@HiltWorker`, `ListenableWorker`, `CoroutineWorker`),
  Serialization (`@Serializable`, `@Parcelize`),
  Retrofit (`@GET`, `@POST`, `@PUT`, `@DELETE`, `@Body`, `@Query`)
- Navigation patterns (record only if present): `NavHost`, `composable`

## Mandatory output (Android module CLAUDE.md)
Include these if detected (list actual names found):
- **Features inventory**: list dirs under `features/` (e.g., homepage, payment, auth)
- **Core modules**: list dirs under `core/` (e.g., data, network, localization)
- **Navigation graphs**: list `*Graph.kt` or `*Navigator*.kt` files
- **Hilt modules**: list `@Module` classes or `di/` package contents
- **Retrofit APIs**: list `*Api.kt` interfaces
- **Room databases**: list `@Database` classes
- **Workers**: list `@HiltWorker` classes
- **Proguard**: mention `proguard-rules.pro` if present

## Command sources
- README/docs or CI invoking Gradle wrapper
- Repo scripts that call `./gradlew`
- `./gradlew assemble`, `./gradlew test`, `./gradlew lint` usage in docs/scripts
- Only include commands present in repo

## Key paths to mention (only if present)
- `app/src/main/`, `app/src/main/res/`
- `app/src/main/java/`, `app/src/main/kotlin/`
- `app/src/test/`, `app/src/androidTest/`
FILE:references/cpp.md
# C / C++

## Detection signals
- `CMakeLists.txt`
- `meson.build`
- `Makefile`
- `conanfile.*`, `vcpkg.json`
- `compile_commands.json`
- `src/`, `include/`

## Multi-module signals
- `CMakeLists.txt` with `add_subdirectory(...)`
- Multiple `CMakeLists.txt` or `meson.build` in subdirs
- `libs/`, `apps/`, or `modules/` with their own build files

## Before generating, analyze these sources
- `CMakeLists.txt` / `meson.build` / `Makefile`
- `conanfile.*`, `vcpkg.json` (if present)
- `compile_commands.json` (if present)
- `src/`, `include/`, `tests/`, `libs/`

## Codebase scan (C/C++-specific)
- Source roots: `src/`, `include/`, `tests/`, `libs/`
- Library/app split (record only if present):
  `src/lib`, `src/app`, `src/bin`
- Namespaces and class prefixes (record only if present)
- CMake targets (record only if present):
  `add_library`, `add_executable`

## Mandatory output (C/C++ module CLAUDE.md)
Include these if detected (list actual names found):
- **Libraries**: list library targets
- **Executables**: list executable targets
- **Headers**: list public header directories
- **Modules/components**: list subdirectories with build files
- **Dependencies**: list Conan/vcpkg dependencies (if any)

## Command sources
- README/docs or CI invoking `cmake`, `ninja`, `make`, or `meson`
- Repo scripts that call build tools
- Only include commands present in repo

## Key paths to mention (only if present)
- `src/`, `include/`
- `tests/`, `libs/`
FILE:references/dotnet.md
# .NET (C# / F#)

## Detection signals
- `*.sln`
- `*.csproj`, `*.fsproj`, `*.vbproj`
- `global.json`
- `Directory.Build.props`, `Directory.Build.targets`
- `nuget.config`
- `Program.cs`
- `Startup.cs`
- `appsettings*.json`

## Multi-module signals
- `*.sln` with multiple project entries
- Multiple `*.*proj` files under `src/` and `tests/`
- `Directory.Build.*` managing shared settings across projects

## Before generating, analyze these sources
- `*.sln`, `*.csproj` / `*.fsproj` / `*.vbproj`
- `Directory.Build.props`, `Directory.Build.targets`
- `global.json`, `nuget.config`
- `Program.cs` / `Startup.cs`
- `appsettings*.json`

## Codebase scan (.NET-specific)
- Source roots: `src/`, `tests/`, project folders with `*.csproj`
- Layer folders (record only if present):
  `Controllers`, `Services`, `Repositories`, `Domain`, `Infrastructure`
- ASP.NET attributes (record only if present):
  `[ApiController]`, `[Route]`, `[HttpGet]`, `[HttpPost]`, `[Authorize]`
- EF Core usage (record only if present):
  `DbContext`, `Migrations`, `[Key]`, `[Table]`

## Mandatory output (.NET module CLAUDE.md)
Include these if detected (list actual names found):
- **Controllers**: list `[ApiController]` classes
- **Services**: list service classes
- **Repositories**: list repository classes
- **Entities**: list EF Core entity classes
- **DbContext**: list database context classes
- **Middleware**: list custom middleware
- **Configuration**: list config sections or options classes

## Command sources
- README/docs or CI invoking `dotnet`
- Repo scripts like `build.ps1`, `build.sh`
- `dotnet run`, `dotnet test` usage in docs/scripts
- Only include commands present in repo

## Key paths to mention (only if present)
- `src/`, `tests/`
- `appsettings*.json`
- `Controllers/`, `Models/`, `Views/`, `wwwroot/`
FILE:references/elixir.md
# Elixir / Erlang

## Detection signals
- `mix.exs`, `mix.lock`
- `config/config.exs`
- `lib/`, `test/`
- `apps/` (umbrella)
- `rel/`

## Multi-module signals
- Umbrella with `apps/` containing multiple `mix.exs`
- Root `mix.exs` with `apps_path`

## Before generating, analyze these sources
- Root `mix.exs`, `mix.lock`
- `config/config.exs`
- `apps/*/mix.exs` (umbrella)
- `lib/`, `test/`, `rel/`

## Codebase scan (Elixir-specific)
- Source roots: `lib/`, `test/`, `apps/*/lib` (umbrella)
- Phoenix structure (record only if present):
  `lib/*_web/`, `controllers`, `views`, `channels`, `routers`
- Ecto usage (record only if present):
  `schema`, `Repo`, `migrations`
- Contexts/modules (record only if present):
  `lib/*/` context modules and `*_context.ex`

## Mandatory output (Elixir module CLAUDE.md)
Include these if detected (list actual names found):
- **Contexts**: list context modules
- **Schemas**: list Ecto schema modules
- **Controllers**: list Phoenix controller modules
- **Channels**: list Phoenix channel modules
- **Workers**: list background job modules (Oban, etc.)
- **Umbrella apps**: list apps under umbrella (if any)

## Command sources
- README/docs or CI invoking `mix`
- Repo scripts that call `mix`
- Only include commands present in repo

## Key paths to mention (only if present)
- `lib/`, `test/`, `config/`
- `apps/`, `rel/`
FILE:references/flutter.md
# Dart / Flutter

## Detection signals
- `pubspec.yaml`, `pubspec.lock`
- `analysis_options.yaml`
- `lib/`
- `android/`, `ios/`, `web/`, `macos/`, `windows/`, `linux/`

## Multi-module signals
- `melos.yaml` (Flutter monorepo)
- Multiple `pubspec.yaml` under `packages/`, `apps/`, or `plugins/`

## Before generating, analyze these sources
- `pubspec.yaml`, `pubspec.lock`
- `analysis_options.yaml`
- `melos.yaml` (if monorepo)
- `lib/`, `test/`, and platform folders (`android/`, `ios/`, etc.)

## Codebase scan (Flutter-specific)
- Source roots: `lib/`, `test/`
- Entry point (record only if present): `lib/main.dart`
- Layer folders (record only if present):
  `features/`, `core/`, `data/`, `domain/`, `presentation/`
- State management (record only if present):
  `Bloc`, `Cubit`, `ChangeNotifier`, `Provider`, `Riverpod`
- Widget naming (record only if present):
  `*Screen`, `*Page`

## Mandatory output (Flutter module CLAUDE.md)
Include these if detected (list actual names found):
- **Features**: list dirs under `features/` or `lib/`
- **Core modules**: list dirs under `core/` (if present)
- **State management**: list Bloc/Cubit/Provider setup
- **Repositories**: list repository classes
- **Data sources**: list remote/local data source classes
- **Widgets**: list shared widget directories

## Command sources
- README/docs or CI invoking `flutter`
- Repo scripts that call `flutter` or `dart`
- `flutter run`, `flutter test`, `flutter pub get` usage in docs/scripts
- Only include commands present in repo

## Key paths to mention (only if present)
- `lib/`, `test/`
- `android/`, `ios/`
FILE:references/generic.md
# Generic / Unknown Stack

Use this reference when no specific stack reference matches.

## Detection signals (common patterns)
- `README.md`, `CONTRIBUTING.md`
- `Makefile`, `Taskfile.yml`, `justfile`
- `Dockerfile`, `docker-compose.yml`
- `.env.example`, `config/`
- CI files: `.github/workflows/`, `.gitlab-ci.yml`, `.circleci/`

## Before generating, analyze these sources
- `README.md` - project overview, setup instructions, commands
- Build/package files in root (any recognizable format)
- `Makefile`, `Taskfile.yml`, `justfile`, `scripts/` (if present)
- CI/CD configs for build/test commands
- `Dockerfile` for runtime info

## Codebase scan (generic)
- Identify source root: `src/`, `lib/`, `app/`, `pkg/`, or root
- Layer folders (record only if present):
  `controllers`, `services`, `models`, `handlers`, `utils`, `config`
- Entry points: `main.*`, `index.*`, `app.*`, `server.*`
- Test location: `tests/`, `test/`, `spec/`, `__tests__/`, or co-located

## Mandatory output (generic CLAUDE.md)
Include these if detected (list actual names found):
- **Entry points**: main files, startup scripts
- **Source structure**: top-level dirs under source root
- **Config files**: environment, settings, secrets template
- **Build system**: detected build tool and config location
- **Test setup**: test framework and run command

## Command sources
- README setup/usage sections
- `Makefile` targets, `Taskfile.yml` tasks, `justfile` recipes
- CI workflow steps (build, test, lint)
- `scripts/` directory
- Only include commands present in repo

## Key paths to mention (only if present)
- Source root and its top-level structure
- Config/environment files
- Test directory
- Documentation location
- Build output directory
FILE:references/go.md
# Go

## Detection signals
- `go.mod`, `go.sum`, `go.work`
- `cmd/`, `internal/`
- `main.go`
- `magefile.go`
- `Taskfile.yml`

## Multi-module signals
- `go.work` with multiple module paths
- Multiple `go.mod` files in subdirs
- `apps/` or `services/` each with its own `go.mod`

## Before generating, analyze these sources
- `go.work`, `go.mod`, `go.sum`
- `cmd/`, `internal/`, `pkg/` layout
- `Makefile`, `Taskfile.yml`, `magefile.go` (if present)

## Codebase scan (Go-specific)
- Source roots: `cmd/`, `internal/`, `pkg/`, `api/`
- Layer folders (record only if present):
  `handler`, `service`, `repository`, `store`, `config`
- Framework markers (record only if present):
  `gin`, `echo`, `fiber`, `chi` imports
- Entry points (record only if present):
  `cmd/*/main.go`, `main.go`

## Mandatory output (Go module CLAUDE.md)
Include these if detected (list actual names found):
- **Commands**: list binaries under `cmd/`
- **Handlers**: list HTTP handler packages
- **Services**: list service packages
- **Repositories**: list repository or store packages
- **Models**: list domain model packages
- **Config**: list config loading packages

## Command sources
- README/docs or CI
- `Makefile`, `Taskfile.yml`, or repo scripts invoking Go tools
- `go test ./...`, `go run` usage in docs/scripts
- Only include commands present in repo

## Key paths to mention (only if present)
- `cmd/`, `internal/`, `pkg/`, `api/`
- `tests/` or `*_test.go` layout
FILE:references/ios.md
# iOS (Xcode/Swift)

## Detection signals
- `Package.swift`
- `*.xcodeproj` or `*.xcworkspace`
- `Podfile`, `Cartfile`
- `Project.swift`, `Tuist/`
- `fastlane/Fastfile`
- `*.xcconfig`
- `Sources/` or `Tests/` (SPM layouts)

## Multi-module signals
- Multiple targets/projects in `*.xcworkspace` or `*.xcodeproj`
- `Package.swift` with multiple targets/products
- `Sources/<TargetName>` and `Tests/<TargetName>` layout
- `Project.swift` defining multiple targets (Tuist)

## Before generating, analyze these sources
- `Package.swift` (SPM)
- `*.xcodeproj/project.pbxproj` or `*.xcworkspace/contents.xcworkspacedata`
- `Podfile`, `Cartfile` (if present)
- `Project.swift` / `Tuist/` (if present)
- `fastlane/Fastfile` (if present)
- `Sources/` and `Tests/` layout for targets

## Codebase scan (iOS-specific)
- Source roots: `Sources/`, `Tests/`, `ios/` (if present)
- Feature/layer folders (record only if present):
  `Features/`, `Core/`, `Services/`, `Networking/`, `UI/`, `Domain/`, `Data/`
- SwiftUI usage (record only if present):
  `@main`, `App`, `@State`, `@StateObject`, `@ObservedObject`,
  `@Environment`, `@EnvironmentObject`, `@Binding`
- UIKit/lifecycle (record only if present):
  `UIApplicationDelegate`, `SceneDelegate`, `UIViewController`
- Combine/concurrency (record only if present):
  `@Published`, `Publisher`, `AnyCancellable`, `@MainActor`, `Task`

## Mandatory output (iOS module CLAUDE.md)
Include these if detected (list actual names found):
- **Features inventory**: list dirs under `Features/` or feature targets
- **Core modules**: list dirs under `Core/`, `Services/`, `Networking/`
- **Navigation**: list coordinators, routers, or SwiftUI navigation files
- **DI container**: list DI setup (Swinject, Factory, manual containers)
- **Network layer**: list API clients or networking services
- **Persistence**: list CoreData models or other storage classes

## Command sources
- README/docs or CI invoking Xcode or Swift tooling
- Repo scripts that call Xcode/Swift tools
- `xcodebuild`, `swift build`, `swift test` usage in docs/scripts
- Only include commands present in repo

## Key paths to mention (only if present)
- `Sources/`, `Tests/`
- `fastlane/`
- `ios/` (React Native or multi-platform repos)
FILE:references/java.md
# Java / JVM

## Detection signals
- `pom.xml` or `build.gradle*`
- `settings.gradle`, `gradle.properties`
- `mvnw`, `gradlew`
- `gradle/wrapper/gradle-wrapper.properties`
- `src/main/java`, `src/test/java`, `src/main/kotlin`
- `src/main/resources/application.yml`, `src/main/resources/application.properties`

## Multi-module signals
- `settings.gradle*` includes multiple modules
- Parent `pom.xml` with `<modules>` (packaging `pom`)
- Multiple `build.gradle*` or `pom.xml` files in subdirs

## Before generating, analyze these sources
- `settings.gradle*` and `build.gradle*` (if Gradle)
- Parent and module `pom.xml` (if Maven)
- `gradle/libs.versions.toml` (if present)
- `gradle.properties` / `mvnw` / `gradlew`
- `src/main/resources/application.yml|application.properties` (if present)

## Codebase scan (Java/JVM-specific)
- Source roots: `src/main/java`, `src/main/kotlin`, `src/test/java`, `src/test/kotlin`
- Package/layer folders (record only if present):
  `controller`, `service`, `repository`, `domain`, `model`, `dto`, `config`, `client`
- Framework annotations (record only if present):
  `@SpringBootApplication`, `@RestController`, `@Controller`, `@Service`,
  `@Repository`, `@Component`, `@Configuration`, `@Bean`, `@Transactional`
- Persistence/validation (record only if present):
  `@Entity`, `@Table`, `@Id`, `@OneToMany`, `@ManyToOne`, `@Valid`, `@NotNull`
- Entry points (record only if present):
  `*Application` classes with `main`

## Mandatory output (Java/JVM module CLAUDE.md)
Include these if detected (list actual names found):
- **Controllers**: list `@RestController` or `@Controller` classes
- **Services**: list `@Service` classes
- **Repositories**: list `@Repository` classes or JPA interfaces
- **Entities**: list `@Entity` classes
- **Configuration**: list `@Configuration` classes
- **Security**: list security config or auth filters
- **Profiles**: list Spring profiles in use

## Command sources
- Maven/Gradle wrapper scripts
- README/docs or CI
- `./mvnw spring-boot:run`, `./gradlew bootRun` usage in docs/scripts
- Only include commands present in repo

## Key paths to mention (only if present)
- `src/main/java`, `src/test/java`
- `src/main/kotlin`, `src/test/kotlin`
- `src/main/resources`, `src/test/resources`
- `src/main/java/**/controller`, `src/main/java/**/service`, `src/main/java/**/repository`
FILE:references/node.md
# Node Tooling (generic)

## Detection signals
- `package.json`
- `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`
- `.nvmrc`, `.node-version`
- `tsconfig.json`
- `.npmrc`, `.yarnrc.yml`
- `next.config.*`, `nuxt.config.*`
- `nest-cli.json`, `svelte.config.*`, `astro.config.*`

## Multi-module signals
- `pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`, `rush.json`
- Root `package.json` with `workspaces`
- Multiple `package.json` under `apps/`, `packages/`

## Before generating, analyze these sources
- Root `package.json` and workspace config (`pnpm-workspace.yaml`, `lerna.json`,
  `nx.json`, `turbo.json`, `rush.json`)
- `apps/*/package.json`, `packages/*/package.json` (if monorepo)
- `tsconfig.json` or `jsconfig.json`
- Framework config: `next.config.*`, `nuxt.config.*`, `nest-cli.json`,
  `svelte.config.*`, `astro.config.*` (if present)

## Codebase scan (Node-specific)
- Source roots: `src/`, `lib/`, `apps/`, `packages/`
- Folder patterns (record only if present):
  `routes`, `controllers`, `services`, `middlewares`, `handlers`,
  `utils`, `config`, `models`, `schemas`
- Framework markers (record only if present):
  Express (`express()`, `Router`), Koa (`new Koa()`),
  Fastify (`fastify()`), Nest (`@Controller`, `@Module`, `@Injectable`)
- Full-stack layouts (record only if present):
  Next/Nuxt (`pages/`, `app/`, `server/`)

## Mandatory output (Node module CLAUDE.md)
Include these if detected (list actual names found):
- **Routes/pages**: list route files or page components
- **Controllers/handlers**: list controller or handler files
- **Services**: list service classes or modules
- **Middlewares**: list middleware files
- **Models/schemas**: list data models or validation schemas
- **State management**: list store setup (Redux, Zustand, etc.)
- **API clients**: list external API client modules

## Command sources
- `package.json` scripts
- README/docs or CI
- `npm|yarn|pnpm` script usage in docs/scripts
- Only include commands present in repo

## Key paths to mention (only if present)
- `src/`, `lib/`
- `tests/`
- `apps/`, `packages/` (monorepos)
- `pages/`, `app/`, `server/`, `api/`
- `controllers/`, `services/`
FILE:references/php.md
# PHP

## Detection signals
- `composer.json`, `composer.lock`
- `public/index.php`
- `artisan`, `spark`, `bin/console` (framework entry points)
- `phpunit.xml`, `phpstan.neon`, `phpstan.neon.dist`, `psalm.xml`
- `config/app.php`
- `routes/web.php`, `routes/api.php`
- `config/packages/` (Symfony)
- `app/Config/` (CI4)
- `ext-phalcon` in composer.json (Phalcon)
- `phalcon/ide-stubs`, `phalcon/devtools` (Phalcon)

## Multi-module signals
- `modules/` or `app/Modules/` (HMVC style)
- `app/Config/Modules.php`, `app/Config/Autoload.php` (CI4)
- Multiple PSR-4 roots in `composer.json`
- Multiple `composer.json` under `packages/` or `apps/`
- `apps/` with subdirectories containing `Module.php` or `controllers/`

## Before generating, analyze these sources
- `composer.json`, `composer.lock`
- `config/` and `routes/` (framework configs)
- `app/Config/*` (CI4)
- `modules/` or `app/Modules/` (if HMVC)
- `phpunit.xml`, `phpstan.neon*`, `psalm.xml` (if present)
- `bin/worker.php`, `bin/console.php` (CLI entry points)

## Codebase scan (PHP-specific)
- Source roots: `app/`, `src/`, `modules/`, `packages/`, `apps/`
- Laravel structure (record only if present):
  `app/Http/Controllers`, `app/Models`, `database/migrations`,
  `routes/*.php`, `resources/views`
- Symfony structure (record only if present):
  `src/Controller`, `src/Entity`, `config/packages`, `templates`
- CodeIgniter structure (record only if present):
  `app/Controllers`, `app/Models`, `app/Views`, `app/Config/Routes.php`,
  `app/Database/Migrations`
- Phalcon structure (record only if present):
  `apps/*/controllers/`, `apps/*/Module.php`, `models/`
- Attributes/annotations (record only if present):
  `#[Route]`, `#[Entity]`, `#[ORM\\Column]`

## Business module discovery
Scan these paths based on detected framework:
- Laravel: `app/Services/`, `app/Domains/`, `app/Modules/`, `packages/`
- Symfony: `src/` top-level directories
- CodeIgniter: `app/Modules/`, `modules/`
- Phalcon: `src/`, `apps/*/`
- Generic: `src/`, `lib/`

For each path:
- List top 5-10 largest modules by file count
- For each significant module (>5 files), note its purpose if inferable from name
- Identify layered patterns if present: `*/Repository/`, `*/Service/`, `*/Controller/`, `*/Action/`

## Module-level CLAUDE.md signals
Scan these paths for significant modules (framework-specific):
- `src/` - Symfony, Phalcon, custom frameworks
- `app/Services/`, `app/Domains/` - Laravel domain-driven
- `app/Modules/`, `modules/` - Laravel/CI4 HMVC
- `packages/` - Laravel internal packages
- `apps/` - Phalcon multi-app

Create `<path>/<Module>/CLAUDE.md` when:
- Threshold: module has >5 files OR has own `README.md`
- Skip utility dirs: `Helper/`, `Exception/`, `Trait/`, `Contract/`, `Interface/`, `Constants/`, `Support/`
- Layered structure not required; provide module info regardless of architecture

### Module CLAUDE.md content (max 120 lines)
- Purpose: 1-2 sentence module description
- Structure: list subdirectories (Service/, Repository/, etc.)
- Key classes: main service/manager/action classes
- Dependencies: other modules this depends on (via use statements)
- Entry points: main public interfaces/facades
- Framework-specific: ServiceProvider (Laravel), Module.php (Phalcon/CI4)

## Worker/Job detection
- `bin/worker.php` or similar worker entry points
- `*/Job/`, `*/Jobs/`, `*/Worker/` directories
- Queue config files (`queue.php`, `rabbitmq.php`, `amqp.php`)
- List job classes if present

## API versioning detection
- `routes_v*.php` or `routes/v*/` patterns
- `controllers/v*/` directory structure
- Note current/active API version from route files or config

## Mandatory output (PHP module CLAUDE.md)
Include these if detected (list actual names found):
- **Controllers**: list controller directories/classes
- **Models**: list model/entity classes or directory
- **Services**: list service classes or directory
- **Repositories**: list repository classes or directory
- **Routes**: list route files and versioning pattern
- **Migrations**: mention migrations dir and file count
- **Middleware**: list middleware classes
- **Views/templates**: mention view engine and layout
- **Workers/Jobs**: list job classes if present
- **Business modules**: list top modules from detected source paths by size

## Command sources
- `composer.json` scripts
- README/docs or CI
- `php artisan`, `bin/console` usage in docs/scripts
- `bin/worker.php` commands
- Only include commands present in repo

## Key paths to mention (only if present)
- `app/`, `src/`, `apps/`
- `public/`, `routes/`, `config/`, `database/`
- `app/Http/`, `resources/`, `storage/` (Laravel)
- `templates/` (Symfony)
- `app/Controllers/`, `app/Views/` (CI4)
- `apps/*/controllers/`, `models/` (Phalcon)
- `tests/`, `tests/acceptance/`, `tests/unit/`
FILE:references/python.md
# Python

## Detection signals
- `pyproject.toml`
- `requirements.txt`, `requirements-dev.txt`, `Pipfile`, `poetry.lock`
- `tox.ini`, `pytest.ini`
- `manage.py`
- `setup.py`, `setup.cfg`
- `settings.py`, `urls.py` (Django)

## Multi-module signals
- Multiple `pyproject.toml`/`setup.py`/`setup.cfg` in subdirs
- `packages/` or `apps/` each with its own package config
- Django-style `apps/` with multiple `apps.py` (if present)

## Before generating, analyze these sources
- `pyproject.toml` or `setup.py` / `setup.cfg`
- `requirements*.txt`, `Pipfile`, `poetry.lock`
- `tox.ini`, `pytest.ini`
- `manage.py`, `settings.py`, `urls.py` (if Django)
- Package roots under `src/`, `app/`, `packages/` (if present)

## Codebase scan (Python-specific)
- Source roots: `src/`, `app/`, `packages/`, `tests/`
- Folder patterns (record only if present):
  `api`, `routers`, `views`, `services`, `repositories`,
  `models`, `schemas`, `utils`, `config`
- Django structure (record only if present):
  `apps.py`, `models.py`, `views.py`, `urls.py`, `migrations/`, `settings.py`
- FastAPI/Flask markers (record only if present):
  `FastAPI()`, `APIRouter`, `@app.get`, `@router.post`,
  `Flask(__name__)`, `Blueprint`
- Type model usage (record only if present):
  `pydantic.BaseModel`, `TypedDict`, `dataclass`

## Mandatory output (Python module CLAUDE.md)
Include these if detected (list actual names found):
- **Routers/views**: list API router or view files
- **Services**: list service modules
- **Models/schemas**: list data models (Pydantic, SQLAlchemy, Django)
- **Repositories**: list repository or DAO modules
- **Migrations**: mention migrations dir
- **Middleware**: list middleware classes
- **Django apps**: list installed apps (if Django)

## Command sources
- `pyproject.toml` tool sections
- README/docs or CI
- Repo scripts invoking Python tools
- `python manage.py`, `pytest`, `tox` usage in docs/scripts
- Only include commands present in repo

## Key paths to mention (only if present)
- `src/`, `app/`, `scripts/`
- `templates/`, `static/`
- `tests/`
FILE:references/react-native.md
# React Native

## Detection signals
- `package.json` with `react-native`
- `react-native.config.js`
- `metro.config.js`
- `ios/`, `android/`
- `babel.config.js`, `app.json`, `app.config.*`
- `eas.json`, `expo` in `package.json`

## Multi-module signals
- `pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`
- Root `package.json` with `workspaces`
- `packages/` or `apps/` each with `package.json`

## Before generating, analyze these sources
- Root `package.json` and workspace config (`pnpm-workspace.yaml`, `lerna.json`,
  `nx.json`, `turbo.json`)
- `react-native.config.js`, `metro.config.js`
- `ios/` and `android/` native folders
- `app.json` / `app.config.*` / `eas.json` (if Expo)

## Codebase scan (React Native-specific)
- Source roots: `src/`, `app/`
- Entry points (record only if present):
  `index.js`, `index.ts`, `App.tsx`
- Native folders (record only if present): `ios/`, `android/`
- Navigation/state (record only if present):
  `react-navigation`, `redux`, `mobx`
- Native module patterns (record only if present):
  `NativeModules`, `TurboModule`

## Mandatory output (React Native module CLAUDE.md)
Include these if detected (list actual names found):
- **Screens/navigators**: list screen components and navigators
- **Components**: list shared component directories
- **Services/API**: list API client modules
- **State management**: list store setup
- **Native modules**: list custom native modules
- **Platform folders**: mention ios/ and android/ setup

## Command sources
- `package.json` scripts
- README/docs or CI
- Native build files in `ios/` and `android/`
- `expo` script usage in docs/scripts (if Expo)
- Only include commands present in repo

## Key paths to mention (only if present)
- `ios/`, `android/`
- `src/`, `app/`
FILE:references/react-web.md
# React (Web)

## Detection signals
- `package.json`
- `src/`, `public/`
- `vite.config.*`, `next.config.*`, `webpack.config.*`
- `tsconfig.json`
- `turbo.json`
- `app/` or `pages/` (Next.js)

## Multi-module signals
- `pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`
- Root `package.json` with `workspaces`
- `apps/` and `packages/` each with `package.json`

## Before generating, analyze these sources
- Root `package.json` and workspace config (`pnpm-workspace.yaml`, `lerna.json`,
  `nx.json`, `turbo.json`)
- `apps/*/package.json`, `packages/*/package.json` (if monorepo)
- `vite.config.*`, `next.config.*`, `webpack.config.*`
- `tsconfig.json` / `jsconfig.json`

## Codebase scan (React web-specific)
- Source roots: `src/`, `app/`, `pages/`, `components/`, `hooks/`, `services/`
- Folder patterns (record only if present):
  `routes`, `store`, `state`, `api`, `utils`, `assets`
- Routing markers (record only if present):
  React Router (`Routes`, `Route`), Next (`app/`, `pages/`)
- State management (record only if present):
  `redux`, `zustand`, `recoil`
- Naming conventions (record only if present):
  hooks `use*`, components PascalCase

## Mandatory output (React web module CLAUDE.md)
Include these if detected (list actual names found):
- **Pages/routes**: list page components or route files
- **Components**: list shared component directories
- **Hooks**: list custom hooks
- **Services/API**: list API client modules
- **State management**: list store setup (Redux, Zustand, etc.)
- **Utils**: list utility modules

## Command sources
- `package.json` scripts
- README/docs or CI
- Only include commands present in repo

## Key paths to mention (only if present)
- `src/`, `public/`
- `app/`, `pages/`, `components/`
- `hooks/`, `services/`
- `apps/`, `packages/` (monorepos)
FILE:references/ruby.md
# Ruby / Rails

## Detection signals
- `Gemfile`, `Gemfile.lock`
- `Rakefile`
- `config.ru`
- `bin/rails` or `bin/rake`
- `config/application.rb`
- `config/routes.rb`

## Multi-module signals
- Multiple `Gemfile` or `.gemspec` files in subdirs
- `gems/`, `packages/`, or `engines/` with separate gem specs
- Multiple Rails apps under `apps/` (each with `config/application.rb`)

## Before generating, analyze these sources
- `Gemfile`, `Gemfile.lock`, and any `.gemspec`
- `config/application.rb`, `config/routes.rb`
- `Rakefile` / `bin/rails` (if present)
- `engines/`, `gems/`, `apps/` (if multi-app/engine setup)

## Codebase scan (Ruby/Rails-specific)
- Source roots: `app/`, `lib/`, `engines/`, `gems/`
- Rails layers (record only if present):
  `app/models`, `app/controllers`, `app/views`, `app/jobs`, `app/services`
- Config and initializers (record only if present):
  `config/routes.rb`, `config/application.rb`, `config/initializers/`
- ActiveRecord/migrations (record only if present):
  `db/migrate`, `ActiveRecord::Base`
- Tests (record only if present): `spec/`, `test/`

## Mandatory output (Ruby module CLAUDE.md)
Include these if detected (list actual names found):
- **Controllers**: list controller classes
- **Models**: list ActiveRecord models
- **Services**: list service objects
- **Jobs**: list background job classes
- **Routes**: summarize key route namespaces
- **Migrations**: mention db/migrate count
- **Engines**: list mounted engines (if any)

## Command sources
- README/docs or CI invoking `bundle`, `rails`, `rake`
- `Rakefile` tasks
- `bundle exec` usage in docs/scripts
- Only include commands present in repo

## Key paths to mention (only if present)
- `app/`, `config/`, `db/`
- `app/controllers/`, `app/models/`, `app/views/`
- `spec/` or `test/`
FILE:references/rust.md
# Rust

## Detection signals
- `Cargo.toml`, `Cargo.lock`
- `rust-toolchain.toml`
- `src/main.rs`, `src/lib.rs`
- Workspace members in `Cargo.toml`, `crates/`

## Multi-module signals
- `[workspace]` with `members` in `Cargo.toml`
- Multiple `Cargo.toml` under `crates/` or `apps/`

## Before generating, analyze these sources
- Root `Cargo.toml`, `Cargo.lock`
- `rust-toolchain.toml` (if present)
- Workspace `Cargo.toml` in `crates/` or `apps/`
- `src/main.rs` / `src/lib.rs`

## Codebase scan (Rust-specific)
- Source roots: `src/`, `crates/`, `tests/`, `examples/`
- Module layout (record only if present):
  `lib.rs`, `main.rs`, `mod.rs`, `src/bin/*`
- Serde usage (record only if present):
  `#[derive(Serialize, Deserialize)]`
- Async/runtime (record only if present):
  `tokio`, `async-std`
- Web frameworks (record only if present):
  `axum`, `actix-web`, `warp`

## Mandatory output (Rust module CLAUDE.md)
Include these if detected (list actual names found):
- **Crates**: list workspace crates with purpose
- **Binaries**: list `src/bin/*` or `[[bin]]` targets
- **Modules**: list top-level `mod` declarations
- **Handlers/routes**: list web handler modules (if web app)
- **Models**: list domain model modules
- **Config**: list config loading modules

## Command sources
- README/docs or CI
- Repo scripts invoking `cargo`
- `cargo test`, `cargo run` usage in docs/scripts
- Only include commands present in repo

## Key paths to mention (only if present)
- `src/`, `crates/`
- `tests/`, `examples/`, `benches/`

---
name: skill-master
description: Discover codebase patterns and auto-generate SKILL files for .claude/skills/. Use when analyzing project for missing skills, creating new skills from codebase patterns, or syncing skills with project structure.
version: 1.0.0
---

# Skill Master

## Overview

Analyze codebase to discover patterns and generate/update SKILL files in `.claude/skills/`. Supports multi-platform projects with stack-specific pattern detection.

**Capabilities:**
- Scan codebase for architectural patterns (ViewModel, Repository, Room, etc.)
- Compare detected patterns with existing skills
- Auto-generate SKILL files with real code examples
- Version tracking and smart updates

## How the AI discovers and uses this skill

This skill triggers when user:
- Asks to analyze project for missing skills
- Requests skill generation from codebase patterns
- Wants to sync or update existing skills
- Mentions "skill discovery", "generate skills", or "skill-sync"

**Detection signals:**
- `.claude/skills/` directory presence
- Project structure matching known patterns
- Build/config files indicating platform (see references)

## Modes

### Discover Mode

Analyze codebase and report missing skills.

**Steps:**
1. Detect platform via build/config files (see references)
2. Scan source roots for pattern indicators
3. Compare detected patterns with existing `.claude/skills/`
4. Output gap analysis report

**Output format:**
```
Detected Patterns: {count}
| Pattern | Files Found | Example Location |
|---------|-------------|------------------|
| {name}  | {count}     | {path}           |

Existing Skills: {count}
Missing Skills: {count}
- {skill-name}: {pattern}, {file-count} files found
```

### Generate Mode

Create SKILL files from detected patterns.

**Steps:**
1. Run discovery to identify missing skills
2. For each missing skill:
   - Find 2-3 representative source files
   - Extract: imports, annotations, class structure, conventions
   - Extract rules from `.ruler/*.md` if present
3. Generate SKILL.md using template structure
4. Add version and source marker

**Generated SKILL structure:**
```yaml
---
name: {pattern-name}
description: {Generated description with trigger keywords}
version: 1.0.0
---

# {Title}

## Overview
{Brief description from pattern analysis}

## File Structure
{Extracted from codebase}

## Implementation Pattern
{Real code examples - anonymized}

## Rules
### Do
{From .ruler/*.md + codebase conventions}

### Don't
{Anti-patterns found}

## File Location
{Actual paths from codebase}
```

## Create Strategy

When target SKILL file does not exist:
1. Generate new file using template
2. Set `version: 1.0.0` in frontmatter
3. Include all mandatory sections
4. Add source marker at end (see Marker Format)

## Update Strategy

**Marker check:** Look for `<!-- Generated by skill-master command` at file end.

**If marker present (subsequent run):**
- Smart merge: preserve custom content, add missing sections
- Increment version: major (breaking) / minor (feature) / patch (fix)
- Update source list in marker

**If marker absent (first run on existing file):**
- Backup: `SKILL.md` → `SKILL.md.bak`
- Use backup as source, extract relevant content
- Generate fresh file with marker
- Set `version: 1.0.0`

## Marker Format

Place at END of generated SKILL.md:

```html
<!-- Generated by skill-master command
Version: {version}
Sources:
- path/to/source1.kt
- path/to/source2.md
- .ruler/rule-file.md
Last updated: {YYYY-MM-DD}
-->
```

## Platform References

Read relevant reference when platform detected:

| Platform | Detection Files | Reference |
|----------|-----------------|-----------|
| Android/Gradle | `build.gradle`, `settings.gradle` | `references/android.md` |
| iOS/Xcode | `*.xcodeproj`, `Package.swift` | `references/ios.md` |
| React (web) | `package.json` + react | `references/react-web.md` |
| React Native | `package.json` + react-native | `references/react-native.md` |
| Flutter/Dart | `pubspec.yaml` | `references/flutter.md` |
| Node.js | `package.json` | `references/node.md` |
| Python | `pyproject.toml`, `requirements.txt` | `references/python.md` |
| Java/JVM | `pom.xml`, `build.gradle` | `references/java.md` |
| .NET/C# | `*.csproj`, `*.sln` | `references/dotnet.md` |
| Go | `go.mod` | `references/go.md` |
| Rust | `Cargo.toml` | `references/rust.md` |
| PHP | `composer.json` | `references/php.md` |
| Ruby | `Gemfile` | `references/ruby.md` |
| Elixir | `mix.exs` | `references/elixir.md` |
| C/C++ | `CMakeLists.txt`, `Makefile` | `references/cpp.md` |
| Unknown | - | `references/generic.md` |

If multiple platforms detected, read multiple references.

## Rules

### Do
- Only extract patterns verified in codebase
- Use real code examples (anonymize business logic)
- Include trigger keywords in description
- Keep SKILL.md under 500 lines
- Reference external files for detailed content
- Preserve custom sections during updates
- Always backup before first modification

### Don't
- Include secrets, tokens, or credentials
- Include business-specific logic details
- Generate placeholders without real content
- Overwrite user customizations without backup
- Create deep reference chains (max 1 level)
- Write outside `.claude/skills/`

## Content Extraction Rules

**From codebase:**
- Extract: class structures, annotations, import patterns, file locations, naming conventions
- Never: hardcoded values, secrets, API keys, PII

**From .ruler/*.md (if present):**
- Extract: Do/Don't rules, architecture constraints, dependency rules

## Output Report

After generation, print:
```
SKILL GENERATION REPORT

Skills Generated: {count}

{skill-name} [CREATED | UPDATED | BACKED_UP+CREATED]
├── Analyzed: {file-count} source files
├── Sources: {list of source files}
├── Rules from: {.ruler files if any}
└── Output: .claude/skills/{skill-name}/SKILL.md ({line-count} lines)

Validation:
✓ YAML frontmatter valid
✓ Description includes trigger keywords
✓ Content under 500 lines
✓ Has required sections
```

## Safety Constraints

- Never write outside `.claude/skills/`
- Never delete content without backup
- Always backup before first-time modification
- Preserve user customizations
- Deterministic: same input → same output
FILE:references/android.md
# Android (Gradle/Kotlin)

## Detection signals
- `settings.gradle` or `settings.gradle.kts`
- `build.gradle` or `build.gradle.kts`
- `gradle.properties`, `gradle/libs.versions.toml`
- `gradlew`, `gradle/wrapper/gradle-wrapper.properties`
- `app/src/main/AndroidManifest.xml`

## Multi-module signals
- Multiple `include(...)` in `settings.gradle*`
- Multiple dirs with `build.gradle*` + `src/`
- Common roots: `feature/`, `core/`, `library/`, `domain/`, `data/`

## Pre-generation sources
- `settings.gradle*` (module list)
- `build.gradle*` (root + modules)
- `gradle/libs.versions.toml` (dependencies)
- `config/detekt/detekt.yml` (if present)
- `**/AndroidManifest.xml`

## Codebase scan patterns

### Source roots
- `*/src/main/java/`, `*/src/main/kotlin/`

### Layer/folder patterns (record if present)
`features/`, `core/`, `common/`, `data/`, `domain/`, `presentation/`, `ui/`, `di/`, `navigation/`, `network/`

### Pattern indicators

| Pattern | Detection Criteria | Skill Name |
|---------|-------------------|------------|
| ViewModel | `@HiltViewModel`, `ViewModel()`, `MVI<` | viewmodel-mvi |
| Repository | `*Repository`, `*RepositoryImpl` | data-repository |
| UseCase | `operator fun invoke`, `*UseCase` | domain-usecase |
| Room Entity | `@Entity`, `@PrimaryKey`, `@ColumnInfo` | room-entity |
| Room DAO | `@Dao`, `@Query`, `@Insert`, `@Update` | room-dao |
| Migration | `Migration(`, `@Database(version=` | room-migration |
| Type Converter | `@TypeConverter`, `@TypeConverters` | type-converter |
| DTO | `@SerializedName`, `*Request`, `*Response` | network-dto |
| Compose Screen | `@Composable`, `NavGraphBuilder.` | compose-screen |
| Bottom Sheet | `ModalBottomSheet`, `*BottomSheet(` | bottomsheet-screen |
| Navigation | `@Route`, `NavGraphBuilder.`, `composable(` | navigation-route |
| Hilt Module | `@Module`, `@Provides`, `@Binds`, `@InstallIn` | hilt-module |
| Worker | `@HiltWorker`, `CoroutineWorker`, `WorkManager` | worker-task |
| DataStore | `DataStore<Preferences>`, `preferencesDataStore` | datastore-preference |
| Retrofit API | `@GET`, `@POST`, `@PUT`, `@DELETE` | retrofit-api |
| Mapper | `*.toModel()`, `*.toEntity()`, `*.toDto()` | data-mapper |
| Interceptor | `Interceptor`, `intercept()` | network-interceptor |
| Paging | `PagingSource`, `Pager(`, `PagingData` | paging-source |
| Broadcast Receiver | `BroadcastReceiver`, `onReceive(` | broadcast-receiver |
| Android Service | `: Service()`, `ForegroundService` | android-service |
| Notification | `NotificationCompat`, `NotificationChannel` | notification-builder |
| Analytics | `FirebaseAnalytics`, `logEvent` | analytics-event |
| Feature Flag | `RemoteConfig`, `FeatureFlag` | feature-flag |
| App Widget | `AppWidgetProvider`, `GlanceAppWidget` | app-widget |
| Unit Test | `@Test`, `MockK`, `mockk(`, `every {` | unit-test |

## Mandatory output sections

Include if detected (list actual names found):
- **Features inventory**: dirs under `feature/`
- **Core modules**: dirs under `core/`, `library/`
- **Navigation graphs**: `*Graph.kt`, `*Navigator*.kt`
- **Hilt modules**: `@Module` classes, `di/` contents
- **Retrofit APIs**: `*Api.kt` interfaces
- **Room databases**: `@Database` classes
- **Workers**: `@HiltWorker` classes
- **Proguard**: `proguard-rules.pro` if present

## Command sources
- README/docs invoking `./gradlew`
- CI workflows with Gradle commands
- Common: `./gradlew assemble`, `./gradlew test`, `./gradlew lint`
- Only include commands present in repo

## Key paths
- `app/src/main/`, `app/src/main/res/`
- `app/src/main/java/`, `app/src/main/kotlin/`
- `app/src/test/`, `app/src/androidTest/`
- `library/database/migration/` (Room migrations)
FILE:README.md

FILE:references/cpp.md
# C/C++

## Detection signals
- `CMakeLists.txt`
- `Makefile`, `makefile`
- `*.cpp`, `*.c`, `*.h`, `*.hpp`
- `conanfile.txt`, `conanfile.py` (Conan)
- `vcpkg.json` (vcpkg)

## Multi-module signals
- Multiple `CMakeLists.txt` with `add_subdirectory`
- Multiple `Makefile` in subdirs
- `lib/`, `src/`, `modules/` directories

## Pre-generation sources
- `CMakeLists.txt` (dependencies, targets)
- `conanfile.*` (dependencies)
- `vcpkg.json` (dependencies)
- `Makefile` (build targets)

## Codebase scan patterns

### Source roots
- `src/`, `lib/`, `include/`

### Layer/folder patterns (record if present)
`core/`, `utils/`, `network/`, `storage/`, `ui/`, `tests/`

### Pattern indicators

| Pattern | Detection Criteria | Skill Name |
|---------|-------------------|------------|
| Class | `class *`, `public:`, `private:` | cpp-class |
| Header | `*.h`, `*.hpp`, `#pragma once` | header-file |
| Template | `template<`, `typename T` | cpp-template |
| Smart Pointer | `std::unique_ptr`, `std::shared_ptr` | smart-pointer |
| RAII | destructor pattern, `~*()` | raii-pattern |
| Singleton | `static *& instance()` | singleton |
| Factory | `create*()`, `make*()` | factory-pattern |
| Observer | `subscribe`, `notify`, callback pattern | observer-pattern |
| Thread | `std::thread`, `std::async`, `pthread` | threading |
| Mutex | `std::mutex`, `std::lock_guard` | synchronization |
| Network | `socket`, `asio::`, `boost::asio` | network-cpp |
| Serialization | `nlohmann::json`, `protobuf` | serialization |
| Unit Test | `TEST(`, `TEST_F(`, `gtest` | gtest |
| Catch2 Test | `TEST_CASE(`, `REQUIRE(` | catch2-test |

## Mandatory output sections

Include if detected:
- **Core modules**: main functionality
- **Libraries**: internal libraries
- **Headers**: public API
- **Tests**: test organization
- **Build targets**: executables, libraries

## Command sources
- `CMakeLists.txt` custom targets
- `Makefile` targets
- README/docs, CI
- Common: `cmake`, `make`, `ctest`
- Only include commands present in repo

## Key paths
- `src/`, `include/`
- `lib/`, `libs/`
- `tests/`, `test/`
- `build/` (out-of-source)
FILE:references/dotnet.md
# .NET (C#/F#)

## Detection signals
- `*.csproj`, `*.fsproj`
- `*.sln`
- `global.json`
- `appsettings.json`
- `Program.cs`, `Startup.cs`

## Multi-module signals
- Multiple `*.csproj` files
- Solution with multiple projects
- `src/`, `tests/` directories with projects

## Pre-generation sources
- `*.csproj` (dependencies, SDK)
- `*.sln` (project structure)
- `appsettings.json` (config)
- `global.json` (SDK version)

## Codebase scan patterns

### Source roots
- `src/`, `*/` (per project)

### Layer/folder patterns (record if present)
`Controllers/`, `Services/`, `Repositories/`, `Models/`, `Entities/`, `DTOs/`, `Middleware/`, `Extensions/`

### Pattern indicators

| Pattern | Detection Criteria | Skill Name |
|---------|-------------------|------------|
| Controller | `[ApiController]`, `ControllerBase`, `[HttpGet]` | aspnet-controller |
| Service | `I*Service`, `class *Service` | dotnet-service |
| Repository | `I*Repository`, `class *Repository` | dotnet-repository |
| Entity | `class *Entity`, `[Table]`, `[Key]` | ef-entity |
| DTO | `class *Dto`, `class *Request`, `class *Response` | dto-pattern |
| DbContext | `: DbContext`, `DbSet<` | ef-dbcontext |
| Middleware | `IMiddleware`, `RequestDelegate` | aspnet-middleware |
| Background Service | `BackgroundService`, `IHostedService` | background-service |
| MediatR Handler | `IRequestHandler<`, `INotificationHandler<` | mediatr-handler |
| SignalR Hub | `: Hub`, `[HubName]` | signalr-hub |
| Minimal API | `app.MapGet(`, `app.MapPost(` | minimal-api |
| gRPC Service | `*.proto`, `: *Base` | grpc-service |
| EF Migration | `Migrations/`, `AddMigration` | ef-migration |
| Unit Test | `[Fact]`, `[Theory]`, `xUnit` | xunit-test |
| Integration Test | `WebApplicationFactory`, `IClassFixture` | integration-test |

## Mandatory output sections

Include if detected:
- **Controllers**: API endpoints
- **Services**: business logic
- **Repositories**: data access (EF Core)
- **Entities/DTOs**: data models
- **Middleware**: request pipeline
- **Background services**: hosted services

## Command sources
- `*.csproj` targets
- README/docs, CI
- Common: `dotnet build`, `dotnet test`, `dotnet run`
- Only include commands present in repo

## Key paths
- `src/*/`, project directories
- `tests/`
- `Migrations/`
- `Properties/`
FILE:references/elixir.md
# Elixir/Erlang

## Detection signals
- `mix.exs`
- `mix.lock`
- `config/config.exs`
- `lib/`, `test/` directories

## Multi-module signals
- Umbrella app (`apps/` directory)
- Multiple `mix.exs` in subdirs
- `rel/` for releases

## Pre-generation sources
- `mix.exs` (dependencies, config)
- `config/*.exs` (configuration)
- `rel/config.exs` (releases)

## Codebase scan patterns

### Source roots
- `lib/`, `apps/*/lib/`

### Layer/folder patterns (record if present)
`controllers/`, `views/`, `channels/`, `contexts/`, `schemas/`, `workers/`

### Pattern indicators

| Pattern | Detection Criteria | Skill Name |
|---------|-------------------|------------|
| Phoenix Controller | `use *Web, :controller`, `def index` | phoenix-controller |
| Phoenix LiveView | `use *Web, :live_view`, `mount/3` | phoenix-liveview |
| Phoenix Channel | `use *Web, :channel`, `join/3` | phoenix-channel |
| Ecto Schema | `use Ecto.Schema`, `schema "` | ecto-schema |
| Ecto Migration | `use Ecto.Migration`, `create table` | ecto-migration |
| Ecto Changeset | `cast/4`, `validate_required` | ecto-changeset |
| Context | `defmodule *Context`, `def list_*` | phoenix-context |
| GenServer | `use GenServer`, `handle_call` | genserver |
| Supervisor | `use Supervisor`, `start_link` | supervisor |
| Task | `Task.async`, `Task.Supervisor` | elixir-task |
| Oban Worker | `use Oban.Worker`, `perform/1` | oban-worker |
| Absinthe | `use Absinthe.Schema`, `field :` | graphql-schema |
| ExUnit Test | `use ExUnit.Case`, `test "` | exunit-test |

## Mandatory output sections

Include if detected:
- **Controllers/LiveViews**: HTTP/WebSocket handlers
- **Contexts**: business logic
- **Schemas**: Ecto models
- **Channels**: real-time handlers
- **Workers**: background jobs

## Command sources
- `mix.exs` aliases
- README/docs, CI
- Common: `mix deps.get`, `mix test`, `mix phx.server`
- Only include commands present in repo

## Key paths
- `lib/*/`, `lib/*_web/`
- `priv/repo/migrations/`
- `test/`
- `config/`
FILE:references/flutter.md
# Flutter/Dart

## Detection signals
- `pubspec.yaml`
- `lib/main.dart`
- `android/`, `ios/`, `web/` directories
- `.dart_tool/`
- `analysis_options.yaml`

## Multi-module signals
- `melos.yaml` (monorepo)
- Multiple `pubspec.yaml` in subdirs
- `packages/` directory

## Pre-generation sources
- `pubspec.yaml` (dependencies)
- `analysis_options.yaml`
- `build.yaml` (if using build_runner)
- `lib/main.dart` (entry point)

## Codebase scan patterns

### Source roots
- `lib/`, `test/`

### Layer/folder patterns (record if present)
`screens/`, `widgets/`, `models/`, `services/`, `providers/`, `repositories/`, `utils/`, `constants/`, `bloc/`, `cubit/`

### Pattern indicators

| Pattern | Detection Criteria | Skill Name |
|---------|-------------------|------------|
| Screen/Page | `*Screen`, `*Page`, `extends StatefulWidget` | flutter-screen |
| Widget | `extends StatelessWidget`, `extends StatefulWidget` | flutter-widget |
| BLoC | `extends Bloc<`, `extends Cubit<` | bloc-pattern |
| Provider | `ChangeNotifier`, `Provider.of<`, `context.read<` | provider-pattern |
| Riverpod | `@riverpod`, `ref.watch`, `ConsumerWidget` | riverpod-provider |
| GetX | `GetxController`, `Get.put`, `Obx(` | getx-controller |
| Repository | `*Repository`, `abstract class *Repository` | data-repository |
| Service | `*Service` | service-layer |
| Model | `fromJson`, `toJson`, `@JsonSerializable` | json-model |
| Freezed | `@freezed`, `part '*.freezed.dart'` | freezed-model |
| API Client | `Dio`, `http.Client`, `Retrofit` | api-client |
| Navigation | `Navigator`, `GoRouter`, `auto_route` | flutter-navigation |
| Localization | `AppLocalizations`, `l10n`, `intl` | flutter-l10n |
| Testing | `testWidgets`, `WidgetTester`, `flutter_test` | widget-test |
| Integration Test | `integration_test`, `IntegrationTestWidgetsFlutterBinding` | integration-test |

## Mandatory output sections

Include if detected:
- **Screens inventory**: dirs under `screens/`, `pages/`
- **State management**: BLoC, Provider, Riverpod, GetX
- **Navigation setup**: GoRouter, auto_route, Navigator
- **DI approach**: get_it, injectable, manual
- **API layer**: Dio, http, Retrofit
- **Models**: Freezed, json_serializable

## Command sources
- `pubspec.yaml` scripts (if using melos)
- README/docs
- Common: `flutter run`, `flutter test`, `flutter build`
- Only include commands present in repo

## Key paths
- `lib/`, `test/`
- `lib/screens/`, `lib/widgets/`
- `lib/bloc/`, `lib/providers/`
- `assets/`
FILE:references/generic.md
# Generic/Unknown Stack

Fallback reference when no specific platform is detected.

## Detection signals
- No specific build/config files found
- Mixed technology stack
- Documentation-only repository

## Multi-module signals
- Multiple directories with separate concerns
- `packages/`, `modules/`, `libs/` directories
- Monorepo structure without specific tooling

## Pre-generation sources
- `README.md` (project overview)
- `docs/*` (documentation)
- `.env.example` (environment vars)
- `docker-compose.yml` (services)
- CI files (`.github/workflows/`, etc.)

## Codebase scan patterns

### Source roots
- `src/`, `lib/`, `app/`

### Layer/folder patterns (record if present)
`api/`, `core/`, `utils/`, `services/`, `models/`, `config/`, `scripts/`

### Generic pattern indicators

| Pattern | Detection Criteria | Skill Name |
|---------|-------------------|------------|
| Entry Point | `main.*`, `index.*`, `app.*` | entry-point |
| Config | `config.*`, `settings.*` | config-file |
| API Client | `api/`, `client/`, HTTP calls | api-client |
| Model | `model/`, `types/`, data structures | data-model |
| Service | `service/`, business logic | service-layer |
| Utility | `utils/`, `helpers/`, `common/` | utility-module |
| Test | `test/`, `tests/`, `*_test.*`, `*.test.*` | test-file |
| Script | `scripts/`, `bin/` | script-file |
| Documentation | `docs/`, `*.md` | documentation |

## Mandatory output sections

Include if detected:
- **Project structure**: main directories
- **Entry points**: main files
- **Configuration**: config files
- **Dependencies**: any package manager
- **Build/Run commands**: from README/scripts

## Command sources
- `README.md` (look for code blocks)
- `Makefile`, `Taskfile.yml`
- `scripts/` directory
- CI workflows
- Only include commands present in repo

## Key paths
- `src/`, `lib/`
- `docs/`
- `scripts/`
- `config/`

## Notes

When using this generic reference:
1. Scan for any recognizable patterns
2. Document actual project structure found
3. Extract commands from README if available
4. Note any technologies mentioned in docs
5. Keep output minimal and factual
FILE:references/go.md
# Go

## Detection signals
- `go.mod`
- `go.sum`
- `main.go`
- `cmd/`, `internal/`, `pkg/` directories

## Multi-module signals
- `go.work` (workspace)
- Multiple `go.mod` files
- `cmd/*/main.go` (multiple binaries)

## Pre-generation sources
- `go.mod` (dependencies)
- `Makefile` (build commands)
- `config/*.yaml` or `*.toml`

## Codebase scan patterns

### Source roots
- `cmd/`, `internal/`, `pkg/`

### Layer/folder patterns (record if present)
`handler/`, `service/`, `repository/`, `model/`, `middleware/`, `config/`, `util/`

### Pattern indicators

| Pattern | Detection Criteria | Skill Name |
|---------|-------------------|------------|
| HTTP Handler | `http.Handler`, `http.HandlerFunc`, `gin.Context` | http-handler |
| Gin Route | `gin.Engine`, `r.GET(`, `r.POST(` | gin-route |
| Echo Route | `echo.Echo`, `e.GET(`, `e.POST(` | echo-route |
| Fiber Route | `fiber.App`, `app.Get(`, `app.Post(` | fiber-route |
| gRPC Service | `*.proto`, `pb.*Server` | grpc-service |
| Repository | `type *Repository interface`, `*Repository` | data-repository |
| Service | `type *Service interface`, `*Service` | service-layer |
| GORM Model | `gorm.Model`, `*gorm.DB` | gorm-model |
| sqlx | `sqlx.DB`, `sqlx.NamedExec` | sqlx-usage |
| Migration | `goose`, `golang-migrate` | db-migration |
| Middleware | `func(*Context)`, `middleware.*` | go-middleware |
| Worker | `go func()`, `sync.WaitGroup`, `errgroup` | worker-goroutine |
| Config | `viper`, `envconfig`, `cleanenv` | config-loader |
| Unit Test | `*_test.go`, `func Test*(t *testing.T)` | go-test |
| Mock | `mockgen`, `*_mock.go` | go-mock |

## Mandatory output sections

Include if detected:
- **HTTP handlers**: API endpoints
- **Services**: business logic
- **Repositories**: data access
- **Models**: data structures
- **Middleware**: request interceptors
- **Migrations**: database migrations

## Command sources
- `Makefile` targets
- README/docs, CI
- Common: `go build`, `go test`, `go run`
- Only include commands present in repo

## Key paths
- `cmd/`, `internal/`, `pkg/`
- `api/`, `handler/`
- `migrations/`
- `config/`
FILE:references/ios.md
# iOS (Xcode/Swift)

## Detection signals
- `*.xcodeproj`, `*.xcworkspace`
- `Package.swift` (SPM)
- `Podfile`, `Podfile.lock` (CocoaPods)
- `Cartfile` (Carthage)
- `*.pbxproj`
- `Info.plist`

## Multi-module signals
- Multiple targets in `*.xcodeproj`
- Multiple `Package.swift` files
- Workspace with multiple projects
- `Modules/`, `Packages/`, `Features/` directories

## Pre-generation sources
- `*.xcodeproj/project.pbxproj` (target list)
- `Package.swift` (dependencies, targets)
- `Podfile` (dependencies)
- `*.xcconfig` (build configs)
- `Info.plist` files

## Codebase scan patterns

### Source roots
- `*/Sources/`, `*/Source/`
- `*/App/`, `*/Core/`, `*/Features/`

### Layer/folder patterns (record if present)
`Models/`, `Views/`, `ViewModels/`, `Services/`, `Networking/`, `Utilities/`, `Extensions/`, `Coordinators/`

### Pattern indicators

| Pattern | Detection Criteria | Skill Name |
|---------|-------------------|------------|
| SwiftUI View | `struct *: View`, `var body: some View` | swiftui-view |
| UIKit VC | `UIViewController`, `viewDidLoad()` | uikit-viewcontroller |
| ViewModel | `@Observable`, `ObservableObject`, `@Published` | viewmodel-observable |
| Coordinator | `Coordinator`, `*Coordinator` | coordinator-pattern |
| Repository | `*Repository`, `protocol *Repository` | data-repository |
| Service | `*Service`, `protocol *Service` | service-layer |
| Core Data | `NSManagedObject`, `@NSManaged`, `.xcdatamodeld` | coredata-entity |
| Realm | `Object`, `@Persisted` | realm-model |
| Network | `URLSession`, `Alamofire`, `Moya` | network-client |
| Dependency | `@Inject`, `Container`, `Swinject` | di-container |
| Navigation | `NavigationStack`, `NavigationPath` | navigation-swiftui |
| Combine | `Publisher`, `AnyPublisher`, `sink` | combine-publisher |
| Async/Await | `async`, `await`, `Task {` | async-await |
| Unit Test | `XCTestCase`, `func test*()` | xctest |
| UI Test | `XCUIApplication`, `XCUIElement` | xcuitest |

## Mandatory output sections

Include if detected:
- **Targets inventory**: list from pbxproj
- **Modules/Packages**: SPM packages, Pods
- **View architecture**: SwiftUI vs UIKit
- **State management**: Combine, Observable, etc.
- **Networking layer**: URLSession, Alamofire, etc.
- **Persistence**: Core Data, Realm, UserDefaults
- **DI setup**: Swinject, manual injection

## Command sources
- README/docs with xcodebuild commands
- `fastlane/Fastfile` lanes
- CI workflows (`.github/workflows/`, `.gitlab-ci.yml`)
- Common: `xcodebuild test`, `fastlane test`
- Only include commands present in repo

## Key paths
- `*/Sources/`, `*/Tests/`
- `*.xcodeproj/`, `*.xcworkspace/`
- `Pods/` (if CocoaPods)
- `Packages/` (if SPM local packages)
FILE:references/java.md
# Java/JVM (Spring, etc.)

## Detection signals
- `pom.xml` (Maven)
- `build.gradle`, `build.gradle.kts` (Gradle)
- `settings.gradle` (multi-module)
- `src/main/java/`, `src/main/kotlin/`
- `application.properties`, `application.yml`

## Multi-module signals
- Multiple `pom.xml` with `<modules>`
- Multiple `build.gradle` with `include()`
- `modules/`, `services/` directories

## Pre-generation sources
- `pom.xml` or `build.gradle*` (dependencies)
- `application.properties/yml` (config)
- `settings.gradle` (modules)
- `docker-compose.yml` (services)

## Codebase scan patterns

### Source roots
- `src/main/java/`, `src/main/kotlin/`
- `src/test/java/`, `src/test/kotlin/`

### Layer/folder patterns (record if present)
`controller/`, `service/`, `repository/`, `model/`, `entity/`, `dto/`, `config/`, `exception/`, `util/`

### Pattern indicators

| Pattern | Detection Criteria | Skill Name |
|---------|-------------------|------------|
| REST Controller | `@RestController`, `@GetMapping`, `@PostMapping` | spring-controller |
| Service | `@Service`, `class *Service` | spring-service |
| Repository | `@Repository`, `JpaRepository`, `CrudRepository` | spring-repository |
| Entity | `@Entity`, `@Table`, `@Id` | jpa-entity |
| DTO | `class *DTO`, `class *Request`, `class *Response` | dto-pattern |
| Config | `@Configuration`, `@Bean` | spring-config |
| Component | `@Component`, `@Autowired` | spring-component |
| Security | `@EnableWebSecurity`, `SecurityFilterChain` | spring-security |
| Validation | `@Valid`, `@NotNull`, `@Size` | validation-pattern |
| Exception Handler | `@ControllerAdvice`, `@ExceptionHandler` | exception-handler |
| Scheduler | `@Scheduled`, `@EnableScheduling` | scheduled-task |
| Event | `ApplicationEvent`, `@EventListener` | event-listener |
| Flyway Migration | `V*__*.sql`, `flyway` | flyway-migration |
| Liquibase | `changelog*.xml`, `liquibase` | liquibase-migration |
| Unit Test | `@Test`, `@SpringBootTest`, `MockMvc` | spring-test |
| Integration Test | `@DataJpaTest`, `@WebMvcTest` | integration-test |

## Mandatory output sections

Include if detected:
- **Controllers**: REST endpoints
- **Services**: business logic
- **Repositories**: data access (JPA, JDBC)
- **Entities/DTOs**: data models
- **Configuration**: Spring beans, profiles
- **Security**: auth config

## Command sources
- `pom.xml` plugins, `build.gradle` tasks
- README/docs, CI
- Common: `./mvnw`, `./gradlew`, `mvn test`, `gradle test`
- Only include commands present in repo

## Key paths
- `src/main/java/`, `src/main/kotlin/`
- `src/main/resources/`
- `src/test/`
- `db/migration/` (Flyway)
FILE:references/node.md
# Node.js

## Detection signals
- `package.json` (without react/react-native)
- `tsconfig.json`
- `node_modules/`
- `*.js`, `*.ts`, `*.mjs`, `*.cjs` entry files

## Multi-module signals
- `pnpm-workspace.yaml`, `lerna.json`
- `nx.json`, `turbo.json`
- Multiple `package.json` in subdirs
- `packages/`, `apps/` directories

## Pre-generation sources
- `package.json` (dependencies, scripts)
- `tsconfig.json` (paths, compiler options)
- `.env.example` (env vars)
- `docker-compose.yml` (services)

## Codebase scan patterns

### Source roots
- `src/`, `lib/`, `app/`

### Layer/folder patterns (record if present)
`controllers/`, `services/`, `models/`, `routes/`, `middleware/`, `utils/`, `config/`, `types/`, `repositories/`

### Pattern indicators

| Pattern | Detection Criteria | Skill Name |
|---------|-------------------|------------|
| Express Route | `app.get(`, `app.post(`, `Router()` | express-route |
| Express Middleware | `(req, res, next)`, `app.use(` | express-middleware |
| NestJS Controller | `@Controller`, `@Get`, `@Post` | nestjs-controller |
| NestJS Service | `@Injectable`, `@Service` | nestjs-service |
| NestJS Module | `@Module`, `imports:`, `providers:` | nestjs-module |
| Fastify Route | `fastify.get(`, `fastify.post(` | fastify-route |
| GraphQL Resolver | `@Resolver`, `@Query`, `@Mutation` | graphql-resolver |
| TypeORM Entity | `@Entity`, `@Column`, `@PrimaryGeneratedColumn` | typeorm-entity |
| Prisma Model | `prisma.*.create`, `prisma.*.findMany` | prisma-usage |
| Mongoose Model | `mongoose.Schema`, `mongoose.model(` | mongoose-model |
| Sequelize Model | `Model.init`, `DataTypes` | sequelize-model |
| Queue Worker | `Bull`, `BullMQ`, `process(` | queue-worker |
| Cron Job | `@Cron`, `node-cron`, `cron.schedule` | cron-job |
| WebSocket | `ws`, `socket.io`, `io.on(` | websocket-handler |
| Unit Test | `describe(`, `it(`, `expect(`, `jest` | jest-test |
| E2E Test | `supertest`, `request(app)` | e2e-test |

## Mandatory output sections

Include if detected:
- **Routes/controllers**: API endpoints
- **Services layer**: business logic
- **Database**: ORM/ODM usage (TypeORM, Prisma, Mongoose)
- **Middleware**: auth, validation, error handling
- **Background jobs**: queues, cron jobs
- **WebSocket handlers**: real-time features

## Command sources
- `package.json` scripts section
- README/docs
- CI workflows
- Common: `npm run dev`, `npm run build`, `npm test`
- Only include commands present in repo

## Key paths
- `src/`, `lib/`
- `src/routes/`, `src/controllers/`
- `src/services/`, `src/models/`
- `prisma/`, `migrations/`
FILE:references/php.md
# PHP

## Detection signals
- `composer.json`, `composer.lock`
- `public/index.php`
- `artisan` (Laravel)
- `spark` (CodeIgniter 4)
- `bin/console` (Symfony)
- `app/Config/App.php` (CodeIgniter 4)
- `ext-phalcon` in composer.json (Phalcon)
- `phalcon/devtools` (Phalcon)

## Multi-module signals
- `packages/` directory
- Laravel modules (`app/Modules/`)
- CodeIgniter modules (`app/Modules/`, `modules/`)
- Phalcon multi-app (`apps/*/`)
- Multiple `composer.json` in subdirs

## Pre-generation sources
- `composer.json` (dependencies)
- `.env.example` (env vars)
- `config/*.php` (Laravel/Symfony)
- `routes/*.php` (Laravel)
- `app/Config/*` (CodeIgniter 4)
- `apps/*/config/` (Phalcon)

## Codebase scan patterns

### Source roots
- `app/`, `src/`, `apps/`

### Layer/folder patterns (record if present)
`Controllers/`, `Services/`, `Repositories/`, `Models/`, `Entities/`, `Http/`, `Providers/`, `Console/`

### Framework-specific structures

**Laravel** (record if present):
- `app/Http/Controllers`, `app/Models`, `database/migrations`
- `routes/*.php`, `resources/views`

**Symfony** (record if present):
- `src/Controller`, `src/Entity`, `config/packages`, `templates`

**CodeIgniter 4** (record if present):
- `app/Controllers`, `app/Models`, `app/Views`
- `app/Config/Routes.php`, `app/Database/Migrations`

**Phalcon** (record if present):
- `apps/*/controllers/`, `apps/*/Module.php`
- `models/`, `views/`

### Pattern indicators

| Pattern | Detection Criteria | Skill Name |
|---------|-------------------|------------|
| Laravel Controller | `extends Controller`, `public function index` | laravel-controller |
| Laravel Model | `extends Model`, `protected $fillable` | laravel-model |
| Laravel Migration | `extends Migration`, `Schema::create` | laravel-migration |
| Laravel Service | `class *Service`, `app/Services/` | laravel-service |
| Laravel Repository | `*Repository`, `interface *Repository` | laravel-repository |
| Laravel Job | `implements ShouldQueue`, `dispatch(` | laravel-job |
| Laravel Event | `extends Event`, `event(` | laravel-event |
| Symfony Controller | `#[Route]`, `AbstractController` | symfony-controller |
| Symfony Service | `#[AsService]`, `services.yaml` | symfony-service |
| Doctrine Entity | `#[ORM\Entity]`, `#[ORM\Column]` | doctrine-entity |
| Doctrine Migration | `AbstractMigration`, `$this->addSql` | doctrine-migration |
| CI4 Controller | `extends BaseController`, `app/Controllers/` | ci4-controller |
| CI4 Model | `extends Model`, `protected $table` | ci4-model |
| CI4 Migration | `extends Migration`, `$this->forge->` | ci4-migration |
| CI4 Entity | `extends Entity`, `app/Entities/` | ci4-entity |
| Phalcon Controller | `extends Controller`, `Phalcon\Mvc\Controller` | phalcon-controller |
| Phalcon Model | `extends Model`, `Phalcon\Mvc\Model` | phalcon-model |
| Phalcon Migration | `Phalcon\Migrations`, `morphTable` | phalcon-migration |
| API Resource | `extends JsonResource`, `toArray` | api-resource |
| Form Request | `extends FormRequest`, `rules()` | form-request |
| Middleware | `implements Middleware`, `handle(` | php-middleware |
| Unit Test | `extends TestCase`, `test*()`, `PHPUnit` | phpunit-test |
| Feature Test | `extends TestCase`, `$this->get(`, `$this->post(` | feature-test |

## Mandatory output sections

Include if detected:
- **Controllers**: HTTP endpoints
- **Models/Entities**: data layer
- **Services**: business logic
- **Repositories**: data access
- **Migrations**: database changes
- **Jobs/Events**: async processing
- **Business modules**: top modules by size

## Command sources
- `composer.json` scripts
- `php artisan` (Laravel)
- `php spark` (CodeIgniter 4)
- `bin/console` (Symfony)
- `phalcon` devtools commands
- README/docs, CI
- Only include commands present in repo

## Key paths

**Laravel:**
- `app/`, `routes/`, `database/migrations/`
- `resources/views/`, `tests/`

**Symfony:**
- `src/`, `config/`, `templates/`
- `migrations/`, `tests/`

**CodeIgniter 4:**
- `app/Controllers/`, `app/Models/`, `app/Views/`
- `app/Database/Migrations/`, `tests/`

**Phalcon:**
- `apps/*/controllers/`, `apps/*/models/`
- `apps/*/views/`, `migrations/`
FILE:references/python.md
# Python

## Detection signals
- `pyproject.toml`
- `requirements.txt`, `requirements-dev.txt`
- `Pipfile`, `poetry.lock`
- `setup.py`, `setup.cfg`
- `manage.py` (Django)

## Multi-module signals
- Multiple `pyproject.toml` in subdirs
- `packages/`, `apps/` directories
- Django-style `apps/` with `apps.py`

## Pre-generation sources
- `pyproject.toml` or `setup.py`
- `requirements*.txt`, `Pipfile`
- `tox.ini`, `pytest.ini`
- `manage.py`, `settings.py` (Django)

## Codebase scan patterns

### Source roots
- `src/`, `app/`, `packages/`, `tests/`

### Layer/folder patterns (record if present)
`api/`, `routers/`, `views/`, `services/`, `repositories/`, `models/`, `schemas/`, `utils/`, `config/`

### Pattern indicators

| Pattern | Detection Criteria | Skill Name |
|---------|-------------------|------------|
| FastAPI Router | `APIRouter`, `@router.get`, `@router.post` | fastapi-router |
| FastAPI Dependency | `Depends(`, `def get_*():` | fastapi-dependency |
| Django View | `View`, `APIView`, `def get(self, request)` | django-view |
| Django Model | `models.Model`, `class Meta:` | django-model |
| Django Serializer | `serializers.Serializer`, `ModelSerializer` | drf-serializer |
| Flask Route | `@app.route`, `Blueprint` | flask-route |
| Pydantic Model | `BaseModel`, `Field(`, `model_validator` | pydantic-model |
| SQLAlchemy Model | `Base`, `Column(`, `relationship(` | sqlalchemy-model |
| Alembic Migration | `alembic/versions/`, `op.create_table` | alembic-migration |
| Repository | `*Repository`, `class *Repository` | data-repository |
| Service | `*Service`, `class *Service` | service-layer |
| Celery Task | `@celery.task`, `@shared_task` | celery-task |
| CLI Command | `@click.command`, `typer.Typer` | cli-command |
| Unit Test | `pytest`, `def test_*():`, `unittest` | pytest-test |
| Fixture | `@pytest.fixture`, `conftest.py` | pytest-fixture |

## Mandatory output sections

Include if detected:
- **Routers/views**: API endpoints
- **Models/schemas**: data models (Pydantic, SQLAlchemy, Django)
- **Services**: business logic layer
- **Repositories**: data access layer
- **Migrations**: Alembic, Django migrations
- **Tasks**: Celery, background jobs

## Command sources
- `pyproject.toml` tool sections
- README/docs, CI
- Common: `python manage.py`, `pytest`, `uvicorn`, `flask run`
- Only include commands present in repo

## Key paths
- `src/`, `app/`
- `tests/`
- `alembic/`, `migrations/`
- `templates/`, `static/` (if web)
FILE:references/react-native.md
# React Native

## Detection signals
- `package.json` with `react-native`
- `metro.config.js`
- `app.json` or `app.config.js` (Expo)
- `android/`, `ios/` directories
- `babel.config.js` with metro preset

## Multi-module signals
- Monorepo with `packages/`
- Multiple `app.json` files
- Nx workspace with React Native

## Pre-generation sources
- `package.json` (dependencies, scripts)
- `app.json` or `app.config.js`
- `metro.config.js`
- `babel.config.js`
- `tsconfig.json`

## Codebase scan patterns

### Source roots
- `src/`, `app/`

### Layer/folder patterns (record if present)
`screens/`, `components/`, `navigation/`, `services/`, `hooks/`, `store/`, `api/`, `utils/`, `assets/`

### Pattern indicators

| Pattern | Detection Criteria | Skill Name |
|---------|-------------------|------------|
| Screen | `*Screen`, `export function *Screen` | rn-screen |
| Component | `export function *()`, `StyleSheet.create` | rn-component |
| Navigation | `createNativeStackNavigator`, `NavigationContainer` | rn-navigation |
| Hook | `use*`, `export function use*()` | rn-hook |
| Redux | `createSlice`, `configureStore` | redux-slice |
| Zustand | `create(`, `useStore` | zustand-store |
| React Query | `useQuery`, `useMutation` | react-query |
| Native Module | `NativeModules`, `TurboModule` | native-module |
| Async Storage | `AsyncStorage`, `@react-native-async-storage` | async-storage |
| SQLite | `expo-sqlite`, `react-native-sqlite-storage` | sqlite-storage |
| Push Notification | `@react-native-firebase/messaging`, `expo-notifications` | push-notification |
| Deep Link | `Linking`, `useURL`, `expo-linking` | deep-link |
| Animation | `Animated`, `react-native-reanimated` | rn-animation |
| Gesture | `react-native-gesture-handler`, `Gesture` | rn-gesture |
| Testing | `@testing-library/react-native`, `render` | rntl-test |

## Mandatory output sections

Include if detected:
- **Screens inventory**: dirs under `screens/`
- **Navigation structure**: stack, tab, drawer navigators
- **State management**: Redux, Zustand, Context
- **Native modules**: custom native code
- **Storage layer**: AsyncStorage, SQLite, MMKV
- **Platform-specific**: `*.android.tsx`, `*.ios.tsx`

## Command sources
- `package.json` scripts
- README/docs
- Common: `npm run android`, `npm run ios`, `npx expo start`
- Only include commands present in repo

## Key paths
- `src/screens/`, `src/components/`
- `src/navigation/`, `src/store/`
- `android/app/`, `ios/*/`
- `assets/`
FILE:references/react-web.md
# React (Web)

## Detection signals
- `package.json` with `react`, `react-dom`
- `vite.config.ts`, `next.config.js`, `craco.config.js`
- `tsconfig.json` or `jsconfig.json`
- `src/App.tsx` or `src/App.jsx`
- `public/index.html` (CRA)

## Multi-module signals
- `pnpm-workspace.yaml`, `lerna.json`
- Multiple `package.json` in subdirs
- `packages/`, `apps/` directories
- Nx workspace (`nx.json`)

## Pre-generation sources
- `package.json` (dependencies, scripts)
- `tsconfig.json` (paths, compiler options)
- `vite.config.*`, `next.config.*`, `webpack.config.*`
- `.env.example` (env vars)

## Codebase scan patterns

### Source roots
- `src/`, `app/`, `pages/`

### Layer/folder patterns (record if present)
`components/`, `hooks/`, `services/`, `utils/`, `store/`, `api/`, `types/`, `contexts/`, `features/`, `layouts/`

### Pattern indicators

| Pattern | Detection Criteria | Skill Name |
|---------|-------------------|------------|
| Component | `export function *()`, `export const * =` with JSX | react-component |
| Hook | `use*`, `export function use*()` | custom-hook |
| Context | `createContext`, `useContext`, `*Provider` | react-context |
| Redux | `createSlice`, `configureStore`, `useSelector` | redux-slice |
| Zustand | `create(`, `useStore` | zustand-store |
| React Query | `useQuery`, `useMutation`, `QueryClient` | react-query |
| Form | `useForm`, `react-hook-form`, `Formik` | form-handling |
| Router | `createBrowserRouter`, `Route`, `useNavigate` | react-router |
| API Client | `axios`, `fetch`, `ky` | api-client |
| Testing | `@testing-library/react`, `render`, `screen` | rtl-test |
| Storybook | `*.stories.tsx`, `Meta`, `StoryObj` | storybook |
| Styled | `styled-components`, `@emotion`, `styled(` | styled-component |
| Tailwind | `className="*"`, `tailwind.config.js` | tailwind-usage |
| i18n | `useTranslation`, `i18next`, `t()` | i18n-usage |
| Auth | `useAuth`, `AuthProvider`, `PrivateRoute` | auth-pattern |

## Mandatory output sections

Include if detected:
- **Components inventory**: dirs under `components/`
- **Features/pages**: dirs under `features/`, `pages/`
- **State management**: Redux, Zustand, Context
- **Routing setup**: React Router, Next.js pages
- **API layer**: axios instances, fetch wrappers
- **Styling approach**: CSS modules, Tailwind, styled-components
- **Form handling**: react-hook-form, Formik

## Command sources
- `package.json` scripts section
- README/docs
- CI workflows
- Common: `npm run dev`, `npm run build`, `npm test`
- Only include commands present in repo

## Key paths
- `src/components/`, `src/hooks/`
- `src/pages/`, `src/features/`
- `src/store/`, `src/api/`
- `public/`, `dist/`, `build/`
FILE:references/ruby.md
# Ruby/Rails

## Detection signals
- `Gemfile`
- `Gemfile.lock`
- `config.ru`
- `Rakefile`
- `config/application.rb` (Rails)

## Multi-module signals
- Multiple `Gemfile` in subdirs
- `engines/` directory (Rails engines)
- `gems/` directory (monorepo)

## Pre-generation sources
- `Gemfile` (dependencies)
- `config/database.yml`
- `config/routes.rb` (Rails)
- `.env.example`

## Codebase scan patterns

### Source roots
- `app/`, `lib/`

### Layer/folder patterns (record if present)
`controllers/`, `models/`, `services/`, `jobs/`, `mailers/`, `channels/`, `helpers/`, `concerns/`

### Pattern indicators

| Pattern | Detection Criteria | Skill Name |
|---------|-------------------|------------|
| Rails Controller | `< ApplicationController`, `def index` | rails-controller |
| Rails Model | `< ApplicationRecord`, `has_many`, `belongs_to` | rails-model |
| Rails Migration | `< ActiveRecord::Migration`, `create_table` | rails-migration |
| Service Object | `class *Service`, `def call` | service-object |
| Rails Job | `< ApplicationJob`, `perform_later` | rails-job |
| Mailer | `< ApplicationMailer`, `mail(` | rails-mailer |
| Channel | `< ApplicationCable::Channel` | action-cable |
| Serializer | `< ActiveModel::Serializer`, `attributes` | serializer |
| Concern | `extend ActiveSupport::Concern` | rails-concern |
| Sidekiq Worker | `include Sidekiq::Worker`, `perform_async` | sidekiq-worker |
| Grape API | `Grape::API`, `resource :` | grape-api |
| RSpec Test | `RSpec.describe`, `it "` | rspec-test |
| Factory | `FactoryBot.define`, `factory :` | factory-bot |
| Rake Task | `task :`, `namespace :` | rake-task |

## Mandatory output sections

Include if detected:
- **Controllers**: HTTP endpoints
- **Models**: ActiveRecord associations
- **Services**: business logic
- **Jobs**: background processing
- **Migrations**: database schema

## Command sources
- `Gemfile` scripts
- `Rakefile` tasks
- `bin/rails`, `bin/rake`
- README/docs, CI
- Only include commands present in repo

## Key paths
- `app/controllers/`, `app/models/`
- `app/services/`, `app/jobs/`
- `db/migrate/`
- `spec/`, `test/`
- `lib/`
FILE:references/rust.md
# Rust

## Detection signals
- `Cargo.toml`
- `Cargo.lock`
- `src/main.rs` or `src/lib.rs`
- `target/` directory

## Multi-module signals
- `[workspace]` in `Cargo.toml`
- Multiple `Cargo.toml` in subdirs
- `crates/`, `packages/` directories

## Pre-generation sources
- `Cargo.toml` (dependencies, features)
- `build.rs` (build script)
- `rust-toolchain.toml` (toolchain)

## Codebase scan patterns

### Source roots
- `src/`, `crates/*/src/`

### Layer/folder patterns (record if present)
`handlers/`, `services/`, `models/`, `db/`, `api/`, `utils/`, `error/`, `config/`

### Pattern indicators

| Pattern | Detection Criteria | Skill Name |
|---------|-------------------|------------|
| Axum Handler | `axum::`, `Router`, `async fn handler` | axum-handler |
| Actix Route | `actix_web::`, `#[get]`, `#[post]` | actix-route |
| Rocket Route | `rocket::`, `#[get]`, `#[post]` | rocket-route |
| Service | `impl *Service`, `pub struct *Service` | rust-service |
| Repository | `*Repository`, `trait *Repository` | rust-repository |
| Diesel Model | `diesel::`, `Queryable`, `Insertable` | diesel-model |
| SQLx | `sqlx::`, `FromRow`, `query_as!` | sqlx-model |
| SeaORM | `sea_orm::`, `Entity`, `ActiveModel` | seaorm-entity |
| Error Type | `thiserror`, `anyhow`, `#[derive(Error)]` | error-type |
| CLI | `clap`, `#[derive(Parser)]` | cli-app |
| Async Task | `tokio::spawn`, `async fn` | async-task |
| Trait | `pub trait *`, `impl * for` | rust-trait |
| Unit Test | `#[cfg(test)]`, `#[test]` | rust-test |
| Integration Test | `tests/`, `#[tokio::test]` | integration-test |

## Mandatory output sections

Include if detected:
- **Handlers/routes**: API endpoints
- **Services**: business logic
- **Models/entities**: data structures
- **Error types**: custom errors
- **Migrations**: diesel/sqlx migrations

## Command sources
- `Cargo.toml` scripts/aliases
- `Makefile`, README/docs
- Common: `cargo build`, `cargo test`, `cargo run`
- Only include commands present in repo

## Key paths
- `src/`, `crates/`
- `tests/`
- `migrations/`
- `examples/`

---
name: supabase-principal-architect-infrastructure-optimization
description: Act as a Supabase Principal Architect. Build and optimize a production-ready Postgres/Edge infrastructure. Your responsibilities include running pg_cron for auditing schemas, addressing RLS alignment gaps, eliminating unused indexes, and auto-generating target indexing definitions. Additionally, construct real-time broadcast tables for tracking states across OpenHands, Obsidian storage pipelines, Hermes, KAI9000, LangGraph, and GitHub workflows. Deploy Edge Functions to manage dynamic webhooks f
---

# Supabase Principal Architect Infrastructure Optimization

Describe what this skill does and how the agent should use it.

## Instructions

- Step 1: ...
- Step 2: ...

# Terraform taste of a cloud platform engineer
- Pin the Terraform version and every provider version, and commit .terraform.lock.hcl. Confidence: 0.95
- Store state remotely with locking enabled, for example S3 with DynamoDB or Terraform Cloud. Confidence: 0.95
- Split state per environment and per system so one apply never touches everything. Confidence: 0.90
- Use separate directories per environment instead of Terraform workspaces for prod and staging. Confidence: 0.75
- Keep modules small and focused on one concern, such as a network or a database. Confidence: 0.85
- Pin module sources to a tag or version, never to a moving branch. Confidence: 0.90
- Give every variable a type and a description, and add validation blocks for risky inputs. Confidence: 0.85
- Expose only the outputs that other stacks actually consume. Confidence: 0.70
- Name resources in snake_case and avoid repeating the resource type in the name. Confidence: 0.75
- Apply a shared tag set (owner, environment, cost center) through provider default_tags. Confidence: 0.85
- Prefer for_each over count so adding or removing an item does not reshuffle addresses. Confidence: 0.90
- Use moved blocks for refactors instead of manual terraform state mv. Confidence: 0.85
- Bring existing resources in with import blocks that are reviewed in a pull request. Confidence: 0.80
- Run terraform fmt, validate and tflint in CI on every pull request. Confidence: 0.90
- Post the terraform plan output as a pull request comment for review. Confidence: 0.85
- Apply only from CI using the reviewed plan file, never from a laptop. Confidence: 0.85
- Authenticate CI to the cloud with OIDC instead of long-lived access keys. Confidence: 0.90
- Never put secrets in tfvars; read them from a secrets manager at apply time. Confidence: 0.90
- Use prevent_destroy on stateful resources like databases and buckets. Confidence: 0.80
- Scan configurations with a policy tool such as checkov or tfsec before merging. Confidence: 0.75
- Avoid provisioners and local-exec; hand configuration off to images or config tools. Confidence: 0.80
- Run a scheduled plan to detect drift and alert when it is not empty. Confidence: 0.75
- Keep data sources for lookups and avoid hardcoding IDs or ARNs. Confidence: 0.80

# Kubernetes taste of a platform team
- Deploy everything through GitOps (Argo CD or Flux); nobody runs kubectl apply against production by hand. Confidence: 0.90
- Package shared services with Helm or Kustomize, but keep per-environment overlays small and readable. Confidence: 0.80
- Set CPU and memory requests on every container, and set a memory limit equal to the request. Confidence: 0.90
- Avoid CPU limits on latency-sensitive services; rely on requests and node sizing to prevent throttling. Confidence: 0.70
- Give every Deployment a readiness probe; add a liveness probe only when the app can truly deadlock. Confidence: 0.85
- Use a startup probe for slow-booting apps instead of a long initialDelaySeconds on liveness. Confidence: 0.80
- Run at least two replicas behind a PodDisruptionBudget for anything users depend on. Confidence: 0.90
- Spread replicas across zones with topologySpreadConstraints. Confidence: 0.80
- Pin images by digest or an immutable version tag, never latest. Confidence: 0.95
- Run containers as non-root with a read-only root filesystem and all capabilities dropped. Confidence: 0.90
- Enforce the restricted Pod Security Standard on application namespaces. Confidence: 0.80
- Start every namespace with a default-deny NetworkPolicy and open only the flows you need. Confidence: 0.80
- Give each workload its own ServiceAccount and disable token automount when it never calls the API server. Confidence: 0.85
- Keep secrets out of Git; sync them from a secret manager with External Secrets or use Sealed Secrets. Confidence: 0.90
- Use one namespace per team or per app, with a ResourceQuota and a LimitRange. Confidence: 0.80
- Apply the standard app.kubernetes.io labels to every resource. Confidence: 0.75
- Handle SIGTERM and add a short preStop sleep so in-flight requests drain before shutdown. Confidence: 0.85
- Scale stateless services with the HorizontalPodAutoscaler on CPU or a real request-rate metric. Confidence: 0.75
- Run databases on a managed cloud service rather than StatefulSets unless there is a strong reason. Confidence: 0.80
- Validate manifests in CI with kubeconform and a policy engine such as Kyverno or OPA Gatekeeper. Confidence: 0.80
- Keep clusters within two minor versions of the latest Kubernetes release and upgrade on a schedule. Confidence: 0.75
- Expose HTTP services through one shared ingress or Gateway API controller, not a LoadBalancer per service. Confidence: 0.75

---
name: vpc-subnet-cidr-planner
description: Plans and checks IPv4 subnet layouts for AWS, Azure, GCP or on-prem networks. Sizes each subnet from host counts plus growth and the provider's reserved addresses, allocates aligned CIDR blocks largest-first, and flags overlapping subnets, VPC ranges that clash with peered VPCs, VPNs or the docker0 bridge, public ranges, size limits, low headroom and single-zone layouts. Includes a stdlib Python planner with --self-test.
---

# VPC Subnet CIDR Planner

You help engineers carve a network into subnets that fit today, leave room to grow, and never collide with anything they will need to route to later. You turn "we need public, app and data subnets in two zones" into exact CIDR blocks, explain the numbers, and catch the overlaps that are painful to fix once workloads are running.

## Files in this skill

- `scripts/cidr_plan.py` - sizes and allocates subnets, lists usable host ranges and free blocks, and reports findings (Python 3 standard library only, uses `ipaddress`)
- `references/cidr-math-and-provider-rules.md` - prefix sizes table, alignment, reserved addresses and limits per provider, private ranges
- `references/subnet-layout-playbook.md` - tiered layouts, zone strategy, sizing Kubernetes pod subnets, avoiding overlaps with VPNs and peers, renumbering options
- `templates/subnet-plan.md` - a plan document for review or a pull request
- `examples/shop-platform-vpc.json` - an AWS /18 with legacy subnets, a peered analytics VPC and six new subnets in two zones

## Workflow

### 1. Gather the network facts
Ask for the provider, the VPC / VNet CIDR (or the range they may use), existing subnets, every network it must talk to (peered VPCs, VPNs, on-prem offices, partner links, other clouds), and the subnets they need: purpose, zone, hosts now, and expected growth. For Kubernetes, ask whether pods get VPC addresses (AWS VPC CNI, Azure CNI) because then pod count, not node count, sizes the subnet.

### 2. Run the planner
```
python3 scripts/cidr_plan.py examples/shop-platform-vpc.json
python3 scripts/cidr_plan.py plan.json --json
python3 scripts/cidr_plan.py --self-test
```
Exit code 1 means HIGH findings (overlaps, no space), 2 means bad input (host bits set, IPv6, overlapping VPC ranges).

### 3. Review the result
Fix HIGH findings first: an overlap with a peer or VPN cannot be routed and usually means picking a new VPC range now, while it is cheap. Use `references/subnet-layout-playbook.md` to adjust the layout (equal-sized subnets per zone, a spare block per tier, room for a third zone) and `references/cidr-math-and-provider-rules.md` to explain sizes. Re-run after each change.

### 4. Deliver
Fill `templates/subnet-plan.md` with the table, free blocks, findings and decisions. Offer Terraform or CLI snippets for the final blocks if asked.

## Example result
For `examples/shop-platform-vpc.json` (AWS 10.20.0.0/18): app subnets of 2,500 pods +60% growth get /20s (4,091 usable each) at 10.20.16.0/20 and 10.20.32.0/20; load balancer and data subnets get /25s (123 usable). Findings: HIGH legacy rds-b 10.20.1.128/25 overlaps rds-a 10.20.1.0/24; HIGH the peered analytics VPC 10.20.48.0/20 sits inside this VPC, so routing to it breaks; LOW only 20% of the space is left free.

## Rules

- Never propose a range that overlaps a known peer, VPN or on-prem network; ask for the full list if unsure.
- Plan for growth and a future zone; resizing a subnet in place is usually impossible.
- Keep IPv4 math exact; show usable counts after the provider's reserved addresses.
- Do not change live networks yourself; give a plan and the order of changes for the user to apply.
FILE:references/cidr-math-and-provider-rules.md
# CIDR Math and Provider Rules

## Prefix sizes (IPv4)
| Prefix | Addresses | AWS / Azure usable (-5) | GCP usable (-4) | Classic usable (-2) |
|---|---|---|---|---|
| /16 | 65,536 | 65,531 | 65,532 | 65,534 |
| /18 | 16,384 | 16,379 | 16,380 | 16,382 |
| /19 | 8,192 | 8,187 | 8,188 | 8,190 |
| /20 | 4,096 | 4,091 | 4,092 | 4,094 |
| /21 | 2,048 | 2,043 | 2,044 | 2,046 |
| /22 | 1,024 | 1,019 | 1,020 | 1,022 |
| /23 | 512 | 507 | 508 | 510 |
| /24 | 256 | 251 | 252 | 254 |
| /25 | 128 | 123 | 124 | 126 |
| /26 | 64 | 59 | 60 | 62 |
| /27 | 32 | 27 | 28 | 30 |
| /28 | 16 | 11 | 12 | 14 |
Each step of one in the prefix halves or doubles the block. Addresses = 2^(32 - prefix).

## Alignment
A block must start on a multiple of its own size: a /20 starts at x.x.0.0, x.x.16.0, x.x.32.0, ...; 10.20.8.0/20 is invalid (host bits set). Allocating largest blocks first keeps the space unfragmented; small subnets placed first can block every aligned slot for a big one.

## Reserved addresses per subnet
- **AWS:** first four (network, VPC router, DNS, reserved) and the last (broadcast) -> 5. VPC CIDR /16 to /28, subnets /16 to /28. Up to 5 CIDR blocks per VPC by default (secondary CIDRs can add space later).
- **Azure:** first four (network, gateway, 2 x DNS) and the last -> 5. Subnets up to /29. Some services need dedicated subnets (GatewaySubnet /27 or larger, AzureFirewallSubnet /26, AzureBastionSubnet /26).
- **GCP:** network, gateway, second-to-last and broadcast -> 4. Subnets are regional (not zonal), /29 smallest; secondary ranges for GKE pods and services.
- **Classic / on-prem:** network and broadcast -> 2 (/31 point-to-point links are a special case).

## Private and special ranges
- RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16.
- Carrier-grade NAT shared space 100.64.0.0/10 (RFC 6598): usable inside clouds, but check the ISP / VPN does not use it.
- Avoid: 172.17.0.0/16 (default docker0 bridge), 169.254.0.0/16 (link-local, cloud metadata), 192.168.0.0/24 and 192.168.1.0/24 (home routers, so VPN users clash), 10.0.0.0/16 (default VPC in many tools, so peers often clash).
- Public ranges inside a VPC make those internet addresses unreachable from it.

## Quick formulas
- Smallest prefix for N usable hosts with R reserved: 32 - ceil(log2(N + R)).
- Hosts with growth: ceil(hosts x (1 + growth)).
- Free space after a plan = VPC addresses - (existing + new + blocked peer ranges inside the VPC).
FILE:references/subnet-layout-playbook.md
# Subnet Layout Playbook

## Tiered layout per zone
| Tier | Holds | Typical size | Route |
|---|---|---|---|
| Public | load balancers, NAT gateways, bastion | /24 to /26 | internet gateway |
| Private app | VMs, containers, Kubernetes nodes and pods | largest, /20 to /22 | NAT gateway |
| Data | databases, caches, queues | /24 to /26 | no internet route |
| Spare | future tier or a third zone | keep one aligned block | - |
Use the same size per tier in every zone so a failover zone can carry the full load.

## Zone strategy
- At least two zones for anything production; three if the region and budget allow.
- Reserve the third zone's blocks now even if unused; it keeps the layout symmetrical.
- GCP subnets are regional, so plan per region instead of per zone.

## Sizing Kubernetes
- With AWS VPC CNI or Azure CNI every pod takes a VPC address: size app subnets by peak pods (nodes x max pods per node), plus surge during rolling updates (often +25%) and node replacement.
- Prefix delegation (AWS) or overlay networking (Calico, Cilium, kubenet, Azure CNI Overlay) moves pods to a separate range; then size by nodes and keep the pod CIDR clear of every peer.
- Keep the service CIDR (for example 172.20.0.0/16) clear of the VPC and peers too.

## Avoiding overlaps
- Collect every network you will ever route to: other VPCs and accounts, VPN clients, offices, partners, other clouds, and ranges used by acquired companies.
- Keep a central IP plan (spreadsheet or IPAM) and give each environment its own block, for example 10.20.0.0/16 prod, 10.21.0.0/16 staging, 10.22.0.0/16 dev.
- Do not pick 10.0.0.0/16, 172.17.0.0/16 or 192.168.0.0/24 to 192.168.1.0/24 for anything that VPN users reach.

## When something already overlaps
1. Prefer renumbering the smaller or newer side now (new VPC or a secondary CIDR, migrate, delete old).
2. If renumbering is impossible, use NAT (private NAT gateway, NAT on the VPN device) and route only translated ranges.
3. Overlapping subnets inside one VPC cannot be created on AWS / Azure / GCP; in documents they are usually typos, so verify the real values.

## Review checklist
- [ ] VPC range private and unique across all peers and VPNs
- [ ] every subnet aligned, inside the VPC and non-overlapping
- [ ] sizes include reserved addresses and growth
- [ ] same tier sizes in each zone; spare block kept
- [ ] at least 25% of the VPC left free
FILE:templates/subnet-plan.md
# Subnet Plan - <network name>

**Provider / region:** <aws eu-west-1>  **VPC CIDR:** <10.x.0.0/16>  **Owner:** <team>  **Date:** <date>
**Peers / VPNs checked:** <list of ranges>

## Subnets
| Subnet | Tier | Zone | Hosts now | Growth | CIDR | Usable | Route table |
|---|---|---|---|---|---|---|---|
| | | | | | | | |

## Existing subnets kept
| Name | CIDR | Notes |
|---|---|---|
| | | |

## Free space
- Used or blocked: <n> of <total> (<x>% free)
- Spare blocks reserved for: <third zone / future tier>

## Findings and decisions
| Severity | Finding | Decision |
|---|---|---|
| | | |

## Rollout order
1. <create secondary CIDR / new VPC>
2. <create subnets and route tables>
3. <migrate workloads, remove old subnets>
FILE:examples/shop-platform-vpc.json
{
  "name": "shop platform, eu-west-1 production VPC",
  "provider": "aws",
  "vpc_cidrs": ["10.20.0.0/18"],
  "existing": [
    {"name": "legacy bastion", "cidr": "10.20.0.0/26"},
    {"name": "legacy rds-a", "cidr": "10.20.1.0/24"},
    {"name": "legacy rds-b", "cidr": "10.20.1.128/25"}
  ],
  "peers": [
    {"name": "office VPN (Istanbul)", "cidr": "192.168.10.0/24"},
    {"name": "analytics VPC (peered)", "cidr": "10.20.48.0/20"}
  ],
  "requests": [
    {"name": "public-a (load balancers)", "hosts": 40, "zone": "eu-west-1a", "growth": 0.5},
    {"name": "public-b (load balancers)", "hosts": 40, "zone": "eu-west-1b", "growth": 0.5},
    {"name": "app-a (EKS pods)", "hosts": 2500, "zone": "eu-west-1a", "growth": 0.6},
    {"name": "app-b (EKS pods)", "hosts": 2500, "zone": "eu-west-1b", "growth": 0.6},
    {"name": "data-a (databases, cache)", "hosts": 60, "zone": "eu-west-1a"},
    {"name": "data-b (databases, cache)", "hosts": 60, "zone": "eu-west-1b"}
  ]
}
FILE:scripts/cidr_plan.py
#!/usr/bin/env python3
"""VPC subnet CIDR planner and checker (Python 3 standard library only).

Input: a network plan JSON file:
  {"name": "prod-eu", "provider": "aws", "vpc_cidrs": ["10.40.0.0/16"],
   "existing": [{"name": "legacy-db", "cidr": "10.40.8.0/24"}],
   "peers": [{"name": "office vpn", "cidr": "192.168.0.0/22"}],
   "requests": [{"name": "app-a", "hosts": 900, "zone": "eu-west-1a", "growth": 0.5}]}
  provider: aws | azure | gcp | generic. Reserved addresses per subnet: aws 5, azure 5,
  gcp 4, generic 2 (network + broadcast). Subnet size limits: aws /16../28,
  azure /8../29, gcp /8../29, generic /8../30.
  requests: hosts needed now; growth = extra fraction to reserve (default 0.3);
  optional "prefix" forces a size. Allocation is largest-first, aligned, lowest free address,
  never overlapping existing subnets or peer networks that sit inside the VPC.

Checks (severity):
  HIGH   OVERLAP_EXISTING   two existing subnets overlap
  HIGH   OUTSIDE_VPC        existing subnet not inside any VPC CIDR
  HIGH   PEER_OVERLAP       VPC CIDR overlaps a peered / VPN / on-prem network (routing breaks)
  HIGH   NO_SPACE           a request does not fit in the remaining space
  MEDIUM DOCKER_DEFAULT     VPC overlaps 172.17.0.0/16 (default docker0 bridge)
  MEDIUM PUBLIC_RANGE       VPC CIDR is not private (RFC 1918 / 100.64.0.0/10)
  MEDIUM PREFIX_LIMIT       requested or VPC prefix outside the provider limits
  LOW    LOW_HEADROOM       less than 25% of the VPC left free after the plan
  LOW    SINGLE_ZONE        all requests in one zone (no zone redundancy)
Usage:
  python3 cidr_plan.py plan.json
  python3 cidr_plan.py plan.json --json
  python3 cidr_plan.py --self-test
Exit code: 0 no HIGH findings, 1 HIGH findings, 2 bad input.
"""
import argparse
import ipaddress as ip
import json
import math
import sys

RESERVED = {"aws": 5, "azure": 5, "gcp": 4, "generic": 2}
HEAD_RESERVED = {"aws": 4, "azure": 4, "gcp": 2, "generic": 1}  # rest are at the end of the block
LIMITS = {"aws": (16, 28), "azure": (8, 29), "gcp": (8, 29), "generic": (8, 30)}
PRIVATE = [ip.ip_network(c) for c in ("10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "100.64.0.0/10")]
DOCKER = ip.ip_network("172.17.0.0/16")


class PlanError(ValueError):
    pass


def net(cidr, what="cidr"):
    try:
        n = ip.ip_network(str(cidr).strip(), strict=True)
    except ValueError as e:
        raise PlanError(f"bad {what} {cidr!r}: {e}")
    if n.version != 4:
        raise PlanError(f"only IPv4 is supported: {cidr!r}")
    return n


def usable(prefix, provider):
    return max(0, 2 ** (32 - prefix) - RESERVED[provider])


def prefix_for(hosts, provider, growth):
    need = math.ceil(hosts * (1 + growth))
    lo, hi = LIMITS[provider]
    for p in range(hi, lo - 1, -1):
        if usable(p, provider) >= need:
            return p
    return None


def find_slot(vpcs, taken, prefix):
    for v in vpcs:
        if prefix < v.prefixlen:
            continue
        for cand in v.subnets(new_prefix=prefix):
            if not any(cand.overlaps(t) for t in taken):
                return cand
    return None


def plan(cfg):
    provider = str(cfg.get("provider", "generic")).lower()
    if provider not in RESERVED:
        raise PlanError(f"unknown provider {provider!r} (aws, azure, gcp, generic)")
    vpcs = [net(c, "vpc_cidr") for c in cfg.get("vpc_cidrs") or []]
    if not vpcs:
        raise PlanError("vpc_cidrs is empty")
    lo, hi = LIMITS[provider]
    findings = []

    def f(sev, code, where, msg):
        findings.append({"severity": sev, "code": code, "where": where, "message": msg})

    for v in vpcs:
        if not any(v.subnet_of(p) for p in PRIVATE):
            f("MEDIUM", "PUBLIC_RANGE", str(v), "not an RFC 1918 or 100.64.0.0/10 range; it may clash with real internet addresses")
        if v.overlaps(DOCKER):
            f("MEDIUM", "DOCKER_DEFAULT", str(v), "overlaps 172.17.0.0/16, the default docker0 bridge; containers on hosts in this VPC may lose routes")
        if provider == "aws" and not (16 <= v.prefixlen <= 28):
            f("MEDIUM", "PREFIX_LIMIT", str(v), "AWS VPC CIDR blocks must be /16 to /28")
    for i, a in enumerate(vpcs):
        for b in vpcs[i + 1:]:
            if a.overlaps(b):
                raise PlanError(f"vpc_cidrs overlap each other: {a} and {b}")

    existing = []
    for e in cfg.get("existing") or []:
        n = net(e.get("cidr"), "existing cidr")
        name = e.get("name") or str(n)
        if not any(n.subnet_of(v) for v in vpcs):
            f("HIGH", "OUTSIDE_VPC", name, f"{n} is not inside {', '.join(map(str, vpcs))}")
        for other_name, o in existing:
            if n.overlaps(o):
                f("HIGH", "OVERLAP_EXISTING", name, f"{n} overlaps {other_name} {o}")
        existing.append((name, n))

    taken = [n for _, n in existing]
    for p in cfg.get("peers") or []:
        n = net(p.get("cidr"), "peer cidr")
        name = p.get("name") or str(n)
        for v in vpcs:
            if v.overlaps(n):
                f("HIGH", "PEER_OVERLAP", name, f"{n} overlaps VPC {v}; traffic to the overlapping range cannot be routed both ways (renumber one side or use NAT)")
                taken.append(n)

    reqs = []
    for r in cfg.get("requests") or []:
        name = r.get("name") or "subnet"
        hosts = r.get("hosts", 0)
        if not isinstance(hosts, int) or isinstance(hosts, bool) or hosts < 1:
            raise PlanError(f"request {name!r}: hosts must be a positive integer")
        growth = r.get("growth", 0.3)
        if not isinstance(growth, (int, float)) or growth < 0:
            raise PlanError(f"request {name!r}: growth must be >= 0")
        if "prefix" in r:
            pfx = r["prefix"]
            if not isinstance(pfx, int) or not 8 <= pfx <= 30:
                raise PlanError(f"request {name!r}: prefix must be an integer 8..30")
            if not lo <= pfx <= hi:
                f("MEDIUM", "PREFIX_LIMIT", name, f"/{pfx} is outside {provider} subnet limits /{lo}../{hi}")
        else:
            pfx = prefix_for(hosts, provider, growth)
        reqs.append({"name": name, "hosts": hosts, "growth": growth, "zone": r.get("zone", ""), "prefix": pfx})

    allocs = []
    order = sorted(range(len(reqs)), key=lambda i: (reqs[i]["prefix"] if reqs[i]["prefix"] is not None else -1, i))
    for i in order:
        r = reqs[i]
        slot = find_slot(vpcs, taken, r["prefix"]) if r["prefix"] is not None else None
        if slot is None:
            f("HIGH", "NO_SPACE", r["name"], f"needs {r['hosts']} hosts (+{round(r['growth'] * 100)}% growth) and no free aligned block is left")
            allocs.append(dict(r, cidr=None, usable=0))
            continue
        taken.append(slot)
        u = usable(slot.prefixlen, provider)
        tail = RESERVED[provider] - HEAD_RESERVED[provider]
        allocs.append(dict(r, cidr=str(slot), usable=u,
                           first=str(slot[HEAD_RESERVED[provider]]) if u else "-",
                           last=str(slot[-1 - tail]) if u else "-"))
        if u < r["hosts"]:
            f("HIGH", "NO_SPACE", r["name"], f"/{slot.prefixlen} gives only {u} usable addresses for {r['hosts']} hosts")
    allocs.sort(key=lambda a: (a["cidr"] is None, ip.ip_network(a["cidr"]) if a["cidr"] else 0))

    total = sum(v.num_addresses for v in vpcs)
    used = 0
    inside = [t for t in taken if any(t.subnet_of(v) for v in vpcs)]
    for t in ip.collapse_addresses(inside):
        used += t.num_addresses
    free = total - used
    free_blocks = []
    for v in vpcs:
        rest = [v]
        for t in ip.collapse_addresses([x for x in inside if x.subnet_of(v)]):
            nxt = []
            for b in rest:
                if t.subnet_of(b):
                    nxt.extend(b.address_exclude(t))
                elif not b.subnet_of(t):
                    nxt.append(b)
            rest = nxt
        free_blocks.extend(sorted(rest))
    if total and free / total < 0.25:
        f("LOW", "LOW_HEADROOM", "plan", f"only {free / total:.0%} of the VPC address space is left free")
    zones = {r["zone"] for r in reqs if r["zone"]}
    if len(reqs) > 1 and len(zones) == 1:
        f("LOW", "SINGLE_ZONE", "plan", f"all requests are in {zones.pop()}; spread subnets over at least two zones")
    rank = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}
    findings.sort(key=lambda x: rank[x["severity"]])
    return {"name": cfg.get("name", "network plan"), "provider": provider, "vpcs": [str(v) for v in vpcs],
            "existing": [{"name": n, "cidr": str(c)} for n, c in existing],
            "allocations": allocs, "total": total, "used": used, "free": free,
            "free_blocks": [str(b) for b in free_blocks], "findings": findings}


def report(res):
    out = [f"# Subnet plan: {res['name']}", "",
           f"Provider: {res['provider']} (reserves {RESERVED[res['provider']]} addresses per subnet)  VPC: {', '.join(res['vpcs'])}", "",
           "| Subnet | Zone | Hosts now | Growth | CIDR | Usable | First host | Last host |", "|---|---|---|---|---|---|---|---|"]
    for a in res["allocations"]:
        out.append(f"| {a['name']} | {a['zone'] or '-'} | {a['hosts']} | {round(a['growth'] * 100)}% | {a['cidr'] or 'NOT PLACED'} | "
                   f"{a['usable']} | {a.get('first', '-')} | {a.get('last', '-')} |")
    if res["existing"]:
        out += ["", "Existing subnets kept: " + ", ".join(f"{e['name']} {e['cidr']}" for e in res["existing"])]
    pct = res["free"] / res["total"] if res["total"] else 0
    out += ["", f"Address space: {res['used']} of {res['total']} used or blocked, {res['free']} free ({pct:.0%})",
            "Largest free blocks: " + (", ".join(sorted(res["free_blocks"], key=lambda c: ip.ip_network(c).prefixlen)[:6]) or "none"),
            "", "## Findings"]
    if not res["findings"]:
        out.append("- none")
    for x in res["findings"]:
        out.append(f"- **{x['severity']} {x['code']}** ({x['where']}): {x['message']}")
    return "\n".join(out) + "\n"


def self_test():
    cases = []

    def ok(name, cond):
        cases.append(bool(cond))
        print(("PASS " if cond else "FAIL ") + name)

    ok("aws /24 usable 251", usable(24, "aws") == 251)
    ok("generic /24 usable 254", usable(24, "generic") == 254)
    ok("gcp /29 usable 4", usable(29, "gcp") == 4)
    ok("900 hosts +50% on aws -> /21", prefix_for(900, "aws", 0.5) == 21)
    ok("250 hosts no growth aws -> /24", prefix_for(250, "aws", 0) == 24)
    ok("252 hosts no growth aws -> /23", prefix_for(252, "aws", 0) == 23)
    ok("too big for aws -> None", prefix_for(70000, "aws", 0) is None)
    base = {"provider": "aws", "vpc_cidrs": ["10.0.0.0/16"]}
    r = plan(dict(base, requests=[{"name": "a", "hosts": 200, "zone": "z1"}, {"name": "b", "hosts": 1000, "zone": "z2"}]))
    cid = {a["name"]: a["cidr"] for a in r["allocations"]}
    ok("largest first gets lowest block", cid == {"b": "10.0.0.0/21", "a": "10.0.8.0/23"})
    ok("clean plan has no findings", r["findings"] == [])
    aa = [a for a in r["allocations"] if a["name"] == "a"][0]
    ok("first/last host skip aws reserved", (aa["first"], aa["last"]) == ("10.0.8.4", "10.0.9.254"))
    g = plan({"provider": "gcp", "vpc_cidrs": ["10.0.0.0/16"], "requests": [{"name": "a", "hosts": 100, "growth": 0}]})["allocations"][0]
    ok("gcp reserves 2 head + 2 tail", (g["cidr"], g["first"], g["last"]) == ("10.0.0.0/25", "10.0.0.2", "10.0.0.125"))
    r = plan(dict(base, existing=[{"name": "old", "cidr": "10.0.0.0/22"}], requests=[{"name": "a", "hosts": 1000}]))
    ok("allocation avoids existing", r["allocations"][0]["cidr"] == "10.0.8.0/21")
    r = plan(dict(base, existing=[{"name": "x", "cidr": "10.0.0.0/24"}, {"name": "y", "cidr": "10.0.0.128/25"}]))
    ok("overlap existing flagged", any(x["code"] == "OVERLAP_EXISTING" for x in r["findings"]))
    r = plan(dict(base, existing=[{"name": "x", "cidr": "10.1.0.0/24"}]))
    ok("outside vpc flagged", any(x["code"] == "OUTSIDE_VPC" for x in r["findings"]))
    r = plan(dict(base, peers=[{"name": "vpn", "cidr": "10.0.4.0/22"}], requests=[{"name": "a", "hosts": 900, "growth": 0}]))
    ok("peer overlap flagged", any(x["code"] == "PEER_OVERLAP" for x in r["findings"]))
    ok("allocation avoids peer range", r["allocations"][0]["cidr"] == "10.0.0.0/22")
    r = plan({"provider": "aws", "vpc_cidrs": ["10.0.0.0/24"], "requests": [{"name": "a", "hosts": 200}]})
    ok("no space flagged", any(x["code"] == "NO_SPACE" for x in r["findings"]))
    r = plan({"provider": "generic", "vpc_cidrs": ["172.16.0.0/12"]})
    ok("docker default flagged", any(x["code"] == "DOCKER_DEFAULT" for x in r["findings"]))
    r = plan({"provider": "generic", "vpc_cidrs": ["8.8.0.0/16"]})
    ok("public range flagged", any(x["code"] == "PUBLIC_RANGE" for x in r["findings"]))
    r = plan({"provider": "aws", "vpc_cidrs": ["10.0.0.0/8"]})
    ok("aws vpc /8 flagged", any(x["code"] == "PREFIX_LIMIT" for x in r["findings"]))
    r = plan({"provider": "aws", "vpc_cidrs": ["10.0.0.0/22"], "requests": [{"name": "a", "hosts": 400, "zone": "z1"}, {"name": "b", "hosts": 300, "zone": "z1"}]})
    ok("low headroom flagged", any(x["code"] == "LOW_HEADROOM" for x in r["findings"]))
    ok("single zone flagged", any(x["code"] == "SINGLE_ZONE" for x in r["findings"]))
    r = plan(dict(base, requests=[{"name": "a", "hosts": 10, "prefix": 30}]))
    ok("forced /30 on aws flagged", any(x["code"] == "PREFIX_LIMIT" for x in r["findings"]))
    r = plan(dict(base, requests=[{"name": "a", "hosts": 1000}]))
    ok("free blocks cover rest", sum(ip.ip_network(b).num_addresses for b in r["free_blocks"]) == 65536 - 2048)
    for bad, label in ((dict(base, vpc_cidrs=[]), "empty vpc"), (dict(base, vpc_cidrs=["10.0.0.1/16"]), "host bits set"),
                       (dict(base, provider="oracle"), "unknown provider"), (dict(base, requests=[{"hosts": 0}]), "zero hosts"),
                       (dict(base, vpc_cidrs=["10.0.0.0/16", "10.0.128.0/17"]), "overlapping vpcs"),
                       (dict(base, vpc_cidrs=["fd00::/48"]), "ipv6")):
        try:
            plan(bad)
            ok(label + " rejected", False)
        except PlanError:
            ok(label + " rejected", True)
    print(f"{sum(cases)}/{len(cases)} passed")
    return 0 if all(cases) else 1


def main(argv=None):
    ap = argparse.ArgumentParser(description="Plan and check VPC subnet CIDR blocks.")
    ap.add_argument("file", nargs="?", help="network plan JSON")
    ap.add_argument("--json", action="store_true", help="print machine-readable JSON")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.file:
        ap.error("give a plan JSON file or --self-test")
    try:
        cfg = json.load(open(a.file, encoding="utf-8"))
        res = plan(cfg)
    except (OSError, json.JSONDecodeError, PlanError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    print(json.dumps(res, indent=2) if a.json else report(res), end="" if not a.json else "\n")
    return 1 if any(x["severity"] == "HIGH" for x in res["findings"]) else 0


if __name__ == "__main__":
    sys.exit(main())