Bootstrap a repository for agent-first development when there is no agent harness yet, or when the repo has only minimal ad hoc scaffolding. Use when the user asks to set up a new repo, scaffold an agent-ready project, add AGENTS.md, create harness scripts, validation gates, source-of-truth docs, CI, smoke or e2e loops, repo-local review skills, or automerge policy. For a repo that already has a working agent harness and needs modernization or repair, prefer update-harness.
Bootstrap a repository for agent-first development when there is no agent harness yet, or when the repo has only minimal ad hoc scaffolding. Use when the user asks to set up a new repo, scaffold an agent-ready project, add AGENTS.md, create harness scripts, validation gates, source-of-truth docs, CI, smoke or e2e loops, repo-local review skills, or automerge policy. For a repo that already has a working agent harness and needs modernization or repair, prefer update-harness.
Setup Harness
Set up the repository so future agents can learn the project from committed
artifacts, run the same commands humans run, validate their own work, and leave
auditable evidence. The rule of thumb: when an agent struggles, improve the
environment before adding more prompt text.
This skill is language and framework agnostic. Discover the target repo's
toolchain first, then express the harness through that repo's existing scripts,
package manager, test runner, CI provider, and documentation style.
Operating Rules
Inspect before writing: read the existing README, build files, package or
workspace manifests, CI, scripts, and docs.
Keep AGENTS.md short. It is a router to deeper docs, not the encyclopedia.
Prefer mechanical checks over advisory prose whenever a rule will matter more
than once.
Put durable decisions in the repo: docs, scripts, schemas, generated reports,
tests, workflows, or repo-local skills.
Add narrow, composable scripts. Agents should run script entrypoints, not
reconstruct command chains from memory.
Use the target repo's existing tooling unless there is no reasonable local
choice. Do not impose Rust, Node, Playwright, Docker, GitHub Actions, or any
other stack by default.
Make expensive or environment-specific checks opt-in unless the repo's normal
development loop already requires them.
Preserve user work and local conventions. Do not overwrite existing harness
files; evolve them.
Phase 1: Orientation
Build a harness inventory before creating files:
product or library purpose
app type: service, frontend, CLI, library, worker, monorepo, data pipeline,
mobile app, infrastructure repo, or mixed workspace
language and framework surfaces
package manager, build tool, test runner, formatter, linter, and CI provider
local dependencies such as databases, queues, browsers, emulators, secrets, or
external services
docs/HARNESS_ENGINEERING.md or docs/HARNESS.md: harness strategy,
required commands, validation contract, and merge policy
docs/PLANS.md: execution-plan workflow and required sections
docs/QUALITY_SCORE.md: current quality baseline, ratchets, and next targets
docs/SECURITY.md and docs/RELIABILITY.md when the repo has security,
persistence, runtime, or production reliability concerns
docs/behaviours/: canonical scenarios, current validation state, and e2e or
manual checklist
docs/design-docs/, docs/product-specs/, or docs/references/ when deeper
design decisions, product behavior, or external references need a stable home
docs/generated/: generated inventory, public-surface reference, quality
snapshot, CLI help, API schema, load baseline, or whatever generated
references are valuable for the repo
Use last_reviewed: YYYY-MM-DD frontmatter on source-of-truth docs if the repo
needs freshness checks.
Execution Plans
Create docs/exec-plans/active/ and docs/exec-plans/completed/ for complex
work. Every non-readme plan should include:
## Goal
## Scope
## Tasks
## Decision Log
## Verification
Plans are for coupled or multi-step work. Small edits should not be buried in
process.
Script Entry Points
Add a scripts/README.md that catalogs all important scripts. Prefer these
entrypoints:
scripts/fast-feedback.sh: local pre-PR gate for cheap deterministic checks
scripts/harness-check.sh: full CI gate; includes slower tests and stricter
drift checks
scripts/validate-harness-docs.sh: required docs, links between router docs,
plan headings, and doc structure
scripts/check-doc-links.*: markdown links and source-of-truth references
scripts/check-agents-drift.*: AGENTS.md still points at the real docs and
repo surfaces
scripts/check-behaviour-docs.*: canonical scenarios appear in current-state
and e2e checklist docs
scripts/check-doc-freshness.*: source-of-truth docs are recently reviewed
scripts/check-generated-docs.*: generated references are current
boundary checks for the repo's architecture, such as package dependencies,
module ownership, API compatibility, or import rules
generators for workspace inventory, public APIs, CLI help, schemas, quality
health, or performance baselines
local dependency helpers that allocate random ports or per-worktree data
directories instead of assuming global ports
an e2e or smoke runner that writes logs and artifacts and reports skipped
environment-gated steps explicitly
Implementation language is a repo choice. Shell is useful for orchestration, but
checks can be Python, JavaScript, Go, Rust, Ruby, Make, Just, or any tool the
repo already standardizes on.
Review Gates
If repo-local skills are supported, add narrow pre-PR skills:
.agents/skills/review/SKILL.md: confirmed-issue-only correctness and
reliability review
Wire a mechanical companion such as scripts/pre-pr-review.sh into
fast-feedback and harness-check. It should verify the review artifacts are
present and catch changed-file hazards across unstaged, staged, and committed
branch diffs.
CI And Gardening
Use the target repo's CI provider. A good baseline has:
a PR/push workflow that runs scripts/harness-check.sh
a PR template requiring intent, behavior changes, validation evidence, and
screenshots or artifacts when relevant
scheduled generated-doc refresh
scheduled doc freshness or source-of-truth review
scheduled plan sweep for stale active plans
scheduled boundary or dependency audit if the repo has important module
contracts
scheduled review-pattern mining if the team wants recurring PR feedback to
become new checks or docs
Start automerge conservatively. Critical paths should require a human until the
repo has enough green history to widen automation. Critical paths are
repo-specific, but commonly include migrations, auth, billing, credentials,
secrets, sandboxing, workflow files, root agent instructions, harness policy,
and shared public contracts.
Phase 3: Scaffold In Slices
Work in reviewable slices, continuing unless the user asks to pause:
Add the router and docs map.
Add execution-plan directories and plan template.
Add script entrypoints and script catalog.
Add generated docs and drift checks.
Add smoke or e2e runners with artifacts.
Add review and security review gates.
Add CI and scheduled gardening.
Add automerge only after the validation and review gates exist.
For each slice, adapt the templates in references/ to the target repo. Treat
those files as examples, not mandatory stack choices.
Validation Strategy
Order checks so cheap, structural failures surface first:
environment-gated tests such as databases, browsers, live providers, or
observability stacks
fast-feedback should be fast enough for every normal PR. harness-check
should match CI and can be slower. Environment-gated checks should either run
when prerequisites are present or skip with a clear reason.
If the repo already has violations, baseline them deliberately and fail only on
regressions. Tell the user what was baselined and where the burn-down target
lives.
Definition Of Done
A setup is complete when:
a new agent can start at AGENTS.md and find the right docs, scripts, and
validation path
repeated project rules are encoded in scripts, CI, generated docs, or
templates
scripts/fast-feedback.sh and the full CI-equivalent gate both run or have
documented blockers
generated docs can be refreshed and checked for drift
behavior-changing work has a place to update canonical scenarios
complex work has a checked-in plan lifecycle
risky paths have a human-review or automerge refusal policy
the final response lists the created or updated files and the validation that
passed or could not be run
