ecosystem-standardizer

name	ecosystem-standardizer
skill_type	workflow
description	Unified ecosystem standardization workflow for the agent-packages repository. Audits all projects for structural drift, generates missing standardized files, migrates environment variables, extracts MCP subdirectories, and creates standard test suites. Produces a comprehensive drift report with per-project scorecards. Use when onboarding a new agent, auditing ecosystem compliance, running "standardize the ecosystem", "check for drift", "onboard new agent", or "ecosystem audit".
domain	development-workflows
tags	["standardization","drift","audit","ecosystem","onboarding","dev-workflows"]
requires	["repository-manager-mcp"]
metadata	{"version":"1.2.1","author":"Genius"}

ecosystem-standardizer Workflow

Autonomous workflow for auditing and enforcing structural standards across all agent-packages projects. Detects drift from the ecosystem conventions, generates missing files, and produces a graded compliance report.

Trigger Phrases

• "standardize the ecosystem"
• "check for drift" / "drift analysis"
• "onboard new agent"
• "ecosystem audit"
• "check ecosystem compliance"
• "run ecosystem standardizer"

---

Ecosystem Standard Manifest

Every agent-package project MUST have the following files. The drift audit checks for the presence and correctness of each one.

Root Files (14 mandatory)

File	Purpose	Generated By
README.md	Project overview, quick start, tool tables	Manual
CHANGELOG.md	Keep a Changelog format	generate_changelog
AGENTS.md	AI coding agent context	agents-md-generator
pyproject.toml	Package metadata, deps, tools	Scaffold
requirements.txt	Pinned deps for Docker	uv pip compile
.pre-commit-config.yaml	Pre-commit hooks	Scaffold
.bumpversion.cfg	Version bump config	Scaffold
.gitignore	Git ignores	Scaffold
.gitattributes	Git attributes	Scaffold
.dockerignore	Docker build ignores	Scaffold
.env	Environment variable template	Scaffold

Documentation (3 mandatory)

File	Purpose
docs/index.md	Navigation hub linking all docs
docs/overview.md	Full technical overview with concepts
docs/concepts.md	CONCEPT ID registry with unique prefix

Deprecated (must NOT exist)

File	Why
docs/legacy_readme.md	Content migrated to README.md/overview.md

Docker (2 mandatory)

File	Purpose
docker/Dockerfile	Production image
docker/mcp.compose.yml	MCP server compose config

Source Structure (5 mandatory files + 1 mandatory subdir)

File/Dir	Purpose
{pkg}/__init__.py	Package init with version
{pkg}/__main__.py	CLI entrypoint
{pkg}/agent_server.py	A2A agent server
{pkg}/mcp_server.py	MCP server entrypoint
{pkg}/auth.py	Authentication setup (if project has API)
{pkg}/mcp/	REQUIRED subdirectory with register_*_tools modules
{pkg}/api/	Required IF project has api_client.py or API integration

Tests (4 mandatory standard files)

File	Purpose
tests/conftest.py	Shared fixtures
tests/test_concept_parity.py	CONCEPT ID doc↔code validation
tests/test_init_dynamics.py	Package import + version tests
tests/test_startup.py	Basic smoke test

Environment Variable Standard

All auth.py files must use these patterns:

Pattern	Standard	NOT
Service URL	{SERVICE}_URL	_BASE_URL, _INSTANCE
API Token	{SERVICE}_TOKEN	_API_KEY, _ACCESS_TOKEN
TLS Verify	{SERVICE}_SSL_VERIFY	_VERIFY, _AGENT_VERIFY
Username	{SERVICE}_USERNAME	—
Password	{SERVICE}_PASSWORD	—

Exception: First-party env vars are preserved (e.g., GITHUB_TOKEN, LANGFUSE_PUBLIC_KEY).

CONCEPT ID Standard

• Every project has a unique prefix (no collisions across ecosystem)
• docs/concepts.md references CONCEPT:ECO-4.0 as the bridge to agent-utilities
• Tool descriptions in mcp_server.py annotate their CONCEPT ID

---

Workflow Steps

Step 0: user-interaction

Ask the user what mode to run in:

• audit — Scan all projects and produce a drift report (read-only, no changes)
• fix — Scan, then auto-fix all detected drift (creates missing files, migrates env vars)
• onboard — Run full standardization for a specific new project
• report-only — Just print the current compliance scores

Also ask:

• Target scope: all projects, or a specific comma-separated list?
• Should we also run workspace-validator-workflow after fixes? Expected: mode, scope, run_validator

Step 1: audit-ecosystem

Run the comprehensive drift audit script against all (or targeted) projects:

python scripts/audit_ecosystem.py \
    --agents-dir /home/apps/workspace/agent-packages/agents \
    --output /home/apps/workspace/reports/ecosystem-drift-report.md

This produces a full drift report with:

• Per-project compliance scorecard (0–100)
• Per-category breakdown (root files, docs, docker, source, tests, env vars, concepts)
• Specific missing/non-standard items per project
• Ecosystem-wide summary statistics
• CONCEPT ID collision detection Expected: drift_report_path

Step 2: review-report

Present the drift report to the user. If mode is audit or report-only, stop here. Show:

