pm-ops package spec

pm-ops is a proposed TypeScript-first pm package focused on agent workflows across many repositories.

Why this package

Teams running multiple pm-* repositories currently need ad-hoc shell loops to:

• audit release readiness across repos
• check dependency/security/reporting drift
• collect test evidence and changelog health
• enforce naming and workflow policies

pm-ops standardizes those operations into deterministic pm commands that are token-efficient and automation-friendly.

Core goals

• Provide one command surface for cross-repo health and release checks.
• Keep output small and structured for coding agents.
• Integrate with existing pm tracking to attach evidence automatically.
• Work with local paths first; optional GitHub integration by token.

Proposed command surface

• pm ops scan
  Scan a repo set and produce a readiness snapshot (tests, release workflows, changelog compliance, open PR/issues, security alert visibility).

• pm ops policy
  Validate policy bundles (example: private repo no runners, naming conventions, required scripts/workflows, pm item duplicate guards).

• pm ops verify-release
  Run a configurable release gate matrix per package and summarize pass/fail with machine-readable diagnostics.

• pm ops report
  Emit concise TOON/JSON reports and optional markdown summaries for PRs.

Data model (draft)

• workspace_set: named group of repositories and paths
• policy_bundle: declarative checks with severity
• scan_result: per-repo checks + aggregated score
• evidence_link: command, output hash, timestamp, repo path

Extension capabilities

• commands: primary interface (ops ...)
• schema: policy bundle schema and report schema
• importers: optional ingest of external check artifacts (future)

Agent UX requirements

• Every command supports deterministic JSON output for strict parsing.
• Human output defaults to compact sections with stable ordering.
• Failures include actionable next command hints.
• Support low-noise mode to minimize token usage in loops.

Initial milestone plan

1. Build ops scan MVP for local repositories.
2. Add policy checks for release workflow/changelog/private-runner rules.
3. Add report formatter + PM evidence linking hooks.
4. Add GitHub gh-backed optional enrichments.

Out of scope for v0

• Automatic remediation commits across repos.
• Self-modifying workflow generation without review.
• Any telemetry stack rewiring.