docs: restructure agent instructions to proper skill files

Author: JohannesRudolph

.agents/skills/aws-backplane.md .agents/references/aws-backplane.md.agents/skills/aws-backplane.md renamed to .agents/references/aws-backplane.md

@@ -0,0 +1,95 @@
+---
+name: module
+description: >
+  Create or update a meshstack-hub building block module. Covers the full lifecycle: module
+  structure, backplane identity (per cloud provider), BBD readme, and scorecard compliance.
+  Use when asked to create a new module, add or fix a backplane, write the readme, or resolve
+  scorecard violations.
+---
+
+# Module Skill
+
+This skill drives two workflows: **creating** a new building block module and **keeping modules up
+to date** with the latest conventions (scorecard fixes). For backplane identity details and readme
+conventions, see the reference files in `.agents/references/`.
+
+---
+
+## Workflow: Creating a New Module
+
+1. **Determine scope** — identify the cloud provider and service name → module path `modules/<provider>/<service>/`
+
+2. **Create the directory structure** (AGENTS.md § Module Structure):
+   ```
+   modules/<provider>/<service>/
+   ├── backplane/          # omit if no cloud-side setup needed
+   ├── buildingblock/
+   └── meshstack_integration.tf
+   ```
+
+3. **Implement `buildingblock/`** — `main.tf`, `variables.tf`, `outputs.tf`, `versions.tf`, `provider.tf`, `README.md` (with YAML front-matter), `logo.png`
+
+4. **Implement `backplane/`** (if needed) — read the provider-specific reference:
+   - AWS → `.agents/references/aws-backplane.md`
+   - Azure → `.agents/references/azure-backplane.md`
+   - STACKIT → `.agents/references/stackit-backplane.md`
+
+5. **Write the BBD readme** → `.agents/references/bbd-readme.md`
+
+6. **Write `meshstack_integration.tf`** — follow AGENTS.md § `meshstack_integration.tf` Conventions
+
+7. **Validate**:
+   ```sh
+   terraform validate   # in buildingblock/ and backplane/ if present
+   ```
+
+8. **Run scorecard** and iterate until all checks pass:
+   ```sh
+   tools/scorecard/scorecard.mjs --module=<provider>/<service>
+   ```
+
+---
+
+## Workflow: Fixing Scorecard Violations
+
+1. **Identify violations**:
+   ```sh
+   tools/scorecard/scorecard.mjs --module=<provider>/<service>
+   ```
+
+2. **Get fix hints** — structured list of failing checks with references to the relevant docs:
+   ```sh
+   tools/scorecard/scorecard.mjs --module=<provider>/<service> --fix
+   ```
+
+3. **Apply fixes** — for each failing check, read the referenced section and fix the module. Work category by category: **Core → Integration → Azure Backplane → Testing**.
+
+4. **Verify** after each category:
+   ```sh
+   tools/scorecard/scorecard.mjs --module=<provider>/<service>
+   ```
+   Repeat until all checks show ✅.
+
+5. **Commit**:
+   ```
+   fix(<provider>/<service>): resolve scorecard violations
+   ```
+
+### Scorecard fix notes
+
+- **`logo` check**: requires `buildingblock/logo.png` (256×256 px, flat-design, white-background icon). Generate with an AI image tool if missing, then resize and optimise with `pngquant`.
+- **`e2e_tests` / `e2e_tftest`**: creating a full e2e test is a larger task — check with the module owner before adding. See `.agents/skills/write-e2e-test/SKILL.md`.
+- **Never** fix a check by editing the check logic in `scorecard.mjs` — fix the module.
+
+---
+
+## Key references
+
+| Topic | Reference |
+|---|---|
+| Module structure & `meshstack_integration.tf` | AGENTS.md |
+| BBD readme | `.agents/references/bbd-readme.md` |
+| AWS backplane identity | `.agents/references/aws-backplane.md` |
+| Azure backplane identity | `.agents/references/azure-backplane.md` |
+| STACKIT backplane identity | `.agents/references/stackit-backplane.md` |
+| E2E tests | `.agents/skills/write-e2e-test/SKILL.md` |

