harness-init

harness-init

Bootstrap any repository with OpenAI's harness engineering scaffolding for agent-first development.

Scope: This is the repo initialization subset of harness engineering. Runtime feedback loops, agent review loops, and observability integration are out of scope.

What It Does

Transforms a repository into an agent-ready environment through 8 phases:

Phase	What
0. Discovery	Detect stack, map architecture, identify layers, inject dynamic context
1. AGENTS.md	~100-line orientation map (index, not encyclopedia)
2. docs/	System of record: architecture/LAYERS.md + golden-principles/ + SECURITY.md + guides/
3. Testing	Architecture boundary test with ratchet mechanism
4. Linting	Import restriction rules with remediation in error messages
5. CI	Parallel lint + typecheck + test + build pipeline
6. GC	Garbage collection scripts + scheduled weekly scan
7. Hooks	Pre-commit enforcement

Core Principles (from OpenAI)

1. Engineers become environment designers — define constraints, not implementations
2. Give agents a map, not an encyclopedia — AGENTS.md ~100 lines, progressive disclosure
3. If agents can't see it, it doesn't exist — all knowledge machine-readable in repo
4. Enforce architecture mechanically, not via markdown — linters and tests, not prose
5. Boring technology wins — composable, stable, well-trained-on APIs
6. Entropy management is garbage collection — periodic scans catch drift
7. Throughput changes merge philosophy — minimal blocking gates
8. Agent-to-agent code review — humans intervene only for judgment calls

Installation

Claude Code CLI (recommended)

claude plugin marketplace add https://github.com/Gizele1/harness-init.git
claude plugin install harness-init@harness-init

Restart Claude Code. The /harness-init command and skill will be available in all projects.

Claude Code settings.json (alternative)

Add to your ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "harness-init": {
      "source": {
        "source": "git",
        "url": "https://github.com/Gizele1/harness-init.git"
      }
    }
  },
  "enabledPlugins": {
    "harness-init@harness-init": true
  }
}

Then restart Claude Code.

Claude Code (manual copy)

# Clone and copy skill + references to project-level skills
rm -rf /tmp/harness-init 2>/dev/null; git clone --depth 1 https://github.com/Gizele1/harness-init.git /tmp/harness-init
mkdir -p .claude/skills/harness-init/references
cp /tmp/harness-init/skills/harness-init/SKILL.md .claude/skills/harness-init/
cp /tmp/harness-init/skills/harness-init/references/*.md .claude/skills/harness-init/references/
rm -rf /tmp/harness-init

OpenAI Codex

# Clone and copy to Codex skills directory
rm -rf /tmp/harness-init 2>/dev/null; git clone --depth 1 https://github.com/Gizele1/harness-init.git /tmp/harness-init
mkdir -p .agents/skills/harness-init/references
cp /tmp/harness-init/skills/harness-init/SKILL.md .agents/skills/harness-init/
cp /tmp/harness-init/skills/harness-init/references/*.md .agents/skills/harness-init/references/
rm -rf /tmp/harness-init

Cursor

Copy skills/harness-init/SKILL.md and skills/harness-init/references/ into your .cursor/rules/harness-init/ directory, or inline the reference content into .cursorrules.

Manual

Read skills/harness-init/SKILL.md and follow the phases manually in any AI coding assistant.

Usage

In Claude Code:

/harness-init          # Interactive — asks what to set up
/harness-init full     # Full setup, all phases
/harness-init 2        # Specific phase only
/harness-init 3-4      # Phase range

Or simply say:

• "harness init this repo"
• "make this repo agent-ready"
• "set up architecture boundaries"

What Gets Created