Harness Release Readiness

Harness Release Readiness

Audit, fix, and track your project's path to a publishable release. No release without a passing report.

When to Use

• Before publishing packages to npm — audit readiness and fix gaps
• At milestone boundaries — check progress toward release (fires on on_milestone trigger)
• When resuming release prep after a previous session — loads state and shows what changed
• NOT for actually performing the release (that is CI/CD — Changesets, GitHub Actions, etc.)
• NOT for non-npm targets (Docker, PyPI, etc.) — this skill is npm-focused
• NOT when the project has no packages to publish (use harness-verification for general health)

Arguments

• --comprehensive — Run additional checks beyond the standard set: API doc coverage, example project validation, dependency health audit, and git hygiene scan. These checks are slower and may require network access (e.g., npm audit). Omit for a fast standard audit.

Process

Iron Law

No release may be performed without a passing release readiness report.

If the report shows failures, the project is not ready. Fix the failures first. A "mostly passing" report is not a passing report — every failure is a risk that lands on your users.

---

Phase 1: AUDIT — Release-Specific Checks

Session Resumption

Before running checks, look for existing state:

1. Read .harness/release-readiness.json. If it exists, this is a resumption.

2. Display a delta summary:

   Release Readiness — resuming from <timestamp>
   
   Since last run:
     ✓ N items fixed (<list>)
     → N items remaining (<list>)
   
   Re-running full audit...
   

3. If no state file exists, this is a fresh run. Proceed directly to checks.

Project Type Detection

Before running any checks, verify this is an npm project:

1. Check whether package.json exists at the project root.

2. If package.json does not exist, exit immediately with:

   This project does not appear to be an npm project (no package.json found).
   /harness:release-readiness is npm-focused and cannot audit this project type.
   
   For general project health, use: /harness:verification
   

3. If package.json exists, continue to Monorepo Detection.

Monorepo Detection

Detect whether the project is a monorepo:

1. Check for packages/*/package.json or a workspaces field in root package.json.
2. If monorepo: collect all non-private packages. Run packaging checks against each independently. Run shared checks (docs, repo hygiene, CI/CD) once at the root.
3. If single package: run all checks against the root package.json.

Standard Checks (always run)

Run every check below. Record each as pass, warn, or fail:

• pass — check satisfied, no action needed
• warn — not blocking but should be addressed before release (e.g., missing optional field)
• fail — must be fixed before release

Packaging (per package)

Check	Severity if missing
name field exists and is scoped (@org/name) or valid unscoped name	fail
version field exists and is valid semver	fail
license field exists	fail
exports or main field exists (entry point is defined)	fail
files field exists (controls what gets published)	fail
publishConfig field exists with access: "public" (for scoped packages)	warn
repository field exists with valid URL	warn
bugs field exists	warn
homepage field exists	warn
description field exists	warn
Build succeeds: run the project's build command	fail
Typecheck passes: run the project's typecheck command (e.g., pnpm typecheck)	fail
Tests pass: run the project's test command (e.g., pnpm test)	fail
pnpm pack --dry-run produces expected files (no test files, no src if dist exists)	warn

Documentation (root level)

Check	Severity if missing
README.md exists	fail
README contains an install/quickstart section (search for install, getting started, quickstart, or npm i)	warn
README contains a usage or API section	warn
CHANGELOG.md exists	fail
CHANGELOG has at least one entry (not empty or template-only)	warn
LICENSE file exists	fail

Repo Hygiene (root level)

Check	Severity if missing
CONTRIBUTING.md exists	warn
CODE_OF_CONDUCT.md exists	warn
SECURITY.md exists	warn
.gitignore exists and covers node_modules, dist, .env	fail
No TODO or FIXME in published source files (files matching each package's files glob)	warn

CI/CD (root level)

Check	Severity if missing
CI workflow file exists (.github/workflows/ci.yml or similar)	fail
Release/publish workflow file exists	warn
test script exists in root package.json	fail
lint script exists in root package.json	fail
typecheck or tsc script exists in root package.json	fail
assess_project passes (full harness CI gate)	fail

For the assess_project check, run it with all harness-specific checks including lint:

assess_project({
  path: "<project-root>",
  checks: ["validate", "deps", "docs", "lint", "perf", "security", "entropy", "arch"],
  mode: "detailed"
})

If healthy: false, each failing check in the checks array maps to a separate finding with its topIssue. This replaces running harness validate, harness check-deps, and lint as separate commands.

i18n Coverage (conditional)

When i18n.enabled: true in harness.config.json, run these checks:

Check	Severity if failing
Translation coverage meets i18n.coverage.minimumPercent for all target locales	fail (strict) / warn (standard)
No untranslated values (source text in target locale files) when coverage.detectUntranslated	warn
All CLDR plural forms present for target locales when coverage.requirePlurals	warn
No stale translations (source changed since last translation timestamp)	warn
harness-i18n scan passes with zero errors	fail (strict) / warn (standard)

If i18n.enabled is false or the i18n config block is absent, skip this section entirely and report it as "N/A" in the audit output.

Comprehensive Checks (only with --comprehensive)

These checks run only when --comprehensive is passed. They are slower and may require network access.

API Documentation

Check	Severity if missing
Exported functions/classes/types have JSDoc or TSDoc comments	warn
Coverage threshold: >80% of exports documented	warn

To check: for each package, read the main entry point (exports or main), find all export statements, and verify each has a preceding doc comment (/** ... */).

