agentleFS
jpantsjohajpantsjoha/googlecloud-plugin/.claude/CLAUDE.md

googlecloud-plugin

CLAUDE.md4 starsChanged 4 months agoMITView on GitHub

This file advises AI agents working ON the plugin (building, researching, validating skills). It is committed, and public — write it for contributors, not as a scratchpad. For local notes you don't want published, use .claude/local-CLAUDE.md, which is gitignored. You are building a public plugin that installs a complete GCP team for other developers. Every file you commit must be production quality — real developers will use this. Never commit _plugin/ content. Draft in _plugin/staging/, promote to skills/ only after…

The file

Show its rules and text

We split this CLAUDE.md into the rules it gives an agent

13 rules. About 0 are common, 6 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every file you commit must be production quality — real developers will use this.

    line 10
  2. Very specific:

    Never commit _plugin/ content.

    line 19
  3. Very specific:

    All work on feature branches: feat/phase-N-description

    line 23
  4. Distinctive:

    Commit after each phase with a clear message

    line 25
  5. Distinctive:

    Before any skill merges to main:

    line 29
  6. Very specific:

    Never reintroduce a top-level triggers, version or required_scopes field — that is the exact regression make validate exists to catch.

    line 52
  7. Very specific:

    Run make spec && make validate after any SKILL.md or manifest edit.

    line 56
  8. Distinctive:

    No credential values in any file — location only

    line 60
  9. Distinctive:

    No public Cloud Storage buckets without explicit design intent

    line 62
  10. Distinctive:

    Every billable action gets a cost warning comment before the command

    line 63
  11. Very specific:

    Run make crawl to refresh research/raw/ and research/SOURCES.md.

    line 68
  12. Very specific:

    Run make check to detect URL drift.

    line 69
  13. Very specific:

    Update research/coverage-matrix.md whenever a skill status changes: missing → researched → drafted → normalized → validated

    line 80

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

GoogleCloud Plugin — Construction Guide

This file advises AI agents working ON the plugin (building, researching, validating skills). It is committed, and public — write it for contributors, not as a scratchpad. For local notes you don't want published, use .claude/local-CLAUDE.md, which is gitignored.

Your Role

You are building a public plugin that installs a complete GCP team for other developers. Every file you commit must be production quality — real developers will use this.

The Split

LocationPurposeCommitted?
googlecloud-plugin/Public release — curated, validatedYes (main is protected)
_plugin/Working area — planning, research drafts, auditsNo (gitignored)

Never commit _plugin/ content. Draft in _plugin/staging/, promote to skills/ only after make gate passes.

Branch Strategy

  • All work on feature branches: feat/phase-N-description
  • Main is branch-protected — PRs required
  • Commit after each phase with a clear message

Gate System (Sequential — Enforce This)

Before any skill merges to main:

  1. make gate passes (validate + lint + test)
  2. PR reviewed (devex-charter pr-reviewer or adversarial-gate for high-stakes changes)
  3. Coverage matrix updated in research/coverage-matrix.md

Skill Contract

Frontmatter follows the Agent Skills specification. The field set is closed — adding a top-level key outside {name, description, license, compatibility, allowed-tools, metadata} makes the skill non-conformant, and a conformant client MUST skip it. Everything specific to this plugin is namespaced under metadata as string values:

  • name — matches directory name exactly
  • description — what it does AND when to use it, max 1024 chars, ending with Use when the user mentions: …. This is the only thing a conformant client routes on. Where two skills overlap, name the other and draw the line.
  • metadata["googlecloud-plugin/version"]
  • metadata["googlecloud-plugin/triggers"] — comma-joined, non-empty
  • metadata["googlecloud-plugin/required-scopes"] — comma-joined, "" if none
  • metadata["googlecloud-plugin/mcp-servers"] — comma-joined, omit if none
  • persona skills add persona, tier, gate under the same namespace

Never reintroduce a top-level triggers, version or required_scopes field — that is the exact regression make validate exists to catch. See ADR-007.

Run make spec && make validate after any SKILL.md or manifest edit.

Safety Rules (Non-Negotiable)

  • No credential values in any file — location only
  • No --allow-unauthenticated Cloud Run without gcp-security sign-off in HLD
  • No public Cloud Storage buckets without explicit design intent
  • Every billable action gets a cost warning comment before the command
  • IAM: never grant roles/owner or roles/editor in skill examples

Research Pipeline

Run make crawl to refresh research/raw/ and research/SOURCES.md. Run make check to detect URL drift. Research output lives in _plugin/research/ (gitignored) before being promoted to research/raw/.

Architecture Docs

  • HLD for every feature touching ≥2 components → architecture/HLD/
  • LLD where HLD reveals complexity → architecture/LLD/
  • ADRs for significant decisions → architecture/decisions/ADR-NNN-title.md

Coverage Matrix

Update research/coverage-matrix.md whenever a skill status changes: missing → researched → drafted → normalized → validated

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.