harnessize

harnessize is a CLI for preparing repositories for AI harness workflows.

npx -y harnessize@latest

The CLI exposes the command shape, context topics, build pipeline, tests, and release automation. The default init flow creates a thin AGENTS.md harness handoff when one does not already exist.

Usage

npx -y harnessize@latest [target] [options]
npx -y harnessize@latest context [topic]

Options:

• --dry-run: preview planned harnessization steps without writing files.
• --json: print the plan as JSON.
• -h, --help: show help.
• -v, --version: show the package version.

Harnessization

By default, harnessize creates AGENTS.md as the repository's single source of truth for agent-facing harness guidance. Existing instruction files are not overwritten; the CLI reports a skip so the agent can merge a small harnessize handoff manually when needed. Generated guidance tells agents not to write secrets, credentials, tokens, personal data, or non-public local machine/workspace data into repository artifacts. It also tells agents to align semantic use cases before durable changes, use those cases as TDD input, and keep non-obvious design background, dependencies, key decisions, and semantic logic in code-adjacent comments when tests alone are not enough.

Harnessize also creates thin adapter files by default so repositories behave consistently across multiple coding agents:

npx -y harnessize@latest

This keeps AGENTS.md as the canonical harness document while adding thin routing files for tools with different conventions:

• Codex uses AGENTS.md directly.
• Claude Code gets CLAUDE.md, which imports AGENTS.md.
• Cursor gets .cursor/rules/harnessize.mdc, an always-applied project rule that references AGENTS.md.

Context Topics

Harnessize can provide progressive, agent-facing guidance without copying large manuals into the target repository.

npx -y harnessize@latest context
npx -y harnessize@latest context grill
npx -y harnessize@latest context feature
npx -y harnessize@latest context caseset
npx -y harnessize@latest context verify
npx -y harnessize@latest context review
npx -y harnessize@latest context conduct

context prints the root agent-facing guidelines for using harnessize as a soft workflow orchestrator. Focused topics add deeper guidance only when needed.

grill pressure-tests a concrete plan, design, architecture, PRD, or implementation approach before execution.

feature guides exceptional standalone feature material when behavior or product knowledge is too large or cross-cutting for executable tests and code-adjacent comments.

caseset guides semantic use case alignment and TDD case maintenance so expected behavior is concrete before durable changes.

verify guides quality-gate evidence selection, checks, self-healing, and escalation when the agent needs confidence that work is correct enough to continue or close.

review guides findings-first review of production materials and worktree changes before handoff, stage transition, or external effect.

conduct guides agent behavior before production work or durable project changes, and includes domain extensions such as coding conduct for implementation, refactoring, and review work.

Development

npm install
npm run dev -- --dry-run
npm test
npm run build

Publishing

Publishing is handled by .github/workflows/publish.yml when a GitHub Release is published.

Before the first release:

1. Make sure the npm package harnessize is owned by your npm user or organization.
2. Configure npm Trusted Publishing for this package:
   • Provider: GitHub Actions
   • Repository: the GitHub repository for this project
   • Workflow: publish.yml
3. Ensure package.json has the correct public GitHub repository URL before publishing with provenance.
4. Publish a GitHub Release whose tag matches the package version, for example v0.1.0.

The workflow uses OIDC-based Trusted Publishing instead of a long-lived NPM_TOKEN.