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, a Claude Code pointer, and clear DESIGN.md hierarchy 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/design-md/SKILL.md	Codex skill for creating, auditing, and validating DESIGN.md files
.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
DESIGN.md	Global design baseline for future GUI work
feature_list.json	Machine-readable tracking for features, documents, and decisions
claude-progress.md	Human-readable progress and handoff notes
init.sh	Baseline script that checks required files and document format
docs/HARNESS.md	Harness operating principles used by this starter
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/README_STYLE.md	README presentation patterns (badges, alerts, Mermaid, collapsibles)
docs/DESIGN_SOURCES.md	Template for future brand assets, fonts, screenshots, and reference models
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/AGENT_BEHAVIOR.md	Rules for how agents handle assumptions, scope, and verification
docs/AGENT_WORKFLOWS.md	Task units, prompt structure, 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/FRONTEND.md	Frontend and scoped DESIGN.md operating notes
docs/VISUAL_VALIDATION.md	Visual QA template for future GUI scaffold work
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/	Future home for operational scripts after a stack is chosen
tests/	Future home for tests after a stack is chosen

Bootstrap

./init.sh

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

How To Start A Real Project

1. Follow docs/README_MIGRATION.md and replace starter-specific README content with real project information.
2. Follow docs/CLONE_CLEANUP.md and reset starter-specific progress, handoff, and feature history.
3. Fill out docs/product-specs/project-foundation.md with the problem statement, target users, and first success criteria.
4. When repository structure becomes necessary, record the choice and boundaries in ARCHITECTURE.md.
5. When technical choices become concrete, update docs/TECHNICAL_DECISIONS.md and docs/TECHNICAL_DECISION_BACKLOG.md.
6. When a technical stack is chosen, update feature_list.json, init.sh, docs/VALIDATION.md, and docs/QUALITY_SCORE.md together.
7. When GUI work begins, revise DESIGN.md for the actual brand and product tone 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 And Design Hierarchy

Root-level AGENTS.md and DESIGN.md are the defaults 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 files can be added under narrower paths.

AGENTS.md
CLAUDE.md
DESIGN.md
path/to/scope/AGENTS.md
path/to/scope/CLAUDE.md
path/to/scope/DESIGN.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.

Read DESIGN.md before creating or changing GUI surfaces. If the global design document is enough, note why. If a scope needs different design rules, add a scoped DESIGN.md there.

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.