project-harness-bootstrap

name	project-harness-bootstrap
description	Create or harden the baseline agent-ready structure for a repo. Use when a user asks to prepare a project for Codex, add an agent harness, standardize scripts/docs/CI, or make an existing repo easier and safer for coding agents to work in.

Project Harness Bootstrap

Purpose

Install the baseline repo interfaces that every other harness skill depends on: AGENTS.md, operational docs/, stable scripts/, environment examples, CI, and PR review structure.

Inspect First

• package.json, pyproject.toml, Cargo.toml, go.mod, Gemfile, or equivalent manifests
• existing AGENTS.md, CLAUDE.md, .cursorrules, README, docs, scripts, CI, and env files
• existing test, lint, typecheck, build, and dev commands
• git status when inside a repo, so unrelated user changes are preserved

Procedure

1. Detect the stack and current harness maturity.

   • Use manifests and existing commands, not guesses.
   • Record missing pieces and existing equivalents.
   • For large existing repos, run harness-diagnostics first and use its roadmap to avoid broad unfocused changes.
   • For agent-heavy or multi-session work, run or recommend initialization-readiness-harness and session-continuity-harness before implementation changes.

2. Create the baseline structure.

   • Add AGENTS.md as a short routing map.
   • Add docs/00-index.md and operational docs.
   • Add scripts/ wrappers for stable commands.
   • Add optional surface wrappers when the repo has matching surfaces: scripts/click-path-audit for browser UI, scripts/check-research-evidence for dependency/API/security research, and scripts/ci-local for CI reproduction.
   • Add .env.example when runtime configuration exists or is expected.
   • Add CI only when a repo uses GitHub or the user requested GitHub Actions.

3. Preserve useful generated and user-authored files.

   • If a file already exists, merge the harness intent into it.
   • Do not overwrite project-specific instructions, scripts, or docs without reading them.

4. Delegate details.

   • Use agents-md-author for AGENTS.md.
   • Use repo-knowledge-base-builder for docs.
   • Use quality-gates-installer for scripts and CI checks.
   • Use local-runtime-harness for env/runtime setup.
   • Use v2 lifecycle skills for deeper security, dependency, docs sync, observability, migration, release, and review workflows.
   • Use feature-state-machine and termination-gatekeeper when the repo needs WIP control or completion evidence.
   • Use project-local-skill-generator after the harness exists to add thin repo-specific .codex/skills without copying plugin skills.

Required Stable Interface

Prefer these repo commands when feasible:

• ./scripts/dev
• ./scripts/lint
• ./scripts/typecheck
• ./scripts/test
• ./scripts/build
• ./scripts/validate
• ./scripts/check-boundaries
• ./scripts/check-docs
• ./scripts/audit-entropy

Optional wrappers should be generated only when backed by repo artifacts or current changed surfaces:

• ./scripts/test-e2e
• ./scripts/click-path-audit
• ./scripts/check-research-evidence
• ./scripts/ci-local

Scripts may be thin wrappers around project-native commands. If a command does not apply, the wrapper should explain why and exit successfully only when that absence is intentional.

Files To Create Or Update

• AGENTS.md
• docs/00-index.md
• docs/development/commands.md
• docs/development/environment.md
• docs/architecture/overview.md
• docs/testing/strategy.md
• docs/quality/code-style.md
• scripts/*
• .github/workflows/ci.yml
• .github/pull_request_template.md
• .codex/skills/*/SKILL.md only when generated by project-local-skill-generator

Validation

• Run the narrowest new wrappers first.
• Run ./scripts/validate after the baseline is complete.
• Check that docs link to real paths and commands.
• Check that generated scripts are executable.

Completion Criteria

• A new agent can answer what the project is, how to run it, how to test it, where code belongs, what patterns to copy, and how to validate changes.
• No generated file contains placeholder TODO text.
• Existing project-specific files are preserved or intentionally merged.
• Multi-step agent work has initialization, continuity, feature-state, or termination guidance when useful.