Examples

Check	Severity if missing
Example projects exist (in examples/ directory)	warn
Each example's package.json references workspace packages at current versions	warn
Each example builds successfully: cd examples/<name> && npm install && npm run build	fail

Dependency Health

Check	Severity if missing
npm audit reports no high or critical vulnerabilities	fail
No deprecated dependencies (check npm outdated for deprecated flags)	warn

Git Hygiene

Check	Severity if missing
No binary files >1MB tracked in git (check with git ls-files)	warn
.gitignore covers common artifacts: .env, .DS_Store, *.log, coverage/	warn
No secrets detected in tracked files (search for patterns: API_KEY=, SECRET=, PASSWORD=, private key headers)	fail

Output

After all checks complete, produce a structured summary for the next phases:

AUDIT COMPLETE

Packaging:  8/12 passed, 2 warnings, 2 failures
Docs:       5/6 passed, 1 warning, 0 failures
Hygiene:    3/5 passed, 2 warnings, 0 failures
CI/CD:      4/5 passed, 1 warning, 0 failures
i18n:       N/N passed, N warnings, N failures (or: skipped — i18n not enabled)
[comprehensive] API Docs:  skipped (use --comprehensive)
[comprehensive] Examples:  skipped (use --comprehensive)
[comprehensive] Dep Health: skipped (use --comprehensive)
[comprehensive] Git Hygiene: skipped (use --comprehensive)

Total: 20/28 passed, 6 warnings, 2 failures

Proceed to Phase 2: MAINTAIN.

---

Phase 2: MAINTAIN — Parallel Maintenance Skill Dispatch

Run existing maintenance skills to catch issues that release-specific checks do not cover. These skills are independent of each other and should be dispatched in parallel.

Dispatch

Launch 4 agents concurrently using the Agent tool. Each agent runs one maintenance skill against the project root:

Agent	Skill	Purpose
1	/harness:detect-doc-drift	Find documentation that has fallen out of sync with code
2	/harness:cleanup-dead-code	Find unused exports, imports, and files
3	/harness:enforce-architecture	Validate layer boundaries and dependency rules
4	/harness:diagnostics	Classify any existing errors and route to resolution strategies

Example dispatch (Claude Code):

Use the Agent tool to launch 4 agents in parallel:

Agent 1: "Run /harness:detect-doc-drift on this project and return findings as a structured list"
Agent 2: "Run /harness:cleanup-dead-code on this project and return findings as a structured list"
Agent 3: "Run /harness:enforce-architecture on this project and return findings as a structured list"
Agent 4: "Run /harness:diagnostics on this project and return findings as a structured list"

Result Collection

Wait for all agents to complete. Set a 2-minute timeout per agent — if an agent exceeds this, treat it as failed. For each agent:

