Skip to content

SKILL.md

Latest commit

 

History

History
99 lines (75 loc) · 3.93 KB

SKILL.md

File metadata and controls

99 lines (75 loc) · 3.93 KB
Raw
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
    • GCP → .agents/references/gcp-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

    • Always add lifecycle { ignore_changes = [ availability ] } to every meshstack_platform resource (see AGENTS.md § meshstack_platform Lifecycle)

  7. Validate:

    terraform validate   # in buildingblock/ and backplane/ if present

  8. Run scorecard and iterate until all checks pass:

    tools/scorecard/scorecard.mjs --module=<provider>/<service>

Workflow: Fixing Scorecard Violations

  1. Identify violations:

    tools/scorecard/scorecard.mjs --module=<provider>/<service>

  2. Get fix hints — structured list of failing checks with references to the relevant docs:

    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:

    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 recommended, flat-design, white-background icon). ci/validate_modules.sh rejects anything larger than 512 px in either dimension. Generate with an AI image tool if missing, then run bash ci/validate_modules.sh --fix to resize and optimise it 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/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
Terraform/OpenTofu coding conventions .agents/references/terraform-conventions.md
BBD readme .agents/references/bbd-readme.md
AWS backplane identity .agents/references/aws-backplane.md
Azure backplane identity .agents/references/azure-backplane.md
GCP backplane conventions .agents/references/gcp-backplane.md
STACKIT backplane identity .agents/references/stackit-backplane.md
E2E tests .agents/skills/e2e-test/SKILL.md