googlecloudplatform/cloud-foundation-fabric/contributing

Claude Code and agent skill by googlecloudplatform/cloud-foundation-fabric

Trust tier 2
  • community
LLM review pending
Source check pending

Checking that the SKILL.md file is still in the repository.

End-to-end workflow for contributing to Cloud Foundation Fabric: triaging GitHub issues, proactive feature development, validating with tests and Policy Troubleshooter, and submitting sanitized Pull Requests. Use when addressing a Fabric GitHub issue, developing a module or FAST stage change, or preparing a branch for a pull request.

Install

npx vskill@latest install googlecloudplatform/cloud-foundation-fabric/contributing

SKILL.md

The same SKILL.md was published earlier as googlecloudplatform/cloud-foundation-fabric/contributing.

Fabric Contribution Flow Skill

This skill defines the end-to-end workflow for contributing to Cloud Foundation Fabric. It supports two entry modes:

  • Mode A: Issue Triage & Bug Fix: You are addressing an assigned or reported GitHub Issue. Start at Step 1.
  • Mode B: Proactive Development & PR Prep: You are actively building a feature, refactoring code, or preparing an existing branch for a Pull Request. Jump directly to the Design Sign-off Gate before Step 2.

If it is unclear which mode applies, ask the user before proceeding.

Human-in-the-Loop Gates

Gate on steps that are hard to reverse, costly, or where your judgment is likely to diverge from a maintainer's. Keep mechanical, reversible steps (linting, tests, doc and inventory regeneration) autonomous. Gates are blocking: if you are running non-interactively and cannot get an answer, stop — never assume approval.

GateWhenWhat the human decides
Triage DispositionEnd of Step 1 (Mode A)Whether the issue is in scope and worth pursuing: proceed, reject, or escalate.
Design Sign-offBefore Step 2Approves the proposed design and scope. Mandatory for new features and interface changes; skippable for trivial fixes where the design is self-evident.
E2E Opt-inStep 5Whether to run live cloud verification. Providing a sandbox project ID is the consent to deploy to it.
Behavioral Verification Opt-inStep 5, after read-back verificationWhether to also verify runtime behavior of the deployed resources, given the described extra time and cost.
PR ApprovalStep 6Reviews the final sanitized PR body before submission.

Step-by-Step Workflow

mermaid
graph TD
M1[Mode A: Issue Triage] --> A[1. Triage Issue]
A --> GT{Gate: Triage Disposition}
GT -->|Human approves| GD{Gate: Design Sign-off}
GT -->|Human rejects| X[Stop / Report Back]
M2[Mode B: Proactive Dev] --> GD
GD --> B[2. Develop Fix / Feature]
B --> C[3. Tests, Lint & Inventories]
C --> D[4. Pre-Submission Self-Review]
D -->|Issues found| B
D -->|Clean| GE{Gate: E2E Opt-in}
GE -->|Project ID provided| G[5. Live E2E Verification]
GE -->|Skipped| GS{Gate: PR Approval}
G -->|Failures| B
G -->|Verified| GS
GS --> F[6. Commit & Submit Sanitized PR]
Step 1: Triage the Issue (Mode A Only)
  1. Retrieve Issue Details: Use the GitHub CLI to view the issue context.

``bash gh issue view <issue-number> ``

  1. Explore the Codebase: Identify the target module (modules/<module-name>) or FAST stage (fast/stages/<stage-name>) that requires modification.
  1. Evaluate Fit & Scope: Assess whether the issue is relevant for Fabric. Ensure it aligns with Fabric's core philosophy (modules should be lean, composable, and represent a single resource type context). Confirm the change has a sufficiently large scope and represents a generic, valuable addition to the module or FAST stage rather than a highly specific, one-off customization.
  1. Read Provider Documentation: If the issue involves Google Cloud resources, retrieve and read the documentation for the involved GCP resources or Terraform provider resource/datasource to ensure accurate implementation of its attributes, behaviors, and constraints.
  • Start from the provider registry, e.g. <https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_address>.
  • Check the pinned provider range: the repo pins the google provider in default-versions.tf. If the feature you are implementing requires provider functionality released after the pinned minimum version, that is a good reason to bump the pin — do it across the board with uv run tools/versions.py --provider-min-version <x.y.z> --write-defaults, which rewrites default-versions.tf and propagates it to every module and stage versions.tf (linting enforces they stay in sync). Never edit version pins in individual modules only.
  • Only rely on documentation for functionality available in a released provider version: docs from the provider's main branch may describe unreleased attributes that no released provider accepts at plan time.

