Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Plugins to help open source projects grow and maintain: quickstart a repo with c
| **badge-buddy** | Helps projects of any size achieve meaningful open source badges. An unofficial guide and implementation assistant for the OpenSSF Best Practices badges (Passing, Silver, Gold), the Security Baseline, and Scorecard. Set up useful coverage and analysis badges, improve testing, and maintain secure GitHub workflows. | [plugins/badge-buddy](plugins/badge-buddy/README.md) |
| **starter-buddy** | Quickstart a GitHub repository with key community-files, issue templates, and other sensible defaults, to save you time setting up any project. | [plugins/starter-buddy](plugins/starter-buddy/README.md) |
| **release-buddy** | Versioning and changelog guidance, plus signed source tags and immutable GitHub releases with optional build provenance and scoped dependency evidence. | [plugins/release-buddy](plugins/release-buddy/README.md) |
| **badge-progress** | A mod for Badge Buddy users: a pane with each badge section's answer counts, and a progress bar above the prompt while Claude records answers. | [plugins/badge-progress](plugins/badge-progress/README.md) |
| **badge-progress** | Progress tracking is paused during the MCP migration; its pane explains the transition and points users to Badge Buddy’s retained local preview board. | [plugins/badge-progress](plugins/badge-progress/README.md) |
| **workflow-guard** | A mod that stops Claude from adding unpinned actions or broad top-level token permissions to GitHub Actions workflows. | [plugins/workflow-guard](plugins/workflow-guard/README.md) |

