Harness Engineering Starter

English | 한국어

A starter for setting down project context, decisions, plans, and validation before writing application code.

harness-engineering-starter is a template for projects that have not chosen a product name, technical stack, or repository shape yet. It focuses on giving humans and coding agents the same starting context before implementation begins.

There is no application code in this repository. Product scope, repository structure, technical stack, and deployment target are meant to be decided after cloning this starter into a real project.

At A Glance

Area	Current Value
Purpose	Start new projects with shared context and validation habits
Product scope	TBD after cloning
Technical stack	TBD
Repository shape	TBD
Application code	None yet
Baseline validation	./init.sh
License	MIT
Primary author	hyeonbungi

Current State

• Current repository name: harness-engineering-starter
• Project name after cloning: TBD
• Product or domain: TBD
• Technical stack: TBD
• Repository shape: TBD
• Application code: none
• Baseline validation command: ./init.sh

Who This Is For

• Maintainers starting a new project with coding agents in the loop
• Teams that want project context, decision records, and validation habits before selecting a stack
• Repositories that need an AGENTS.md single source and a Claude Code pointer from day one
• Starter users who prefer explicit TBD fields over guessed product or architecture defaults

Not For

• Projects that need a ready-made web app, API server, CLI, or package scaffold
• Teams that already know their stack and want framework-specific generators
• Repositories that should hide planning, handoff, or agent workflow documents from public view

Repository Map

Path	Purpose
README.md	Default English project entry point
README.ko.md	Korean version of the project entry point
LICENSE	MIT license text and copyright notice
CONTRIBUTING.md	Public contribution guidance for this starter
SECURITY.md	Public security reporting policy for this starter
CHANGELOG.md	Public change log before tagged releases exist
.codex/skills/audit-harness-health/	Product-neutral read-only audit for harness and loop contract drift
.claude/skills	Symlink exposing committed Codex skills to Claude Code
AGENTS.md	Single source of truth for Codex, Claude Code, and general coding agent instructions
CLAUDE.md	Claude Code entrypoint that delegates shared rules to @AGENTS.md
ARCHITECTURE.md	Place to record structure and dependency principles
feature_list.json	Machine-readable tracking for features, documents, and decisions
harness_components.json	Failure-linked harness component, enforcement, cost, and removal ledger
claude-progress.md	Human-readable progress and handoff notes
init.sh	Baseline script that checks required files, document format, and downstream conversion identity
docs/HARNESS.md	Harness operating principles used by this starter
docs/CONTROL_PLANE.md	Authority, per-action risk/authorization, evidence, budget, stop, state, and rollback contract
docs/STATE.md	Durable work-state ownership, transitions, resume, and closeout contract
docs/EVALUATION.md	Producer/evaluator separation, behavioral evidence, thresholds, and calibration
docs/MAINTENANCE.md	Harness component measurement, ablation, consolidation, replacement, and removal
docs/RUNTIME_RESPONSIBILITIES.md	Runtime responsibility, execution isolation/credential grants, tool-result, and artifact contracts
docs/CONTEXT_AND_MEMORY.md	Context trust, source authority/fallback, compaction, memory promotion/lifecycle/portability, and source-preserving synthesis
docs/HARNESS_EVOLUTION.md	Failure evidence, protected surfaces, proposal lineage, promotion, and rollback
docs/LOOP_OPERATIONS.md	Repeated-run contracts, checkpoints, receipts, inner/outer loops, and kill paths
docs/LOOP_ENGINEERING_GUIDE.md	Practical English guide for task instructions, agent authority, evidence, retry, parallel work, and loop adoption
docs/LOOP_ENGINEERING_GUIDE.ko.md	Korean companion to the practical loop-engineering guide
docs/E2E_TESTING.md	Optional GUI journey, fixture, flake, browser-artifact, and CI contract
docs/CONNECTIVITY.md	Skill, CLI, protocol/UI connectivity selection and progressive discovery
docs/IMPLEMENTATION_NOTES.md	Active unknown, decision, deviation, trade-off, question, and evidence notes
docs/UNDERSTANDING.md	Literate explanations, independent ship/learn goals, comprehension checks, and cognitive debt
docs/SKILLS.md	Agent Skills format, failure-based promotion, routing/reachability audits, evaluation, and lifecycle
docs/PLANNED_SKILLS.md	Candidate skill backlog with promotion triggers; entries are not installed requirements
docs/REVIEW.md	Author scope, behavior-preserving refactor evidence, finding severity, decision, and emergency-exception contract
docs/THREAT_MODEL.md	Conditional assets, trust boundaries, abuse paths, mitigations, and residual-risk template
docs/EXPERIMENTS.md	Bounded metric experiments, protected evaluators, negative results, and promotion contract
docs/ENVIRONMENT.md	Account, git, cloud CLI, and agent-execution conventions (template)
docs/EXTENSIONS.md	How to install skills, MCP, subagents, and hooks (team-shared, cross-agent)
docs/REQUIRED_SKILLS.md	Required downstream workflow skills contract (open-pr, new-feature, investigate)
docs/README_STYLE.md	README presentation patterns (badges, alerts, Mermaid, collapsibles)
docs/TECHNICAL_DECISIONS.md	Template entry point for stack and architecture decision summaries
docs/TECHNICAL_DECISION_BACKLOG.md	Template for open, accepted, deferred, and directional technical decisions
docs/VALIDATION.md	Validation ladder from starter baseline to runtime and release checks
docs/SECURITY.md	Security defaults, untrusted CI separation, and scanner coverage/lifecycle evidence
docs/AGENT_BEHAVIOR.md	Rules for how agents handle assumptions, scope, and verification
docs/AGENT_WORKFLOWS.md	Task units, closed/open discovery, orchestration, skills, parallelism, and verification rules
docs/BOOTSTRAP.md	First cleanup steps after copying this starter
docs/CLONE_CLEANUP.md	Cleanup checklist for removing starter-specific history after cloning
docs/README_MIGRATION.md	Checklist for turning the public README into a project-specific README
docs/STARTER_COPY_SIMULATION.md	Evidence template for checking whether the starter copies cleanly
docs/INSTRUCTION_HIERARCHY.md	How to resolve global and scoped instruction files
docs/VISUAL_VALIDATION.md	Visual QA and rendered-evidence selection, capture, coverage, and retention template
docs/OBSERVABILITY.md	Template for runtime signals and agent work traces
docs/PLANS.md	Minimum rules for writing execution plans
docs/product-specs/	Place to define product problem, users, and success criteria
docs/design-docs/	Place to record structural decisions that are hard to reverse
docs/references/	Long references and external link summaries
docs/exec-plans/	Active plans, completed plans, and technical debt notes
docs/generated/	Regenerable agent artifacts
scripts/	Operational checks, including downstream project conversion validation
tests/	Future home for tests after a stack is chosen