> [!WARNING] > Do NOT rely solely on the proposed solution, examples, or partial specifications provided in the issue description. Always retrieve and review the complete documentation schema from the official provider registry. > > Workaround for Registry Page JS/Redirection Errors: > If the registry page fails to load properly with your URL-fetching tool (e.g. returns "Please enable Javascript" or truncates due to HTML formatting issues), find the source markdown file on GitHub and fetch its raw content using curl to a scratch file (the scratch/ directory is gitignored), using the tag of the provider release whose docs you need (e.g. v7.40.0): > ``bash > curl -s https://raw.githubusercontent.com/hashicorp/terraform-provider-google/v7.40.0/website/docs/r/workstations_workstation_config.html.markdown -o scratch/workstation_config_doc.md > `` > You can then search and view it locally to identify all supported arguments and blocks. > Use this information to make an informed decision on which arguments to support. While 100% coverage is not always necessary or desirable, make a deliberate choice to include all arguments that are useful and align with Fabric's composability and simplicity goals, rather than missing them by omission.

  1. Gate — Triage Disposition: Present your assessment (target module/stage, fit with Fabric's philosophy, scope evaluation) and let the human decide whether to proceed. If the issue fails the fit test, report your reasoning and stop — do NOT comment on, label, or close the issue yourself; disposition of the issue is a maintainer decision.
Gate: Design Sign-off (Modes A & B)

Before writing code, present the proposed design for approval:

  • The target module(s)/stage(s) and the shape of the variable interface (new/changed variables, whether context support is added).
  • For provider-surface changes: the explicit list of provider arguments you intend to include and exclude, with reasoning.
  • Whether the change requires bumping the pinned provider version (a repo-wide change — see Step 1.4).

This gate is mandatory for new features and interface changes. For trivial fixes (typos, one-line bugfixes with an obvious solution) where the design is self-evident, state your intent and proceed without blocking.

Step 2: Develop the Fix or Feature (Modes A & B)
  1. Align with Fabric Zen: Ensure the design focuses on composition, encapsulates logical entities (like IAM and log sinks directly inside modules), adopts common interfaces, and keeps code flat and easy to evolve.

> [!IMPORTANT] > You MUST strictly follow the design principles and coding conventions defined in CONTRIBUTING.md and GEMINI.md when designing variables, modules, and factories.

  1. Set Up the Git Branch:
  • If you are not already on a feature branch, create one named after your username and the feature/fix (e.g., <username>/<feature-name>, such as johndoe/feature-name):

``bash git checkout master && git pull git checkout -b <username>/<feature-name> ``

  • If preparing an existing branch (Mode B), do NOT create a new one; instead make sure it is up to date with master (rebase or merge) before submission.
  • Direct branches require push access to the repo (granted to regular contributors on request). Without it, use the fork-based flow described in CONTRIBUTING.md; the rest of this workflow is identical.
  1. Apply Fabric/FAST Design Conventions:
  • Context Interpolation: If context support is relevant and needed for the module (e.g., to support resolving symbolic references like "$project_ids:myprj"), add a context variable block and implement ctx/ctx_p locals in main.tf. Do not add it blindly if the module does not benefit from symbolic interpolation.
  • Compact Variables: Leverage objects with optional() attributes to keep user interfaces clean. Prefer optional() without an explicit default so the provider applies whatever default value it defines; only set a default when module logic needs a known value.
  • Stable State Keys: Always use maps instead of lists for collection variables to avoid index shifts in Terraform state.
  • Scope Isolation: Use private locals (prefixed with _) for intermediate transformations, reserving module-level locals for values referenced by resources.
  • Locals Separation for Complex Manipulations: When adding complex conditional strings, string interpolations, or transformations to resource attributes, compute the map in locals so the resource block references a clean index like local.my_map[each.key]. This keeps resource blocks legible (<79 chars) and avoids cluttering resource definitions.
  • Validate ENUM Variables: When adding or exposing variables that mirror ENUM values in the underlying Terraform provider, always include a validation block to check for allowed values at plan time. Example from modules/gcs:

``hcl variable "storage_class" { description = "Bucket storage class." type = string default = "STANDARD" validation { condition = contains(["STANDARD", "MULTI_REGIONAL", "REGIONAL", "NEARLINE", "COLDLINE", "ARCHIVE"], var.storage_class) error_message = "Storage class must be one of STANDARD, MULTI_REGIONAL, REGIONAL, NEARLINE, COLDLINE, ARCHIVE." } } ``

  1. Reference Implementations & Knowledge Sources:
  • compute-vm: Ideal reference for compact variable design, optional objects with defaults, and map variables.
  • project: Best reference for logical entity encapsulation (IAM, log sinks, Shared VPC configurations), complex locals transformation, and context-based interpolation.
  • adrs/: Architectural Decision Records documenting the rationale behind key design patterns (e.g. the IAM ADR explains the full iam* interface). Before designing, build an index of all ADRs with their title and status:

``bash find adrs -name '*.md' ! -name 'README.md' | sort | while read -r f; do st=$(awk '/^## Status/ {getline; while ($0 == "") getline; print; exit}' "$f") printf '%s | %s | %s\n' "$f" "$(head -1 "$f" | sed 's/^# //')" "$st" done ` Read in full any ADR whose title relates to the area you are changing. Weigh them by status: ignore Rejected ones, treat Draft/Proposed` as directional rather than settled, and remember that even implemented ADRs can lag behind the code — on conflict, the current code and golden-path modules are the source of truth.

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewNot runA model review is scheduled for the next rescan.

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
2,082
Repository forks
1,255
7-day trend score
38

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/googlecloudplatform/cloud-foundation-fabric/contributing/badge)](https://verified-skill.com/skills/googlecloudplatform/cloud-foundation-fabric/contributing)

Something wrong with this skill or its page? Tell us.