## Install
Expand Down Expand Up @@ -62,6 +62,7 @@ hidden = [".github", ".gitignore", ".nvmrc", ".pre-commit-config.yaml", ".pretti
│ │ │ ├── ossf-bp-badges/
│ │ │ ├── ossf-scorecard/
│ │ │ └── static-analysis/
│ │ ├── .mcp.json
│ │ └── README.md
│ ├── badge-progress/
│ ├── release-buddy/
Expand Down Expand Up @@ -94,7 +95,7 @@ make plugin-validate # validate each plugin's structure (needs the Claude Code
make mod-test # run the mods' tests (needs the Claude Code CLI)
```

The runtime uses only the Python standard library; the local `venv` holds the development dependencies. `make check` runs the plugin and maintenance suites in separate processes and compiles the Python sources. Continuous integration runs the same target on every push and pull request. See [criteria maintenance](docs/criteria-maintenance.md) for catalog updates and [plugin releases](docs/releases.md) for how to release a plugin: merge its version and reviewed notes, review the checks and OSV report, then approve publication in GitHub. The workflow tags the checked commit and publishes an immutable release. See [Verifying a plugin release](VERIFYING.md) to check its source and attachments; marketplace installation does not automatically pin or verify a release.
Local Python helpers use the standard library; Badge Buddy’s BadgeApp operations use the separately installed `best-practices-mcp` package. The local `venv` holds development dependencies. `make check` runs the plugin and maintenance suites in separate processes and compiles the Python sources. Continuous integration runs the same target on every push and pull request. See [criteria maintenance](docs/criteria-maintenance.md) for catalog updates and [plugin releases](docs/releases.md) for how to release a plugin: merge its version and reviewed notes, review the checks and OSV report, then approve publication in GitHub. The workflow tags the checked commit and publishes an immutable release. See [Verifying a plugin release](VERIFYING.md) to check its source and attachments; marketplace installation does not automatically pin or verify a release.

See [CONTRIBUTING.md](CONTRIBUTING.md) for how to file issues and propose changes.

Expand Down
2 changes: 1 addition & 1 deletion docs/criteria-maintenance.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Criteria maintenance

Badge Buddy ships a local criteria catalog with each plugin version. Its guidance and preview aim to match the wording and presentation of the public bestpractices.dev application. Ordinary plugin use reads this catalog without downloading criterion pages; assessment synchronization separately fetches public project answers through the API.
Badge Buddy ships a local criteria catalog with each plugin version. Its guidance and preview aim to match the wording and presentation of the public bestpractices.dev application. The local preview board reads this catalog without downloading criterion pages. Application work uses the MCP server’s own pinned criteria catalog and public project-read tools; compare any observed wording differences rather than assuming both packaged snapshots are identical.

The catalog is generated from a pinned [BadgeApp](https://github.com/ossf/best-practices-badge) checkout and its English translations. Before accepting an update, maintainer tooling compares it with the public application pages for Passing, Silver, Gold, and Baseline levels 1–3. The comparison covers criterion identifiers, order, descriptions, details, links, and the requirement markings visible on those pages. Submission flags not exposed in the downloaded HTML remain repository-derived.

Expand Down
34 changes: 34 additions & 0 deletions docs/planning/badge-buddy-mcp-migration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Badge Buddy MCP migration

Date: 2026-11-16. Implementation branch: `codex/badge-buddy-mcp`, based on `origin/main`. The existing code-scanning/release work branch is preserved separately.

## Plan and review

Replace Badge Buddy's duplicate BadgeApp transport and draft controller with the published `best-practices-mcp==0.5.0` stdio server. The plugin remains responsible for advisory material, interpretation, user interaction, peer review, project improvements, and the passive local preview board. The MCP owns project discovery, public reads, mechanical document checks, optional server drafts, and proposal URL generation. Browser review and saving remain user-controlled.

The plan was reviewed before implementation. Review retained the following boundaries:

1. Register the pinned server in the plugin and document `uvx` and Python prerequisites. Use discovered MCP tool names; do not assume identical prefixes across hosts.
2. Make caller-owned explicit documents the ordinary workflow. Server-managed drafts remain optional, and no plugin path is silently repurposed as the MCP data directory.
3. Remove the BadgeApp CLI, local synchronization engine, proposal implementation, and console-fill generator. Preserve Scorecard by extracting its shared GitHub remote normalizer.
4. Retain all advisory reference documents, the bundled display catalog and examples, and the local board assets. Add a small offline renderer accepting an explicit assessment file, output path and section; exercise every badge level.
5. Explain how to reuse existing assessments without automatic migration or silent conflict resolution. Preserve source files and existing answers, including unknown and empty values.
6. Update relevant tests and installation/application documentation. Retire tests for the deleted implementation; retain board, catalog, alias, Scorecard and maintenance coverage.

No release is published by this migration. The current plugin manifest version is left for the maintainer's release decision. The independently released MCP dependency is pinned to 0.5.0.

## Expected review and verification

Run the offline plugin and maintenance suites, source compilation, JSON/Markdown checks, README tree validation and plugin manifest validation. Exercise the board entry point across all six levels and inspect that no CLI BadgeApp network or console-script transfer path remains. A host installation/reload is still needed to qualify automatic MCP registration in a real host; offline configuration checks do not establish that result.

## Dependent progress mod

Review found that `badge-progress` consumed the deleted controller's Bash output and restored cached counts. Its tracking is explicitly suspended in this migration: the pane shows a transition notice, and old counts are neither restored nor displayed. The local board remains available. A future adapter needs documented host MCP events, project-bound state, catalog-aware counts, separate saved/draft semantics, and a defined strategy for patch-only update results. This is preferable to a silent regression or an invented fallback to the removed CLI.

## Verification record

The offline `make check` run passed 180 tests across badge-buddy (72), starter-buddy (17), release-buddy (1), and maintenance (90), then compiled the Python sources. The board CLI tests cover all six levels and preserve the input file. Both badge-progress suspension tests passed, including a check that persisted counts are not read. `claude plugin validate` passes for badge-buddy and badge-progress, with existing missing-icon warnings; the paused mod also receives advice about an omitted install example. Formatting hooks and the README tree check pass. The pinned command reports `bestpractices-mcp 0.5.0` after refreshing uv's package index cache.

The Scorecard helper's only semantic change is importing the extracted remote normalizer; the repository's required formatter also reformats the existing file. No criteria text, board assets or other advisory skill functionality was removed. The deleted tests exercised the retired duplicate BadgeApp implementation; retained behavior has board, alias, Scorecard, catalog and integration/configuration coverage.

Independent implementation review caught a numeric board label that could disagree with the draft’s `id`. The renderer now rejects mismatches before creating or replacing HTML; tests cover mismatches, matching IDs, id-less drafts and explicit local labels.
8 changes: 8 additions & 0 deletions plugins/badge-buddy/.mcp.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"mcpServers": {
"bestpractices": {
"command": "uvx",
"args": ["--from", "best-practices-mcp==0.5.0", "bestpractices-mcp"]
}
}
}
Loading
Loading