From 6753e8776a72c3771f4fa9a462871d1e0a40a453 Mon Sep 17 00:00:00 2001 From: fOuttaMyPaint <154358121+TMHSDigital@users.noreply.github.com> Date: Sat, 23 May 2026 16:25:54 -0400 Subject: [PATCH 1/2] docs: clarify core vs optional workflows and add MCP-server variations to ci-cd.md Signed-off-by: fOuttaMyPaint <154358121+TMHSDigital@users.noreply.github.com> --- standards/ci-cd.md | 56 +++++++++++++++++----------------------------- 1 file changed, 20 insertions(+), 36 deletions(-) diff --git a/standards/ci-cd.md b/standards/ci-cd.md index a062455..6da859a 100644 --- a/standards/ci-cd.md +++ b/standards/ci-cd.md @@ -55,49 +55,22 @@ Automatic version bump, tagging, and GitHub Release creation. - `permissions: contents: write` - `fetch-depth: 0` on checkout for full git history -### 3. `pages.yml` +### 3. `drift-check.yml` -**Triggers:** `push` to `main` (paths: `docs/**`, `assets/**`), `workflow_dispatch` +**Triggers:** `push` to `main`, `pull_request` to `main`, `workflow_dispatch` -Deploys the `docs/` directory to GitHub Pages. +Runs the ecosystem drift checker against the repo's own agent files to detect version-signal drift and missing or broken required references. -**Static HTML approach (default):** +**Required configuration:** ```yaml -steps: - - uses: actions/checkout@v4 - - name: Copy assets into docs - run: cp -r assets docs/assets - - uses: actions/configure-pages@v5 - - uses: actions/upload-pages-artifact@v4 - with: - path: docs - - uses: actions/deploy-pages@v5 +- uses: TMHSDigital/Developer-Tools-Directory/.github/actions/drift-check@v1.9 + with: + mode: self + format: gh-summary ``` -**MkDocs approach (for repos with extensive docs):** - -```yaml -steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 - with: - python-version: "3.12" - - run: pip install mkdocs-material - - run: mkdocs build --strict - - uses: actions/upload-pages-artifact@v3 - with: - path: site/ - - uses: actions/deploy-pages@v4 -``` - -**Required permissions:** - -```yaml -permissions: - pages: write - id-token: write -``` +`mode: self` checks only the calling repo's checkout; no cross-repo token is needed. Findings at `info` severity are advisory. Findings at `error` or `warn` severity indicate real drift that should be addressed. ### 4. `stale.yml` @@ -109,12 +82,23 @@ Marks issues and PRs as stale after inactivity and closes them after further ina | Workflow | Purpose | When to include | | --- | --- | --- | +| `pages.yml` | GitHub Pages deployment | Repos with a `docs/` site; generated by scaffold by default | +| `label-sync.yml` | Auto-label PRs by changed file paths | Any repo; generated by scaffold but not required | | `codeql.yml` | Security scanning via GitHub CodeQL | Repos with substantial code (MCP servers, TypeScript packages) | | `dependency-review.yml` | PR dependency audit | Repos with external dependencies | | `release-drafter.yml` | Draft release notes automatically | Repos with frequent PRs | | `ci.yml` | Extended test/lint/build pipeline | Repos with complex test suites | | Domain-specific update | Auto-fetch external data (e.g., native DBs, API schemas) | Repos that consume external data | +## MCP-server Variations + +MCP-server repos follow the same core requirement as cursor-plugin repos, with these adjustments: + +- **`publish.yml` replaces `release.yml`**. MCP servers release via npm publish (OIDC provenance recommended; see [versioning.md](versioning.md)). A conventional-commit `release.yml` that reads `plugin.json` does not apply. +- **`pages.yml` is optional**. Include it if the repo has a `docs/` site; omit it otherwise. +- **Plugin-manifest checks in `validate.yml` may be omitted**. The JSON-validity, manifest-fields, skill-file-existence, and rule-file-existence checks all assume a `plugin.json`. Remove or skip those checks if no `plugin.json` is present. Credential scanning still applies. +- **`drift-check.yml` and `stale.yml` are required**, same as cursor-plugin repos. + ## Workflow Naming - Use lowercase with hyphens: `validate.yml`, `release.yml`, `pages.yml` From 9966ab983160a475d4003d73d93f3c1b0087532e Mon Sep 17 00:00:00 2001 From: fOuttaMyPaint <154358121+TMHSDigital@users.noreply.github.com> Date: Sat, 23 May 2026 19:53:52 -0400 Subject: [PATCH 2/2] docs: clarify validate.yml not required for mcp-server in ci-cd.md The MCP-server Variations section opened with "follow the same core requirement as cursor-plugin repos," implying validate.yml was required. It is not. All validate.yml checks assume plugin.json; mcp-server repos have no plugin.json. Rewrites the section to state the three required workflows explicitly (drift-check.yml, stale.yml, publish.yml) and explains why validate.yml is absent. Also updates the doc intro to distinguish cursor-plugin (four required) from mcp-server (three required). This brings the prose into exact agreement with the machine-readable config in standards/drift-checker.config.json. Signed-off-by: fOuttaMyPaint Signed-off-by: fOuttaMyPaint <154358121+TMHSDigital@users.noreply.github.com> --- standards/ci-cd.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/standards/ci-cd.md b/standards/ci-cd.md index 6da859a..5cef946 100644 --- a/standards/ci-cd.md +++ b/standards/ci-cd.md @@ -1,6 +1,6 @@ # CI/CD Standards -Every developer tool repository must have these four core GitHub Actions workflows. Optional workflows are documented at the end. +Cursor-plugin repositories must have the four core GitHub Actions workflows listed below. MCP-server repositories require a different set of three; see MCP-server Variations. Optional workflows are documented at the end. ## Core Workflows @@ -92,11 +92,11 @@ Marks issues and PRs as stale after inactivity and closes them after further ina ## MCP-server Variations -MCP-server repos follow the same core requirement as cursor-plugin repos, with these adjustments: +MCP-server repos require three workflows: `drift-check.yml`, `stale.yml`, and `publish.yml`. This is a different set from cursor-plugin repos, not a superset or subset. +- **`validate.yml` is not required**. Every check in `validate.yml` (`plugin.json` validity, manifest fields, skill and rule file existence) assumes a `plugin.json`. MCP-server repos have no `plugin.json`, so `validate.yml` does not apply. CI validation is still expected; use `ci.yml` or an equivalent workflow suited to the server's runtime. - **`publish.yml` replaces `release.yml`**. MCP servers release via npm publish (OIDC provenance recommended; see [versioning.md](versioning.md)). A conventional-commit `release.yml` that reads `plugin.json` does not apply. - **`pages.yml` is optional**. Include it if the repo has a `docs/` site; omit it otherwise. -- **Plugin-manifest checks in `validate.yml` may be omitted**. The JSON-validity, manifest-fields, skill-file-existence, and rule-file-existence checks all assume a `plugin.json`. Remove or skip those checks if no `plugin.json` is present. Credential scanning still applies. - **`drift-check.yml` and `stale.yml` are required**, same as cursor-plugin repos. ## Workflow Naming