1. If the agent succeeded: extract its findings as a list of issues with file paths and descriptions.
2. If the agent failed (error, timeout, or exceeded 2-minute limit): log the failure reason and continue. A failed maintenance check does not block the release readiness report — it is reported as "unavailable" in the final report.

Merge

Combine findings from all maintenance skills into a unified structure:

MAINTENANCE RESULTS

Doc Drift:     2 issues found
  - docs/api/index.md references removed function `parseConfig`
  - docs/guides/getting-started.md version number outdated (0.7.0 → 0.8.0)

Dead Code:     0 issues found (clean)

Architecture:  0 violations found (clean)

Diagnostics:   1 warning
  - TypeScript strict mode warning in packages/cli/src/init.ts:42

Carry these results forward to Phase 3 (FIX) and Phase 4 (REPORT).

---

Phase 3: FIX — Auto-Remediation

Review all findings from Phase 1 (AUDIT) and Phase 2 (MAINTAIN). For each fixable finding, offer to apply a fix. Non-fixable findings are listed with remediation guidance for the human.

Fixable Findings

Finding	Auto-Fix
Missing publishConfig in package.json	Add "publishConfig": { "access": "public" }
Missing repository field in package.json	Add "repository": { "type": "git", "url": "<detected from git remote>" }
Missing bugs field in package.json	Add "bugs": { "url": "<repository>/issues" }
Missing homepage field in package.json	Add "homepage": "<repository>#readme"
Missing description field in package.json	Add "description": "" with a TODO comment for the human to fill in
Missing files field in package.json	Add "files": ["dist"] (or ["dist", "src"] if no build step)
Missing CONTRIBUTING.md	Generate from template with standard sections (how to contribute, development setup, PR process)
Missing CODE_OF_CONDUCT.md	Generate Contributor Covenant v2.1
Missing SECURITY.md	Generate template with vulnerability reporting instructions
Missing CHANGELOG.md (file does not exist)	Generate skeleton with # Changelog header and initial entry from git log since last tag
Doc drift detected	Delegate to /harness:align-documentation
Dead code found	Delegate to /harness:cleanup-dead-code (with --fix intent)

Prompting

Present each fix individually:

[1/6] Fix: Add "repository" field to packages/core/package.json
      Value: { "type": "git", "url": "https://github.com/org/repo.git" }
      [y]es / [n]o / [a]ll remaining

• y — Apply this fix and show the next one.
• n — Skip this fix. Record it as "skipped" in state.
• a — Apply this fix and all remaining fixes without prompting.

After each batch of fixes (or after each individual fix if not batching), run harness validate to ensure the fixes did not introduce new issues.

Non-Fixable Findings

These require human judgment and cannot be auto-fixed. List them with guidance:

Finding	Guidance
TODO/FIXME in published source	List each location with file:line. Human must resolve or move to a tracked issue.
README missing usage/API sections	Suggest section structure but do not generate content — only the author knows the API.
CHANGELOG exists but has no entries (empty or template-only)	Suggest running git log --oneline <last-tag>..HEAD to generate entries. Unlike a missing file (auto-fixable above), an empty CHANGELOG needs human-authored content.
CI workflow missing	Provide a starter template but flag for human review before committing.
Build failure	Show the error output. Do not attempt to fix build issues automatically.
Typecheck failure	Show the error output with file:line. Common causes: orphaned files with stale imports, missing type declarations, exactOptionalPropertyTypes violations. Do not auto-fix — type errors often indicate structural problems.
Test failure	Show the error output with failing test names. Do not attempt to fix test failures automatically — they may indicate real bugs.

Output

FIX COMPLETE

Applied:  4 fixes
Skipped:  1 fix (README usage section — requires human)
Failed:   0 fixes

Remaining manual items:
  - [ ] Write usage section in README.md
  - [ ] Resolve TODO in packages/cli/src/init.ts:42

Proceed to Phase 4: REPORT.

---

Phase 4: REPORT — Final Output

Write two artifacts: a human-readable report and a machine-readable state file.

1. Release Readiness Report (release-readiness-report.md)

Write to the project root by default. If the project uses .harness/reports/ for generated reports, write there instead. Use this template:

# Release Readiness Report

**Date:** YYYY-MM-DD
**Project:** <project name>
**Flags:** standard | comprehensive