Bootstrap

./init.sh

init.sh checks that required documents exist and feature_list.json is valid JSON. Build, test, and lint commands should be added after the technical stack is selected.

How To Start A Real Project

1. Follow docs/BOOTSTRAP.md to choose whether to start with clean Git history or intentionally preserve the starter history, then verify the new origin.
2. Change feature_list.json from the starter identity to the downstream project name and current status.
3. Follow docs/README_MIGRATION.md and replace starter-specific README content with real project information.
4. Follow docs/CLONE_CLEANUP.md, reset starter-specific state, pass scripts/check-project-conversion.sh, and run audit-harness-health once against the downstream truth surfaces.
5. Fill out docs/product-specs/project-foundation.md with the problem statement, target users, and first success criteria.
6. Read docs/LOOP_ENGINEERING_GUIDE.md and use its bounded task contract for the first non-trivial agent run.
7. When repository structure becomes necessary, record the choice and boundaries in ARCHITECTURE.md.
8. When technical choices become concrete, update docs/TECHNICAL_DECISIONS.md and docs/TECHNICAL_DECISION_BACKLOG.md.
9. When a technical stack is chosen, update feature_list.json, init.sh, docs/VALIDATION.md, and docs/QUALITY_SCORE.md together.
10. After the stack is chosen, create the required workflow skills in .codex/skills/ per docs/REQUIRED_SKILLS.md and update WORKFLOW-001 in feature_list.json.
11. When GUI work begins, record product-specific interface requirements in the relevant product specification and connect docs/VISUAL_VALIDATION.md to real checks.

Maintenance Signals

• Baseline validation: ./init.sh
• Contribution guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• Change log: CHANGELOG.md
• Starter copy simulation: docs/STARTER_COPY_SIMULATION.md

Instruction Hierarchy

Root-level AGENTS.md is the default for the whole repository. CLAUDE.md is kept as a Claude Code entrypoint that points to AGENTS.md. If the project grows into multiple apps, packages, libraries, or services, scoped instruction files can be added under narrower paths.

AGENTS.md
CLAUDE.md
path/to/scope/AGENTS.md
path/to/scope/CLAUDE.md

Agents read the files from the repository root down to the target path. A scoped file does not replace the root document wholesale; it only adds or explicitly overrides rules for that scope. Shared agent rules belong in AGENTS.md; CLAUDE.md should stay a pointer plus narrow Claude-only notes.

Operating Rule

Do not paste user prompts directly into project documents. Rewrite them into intent, decisions, non-goals, and validation criteria, then place them in the relevant product spec, execution plan, or decision record.

Author

• Original author and maintainer: hyeonbungi

This starter is maintained as a public project template. Project-specific forks should replace this section only when ownership is intentionally transferred.

License

MIT. See LICENSE.