harness-engineering

Evolve an existing repository toward Harness Engineering by making it more legible to agents, moving critical knowledge into repo-local artifacts, adding pre...

Evolve an existing repository toward Harness Engineering without pretending it must be rebuilt as a blank template. Prefer repo-local knowledge, predictable structure, and executable checks over aspirational documentation and hidden context.

Workflow

1. Audit the current repo

• Read AGENTS.md and the top-level docs under docs/.
• Identify missing source-of-truth artifacts, dead references, placeholder CI, and stack-specific assumptions.
• Confirm whether the repo is a real app, a governance layer, or a starter template.
• Preserve existing product and runtime structure where possible. Do not force a greenfield layout onto a mature codebase.

2. Establish the minimum repo-local artifacts

• Keep AGENTS.md short and map-like.
• Add only the missing artifacts that materially improve agent legibility, such as:
  • docs/ARCHITECTURE.md
  • docs/core-beliefs.md
  • docs/quality-score.md
  • docs/observability.md
  • docs/worktrees.md
  • docs/skills.md
  • docs/product-specs/index.md
  • docs/product-specs/template.md
  • docs/exec-plans/index.md
  • docs/exec-plans/template.md
  • docs/exec-plans/tech-debt-tracker.md
  • docs/generated/README.md
• Match the artifact set to the repository's maturity. A small service may need fewer documents than a large multi-domain product.
• If generated artifacts are referenced but not yet produced, add explicit placeholders rather than leaving silent gaps.

3. Replace policy-only claims with enforcement

• Use the repo's existing stack where needed, but prefer bun for lightweight governance scripts when that does not conflict with the project.
• Add executable checks for required files, stale placeholders, broken references, and obvious contract drift.
• Wire CI to run the checks for every push and pull request.
• Do not leave comments like "run lint later" as the only quality gate.

4. Preserve generality

• Preserve real project names, domains, and runtime details when the repository is already in active use.
• Remove only accidental one-off assumptions, stale tribal knowledge, and undocumented conventions.
• Write docs so a future agent can continue work from the repository itself.
• Prefer incremental hardening over broad rewrites.

5. Make the repo legible to agents

• Keep one clear location for each category of knowledge.
• Put product intent in docs/product-specs/.
• Put multi-step delivery work in docs/exec-plans/.
• Put detailed external library notes in docs/references/.
• Prefer explicit directory conventions over clever local variation.

6. Verify the template

• Run bun run template:check or the project equivalent.
• Fix all hard failures before stopping.
• Treat warnings as backlog only if they are genuinely optional.
• If the repository is not a git checkout, note that you cannot report git status.

Editing rules

• Use imperative language in docs.
• Prefer concise checklists over essays.
• Keep examples aligned with bun.
• Avoid claiming that a metric, score, or automation is "automatic" unless code actually updates it.
• Add placeholder files when the template references an artifact that new projects will generate later.

Reference

Read references/checklist.md when you need a compact audit list while editing or reviewing a template repo.

Deliverables

• Updated repo-local docs
• Missing placeholder artifacts filled in
• Executable validation or governance checks
• CI wired to run real checks
• A short summary of what now supports Harness Engineering and what still depends on hidden context