## Summary

**Result: PASS / FAIL**

| Category                   | Passed       | Warnings | Failures |
| -------------------------- | ------------ | -------- | -------- |
| Packaging                  | N/N          | N        | N        |
| Documentation              | N/N          | N        | N        |
| Repo Hygiene               | N/N          | N        | N        |
| CI/CD                      | N/N          | N        | N        |
| Maintenance — Doc Drift    | N issues     | —        | —        |
| Maintenance — Dead Code    | N issues     | —        | —        |
| Maintenance — Architecture | N violations | —        | —        |
| Maintenance — Diagnostics  | N warnings   | —        | —        |

## Packaging

### <package-name> [pass/warn/fail per check]

- [x] name: `@org/package`
- [x] version: `1.0.0`
- [ ] missing `files` field

(Repeat for each package in monorepo)

## Documentation

- [x] README.md exists
- [x] README has install section
- [ ] README missing usage section

## Repo Hygiene

- [x] CONTRIBUTING.md exists
- [ ] SECURITY.md missing

## CI/CD

- [x] CI workflow exists
- [x] Release workflow exists

## Maintenance Results

### Doc Drift

(findings from detect-doc-drift, or "clean")

### Dead Code

(findings from cleanup-dead-code, or "clean")

### Architecture

(findings from enforce-architecture, or "clean")

### Diagnostics

(findings from diagnostics, or "clean")

## Fixes Applied

- Added `repository` field to packages/core/package.json
- Generated SECURITY.md from template

## Remaining Items

- [ ] Write usage section in README.md
- [ ] Resolve TODO in packages/cli/src/init.ts:42
- [ ] Add `files` field to packages/types/package.json

Result is PASS only when: zero failures across all categories AND zero maintenance issues with "fail" severity. Warnings alone do not block a PASS.

2. State File (.harness/release-readiness.json)

Write to .harness/release-readiness.json. This file enables session resumption.

{
  "schemaVersion": 1,
  "timestamp": "YYYY-MM-DDTHH:MM:SSZ",
  "flags": {
    "comprehensive": false
  },
  "summary": {
    "result": "FAIL",
    "passed": 14,
    "warned": 2,
    "failed": 2,
    "total": 18
  },
  "categories": {
    "packaging": {
      "passed": 5,
      "warned": 1,
      "failed": 1,
      "findings": [
        {
          "package": "packages/types",
          "check": "files field exists",
          "severity": "fail",
          "fixable": true,
          "fixed": false
        }
      ]
    },
    "documentation": {
      "passed": 5,
      "warned": 1,
      "failed": 0,
      "findings": []
    },
    "repo-hygiene": {
      "passed": 3,
      "warned": 2,
      "failed": 0,
      "findings": []
    },
    "ci-cd": {
      "passed": 4,
      "warned": 1,
      "failed": 0,
      "findings": []
    },
    "maintenance": {
      "doc-drift": { "issues": 2, "findings": [] },
      "dead-code": { "issues": 0, "findings": [] },
      "architecture": { "issues": 0, "findings": [] },
      "diagnostics": { "issues": 1, "findings": [] }
    }
  },
  "fixes": {
    "applied": ["added-repository-field-core", "generated-security-md"],
    "pending": ["add-files-field-types", "doc-drift-api-index"],
    "skipped": ["readme-usage-section"]
  }
}

Session Resumption Behavior

When the skill is invoked and .harness/release-readiness.json exists:

1. Load the previous state.
2. Re-run all checks (do not trust cached results — code may have changed).
3. Compare new results against previous state.
4. Display a delta:

Release Readiness — resuming from 2026-03-19T10:30:00Z

Since last run:
  ✓ 2 items fixed (added "files" field to types, resolved doc drift in api/index.md)
  ↑ 1 new issue (CONTRIBUTING.md was deleted)
  → 1 item remaining (TODO in cli/init.ts:42)

Previous: 14/18 passed (FAIL)
Current:  16/19 passed (FAIL)

Milestone Trigger Variant

When the skill fires via on_milestone trigger, use progress framing instead of pass/fail:

