Ecosystem Standardizer

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: driftreportpath

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: userapprovalto_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: conceptscreatedcount 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: migrationsappliedcount 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: mcpdirscreated_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: testfilescreated_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: changelogscreatedcount 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: filesremovedcount 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: postfixcompliance_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 legacyreadme.md | | Docker | 10% | docker/Dockerfile, docker/mcp.compose.yml | | Source Structure | 20% | _init__.py, __main__.py, agentserver.py, mcpserver.py, auth.py, mcp/ subdir, api/ subdir (if applicable) | | Tests | 15% | conftest.py, testconceptparity.py, testinitdynamics.py, teststartup.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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Knuckles-Team
• Source: Knuckles-Team/universal-skills
• License: MIT

Install and usage instructions live in the source repository linked above.