.agents/skills/azure-backplane.md .agents/references/azure-backplane.md.agents/skills/azure-backplane.md renamed to .agents/references/azure-backplane.md

@@ -189,28 +189,28 @@ node tools/scorecard/scorecard.mjs --module=<provider>/<service>
 node tools/scorecard/scorecard.mjs --module=<provider>/<service> --fix
 ```
 
-To fix violations, see [.agents/skills/fix-scorecard.md](.agents/skills/fix-scorecard.md).
+To fix violations, see the `module` skill (`.agents/skills/module/SKILL.md`).
 
 ---
 
 ## AWS Backplane Identity Conventions
 
-See [.agents/skills/aws-backplane.md](.agents/skills/aws-backplane.md) for the full AWS backplane identity conventions, including WIF (OIDC + IAM role) and cross-account (IAM user + CloudFormation StackSet) patterns, required variables/outputs, and the AWS backplane checklist.
+See [.agents/references/aws-backplane.md](.agents/references/aws-backplane.md) for the full AWS backplane identity conventions, including WIF (OIDC + IAM role) and cross-account (IAM user + CloudFormation StackSet) patterns, required variables/outputs, and the AWS backplane checklist.
 
 ## Azure Backplane Identity Conventions
 
-See [.agents/skills/azure-backplane.md](.agents/skills/azure-backplane.md) for the full Azure backplane identity conventions, including UAMI patterns, WIF wiring, required variables/outputs, and the Azure backplane checklist.
+See [.agents/references/azure-backplane.md](.agents/references/azure-backplane.md) for the full Azure backplane identity conventions, including UAMI patterns, WIF wiring, required variables/outputs, and the Azure backplane checklist.
 
 ## STACKIT Backplane Identity Conventions
 
-See [.agents/skills/stackit-backplane.md](.agents/skills/stackit-backplane.md) for the full STACKIT backplane identity conventions, including the service account + key pattern, required variables/outputs, provider configuration, and the STACKIT backplane checklist.
+See [.agents/references/stackit-backplane.md](.agents/references/stackit-backplane.md) for the full STACKIT backplane identity conventions, including the service account + key pattern, required variables/outputs, provider configuration, and the STACKIT backplane checklist.
 
 ---
 
 <!-- scorecard-checks: readme_frontmatter, logo, app_team_readme, bbd_readme, bbd_readme_no_leading_heading, bbd_readme_shared_responsibility -->
 ## Documentation Requirements
 
-See [.agents/skills/bbd-readme.md](.agents/skills/bbd-readme.md) for the complete BBD readme specification, template, and checklist.
+See [.agents/references/bbd-readme.md](.agents/references/bbd-readme.md) for the complete BBD readme specification, template, and checklist.
 
 **`buildingblock/README.md`** — must include YAML front-matter:
 
@@ -225,7 +225,7 @@ description: One-sentence description of what the module provisions.
 
 **User-facing readme — two patterns depending on module completeness:**
 
-- **Modules with `meshstack_integration.tf`** (full building blocks): user-facing readme lives in the `readme` field of `meshstack_building_block_definition.spec`. Always use `chomp(<<-EOT)` inline — never `file()` or a separate file (one-file copy/paste requirement). See [.agents/skills/bbd-readme.md](.agents/skills/bbd-readme.md) for full spec.
+- **Modules with `meshstack_integration.tf`** (full building blocks): user-facing readme lives in the `readme` field of `meshstack_building_block_definition.spec`. Always use `chomp(<<-EOT)` inline — never `file()` or a separate file (one-file copy/paste requirement). See [.agents/references/bbd-readme.md](.agents/references/bbd-readme.md) for full spec.
 
 - **Modules without `meshstack_integration.tf`** (standalone building blocks): place the user-facing readme at `buildingblock/APP_TEAM_README.md`. meshStack uses this file as a fallback when no inline readme is available. The same content requirements apply (plain-text description first, usage motivation, examples, shared responsibility table).
 
@@ -313,7 +313,7 @@ getting-started steps, and shared responsibility matrix.
 
 Modules that can be smoke-tested against a live meshStack instance should include an `e2e/` directory alongside the module root.
 
-See [.claude/skills/write-e2e-test/SKILL.md](.claude/skills/write-e2e-test/SKILL.md) (the `write-e2e-test` skill) for the full e2e testing conventions, including the `e2e/` structure, `test_context` wiring, `e2e/main.tf` and `*.tftest.hcl` conventions, the new-test checklist, and how to run and debug tests via the smoke-test runner.
+See [.agents/skills/write-e2e-test/SKILL.md](.agents/skills/write-e2e-test/SKILL.md) (the `write-e2e-test` skill) for the full e2e testing conventions, including the `e2e/` structure, `test_context` wiring, `e2e/main.tf` and `*.tftest.hcl` conventions, the new-test checklist, and how to run and debug tests via the smoke-test runner.
 
 ---
 
@@ -324,7 +324,7 @@ See [.claude/skills/write-e2e-test/SKILL.md](.claude/skills/write-e2e-test/SKILL
 - [ ] Provider versions pinned with `~>`
 - [ ] Variables in `snake_case` with cloud-provider prefix in `meshstack_integration.tf` (e.g. `azure_tenant_id`)
 - [ ] `buildingblock/README.md` with YAML front-matter
-- [ ] BBD `readme` field uses `chomp(<<-EOT)` inline (no `file()`), starts with plain-text description (no `#` heading), and includes usage motivation, 1–2 examples, and a shared responsibility table with ✅ / ❌ — see [.agents/skills/bbd-readme.md](.agents/skills/bbd-readme.md)
+- [ ] BBD `readme` field uses `chomp(<<-EOT)` inline (no `file()`), starts with plain-text description (no `#` heading), and includes usage motivation, 1–2 examples, and a shared responsibility table with ✅ / ❌ — see [.agents/references/bbd-readme.md](.agents/references/bbd-readme.md)
 - [ ] If no `meshstack_integration.tf`: `buildingblock/APP_TEAM_README.md` is present with the same content requirements (plain-text description first, motivation, examples, shared responsibility table)
 - [ ] `meshstack_integration.tf` declares `meshcloud/meshstack` in `required_providers`
 - [ ] `meshstack_integration.tf` uses `variable "hub" { type = object({git_ref = string}) }` and `variable "meshstack" { type = object({owning_workspace_identifier = string}) }`
