# Ecosystem Standardizer

> 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".

- Skill: `knuckles-team/ecosystem-standardizer` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add knuckles-team/ecosystem-standardizer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/knuckles-team/ecosystem-standardizer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Knuckles-Team (https://skillmd.com/u/knuckles-team)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/knuckles-team/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:

```bash
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`:

```bash
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:

```bash
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`:

```bash
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:

```bash
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`:

```bash
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:

```bash
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:

```bash
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

| 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.