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)

Documentation (3 mandatory)

Deprecated (must NOT exist)

Docker (2 mandatory)

Source Structure (5 mandatory files + 1 mandatory subdir)

Tests (4 mandatory standard files)

Environment Variable Standard

All auth.py files must use these patterns:

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 ${AGENT_UTILITIES_WORKSPACE_ROOT}/agent-packages/agents \
    --output ${AGENT_UTILITIES_WORKSPACE_ROOT}/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 ${AGENT_UTILITIES_WORKSPACE_ROOT}/agent-packages/agents \
    --output ${AGENT_UTILITIES_WORKSPACE_ROOT}/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

Compliance Scoring

Each project is scored 0–100 across 7 categories:

Grading

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.