harness-bootstrap

Harness Bootstrap

Overview

Bootstrap a repository-local Harness that agents can read, extend, and enforce. Start from the closest template, scaffold it with the bootstrap script when possible, and then tailor architecture, rules, validation, and plans to the real project.

Workflow

1. Choose the closest template.
   • Read references/template-selection.md if the repo shape is unclear.
   • Prefer software for product engineering repos, research for experiment-heavy work, and general for mixed operational or knowledge-work systems.
2. Scaffold the first draft.
   • Preferred: run python3 scripts/bootstrap_harness.py --template <template> --target <path> --project-name <name>.
   • Fallback: copy from assets/templates/<template>/ manually if a custom layout is required.
3. Tailor the knowledge base to the real repository.
   • Rewrite AGENTS.md so it points at the real source-of-truth docs.
   • Fill docs/architecture/monorepo-map.md with actual owners, boundaries, and dependency directions.
   • Define the smallest useful checks in docs/validation/checks.md.
   • Record non-trivial work in plans/active/ and real debt in docs/quality/debt-log.md.
4. Encode the operating model instead of relying on chat memory.
   • Keep AGENTS.md short.
   • Treat docs/ as the system of record.
   • Promote repeated review comments into docs, tests, scripts, or automation.
5. Validate and iterate.
   • Run the smallest checks that prove the scaffold matches the repo.
   • Use references/customization-playbook.md to drive the first round of edits.
   • Read references/harness-principles.md when deciding what to encode versus what to leave flexible.

Template Catalog

• software: scaffold apps/, packages/, infra/, and the operating docs needed for code, review, validation, and cleanup.
• research: scaffold datasets/, experiments/, analysis/, reports/, and the docs needed for provenance, reproducibility, and eval loops.
• general: scaffold workflows/, references/, deliverables/, automation/, and the docs needed for mixed operational or knowledge-work systems.

Trigger Examples

• Use $harness-bootstrap to scaffold an agent-first Harness for this monorepo.
• Use $harness-bootstrap to turn this research repo into a reproducible agent workspace with plans and validation.
• Use $harness-bootstrap to create a general-purpose Harness for writing, ops, and automation work.

Resources

scripts/

• bootstrap_harness.py: copy a template into a target repository and replace the fixed placeholders.

references/

• harness-principles.md: rationale for agent-first repo design and why the scaffold is structured this way.
• template-selection.md: choose between software, research, and general.
• customization-playbook.md: minimum edits to make immediately after scaffolding.

assets/

• templates/software
• templates/research
• templates/general