vanguard-frontier-agentic
CLAUDE.md23 starsChanged 4 months agoApache-2.0View on GitHub
This repository is a curated marketplace for cloud, zero-trust, and compliance-aware AI workflows. Two things live here: the catalog itself (agents, skills, rules, MCP references, machine-readable indexes) and the tooling that keeps it honest (validation gates, generators, and the vfa-tui Rust terminal UI). Almost every mistake in this repo is caught by a gate — so the working loop is: make the change, run the gates, fix what they say, and never bypass one. If you touched tools/vfa-tui, also run…
- Installs packages
In this repository15 other files it gives its agents.
- agents/AGENTS.mdAGENTS.md
- AGENTS.mdAGENTS.md
- catalog/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- mcp/AGENTS.mdAGENTS.md
- rules/AGENTS.mdAGENTS.md
- schemas/AGENTS.mdAGENTS.md
- skills/AGENTS.mdAGENTS.md
- templates/AGENTS.mdAGENTS.md
- tests/AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- agentic-delegationSkill
- definition-of-doneSkill
- model-registry-refreshSkill
- pr-babysitSkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
22 rules. About 0 are common, 13 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈13
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 16
If you touched tools/vfa-tui, also run its gates (CI's Gate job runs all three and fails the PR independently):
- Very specific: line 23
If you touched the catalog (agents/skills/roles/providers), run npm run manifest:write:all then npm run asset-integrity:write last, on its …
- Distinctive: line 41
Prefer official docs and live evidence over memory.
- Distinctive: line 42
Default to least privilege, zero trust, and safe rollback paths.
- Distinctive: line 44
Treat broad permissions, destructive automation, and MCP mutation paths as high risk.
- Distinctive: line 45
Do not add secrets, credentials, tokens, tenant IDs, or customer data.
- Distinctive: line 53
Verify external claims against primary sources: before encoding them (model names, retirement dates, API capabilities).
- Distinctive: line 61
Probes over trust: After any generated or delegated change, run one decisive positive probe (the thing now works) AND one negative probe …
- Distinctive: line 63
Correct the record: When new evidence contradicts something you previously reported, say so explicitly and prominently — never let a …
- Distinctive: line 66
Finish means pushed: Follow the Definition of done below, in order, every time.
- Distinctive: line 70
Keep changes scoped and traceable to the task.
- Distinctive: line 71
Update catalog metadata when adding, moving, or removing cataloged assets.
- Very specific: line 72
Run npm run validate before finishing.
- Very specific: line 73
If skills/ changed intentionally, also refresh catalog/skill-manifest.json with npm run manifest:write.
- Very specific: line 74
Every SKILL.md must declare an allowed-tools field (least-privilege baseline) and conform to schemas/skill.frontmatter.schema.json.
- Distinctive: line 94
After any catalog change (agents, skills, roles, providers):
- Very specific: line 109
Jekyll docs: All pages in docs/ use {{ site.data.catalog.X }} Liquid variables sourced from docs/_data/catalog.yml.
- Very specific: line 147
After a non-dry-run apply, run npm run asset-integrity:write (the vfa-tui Model Policy Builder chains this automatically).
- Very specific: line 148
Never hand-edit model / model_reasoning_effort / model_provider / effort lines in harness files directly — edit catalog/model-policy.json …
- Distinctive: line 178
Keep portable logic in canonical specs and shared docs.
- Distinctive: line 179
Keep harness-specific behavior in the right adapter format.
- Very specific: line 180
Do not invent unsupported metadata fields in executable agent files.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 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.
Files
Vanguard Frontier Agentic
This repository is a curated marketplace for cloud, zero-trust, and compliance-aware AI workflows. Two things live here: the catalog itself (agents, skills, rules, MCP references, machine-readable indexes) and the tooling that keeps it honest (validation gates, generators, and the vfa-tui Rust terminal UI). Almost every mistake in this repo is caught by a gate — so the working loop is: make the change, run the gates, fix what they say, and never bypass one.
Quick start
npm install # one-time install
pip install jsonschema # one-time; validate:promotion-gatekeeper imports it and fails without it
# ...make catalog/doc changes...
npm run validate # 20+ gates (every validate:* script in package.json — catalog, schema, asset integrity, model policy, routing, marketplace)
npm run lint:spell # codespell — separate CI gate, NOT part of validate
npx --yes markdownlint-cli2 "**/*.md" "#node_modules" # markdown lint — separate CI gateIf you touched tools/vfa-tui, also run its gates (CI's Gate job runs all three and fails the PR independently):
cd tools/vfa-tui
cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo testIf you touched the catalog (agents/skills/roles/providers), run npm run manifest:write:all then npm run asset-integrity:write last, on its own (see the ordering caveat at the bottom) before npm run validate.
What this repo contains
skills/— reusable workflows for recurring engineering tasksagents/— expert roles with judgment for review, architecture, and operations (each with per-harness variant files underharnesses/)rules/— harness-specific operating guidancemcp/— MCP references and trust-boundary notescatalog/— machine-readable indexes (agents, skills, model policy/registry/assignments, asset-integrity manifest)schemas/— metadata contractsdocs/— governance, taxonomy, compatibility, and quality guidance (Jekyll site)scripts/— generators and the model-policy engine;tests/— the validation gates behindnpm run validatetools/vfa-tui/— Rust terminal UI over the catalog (see its section below)plugins/,powers/,templates/— harness plugin bundles, Kiro Powers, and contribution templates (generated or scaffolding; regenerate, don't hand-edit generated output).claude/skills/— project skills that codify how to work here (agentic-delegation,model-registry-refresh)
Operating stance
- Prefer official docs and live evidence over memory.
- Default to least privilege, zero trust, and safe rollback paths.
- Separate verified facts, judgment, assumptions, and unknowns.
- Treat broad permissions, destructive automation, and MCP mutation paths as high risk.
- Do not add secrets, credentials, tokens, tenant IDs, or customer data.
How to work here
- Delegate by default. Follow
.claude/skills/agentic-delegation/SKILL.md: Haiku subagents for read-only exploration/research (require file:line or URL citations), Sonnet subagents for bulk writing against an exact file-scoped spec, and the orchestrator keeps architecture decisions, security-sensitive edits, verification, and the commit. A delegate's self-report is not verification — read the diff and run the gates yourself. - Run it as a pipeline when the work is big.
.claude/workflows/agentic-delegation.jsis that skill as an executableWorkflow— Haiku recon, a Context7 verification phase, Sonnet writers against file-scoped specs, an independent refuter per change, then the gate suite. Invoke asWorkflow({name: "agentic-delegation", args: {task, questions, libraries, specs}}); see.claude/workflows/README.md. It never commits — the orchestrator still reads the diff and commits. - Ground version-sensitive API claims in Context7, not in service docs. Provider documentation describes features; library documentation pins call signatures. Two wrong MLflow API claims reached this repo from correct-looking Databricks doc pages and were caught only by Context7. Treat absence from a Context7 result as uncorroborated, never as disproven — it serves retrieved snippets, not a complete API inventory, and "correcting" documented content on absence alone introduces the bug it was meant to prevent.
- Orchestrator requirements. Haiku must never be the orchestrator. When Sonnet orchestrates, run it at high reasoning effort at minimum (use the harness's maximum-thinking mode if available) — planning and delegation quality degrade below that, and a weak plan wastes every delegate downstream.
- Verify external claims against primary sources before encoding them (model names, retirement dates, API capabilities). Press coverage and launch blogs get details wrong; official docs pages are the bar. Anything unverifiable stays out — fail closed.
- Commit and push as you go. Sessions are ephemeral; work that isn't pushed to the branch does not exist. Commit messages are conventional commits with a scope (
feat(model-policy): …,fix(exporter): …,chore(codespell): …) because semantic-release derives versions from them. - Never bypass a gate to go green. Fix the cause, or extend the gate's config deliberately with a comment explaining why (e.g. a real API name added to
.codespellrcignore-words-list).
Quality bar (any orchestrator model)
These are the behaviors that make the difference between passable and trustworthy work here. They are not optional at any model tier:
- Probes over trust. After any generated or delegated change, run one decisive positive probe (the thing now works) AND one negative probe (the invalid input now fails with the right message) — green gates alone don't prove semantics. Dry-run first on every mutating script.
- Primary source or it doesn't exist. Before encoding any external fact (model names, retirement dates, API capabilities), fetch the provider's official page yourself. Press, launch blogs, and even a delegate's "verified" label are leads, not evidence. If you can't verify it, leave it out and say so.
- Correct the record. When new evidence contradicts something you previously reported, say so explicitly and prominently — never let a superseded claim stand quietly.
- Lead with the outcome. First sentence of any report: what happened / what you found. Detail after. If tests fail, say so with the output; if a step was skipped, say that.
- Deterministic over clever. Generators and gates must never consult the wall clock or any other ambient state — behavior changes only on committed data, so builds are reproducible and CI can't change color without a commit.
- Finish means pushed. Follow the Definition of done below, in order, every time. A dirty tree or an unpushed branch is unfinished work, not a detail.
When working in this repo
- Keep changes scoped and traceable to the task.
- Update catalog metadata when adding, moving, or removing cataloged assets.
- Run
npm run validatebefore finishing. It runs 20+ gates (everyvalidate:*script inpackage.json) — catalog integrity, schema compliance, asset integrity, model policy, maestro routing, and multi-harness marketplace consistency. Keep the count approximate (10+/20+), never exact — exact counts drift. - If
skills/**changed intentionally, also refreshcatalog/skill-manifest.jsonwithnpm run manifest:write. - Every
SKILL.mdmust declare anallowed-toolsfield (least-privilege baseline) and conform toschemas/skill.frontmatter.schema.json. - For agents that have a 1:1 companion skill, declare it explicitly via
companion_skills: [<skill-id>]in the agent'smetadata.json.
Definition of done
Work is finished only when ALL of these hold — in this order, since the integrity manifest must hash the settled tree:
- Generated files regenerated (
manifest:write:all/docs-data:write/model-policy:applyas applicable to what you touched). npm run asset-integrity:writerun last, on its own if anything it hashes changed (agents/, plugins/, root files, package.json — see the canonical section below).npm run validate— zero failures.npm run lint:spellandnpx --yes markdownlint-cli2 "**/*.md" "#node_modules"— zero failures.cargo fmt --check,cargo clippy --all-targets -- -D warnings,cargo testintools/vfa-tui— required whenevertools/vfa-tui/**changed.git statusclean; changes committed with a conventional-commit message and pushed to the working branch.
A change that passes locally but was never pushed, or that leaves the tree dirty, is not done.
Documentation & Version Sync (DRY)
Never hardcode counts, versions, or provider/role lists in documentation.
After any catalog change (agents, skills, roles, providers):
npm run readme-counts:write # Update README inline count markers
npm run board-counts:write # Update generated count markers in docs/ + index.md + tests/fixtures/README.md
npm run docs-data:write # Update Jekyll docs/_data/catalog.yml
npm run plugin-manifest:write # Sync .claude-plugin version + agents
npm run cursor-plugin:write # Sync .cursor-plugin version + agents
npm run kiro-powers:write # Regenerate Kiro Powers for all providers
python3 tests/validate-asset-integrity.py --write # Refresh SHA256 hashesOr all-in-one: npm run manifest:write:all
Version parity: package.json, .claude-plugin/plugin.json, .cursor-plugin/plugin.json must always show the same version. The generators read from package.json automatically.
Jekyll docs: All pages in docs/ use {{ site.data.catalog.X }} Liquid variables sourced from docs/_data/catalog.yml. Never hardcode agent/skill/provider counts in markdown.
Hand-written provider lists are NOT auto-generated. A few docs enumerate providers by name in prose/bullets/tables and must be updated by hand when a provider is added or removed: docs/taxonomy.md (provider bullet list), docs/language-stack-boards.md (board enumeration + prose), and the Powers table in docs/integrations/installation-guide.md. Counts are the exception and are never hand-written: catalog numbers in docs/language-stack-boards.md, docs/configuration.md, docs/marketplace-model.md, tests/fixtures/README.md, and root index.md sit in marker spans generated by npm run board-counts:write and enforced by validate:board-counts — <!-- count:board:<provider>:<key> -->N<!-- /count --> for per-board figures (providers joinable with +), <!-- count:global:<key> -->N<!-- /count --> for repo-wide ones (agents, skills, providers, roles, gates, maestros, rules, mcp). Edit the catalog, run the generator — never retype a number. README.md has its own count:<key> namespace owned by readme-counts:write. Changelogs, ADRs, and dated plan/research documents are deliberately excluded: they record what was true when written, so regenerating their numbers would falsify the record. Provider invariant: set(provider bullets in docs/taxonomy.md) == provider_list in docs/_data/catalog.yml == {distinct providers that have at least one agent}. Skill-only providers (no agents) are not "boards" and must not be listed/counted — fix the miscategorization at the source (the skill's provider field) rather than inflating the metric.
Releases: semantic-release owns versioning. feat: → minor, fix: → patch. Never manually edit "version" in package.json.
Adding a new provider
A provider value is hardcoded in several places that are not auto-derived from the catalog. When introducing a new provider (e.g. sap), update ALL of these or validation/CI will fail:
schemas/agent.schema.json— add to theproviderenum.schemas/skill.schema.json— add to theproviderenum.tests/validate-catalog.py— add to theALLOWED_PROVIDERSset (a separate hardcoded list from the schemas — easy to miss; thevalidate:cataloggate fails without it).tools/vfa-tui/src/models/provider.rs— add the variant to the RustProviderenum (kebab-case serde). This is a hard, load-bearing requirement, not cosmetic: the TUI deserializescatalog/agents.json/skills.jsonwith this strict enum, so a missing variant makes the catalog fail to load and breakscargo test(theGatejob). CI'sGateis path-filtered totools/vfa-tui/**, so a catalog-only PR will pass CI while leaving the TUI broken against the new provider — runcargo testintools/vfa-tuiafter adding any provider.scripts/generate-docs-data.mjs— add the provider to the correct category in thetaxonomyarray (drivesprovider_taxonomyincatalog.yml).scripts/generate-kiro-powers.mjs— add aPROVIDERSentry only if the provider should ship a Kiro Power (optional; not every provider has one — e.g. netsuite/finance do not).docs/taxonomy.mdanddocs/language-stack-boards.md— add the provider to the hand-written lists (see the provider invariant above). If the new provider gets its own board section, write its counts ascount:board:<provider>:<key>marker spans rather than literals;validate:board-countsfails closed on an unknown provider or key, so a typo is caught rather than silently frozen.- Regenerate derived files:
npm run manifest:write:allthennpm run docs-data:write, then asset-integrity last (see the ordering caveat below).
Marketplaces & export
This repo ships as an npm package AND as four harness marketplaces; each manifest is generated, validated, and must never be hand-edited:
- Claude Code plugin:
.claude-plugin/plugin.json(npm run plugin-manifest:write; install:/plugin marketplace add VincentChuWaiChow/vanguard-frontier-agentic). - Cursor plugin:
.cursor-plugin/plugin.json(npm run cursor-plugin:write); Copilot CLI marketplace:.github/plugin/marketplace.json(repo root is the plugin root). Both validated together byvalidate:multi-harness-marketplace. - Codex marketplace:
.agents/plugins/marketplace.json— validated byvalidate:codex-marketplace(plugin name = folder name, kebab-case,policy.{installation, authentication}+categoryrequired, version parity with package.json). - Kiro Powers:
powers/vanguard-*(npm run kiro-powers:write). Kiro frontmatter is strictly limited to five fields (name,displayName,description,keywords,author) — any other field failsvalidate:kiro-powers. - Export CLI:
vfa-export-agents --list-rolesto list role IDs;vfa-export-agents --platform claude-code --all --repo <path>installs all agents and auto-bundles companion skills.
Adding a maestro / router agent
A <provider>-maestro-agent requires a routing fixture at tests/fixtures/<provider>-maestro-routing/ containing taxonomy.json + inputs/NN-name.json + expected/NN-name.json. Every agent referenced must exist in catalog/agents.json. Generate the expected/ files from the grader (tests/validate-maestro-routing.py → evaluate(task, taxonomy)) so they stay consistent, and list guarded-mutating-live agents under live_guards so they are never auto-dispatched (they only appear in live-guard-gate mode). The validate:maestro-routing gate enforces all of this.
Model policy
Per-harness model/reasoning-effort assignment is policy-driven, not hand-edited. catalog/model-policy.json (schema: schemas/model-policy.schema.json) is the canonical source; scripts/model-policy.mjs resolves it into catalog/model-assignments.json and projects it into harness files (codex.toml model/model_reasoning_effort/model_provider; claude-code .agent.md model:/effort: frontmatter; cursor .agent.md model:). Rules scope to all | provider:<id> | role:<id> | agent:<id> per harness; precedence is agent > role > provider > all; auto clears the field.
npm run model-policy:report/model-policy:check/model-policy:apply— inspect, validate, and project the policy (checkalso runs insidenpm run validateasvalidate:model-policy, right aftervalidate:agent-schema).- After a non-dry-run apply, run
npm run asset-integrity:write(thevfa-tuiModel Policy Builder chains this automatically). - Never hand-edit
model/model_reasoning_effort/model_provider/effortlines in harness files directly — editcatalog/model-policy.jsonand runmodel-policy:apply. catalog/model-registry.json(schema:schemas/model-registry.schema.json) is the verified per-harness model-name and reasoning-effort matrix;model-policy:checkfails closed on any model or effort value not registered there. Extend it via the.claude/skills/model-registry-refresh/SKILL.mdworkflow — never by guessing model names from memory. Human-readable companion:docs/model-policy-matrix.md.- Codex
model_provideris derived from the model's registry namespace (gpt-*/o-series → default;name:tag→ollama;author/model→openrouter) — it is never set by hand and never a policy field. - Model lifecycle: registry entries may carry
status(available|retiring|retired),retirement_date, andsuccessor.retiringwarns everywhere (CLI, assignments index, TUI) but projects unchanged;retiredprojects the documented successor with a persistent warning until the policy is migrated;retiredwithout a successor is a hard error. Behavior flips only on a committed status change — the engine never consults the wall clock, so builds stay reproducible. Encode lifecycle data only from the provider's official deprecations page, never from press coverage.
tools/vfa-tui (Rust TUI)
- Read-first principle: the TUI never duplicates business logic. It reads generated catalog files for display and shells out to the Node/Python scripts for every mutation (dry-run first, then real run). Rust-side validation is injection-safety only (
security/validate.rs); semantics live in the scripts. If you find yourself re-implementing script logic in Rust, stop. - Toolchain:
Cargo.tomlpinsrust-version = "1.96"— the real dependency floor (libsqlite3-sysusescfg_select). If the build fails on unstable-feature errors, runrustup update stablerather than downgrading dependencies, and bump the pin if a dependency raises the floor again. - Serde contracts are strict: catalog-facing structs use
deny_unknown_fields. Any new key emitted into a generated JSON (e.g.catalog/model-assignments.json) requires the matching struct field (use#[serde(default)]for optional additions) plus updates to every struct-literal in tests/fixtures — the compiler will point at them. - Gates:
cargo fmt --check,cargo clippy --all-targets -- -D warnings,cargo test(unit + integration + property tests). CI'sGatejob runs these; a clippy warning is a failure. - Local artifact note:
tools/vfa-tui/target/is skipped in.codespellrcbecause generated build artifacts trip false positives after a local build; CI checks out fresh and never sees them.
CI gates beyond npm run validate
npm run validate does not run spell-check, markdown lint, or the Rust gates — those are separate CI jobs that fail a PR independently. Before pushing, also run:
npm run lint:spell # codespell. For false positives on real API names/acronyms
# (e.g. afterAll, AGS), add the lowercase term to
# ignore-words-list in .codespellrc — do NOT reword valid code.
npx --yes markdownlint-cli2 "**/*.md" "#node_modules" # CI lints every markdown file…and the cargo gates listed above when tools/vfa-tui/** changed (CI job: Gate).
Cross-platform asset rule
This repo supports multiple harnesses without pretending they are identical.
- Keep portable logic in canonical specs and shared docs.
- Keep harness-specific behavior in the right adapter format.
- Do not invent unsupported metadata fields in executable agent files. Extend
HARNESS_CAPABILITIESinscripts/model-policy.mjsonly with officially documented harness support, verified against current docs (capabilities change — claude-code'seffort:frontmatter field was added upstream after this repo's first policy engine landed).
Important files
README.md— human-facing vision and repository storyROADMAP.md— standing PRD + executable roadmap (the canonical work queue; keep it matching reality)AGENTS.md/GEMINI.md— pure pointers to this file (CLAUDE.md is canonical); they must never carry independent rulesCONTRIBUTING.md— contributor onboarding and submission pathSECURITY.md— vulnerability disclosure policy and SLACODE_OF_CONDUCT.md— community standardsdocs/compatibility.md— harness support contractdocs/normalized-platform-matrix.md— naming and platform normalizationdocs/integrations/skills-cli.md— install-path trust matrixdocs/model-policy.md/docs/model-policy-matrix.md— model policy operator guide and verified capability matrixschemas/skill.frontmatter.schema.json— required SKILL.md frontmatter contractschemas/agent.schema.json— agent metadata contract (includescompanion_skills)
Asset integrity (canonical reference)
catalog/asset-integrity.json holds SHA256 hashes of all tracked assets. If any file in agents/, plugins/, .github/plugin/, package.json, or a root file changes and the manifest is not refreshed, the validate:asset-integrity gate fails and blocks release automation. Regenerate it whenever you add/move/remove agents, plugins, or skills; edit .github/workflows/release.yml; or change any root-level file (README.md, AGENTS.md, CLAUDE.md, package.json, …):
python3 tests/validate-asset-integrity.py --write # or: npm run asset-integrity:write
git add catalog/asset-integrity.jsonOrdering caveat: npm run manifest:write:all runs its generators in parallel (& … wait), so asset-integrity:write can hash the tree before the other generators (README counts, plugin manifests, Kiro powers) finish writing files it covers. After manifest:write:all, always run npm run asset-integrity:write once more on its own, last, so it hashes the settled tree. Always run npm run validate before finishing to catch staleness early.
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
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.

