Skip to content

README.md

Latest commit

 

History

History
42 lines (34 loc) · 3.22 KB

README.md

File metadata and controls

42 lines (34 loc) · 3.22 KB

TMHSDigital Developer Tools Standards

Standards and conventions for building Cursor IDE plugins, MCP servers, and developer tool repositories under the TMHSDigital organization.

Quick Reference

Standard Summary
Folder Structure Canonical repo layout for plugins and MCP servers
Plugin Manifest .cursor-plugin/plugin.json specification
CI/CD GitHub Actions workflows every repo must have
GitHub Pages Documentation site setup (static HTML or MkDocs)
Commit Conventions Conventional commits and version bumping rules
README Template Standard README structure and required sections
AGENTS.md Template AI agent guidance file structure
Versioning Semver management and release flow
Release-doc-sync Composite action contract for keeping CHANGELOG, CLAUDE, and ROADMAP in sync after auto-release
Testing Test frameworks, minimum coverage bar, CI wiring
Skills SKILL.md structure, frontmatter, and conventions
Rules .mdc structure, globs, and the secrets rule pattern
MCP Server Tool naming, runtime choice, transport, destructive ops
Security Vulnerability disclosure, secrets, workflow supply chain
Licensing DCO + inbound license grant model
Scope What belongs in the directory and what does not
Lifecycle Tool status transitions (experimental to archived)
Writing Style Prose conventions across all repos

Principles

  1. Derived artifacts are generated, not edited - registry.json is the single source of truth. The README tables, catalog site, and About section are emitted from it. Manual edits drift and get overwritten.
  2. Single branch - All repos use main only. No develop, staging, or release branches.
  3. Conventional commits - Every commit follows the conventional format. Release workflows parse them to determine version bumps.
  4. AI-agent friendly - Every repo includes AGENTS.md and .cursorrules. Standards docs are written so an agent can apply them without guessing.
  5. Inbound DCO, outbound CC-BY-NC-ND-4.0 - Contributors sign off under the Developer Certificate of Origin and grant a broader inbound license so the project can accept pull requests under its outbound license. See licensing.md.
  6. Scope gate - Tools must be developer-facing, Cursor or MCP native, and actively maintained. See scope.md.
  7. Lifecycle transitions are explicit - Tools move through experimental to beta to active to maintenance to deprecated to archived with documented criteria. See lifecycle.md.

Applying These Standards

New repos should be created using the scaffold generator. It produces a fully standards-compliant repository with all required files, workflows, and structure.

Existing repos can adopt these standards incrementally. The standards docs describe what compliance looks like; there is no automated migration tool.