Release Readiness Progress — Milestone: <milestone name>

  16/18 checks passing (up from 12/18 last run)
  1 item auto-fixable
  1 item requires manual attention

  Trend: ↑ improving (4 items resolved since last milestone)

This framing is informational — it does not block anything. It gives the team a sense of trajectory.

---

Harness Integration

• assess_project — Used in AUDIT Phase 1 (CI/CD section) to run the full harness CI gate (validation, dependencies, docs, lint, performance/complexity, security, entropy, and architecture) in a single parallel call. Also run after auto-fixes in Phase 3 to verify project health. Automatically inherits new checks added to assess_project.
• Sub-skill invocations — Phase 2 dispatches detect-doc-drift, cleanup-dead-code, enforce-architecture, and diagnostics as parallel agents. Phase 3 delegates fixes to align-documentation and cleanup-dead-code.
• State file — .harness/release-readiness.json enables session resumption and progress tracking. This file is read at the start of each invocation and written at the end.
• Report file — release-readiness-report.md is written to the project root. It is a snapshot, not a tracked artifact — regenerate it on each run.
• i18n coverage — When i18n.enabled: true, Phase 1 checks translation coverage against configured thresholds. Uses harness-i18n scan results and harness-i18n-workflow coverage tracking. Blocks release in strict mode if coverage is below i18n.coverage.minimumPercent.

Success Criteria

1. Running /harness:release-readiness on a project with known gaps produces a report that identifies all of them — no false negatives on standard checks
2. Running it on a clean project produces an all-pass report with no false positives
3. Maintenance skills are dispatched in parallel and their results appear in the unified report
4. Auto-fix applies correct changes — package.json modifications are valid JSON, generated files match project conventions
5. State file persists across sessions and subsequent runs show accurate deltas
6. --comprehensive flag activates additional checks without affecting standard check behavior
7. on_milestone trigger fires and produces a progress-style report (not just pass/fail)
8. Monorepo support: each package is audited independently with per-package results in the report
9. harness validate passes after the skill's SKILL.md and skill.yaml are written

Rationalizations to Reject

These are common rationalizations that sound reasonable but lead to incorrect results. When you catch yourself thinking any of these, stop and follow the documented process instead.

Rationalization	Why It Is Wrong
"The MAINTAIN phase takes too long, so I will skip dispatching the 4 maintenance agents"	No skipping the MAINTAIN phase. Maintenance checks catch issues that release-specific checks miss.
"This auto-fix is obviously correct, so I can apply it without prompting the user"	No auto-fix without prompting. Every fix must be presented to the human before being applied.
"Most checks pass and only a few warnings remain, so the release is ready"	A "mostly passing" report is not a passing report. The result is PASS only when zero failures exist across all categories.
"The previous run found these issues and I fixed them, so I can trust the cached results"	Session resumption requires re-running all checks. Code may have changed since the last run.

Examples

Example: First Run on a Monorepo with Gaps

Context: A TypeScript monorepo with 3 packages. Two packages are missing files fields, README lacks a usage section, and SECURITY.md does not exist.

Phase 1: AUDIT

No existing state found. Running fresh audit.

Checking packages/core...
  ✓ name: @myorg/core
  ✓ version: 1.2.0
  ✓ license: MIT
  ✓ exports defined
  ✗ files field missing (fail)
  ✗ publishConfig missing (warn)

Checking packages/utils...
  ✓ name: @myorg/utils
  ✓ version: 0.3.0
  ✓ license: MIT
  ✓ exports defined
  ✗ files field missing (fail)

Checking packages/cli...
  ✓ name: @myorg/cli (all fields present)

Documentation:
  ✓ README.md exists
  ✗ README missing usage section (warn)
  ✓ CHANGELOG.md exists with entries
  ✓ LICENSE exists

Repo Hygiene:
  ✓ CONTRIBUTING.md exists
  ✓ CODE_OF_CONDUCT.md exists
  ✗ SECURITY.md missing (warn)
  ✓ .gitignore covers node_modules, dist, .env

CI/CD:
  ✓ CI workflow: .github/workflows/ci.yml
  ✓ Release workflow: .github/workflows/release.yml
  ✓ test, lint, typecheck scripts present

