Harness Init

Harness Init

This is the repo initialization subset of harness engineering. Runtime feedback loops, agent review loops, and observability stack setup are out of scope. If the repo already has observability (logs, metrics, tracing), this skill reads it as dynamic context but does not build it.

Source: OpenAI "Harness engineering: leveraging Codex in an agent-first world" (2026-02-11)

2. Phase 1 — AGENTS.md (~100 lines, orientation map)

   • Read references/agents-md-template.md for the template
   • Fill in from Phase 0 discovery — don't invent, reflect what exists
   • Point to docs/ for details, don't inline them

3. Phase 2 — docs/ system of record Required:

   • Create: ARCHITECTURE.md at repo root (top-level domain map, ~30 lines, points to LAYERS.md)
   • Create: docs/architecture/LAYERS.md (definitive layer hierarchy + remediation guide)
   • Create: docs/golden-principles/ — Read references/golden-principles-guide.md for how to write these
   • Create: docs/SECURITY.md — Read references/security-template.md for template and exclusion rules Recommended:
   • Create: docs/guides/ (setup, testing, deployment — only what's relevant)
   • Create: docs/exec-plans/ — Read references/exec-plan-template.md for the standard (active/ + completed/ subdirs)
   • Create: docs/design-docs/ with index.md (ADR index) and core-beliefs.md (non-negotiable decisions)
   • Create: docs/references/ (external library docs reformatted for LLM consumption, e.g. {library}-llms.txt)
   • Create: docs/DESIGN.md, docs/PLANS.md, docs/QUALITY_SCORE.md Conditional (by project type):
   • docs/RELIABILITY.md — for services (SLA, error budgets, resilience patterns)
   • docs/STACK.md — stack-specific conventions (replaces OpenAI's FRONTEND.md)
   • docs/product-specs/ — for product-driven projects
   • docs/generated/ — auto-generated docs (db-schema.md, api-spec.md)

4. Phase 3 — Architecture boundary test

   • Read references/boundary-test-template.md for test skeletons, KNOWN_VIOLATIONS format, and ratchet logic
   • Read references/stack-routing.md for import parser and test file path per stack
   • Scan all source files, parse imports, validate against layer rules
   • Error format: VIOLATION: {file}:{line} imports {target} — {layer} cannot import {target_layer}. See docs/architecture/LAYERS.md
   • Ratchet: KNOWN_VIOLATIONS stored in tests/architecture/known-violations.json, can only shrink
   • For existing repos: establish baseline first, then ratchet

5. Phase 4 — Linter boundary enforcement

   • Read references/stack-routing.md for linter rule name and config location per stack
   • Use linter's native import restriction rules
   • Every error message MUST include remediation — error output IS agent context

6. Phase 5 — CI pipeline

   • Read references/ci-templates.md for starter YAML templates and command validation rules
   • Read references/stack-routing.md for CI job matrix per stack
   • Adapt to stack — not every stack needs all 4 jobs (lint, typecheck, test, build)
   • Validate discovered commands before embedding in CI — reject shell metacharacters, stop and ask if suspicious

7. Phase 6 — Garbage collection

   • Read references/gc-patterns.md for scan types, safety rules, and migration strategy
   • Read references/stack-routing.md Phase 6 table for per-stack GC tooling
   • Read references/ci-templates.md GC Workflow section for gc.yml template
   • Prioritize entropy scans (doc drift, architecture violations) over style scans
   • Single gc command + scheduled GitHub Action (weekly cron, report-only)

8. Phase 7 — Pre-commit hooks (optional)

   • Read references/stack-routing.md for framework and config per stack
   • Phase 7 is optional — CI (Phase 5) is the authoritative gate

• Explore (lightweight model) — directory mapping, file discovery in Phase 0
• Architect (heavyweight model) — architecture analysis, layer identification in Phase 0
• Write (lightweight model) — AGENTS.md + docs generation in Phases 1-2
• Execute (standard model) — boundary test, linter config, CI, GC scripts in Phases 3-7
• Verify (standard model) — final checklist validation
• Read references/*.md files on demand per phase — don't load all at once

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)       [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

Reference Files

Detailed templates and guides are in references/ — read on demand per phase:

• references/layer-templates.md — 5 layer models (4 tech stacks + OpenAI original)
• references/agents-md-template.md — AGENTS.md template
• references/context-strategy.md — Static vs dynamic context tables
• references/exec-plan-template.md — ExecPlan (docs/exec-plans/) standard
• references/golden-principles-guide.md — How to write golden principles
• references/gc-patterns.md — GC scan types + migration strategy for existing repos
• references/security-template.md — SECURITY.md template with exclusion rules
• references/boundary-test-template.md — Test skeletons, KNOWN_VIOLATIONS format, ratchet logic
• references/tool-routing.md — Platform-specific tool delegation mappings
• references/stack-routing.md — Stack → tooling decision tables for Phases 3-7
• references/ci-templates.md — Starter CI YAML for GitHub Actions, GitLab, Makefile

Source: Gizele1/harness-init — distributed by TomeVault.