{
  "markdown": "# harness-init\n\nBootstrap any repository with [OpenAI's harness engineering](https://openai.com/index/harness-engineering/) scaffolding for agent-first development.\n\n> **Scope:** This is the **repo initialization subset** of harness engineering. Runtime feedback loops, agent review loops, and observability integration are out of scope.\n\n## What It Does\n\nTransforms a repository into an agent-ready environment through 8 phases:\n\n| Phase | What |\n|-------|------|\n| 0. Discovery | Detect stack, map architecture, identify layers, inject dynamic context |\n| 1. AGENTS.md | ~100-line orientation map (index, not encyclopedia) |\n| 2. docs/ | System of record: `architecture/LAYERS.md` + `golden-principles/` + `SECURITY.md` + `guides/` |\n| 3. Testing | Architecture boundary test with ratchet mechanism |\n| 4. Linting | Import restriction rules with remediation in error messages |\n| 5. CI | Parallel lint + typecheck + test + build pipeline |\n| 6. GC | Garbage collection scripts + scheduled weekly scan |\n| 7. Hooks | Pre-commit enforcement |\n\n## Core Principles (from OpenAI)\n\n1. Engineers become environment designers — define constraints, not implementations\n2. Give agents a map, not an encyclopedia — AGENTS.md ~100 lines, progressive disclosure\n3. If agents can't see it, it doesn't exist — all knowledge machine-readable in repo\n4. Enforce architecture mechanically, not via markdown — linters and tests, not prose\n5. Boring technology wins — composable, stable, well-trained-on APIs\n6. Entropy management is garbage collection — periodic scans catch drift\n7. Throughput changes merge philosophy — minimal blocking gates\n8. Agent-to-agent code review — humans intervene only for judgment calls\n\n## Installation\n\n### Claude Code CLI (recommended)\n\n```bash\nclaude plugin marketplace add https://github.com/Gizele1/harness-init.git\nclaude plugin install harness-init@harness-init\n```\n\nRestart Claude Code. The `/harness-init` command and skill will be available in all projects.\n\n### Claude Code settings.json (alternative)\n\nAdd to your `~/.claude/settings.json`:\n\n```json\n{\n  \"extraKnownMarketplaces\": {\n    \"harness-init\": {\n      \"source\": {\n        \"source\": \"git\",\n        \"url\": \"https://github.com/Gizele1/harness-init.git\"\n      }\n    }\n  },\n  \"enabledPlugins\": {\n    \"harness-init@harness-init\": true\n  }\n}\n```\n\nThen restart Claude Code.\n\n### Claude Code (manual copy)\n\n```bash\n# Clone and copy skill + references to project-level skills\nrm -rf /tmp/harness-init 2>/dev/null; git clone --depth 1 https://github.com/Gizele1/harness-init.git /tmp/harness-init\nmkdir -p .claude/skills/harness-init/references\ncp /tmp/harness-init/skills/harness-init/SKILL.md .claude/skills/harness-init/\ncp /tmp/harness-init/skills/harness-init/references/*.md .claude/skills/harness-init/references/\nrm -rf /tmp/harness-init\n```\n\n### OpenAI Codex\n\n```bash\n# Clone and copy to Codex skills directory\nrm -rf /tmp/harness-init 2>/dev/null; git clone --depth 1 https://github.com/Gizele1/harness-init.git /tmp/harness-init\nmkdir -p .agents/skills/harness-init/references\ncp /tmp/harness-init/skills/harness-init/SKILL.md .agents/skills/harness-init/\ncp /tmp/harness-init/skills/harness-init/references/*.md .agents/skills/harness-init/references/\nrm -rf /tmp/harness-init\n```\n\n### Cursor\n\nCopy `skills/harness-init/SKILL.md` and `skills/harness-init/references/` into your `.cursor/rules/harness-init/` directory, or inline the reference content into `.cursorrules`.\n\n### Manual\n\nRead `skills/harness-init/SKILL.md` and follow the phases manually in any AI coding assistant.\n\n## Usage\n\nIn Claude Code:\n\n```\n/harness-init          # Interactive — asks what to set up\n/harness-init full     # Full setup, all phases\n/harness-init 2        # Specific phase only\n/harness-init 3-4      # Phase range\n```\n\nOr simply say:\n\n- \"harness init this repo\"\n- \"make this repo agent-ready\"\n- \"set up architecture boundaries\"\n\n## What Gets Created\n\n```\nproject-root/\n├── AGENTS.md                          # ~100 lines, orientation map          [Required]\n├── ARCHITECTURE.md                    # Top-level domain map                 [Required]\n├── docs/\n│   ├── architecture/\n│   │   └── LAYERS.md                  # Layer hierarchy + enforcement        [Required]\n│   ├── golden-principles/             # DO/DON'T patterns, 30-60 lines each [Required]\n│   ├── SECURITY.md                    # Auth, secrets, threat model          [Required]\n│   ├── guides/                        # Setup, testing, deployment           [Recommended]\n│   ├── exec-plans/                    # ExecPlan lifecycle                   [Recommended]\n│   │   ├── active/\n│   │   ├── completed/\n│   │   └── tech-debt-tracker.md\n│   ├── design-docs/                   # ADRs                                [Recommended]\n│   │   ├── index.md\n│   │   ├── core-beliefs.md\n│   │   └── {NNNN-title}.md\n│   ├── references/                    # External docs for LLMs              [Recommended]\n│   │   └── {library}-llms.txt\n│   ├── DESIGN.md                      # Design philosophy                   [Recommended]\n│   ├── PLANS.md                       # Exec-plans overview                 [Recommended]\n│   ├── QUALITY_SCORE.md               # Per-domain quality grades           [Recommended]\n│   ├── RELIABILITY.md                 # SLA, error budgets (services only)  [Conditional]\n│   ├── STACK.md                       # Stack conventions                   [Conditional]\n│   ├── product-specs/                 # Product specs                       [Conditional]\n│   └── generated/                     # Auto-generated docs                 [Conditional]\n│       └── {db-schema,api-spec}.md\n├── scripts/gc/                        # Garbage collection scripts\n├── tests/architecture/\n│   └── boundary.test.*                # Mechanical layer enforcement\n└── .github/workflows/\n    ├── ci.yml                         # lint + typecheck + test + build\n    └── gc.yml                         # Weekly entropy scan\n```\n\n## File Structure Design\n\nThe file structure above is synthesized from multiple industry sources and designed with clear priority tiers.\n\n### Priority Tiers\n\n| Tier | Meaning | When to create |\n|------|---------|---------------|\n| **Required** | Core scaffolding every agent-ready repo needs | Always — Phase 0-2 |\n| **Recommended** | High-value docs that most projects benefit from | Projects with >1 contributor or >3 months lifespan |\n| **Conditional** | Context-dependent — only when the project type demands it | Phase 0 discovery determines applicability |\n\n### Design Decisions and Sources\n\n**AGENTS.md at repo root** — Industry standard adopted by 20,000+ repositories ([agents.md standard](https://agents-md.org/)). 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.\n\n**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.\n\n**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.\"\n\n**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.\n\n**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.\n\n**docs/exec-plans/ (active/completed/)** — Dual-source design: directory lifecycle from the [Harness article](https://openai.com/index/harness-engineering/) (active → completed with retrospectives), single-file alternative from [OpenAI Cookbook](https://developers.openai.com/cookbook/articles/codex_exec_plans). Active plans move to completed/ when done, preserving context for downstream agents.\n\n**docs/design-docs/ with ADR format** — Architecture Decision Records following the `{NNNN-title}.md` convention ([ADR standard](https://adr.github.io/)). `core-beliefs.md` captures non-negotiable decisions that agents must never violate. `index.md` provides a navigable list.\n\n**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.\n\n**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.\n\n**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.\n\n### What Changed from OpenAI's Original\n\n| OpenAI Original | harness-init | Why |\n|----------------|-------------|-----|\n| FRONTEND.md | docs/STACK.md | Stack-agnostic — works for backend, mobile, etc. |\n| .agent/PLANS.md | docs/exec-plans/ or docs/PLANS.md | Directory lifecycle for multi-feature projects, single-file for simple ones |\n| Flat docs/ | Tiered docs/ with priority levels | Agents know what's essential vs optional |\n| No ADRs | docs/design-docs/ with ADR format | Captures architectural decisions for agent context |\n| No security doc | docs/SECURITY.md as required | Security context is non-optional for agent safety |\n\n## Context Strategy\n\nThe skill distinguishes between two types of context:\n\n**Static context** (lives in repo, always available):\n- `AGENTS.md` — agent entry point, ~100 lines\n- `docs/architecture/LAYERS.md` — authoritative dependency hierarchy\n- `docs/golden-principles/*.md` — canonical patterns\n- Linter rules + boundary tests — mechanical enforcement\n\n**Dynamic context** (probed at each session start):\n- `git status` + `git log` — work progress\n- LSP diagnostics — code health\n- CI/CD status — pipeline health\n- Architecture boundary test — compliance check\n\n## Supported Stacks\n\nWorks with any stack. Layer templates provided for:\n\n- Web Frontend (React / Vue / Svelte)\n- Backend API (Express / FastAPI / Rails)\n- Full-Stack (Next.js / Nuxt / SvelteKit)\n- Monorepo (Turborepo / Nx)\n\nThe skill reads actual import patterns to discover the real dependency graph rather than assuming a structure.\n\n## Limitations\n\nThis skill implements the **repo scaffolding** part of OpenAI's harness engineering methodology. It does **not** cover:\n\n- Runtime legibility (starting apps, browser/CDP verification)\n- Observability integration (logs, metrics, traces queryable by agents)\n- Agent review loops (agent-to-agent PR review)\n- Automatic regression verification\n- PR feedback iteration loops\n- Quality scoring automation (template provided, scoring is manual)\n- Design docs versioning workflows\n\nThese capabilities require runtime infrastructure beyond what a skill file can provide.\n\n## References\n\n- [Harness engineering: leveraging Codex in an agent-first world | OpenAI](https://openai.com/index/harness-engineering/)\n- [Custom instructions with AGENTS.md | OpenAI Developers](https://developers.openai.com/codex/guides/agents-md)\n- [Using PLANS.md for multi-hour problem solving | OpenAI Cookbook](https://developers.openai.com/cookbook/articles/codex_exec_plans)\n- [Best practices | Codex](https://developers.openai.com/codex/learn/best-practices)\n- [Harness Engineering | Martin Fowler](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html)\n\n## License\n\nMIT\n",
  "bytes": 11907,
  "sha": "c66842175d3d8c0b27eed5cc76b6e0fe9bad79c74b8804caec4ca46dfe1a6988",
  "repo_slug": "gizele1/harness-init",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_gizele1_harness_init_harness_init_19213241/readme"
}