Skip to content

docs: Create README.md and CHANGELOG.md for initial metrics package release #18

Description

@jflowers

What Changed

The opsx/universal-coupling-model branch introduces the foundational metrics package — the first implementation code in the vibe-check repository. This includes:

  • 14 production source files defining the universal coupling metrics model
  • Public API types: Module, ModuleResult, ModuleGraph, Adapter interface, Registry, ExternalAdapter
  • Named metric types: Instability, Abstractness, Distance, LCOM with documented value ranges
  • Computation functions: ComputeInstability, ComputeAbstractness, ComputeDistance, ComputeZone
  • JSON-RPC 2.0 protocol for external language adapters
  • JSON Schema (modulegraph.schema.json) for interchange format validation
  • Security: path validation, environment sanitization for subprocess execution

Documentation Needed

README.md (new file)

  • Project description and mission (Martin metrics suite for Go)
  • Installation instructions (go get github.com/zero-dot-force/vibe-check)
  • Quick usage example showing metric computation
  • Link to GoDoc
  • Link to RFC (unbound-force/discussions/483)
  • Architecture overview (two-layer model)
  • License (Apache 2.0)

CHANGELOG.md (new file)

  • Initial entry for the metrics package addition
  • Document all new types, interfaces, and functions
  • Note the JSON schema version (1.0)

AGENTS.md cleanup

  • Remove placeholder comment on line 237 (<!-- Placeholder — update when go.mod and Makefile are created -->)

Why It Matters

This is the project's first public-facing code. Without a README, developers discovering the repository on GitHub have no landing page. Without a CHANGELOG, the project's versioning story (required by AGENTS.md) has no tracking artifact.

References

  • Branch: opsx/universal-coupling-model
  • AGENTS.md behavioral rules: lines 185-193 (documentation gate)

Labels: This issue should be labeled docs once the label is created.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions