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)

name

@org/name

version

license

exports

main

files

publishConfig

access: "public"

repository

bugs

homepage

description

pnpm typecheck

pnpm test

pnpm pack --dry-run

Documentation (root level)

README.md

install

getting started

quickstart

npm i

CHANGELOG.md

LICENSE

Repo Hygiene (root level)

CONTRIBUTING.md

CODE_OF_CONDUCT.md

SECURITY.md

.gitignore

node_modules

dist

.env

TODO

FIXME

files

CI/CD (root level)

.github/workflows/ci.yml

test

package.json

lint

package.json

typecheck

tsc

package.json

assess_project

For the

assess_project

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

If

healthy: false

checks

topIssue

harness validate

harness check-deps

i18n Coverage (conditional)

When

i18n.enabled: true

harness.config.json

i18n.coverage.minimumPercent

coverage.detectUntranslated

coverage.requirePlurals

harness-i18n

If

i18n.enabled

i18n

Comprehensive Checks (only with

--comprehensive

)

These checks run only when

--comprehensive

API Documentation

To check: for each package, read the main entry point (

exports

main

export

/** ... */

Examples

examples/

package.json

cd examples/<name> && npm install && npm run build

Dependency Health

npm audit

npm outdated

Git Hygiene

git ls-files

.gitignore

.env

.DS_Store

*.log

coverage/

API_KEY=

SECRET=

PASSWORD=

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:

/harness:detect-doc-drift

/harness:cleanup-dead-code

/harness:enforce-architecture

/harness:diagnostics

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

publishConfig

"publishConfig": { "access": "public" }

repository

"repository": { "type": "git", "url": "<detected from git remote>" }

bugs

"bugs": { "url": "<repository>/issues" }

homepage

"homepage": "<repository>#readme"

description

"description": ""

files

"files": ["dist"]

["dist", "src"]

CONTRIBUTING.md

CODE_OF_CONDUCT.md

SECURITY.md

CHANGELOG.md

# Changelog

/harness:align-documentation

/harness:cleanup-dead-code

--fix

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

Non-Fixable Findings

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

TODO

FIXME

git log --oneline <last-tag>..HEAD

exactOptionalPropertyTypes

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/

# 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

{
  "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

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

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.

Examples

Example: First Run on a Monorepo with Gaps

Context: A TypeScript monorepo with 3 packages. Two packages are missing

files

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.