AUDIT COMPLETE
Packaging:  9/12 passed, 1 warning, 2 failures
Docs:       5/6 passed, 1 warning, 0 failures
Hygiene:    4/5 passed, 1 warning, 0 failures
CI/CD:      5/5 passed, 0 warnings, 0 failures
Total: 23/28 passed, 3 warnings, 2 failures

Phase 2: MAINTAIN

Dispatching 4 maintenance agents in parallel...

Doc Drift:     1 issue — docs/api/core.md references removed function `legacyParse`
Dead Code:     0 issues (clean)
Architecture:  0 violations (clean)
Diagnostics:   0 warnings (clean)

MAINTENANCE COMPLETE — 1 issue found

Phase 3: FIX

5 fixable findings:

[1/5] Fix: Add "files": ["dist"] to packages/core/package.json
      [y]es / [n]o / [a]ll remaining
> y
      ✓ Applied

[2/5] Fix: Add "files": ["dist"] to packages/utils/package.json
      [y]es / [n]o / [a]ll remaining
> y
      ✓ Applied

[3/5] Fix: Add "publishConfig": { "access": "public" } to packages/core/package.json
      [y]es / [n]o / [a]ll remaining
> a
      ✓ Applied (and all remaining)

[4/5] Fix: Generate SECURITY.md from template
      ✓ Applied (batch)

[5/5] Fix: Delegate doc drift to /harness:align-documentation
      ✓ Applied (batch) — docs/api/core.md updated

Running harness validate... ✓ passes

FIX COMPLETE — 5 applied, 0 skipped, 0 failed

Phase 4: REPORT

Writing release-readiness-report.md...
Writing .harness/release-readiness.json...

# Release Readiness Report
Date: 2026-03-19
Result: PASS (after fixes)

28/28 checks passed, 0 warnings, 0 failures
Maintenance: all clean

Fixes applied this session: 5
Remaining manual items:
  - [ ] Write usage section in README.md (optional — warning only)

Example: Resuming After Partial Fixes

Release Readiness — resuming from 2026-03-18T14:20:00Z

Since last run:
  ✓ 3 items fixed (added files fields, generated SECURITY.md)
  → 2 items remaining (doc drift in api/core.md, README usage section)

Re-running full audit...

Previous: 23/28 passed (FAIL)
Current:  27/28 passed (PASS — 1 warning remaining)

The project is release-ready. The remaining warning (README usage section) is not blocking.

Gates

These are hard stops. Violating any gate means the process has broken down.

• No release without a passing report. If the report result is FAIL, the project must not be released. Fix all failures first.
• No skipping the MAINTAIN phase. Maintenance checks catch issues that release-specific checks miss (dead code, architecture drift, doc drift). They must run every time.
• No auto-fix without prompting. Every fix must be presented to the human before being applied (unless the human chose all to batch-approve remaining fixes). Silent fixes are not allowed.
• All findings must have evidence. Do not report a check as failed without showing the specific file, line, or field that caused the failure. "Packaging looks incomplete" is not a finding — "packages/core/package.json is missing the files field" is.
• State must be written. After every run, .harness/release-readiness.json must be updated. Without state, session resumption is impossible and progress is lost.

Escalation

• When there are too many failures to fix in one session: Present the full report, highlight the most impactful fixes (failures before warnings, blocking before non-blocking), and suggest a prioritized fix order. Save state so the next session can pick up where this one left off.
• When a maintenance skill is unavailable or errors out: Report it as "unavailable" in the maintenance section. Do not block the rest of the report. Suggest running the failed skill manually: "Doc drift check failed — run /harness:detect-doc-drift separately to investigate."
• When monorepo packages have inconsistent configurations: Flag the inconsistency explicitly: "packages/core has publishConfig but packages/utils does not. Should all packages use the same publishing configuration?" Ask the human before applying a uniform fix.
• When the project has no build command: Some packages are types-only and have no build step. Skip the build check for packages without a build script and note it as "N/A" rather than a failure.
• When fixes conflict with each other: Present both findings and let the human choose. Example: dead code cleanup wants to remove a function, but doc drift fix references that function in updated docs. Human must decide which takes priority.