• Overall ecosystem compliance score
• Projects with the lowest scores
• Most common drift categories Expected: user_approval_to_fix

Step 3: generate-concepts

Run the concept ID generator for any projects missing docs/concepts.md:

python scripts/generate_concepts.py

This creates docs/concepts.md with unique CONCEPT prefixes, cross-references to agent-utilities via CONCEPT:ECO-4.0, and tool domain mappings. Expected: concepts_created_count Depends On: Step 2

Step 4: migrate-env-vars

Run the environment variable standardization migration:

python scripts/migrate_env_vars.py

Applies backward-compatible fallbacks in auth.py files. New standard name checked first, old name as fallback. Expected: migrations_applied_count Depends On: Step 2

Step 5: create-mcp-subdirs

Run the MCP subdirectory extraction for any projects still using monolithic mcp_server.py:

python scripts/create_mcp_subdirs.py

AST-parses mcp_server.py, extracts each register_*_tools function into mcp/mcp_{domain}.py, and creates mcp/__init__.py with re-exports. Expected: mcp_dirs_created_count Depends On: Step 2

Step 6: generate-standard-tests

Run the standard test file generator:

python scripts/generate_standard_tests.py

Creates test_concept_parity.py, test_init_dynamics.py, test_startup.py, and conftest.py for any project missing them. Expected: test_files_created_count Depends On: Step 2

Step 7: generate-changelogs

Run changelog generation for any projects missing CHANGELOG.md:

python scripts/generate_changelogs.py

Creates CHANGELOG.md in Keep a Changelog format, populated from git log. Expected: changelogs_created_count Depends On: Step 2

Step 8: cleanup-deprecated

Remove any deprecated files that should no longer exist:

python scripts/cleanup_deprecated.py

Removes docs/legacy_readme.md and any other deprecated artifacts. Expected: files_removed_count Depends On: Step 2

Step 9: re-audit

Run the drift audit again to verify all fixes were applied:

python scripts/audit_ecosystem.py \
    --agents-dir /home/apps/workspace/agent-packages/agents \
    --output /home/apps/workspace/reports/ecosystem-drift-report-post-fix.md

Compare pre-fix and post-fix scores. Present delta to user. Expected: post_fix_compliance_score Depends On: Step 3, Step 4, Step 5, Step 6, Step 7, Step 8

Step 10: workspace-validation (optional)

If user requested it in Step 0, run workspace-validator-workflow workflow to validate all projects pass linting, tests, and pre-commit:

Use the rm_projects MCP tool with action="validate" and type="all". Expected: validation_results Depends On: Step 9

---

Scripts

Script	Purpose
scripts/audit_ecosystem.py	Comprehensive drift audit with compliance scoring
scripts/generate_concepts.py	Create docs/concepts.md for all projects
scripts/migrate_env_vars.py	Standardize env var names in auth.py
scripts/create_mcp_subdirs.py	Extract register_*_tools into mcp/ subpackages
scripts/generate_standard_tests.py	Create standard test suite files
scripts/generate_changelogs.py	Create missing CHANGELOG.md from git history
scripts/cleanup_deprecated.py	Remove deprecated files (legacy_readme.md, etc.)

---

Compliance Scoring

Each project is scored 0–100 across 7 categories:

Category	Weight	What's Checked
Root Files	15%	README, CHANGELOG, AGENTS.md, pyproject.toml, .pre-commit, .bumpversion, .gitignore, .gitattributes, .dockerignore, .env
Documentation	15%	docs/index.md, docs/overview.md, docs/concepts.md, NO legacy_readme.md
Docker	10%	docker/Dockerfile, docker/mcp.compose.yml
Source Structure	20%	init.py, main.py, agent_server.py, mcp_server.py, auth.py, mcp/ subdir, api/ subdir (if applicable)
Tests	15%	conftest.py, test_concept_parity.py, test_init_dynamics.py, test_startup.py
Env Vars	15%	Standard naming (_URL, _TOKEN, _SSL_VERIFY), no duplicates, no deprecated patterns
Concepts	10%	Unique prefix, docs/concepts.md exists, ECO-4.0 bridge reference, no collisions

Grading

Grade	Score	Meaning
🟢 A	90–100	Fully compliant
🟡 B	75–89	Minor drift
🟠 C	60–74	Notable drift
🔴 D	0–59	Critical drift

Execution

Run this workflow as a dependency-ordered DAG. Steps with no unmet depends_on run in parallel; dependents run after their prerequisites complete.

• Run first (in parallel): Step 0 — user-interaction; Step 1 — audit-ecosystem; Step 2 — review-report; Step 3 — generate-concepts; Step 4 — migrate-env-vars; Step 5 — create-mcp-subdirs; Step 6 — generate-standard-tests; Step 7 — generate-changelogs; Step 8 — cleanup-deprecated; Step 9 — re-audit; Step 10 — workspace-validation (optional)

Execution: If graph-os is reachable, offload the whole DAG via graph_orchestrate action=execute_workflow (or the kg-delegate skill) for true parallel/swarm execution. Otherwise execute the steps natively in dependency order: run steps with no unmet depends_on in parallel, then their dependents.