@@ -341,4 +341,4 @@ See [.claude/skills/write-e2e-test/SKILL.md](.claude/skills/write-e2e-test/SKILL
 - [ ] `logo.png` included in `buildingblock/`
 - [ ] No `documentation_md` output in `backplane/` — use BBD `readme` field and `backplane/README.md` instead
 - [ ] No trailing whitespace
-- [ ] **Azure modules**: also follow the [Azure Backplane Checklist](.agents/skills/azure-backplane.md#checklist-for-azure-backplanes)
+- [ ] **Azure modules**: also follow the [Azure Backplane Checklist](.agents/references/azure-backplane.md#checklist-for-azure-backplanes)

.agents/skills/bbd-readme.md .agents/references/bbd-readme.md.agents/skills/bbd-readme.md renamed to .agents/references/bbd-readme.md

@@ -53,9 +53,9 @@ const CATEGORIES = {
 // Each detector returns { pass: boolean, detail?: string }
 
 const AGENTS     = (section) => ({ file: "AGENTS.md", section });
-const AZURE      = (section) => ({ file: ".agents/skills/azure-backplane.md", section });
-const BBD_README = (section) => ({ file: ".agents/skills/bbd-readme.md", section });
-const E2E        = (section) => ({ file: ".claude/skills/write-e2e-test/SKILL.md", section });
+const AZURE      = (section) => ({ file: ".agents/references/azure-backplane.md", section });
+const BBD_README = (section) => ({ file: ".agents/references/bbd-readme.md", section });
+const E2E        = (section) => ({ file: ".agents/skills/write-e2e-test/SKILL.md", section });
 
 const detectors = [
   // ─── Core Structure ─────────────────────────────────────────────────────