From harness-claude
Audits npm projects and monorepos for release readiness with packaging, docs, git hygiene, and CI/CD checks. Fixes issues, tracks progress, requires passing report before publishing.
npx claudepluginhub intense-visions/harness-engineering --plugin harness-claudeThis skill uses the workspace's default tool permissions.
> Audit, fix, and track your project's path to a publishable release. No release without a passing report.
Performs pre-release readiness review: scans debug artifacts, version mismatches, changelog gaps, git hygiene, breaking changes, license compliance; runs tests and build verification for human review.
Audits repository for baseline compliance across 9 categories: configuration, code quality, git hygiene, CI/CD, testing, security, documentation. Outputs Markdown checklist report and JSON sidecar.
Executes local release workflow: pre-flight checks via ci-local-release.sh, git changelog generation, package version bumps, release commit, and annotated git tag. Supports --check, --dry-run modes.
Share bugs, ideas, or general feedback.
Audit, fix, and track your project's path to a publishable release. No release without a passing report.
on_milestone trigger)--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.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.
Before running checks, look for existing state:
Read .harness/release-readiness.json. If it exists, this is a resumption.
Display a delta summary:
Release Readiness — resuming from <timestamp>
Since last run:
✓ N items fixed (<list>)
→ N items remaining (<list>)
Re-running full audit...
If no state file exists, this is a fresh run. Proceed directly to checks.
Before running any checks, verify this is an npm project:
Check whether package.json exists at the project root.
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
If package.json exists, continue to Monorepo Detection.
Detect whether the project is a monorepo:
packages/*/package.json or a workspaces field in root package.json.package.json.Run every check below. Record each as pass, warn, or fail:
| 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 |
| 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 |
| 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 |
| 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.
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)These checks run only when --comprehensive is passed. They are slower and may require network access.
| 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 (/** ... */).
| 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 |
| Check | Severity if missing |
|---|---|
npm audit reports no high or critical vulnerabilities | fail |
No deprecated dependencies (check npm outdated for deprecated flags) | warn |
| 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 |
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.
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.
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"
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:
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).
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.
| 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) |
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
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.
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. |
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.
Write two artifacts: a human-readable report and a machine-readable state file.
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.
.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"]
}
}
When the skill is invoked and .harness/release-readiness.json exists:
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)
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.
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.detect-doc-drift, cleanup-dead-code, enforce-architecture, and diagnostics as parallel agents. Phase 3 delegates fixes to align-documentation and cleanup-dead-code..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.release-readiness-report.md is written to the project root. It is a snapshot, not a tracked artifact — regenerate it on each run.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./harness:release-readiness on a project with known gaps produces a report that identifies all of them — no false negatives on standard checks--comprehensive flag activates additional checks without affecting standard check behavioron_milestone trigger fires and produces a progress-style report (not just pass/fail)harness validate passes after the skill's SKILL.md and skill.yaml are writtenThese 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. |
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)
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.
These are hard stops. Violating any gate means the process has broken down.
all to batch-approve remaining fixes). Silent fixes are not allowed.files field" is..harness/release-readiness.json must be updated. Without state, session resumption is impossible and progress is lost./harness:detect-doc-drift separately to investigate."publishConfig but packages/utils does not. Should all packages use the same publishing configuration?" Ask the human before applying a uniform fix.build script and note it as "N/A" rather than a failure.