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.
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 |
- Engineers become environment designers — define constraints, not implementations
- Give agents a map, not an encyclopedia — AGENTS.md ~100 lines, progressive disclosure
- If agents can't see it, it doesn't exist — all knowledge machine-readable in repo
- Enforce architecture mechanically, not via markdown — linters and tests, not prose
- Boring technology wins — composable, stable, well-trained-on APIs
- Entropy management is garbage collection — periodic scans catch drift
- Throughput changes merge philosophy — minimal blocking gates
- Agent-to-agent code review — humans intervene only for judgment calls
claude plugin marketplace add https://github.com/Gizele1/harness-init.git
claude plugin install harness-init@harness-initRestart Claude Code. The /harness-init command and skill will be available in all projects.
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.
# 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# 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-initCopy skills/harness-init/SKILL.md and skills/harness-init/references/ into your .cursor/rules/harness-init/ directory, or inline the reference content into .cursorrules.
Read skills/harness-init/SKILL.md and follow the phases manually in any AI coding assistant.
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"
project-root/
├── AGENTS.md # ~100 lines, orientation map [Required]
├── ARCHITECTURE.md # Top-level domain map [Required]
├── docs/
│ ├── architecture/
│ │ └── LAYERS.md # Layer hierarchy + enforcement [Required]
│ ├── golden-principles/ # DO/DON'T patterns, 30-60 lines each [Required]
│ ├── SECURITY.md # Auth, secrets, threat model [Required]
│ ├── guides/ # Setup, testing, deployment [Recommended]
│ ├── exec-plans/ # ExecPlan lifecycle [Recommended]
│ │ ├── active/
│ │ ├── completed/
│ │ └── tech-debt-tracker.md
│ ├── design-docs/ # ADRs [Recommended]
│ │ ├── index.md
│ │ ├── core-beliefs.md
│ │ └── {NNNN-title}.md
│ ├── references/ # External docs for LLMs [Recommended]
│ │ └── {library}-llms.txt
│ ├── DESIGN.md # Design philosophy [Recommended]
│ ├── PLANS.md # Exec-plans overview [Recommended]
│ ├── QUALITY_SCORE.md # Per-domain quality grades [Recommended]
│ ├── RELIABILITY.md # SLA, error budgets (services only) [Conditional]
│ ├── STACK.md # Stack conventions [Conditional]
│ ├── product-specs/ # Product specs [Conditional]
│ └── generated/ # Auto-generated docs [Conditional]
│ └── {db-schema,api-spec}.md
├── scripts/gc/ # Garbage collection scripts
├── tests/architecture/
│ └── boundary.test.* # Mechanical layer enforcement
└── .github/workflows/
├── ci.yml # lint + typecheck + test + build
└── gc.yml # Weekly entropy scan
The file structure above is synthesized from multiple industry sources and designed with clear priority tiers.
| Tier | Meaning | When to create |
|---|---|---|
| Required | Core scaffolding every agent-ready repo needs | Always — Phase 0-2 |
| Recommended | High-value docs that most projects benefit from | Projects with >1 contributor or >3 months lifespan |
| Conditional | Context-dependent — only when the project type demands it | Phase 0 discovery determines applicability |
AGENTS.md at repo root — Industry standard adopted by 20,000+ repositories (agents.md standard). Serves as the single entry point for any AI agent. Kept to ~100 lines as an index, not an encyclopedia — following OpenAI's "give agents a map" principle.
ARCHITECTURE.md at repo root — Top-level domain map visible without navigating into docs/. Points to docs/architecture/LAYERS.md for details. Follows progressive disclosure: root-level files are summaries, docs/ has depth.
docs/ as system of record — Consolidates all project knowledge in one discoverable location. Agents scan docs/ as their primary context source. This is directly from OpenAI's harness engineering: "if agents can't see it, it doesn't exist."
docs/architecture/LAYERS.md — The definitive layer hierarchy, mechanically enforced by boundary tests (Phase 3) and linter rules (Phase 4). Not just documentation — it's the source of truth that tooling reads.
docs/golden-principles/ — 30-60 line DO/DON'T files per concern (imports, naming, error handling, testing). Short enough for agents to consume fully, specific enough to prevent drift. From OpenAI's "canonical patterns" concept.
docs/exec-plans/ (active/completed/) — Dual-source design: directory lifecycle from the Harness article (active → completed with retrospectives), single-file alternative from OpenAI Cookbook. Active plans move to completed/ when done, preserving context for downstream agents.
docs/design-docs/ with ADR format — Architecture Decision Records following the {NNNN-title}.md convention (ADR standard). core-beliefs.md captures non-negotiable decisions that agents must never violate. index.md provides a navigable list.
docs/SECURITY.md — Auth flows, secrets management, and threat model in one place. Agents working on auth-adjacent code need this context to avoid introducing vulnerabilities.
Conditional docs (RELIABILITY.md, STACK.md, product-specs/, generated/) — Only created when Phase 0 discovery detects the relevant project type. RELIABILITY.md for services with SLAs. STACK.md replaces OpenAI's original FRONTEND.md with a stack-agnostic name. product-specs/ for product-driven projects. generated/ for auto-generated schemas.
QUALITY_SCORE.md under docs/, not root — Keeps the repo root clean. Only AGENTS.md and ARCHITECTURE.md live at root because they're universal entry points. Everything else lives in docs/ for organization.
| OpenAI Original | harness-init | Why |
|---|---|---|
| FRONTEND.md | docs/STACK.md | Stack-agnostic — works for backend, mobile, etc. |
| .agent/PLANS.md | docs/exec-plans/ or docs/PLANS.md | Directory lifecycle for multi-feature projects, single-file for simple ones |
| Flat docs/ | Tiered docs/ with priority levels | Agents know what's essential vs optional |
| No ADRs | docs/design-docs/ with ADR format | Captures architectural decisions for agent context |
| No security doc | docs/SECURITY.md as required | Security context is non-optional for agent safety |
The skill distinguishes between two types of context:
Static context (lives in repo, always available):
AGENTS.md— agent entry point, ~100 linesdocs/architecture/LAYERS.md— authoritative dependency hierarchydocs/golden-principles/*.md— canonical patterns- Linter rules + boundary tests — mechanical enforcement
Dynamic context (probed at each session start):
git status+git log— work progress- LSP diagnostics — code health
- CI/CD status — pipeline health
- Architecture boundary test — compliance check
Works with any stack. Layer templates provided for:
- Web Frontend (React / Vue / Svelte)
- Backend API (Express / FastAPI / Rails)
- Full-Stack (Next.js / Nuxt / SvelteKit)
- Monorepo (Turborepo / Nx)
The skill reads actual import patterns to discover the real dependency graph rather than assuming a structure.
This skill implements the repo scaffolding part of OpenAI's harness engineering methodology. It does not cover:
- Runtime legibility (starting apps, browser/CDP verification)
- Observability integration (logs, metrics, traces queryable by agents)
- Agent review loops (agent-to-agent PR review)
- Automatic regression verification
- PR feedback iteration loops
- Quality scoring automation (template provided, scoring is manual)
- Design docs versioning workflows
These capabilities require runtime infrastructure beyond what a skill file can provide.
- Harness engineering: leveraging Codex in an agent-first world | OpenAI
- Custom instructions with AGENTS.md | OpenAI Developers
- Using PLANS.md for multi-hour problem solving | OpenAI Cookbook
- Best practices | Codex
- Harness Engineering | Martin Fowler
MIT