googlecloudplatform/cloud-foundation-fabric/contributing
Claude Code and agent skill by googlecloudplatform/cloud-foundation-fabric
- community
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/contributingSKILL.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.
| Gate | When | What the human decides | |
|---|---|---|---|
| Triage Disposition | End of Step 1 (Mode A) | Whether the issue is in scope and worth pursuing: proceed, reject, or escalate. | |
| Design Sign-off | Before Step 2 | Approves the proposed design and scope. Mandatory for new features and interface changes; skippable for trivial fixes where the design is self-evident. | |
| E2E Opt-in | Step 5 | Whether to run live cloud verification. Providing a sandbox project ID is the consent to deploy to it. | |
| Behavioral Verification Opt-in | Step 5, after read-back verification | Whether to also verify runtime behavior of the deployed resources, given the described extra time and cost. | |
| PR Approval | Step 6 | Reviews the final sanitized PR body before submission. |
Step-by-Step Workflow
Step 1: Triage the Issue (Mode A Only)
- Retrieve Issue Details: Use the GitHub CLI to view the issue context.
``bash gh issue view <issue-number> ``
- Explore the Codebase: Identify the target module (
modules/<module-name>) or FAST stage (fast/stages/<stage-name>) that requires modification.
- 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.
- 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
googleprovider 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 withuv run tools/versions.py --provider-min-version <x.y.z> --write-defaults, which rewritesdefault-versions.tfand propagates it to every module and stageversions.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
mainbranch 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.
- 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
contextsupport 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)
- 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.
- 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 asjohndoe/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.
- 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 acontextvariable block and implementctx/ctx_plocals inmain.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. Preferoptional()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
localsso the resource block references a clean index likelocal.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
validationblock to check for allowed values at plan time. Example frommodules/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." } } ``
- 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
- SKILL.md in the repositoryCheckingskills/contributing/SKILL.md
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
[](https://verified-skill.com/skills/googlecloudplatform/cloud-foundation-fabric/contributing)