Federation support and contribution workflow improvements

[r2dedios]

Summary

This PR adds federation support for external agentic packs and improves the contribution workflow for skill authors.

What's new for reviewers

• External packs can now be referenced in our catalog without copying code — federation model
• Contributors get a guided import mode in /agentic-contribution-skill for pre-existing skills
• CI automatically validates federated packs when PRs are labeled federation
• CONTRIBUTING.md goes from 446 lines to 81 — the skill handles the complexity
• Pre-commit hooks now catch Tier 1 spec violations before push

Files at a glance

Area	Files	What changed
Federation	scripts/validate_federation.py, scripts/fetch_federated_skills.py, .github/workflows/federation-validation.yml, .github/ISSUE_TEMPLATE/federation-request.yml, docs/FEDERATION_REVIEW_GUIDE.md, .claude/skills/federation-review/SKILL.md	New validation pipeline, CI workflow, issue template, review guide, and Claude Code skill
Marketplace	marketplace/rh-agentic-collection.yml, scripts/pack_registry.py, scripts/generate_pack_data.py	federated_modules schema, registry loader, docs site generation for federated packs
Docs site	docs/app.js, docs/styles.css	Federated badge (blue) on pack cards
Contributing	.claude/skills/agentic-contribution-skill/SKILL.md, docs/examples.md, CONTRIBUTING.md	Import mode (analyze, adapt, validate), simplified contributor guide
PR/CI	.github/pull_request_template.md, .pre-commit-config.yaml, .github/gemini-review-prompt.md	All 8 packs listed, contribution method checkbox, Tier 1 pre-commit hook, pack-persona review rule
Repo docs	CLAUDE.md, README.md, Makefile	Contribution paths section, federation links, validate-federated target

Federation

• Issue template for federation requests (new + update) with pre-submission checklist
• Review guide (docs/FEDERATION_REVIEW_GUIDE.md) — 8-step evaluation process for maintainers
• Validation script (scripts/validate_federation.py) — automates clone, Lola structure, Tier 1, Tier 2, MCP pinning, and gitleaks checks
• CI workflow triggered by federation label on PRs — runs validation and posts per-module results as PR comment with pass/fail status per check
• /federation-review skill for interactive review from Claude Code with HITL at decision points
• Federated badge on docs site for external packs (CSS + JS)
• Marketplace YAML updated with federated_modules schema and documented example
• CLAUDE.md updated to distinguish federation vs direct contribution paths

Contributing

• Import mode for /agentic-contribution-skill — color inference, MCP tool verification, pack keyword matching
• PR template with all 8 packs, contribution method checkbox, pack-persona alignment, and federation change type
• Pre-commit hook for Tier 1 skill spec linter
• CONTRIBUTING.md simplified (446 → 81 lines)

Pack(s) affected

• Other / repo-wide

Change type

• New skill
• Docs / README
• CI / tooling
• Federation (external pack)

Contribution method

• Manual contribution (validated with make validate + make validate-skill-design-changed)

Pack-persona alignment (new skills only)

N/A — repo-wide infrastructure changes, no pack-specific skills added.

CLAUDE.md compliance

• Agents orchestrate skills; no direct MCP/tool calls in agents
• Skills are single-purpose task executors
• Skills encapsulate all tool access (MCP tools invoked only inside skills)
• Document consultation: file is read with the Read tool, then declared to the user
• No credentials hardcoded; env vars used via ${VAR} references
• Human-in-the-loop confirmation added for any destructive or critical operations

Validation

• make validate passes locally
• New/changed skills have valid YAML frontmatter (name, description)
• New/changed agents have valid YAML frontmatter (name, description)

Test plan

• Federation validation workflow tested on fork (PR Test federation validation workflow r2dedios/agentic-plugins#7)
• Per-module tables, gitleaks install, commit signature verified in CI
• Import mode tested end-to-end with /agentic-contribution-skill
• Pre-commit hook validated with uv run pre-commit run skill-spec-linter --all-files

[ikrispin]

lgtm

[dmartinol]

Please apply the following changes in the next PR:

• Define a Federation Process document and integrate it in the README
  • Include a simple diagram with roles (contributor, maintainer, ...) and steps
• Add a /federation-request skill to create a new federation request PR
  • Includes the generation of catalog files in a local folder (e.g. /.catalog/...)
  • TODO Check with Lola team how to define a commit SHA in the repository URL
• Ask PR# in /federation-review skill
  • Include /collection-compliance check in the skill
  • Avoid using the 'Ref` field in the marketplace file
• In case, remove mentions to ChatGPT

[r2dedios]

• New /federation-request skill — step-by-step interactive guide for users to create federation PRs (gathers module data, creates marketplace entry, generates collection files via /create-collection, opens PR with federation label)

• Federation collection files support — new federation/modules/<name>/.catalog/ structure for storing collection.yaml/collection.json of federated modules (skills live in external repo)

• Tooling adapted for federation modules — pack_registry.py discovers modules under federation/modules/, collection_validate_lib.py skips roster checks for federated modules (no skills/ on disk),
  catalog_yaml_to_json.py --all includes them

• @ref embedded in repository URL — marketplace format uses repository: "url@ref" instead of a separate ref field; added parse_repo_url() helper used by validate_federation.py and pack_registry.py

• Tier 2 is warning-only in federation CI — design principles failures no longer block merge; only Tier 1, MCP pinning, gitleaks, and clone remain blocking

• CI workflow uses pull_request_target — enables posting validation result comments on PRs from forks

• docs/federation_guide.md — contributor-facing guide explaining how to federate an external pack (single path: /federation-request skill)

• README updated — added references to the federation guide in Contributing and Additional Resources sections

[dmartinol]

/lgtm, thank you!