Harness Engineering and Orchestrator

Overview

Harness Engineering and Orchestrator is an orchestration skill, not just a repo generator.

Its job is to turn an idea or an existing codebase into a controlled delivery loop with:

```
docs/PRD.md
```
```
docs/ARCHITECTURE.md
```
a milestone and task plan in
```
docs/PROGRESS.md
```
a runnable scaffold with Harness runtime files
validated implementation until the project reaches
```
COMPLETE
```

Changes in v1.3.0

Reduced
```
SKILL.md
```
to the operating contract instead of a full manual

Centered the workflow on

PRD -> Architecture -> Milestone -> Task -> Validation

Moved detailed prompts and appendix material into
```
references/
```
Added
```
agents/openai.yaml
```
so the skill has explicit UI metadata

Primary Review Surface

Keep user review focused on these artifacts unless the user asks for more:

```
docs/PRD.md
```
for scope, outcomes, and milestone definition
```
docs/ARCHITECTURE.md
```
for system shape, constraints, and dependency direction
```
docs/PROGRESS.md
```
for milestone and task status

Everything else is supporting or machine-owned:

```
.harness/state.json
```
and
```
.harness/*.ts
```
```
docs/adr/
```
```
docs/gitbook/
```
```
AGENTS.md
```
and
```
CLAUDE.md
```
CI/CD, templates, README, and generated scaffolding files

Detailed secondary artifact notes live in references/skill-appendix.md.

Orchestrator Contract

When this skill runs, act as the Orchestrator.

Ask one question at a time during discovery
Keep runtime state, documents, backlog, and gates synchronized
Treat
```
docs/PRD.md
```
and
```
docs/ARCHITECTURE.md
```
as the only planning source of truth
Advance phases through the runtime (
```
bun harness:advance
```
or the underlying
```
.harness/*
```
scripts); do not fake completion
```
bun harness:autoflow
```
may only advance after the current phase's required outputs exist on disk; missing scaffold/runtime artifacts must keep the workflow on the current phase
If the user adds scope outside the current task or milestone, write it back into the PRD first, then run
```
bun harness:sync-backlog
```
before any implementation starts
Read only the agent or reference file needed for the current step
Default the conversation to milestone and task progress, not long file inventories

For the runtime state model and phase gate discipline, see agents/orchestrator.md.

Pacing Discipline

CRITICAL — these rules override all other guidance when there is a conflict:

One phase per response. Complete only the current phase. Never combine work from two phases in a single response.
One question per response during Discovery. Each discovery question (Q0–Q9) must be its own message. End your response after asking the question. Wait for the user's answer before continuing.
STOP at every phase boundary. After completing a phase's work, you MUST:
- Present a completion summary for that phase
- Ask the user to confirm before advancing
- STOP. Do not call
```
bun harness:advance
```
  until the user confirms.
Verify before advancing. Run the phase gate validation command and show the result before asking to advance.
Never auto-advance through multiple phases. Even if a gate passes, wait for user acknowledgment.

Mandatory Checkpoints

After completing...	You must STOP and get confirmation before...
Discovery (Q0–Q9)	Entering Market Research
Market Research summary	Entering Tech Stack
Each tech stack layer	Asking the next layer
All stack decisions confirmed	Entering PRD & Architecture
PRD + Architecture drafts	Entering Scaffold
Scaffold verification checklist	Entering EXECUTING

Runtime Path

text

DISCOVERY -> MARKET_RESEARCH -> TECH_STACK -> PRD_ARCH -> SCAFFOLD -> EXECUTING -> VALIDATING -> COMPLETE

Use the standard path unless the project starts from an existing codebase.

Existing Codebase Hydration

For existing repos, run from inside the target directory:

bash

bun <path-to-skill>/scripts/harness-setup.ts --isGreenfield=false --skipGithub=true

The setup script infers project metadata from

package.json

README.md

, and

docs/

, then generates all harness runtime files while preserving existing files. The project typically enters at

SCAFFOLD

phase.

After hydration, adapt

package.json

scripts if needed — the gate checks expect

typecheck

format:check

, and

build

scripts to exist and pass.

Regardless of the starting point, the project must end up with:

```
docs/PRD.md
```
```
docs/ARCHITECTURE.md
```
Harness runtime files
```
.harness/state.json
```
passing phase gates

Phase 0: Discovery

Goal: capture just enough product, delivery, and design context to enter the research or stack phase cleanly.

Ask exactly one question per response. End your response after the question. Do not ask the next question until the user answers. Persist each answer immediately before asking the next question.

Capture at minimum:

starting point: greenfield or existing codebase
project name and concept
target users and problem
goals, time frame, and success metrics
project type or combination of types
AI needs, if any
feature modules relevant to the selected project type
team size
visual design language for UI projects

The detailed question script lives in references/discovery-questionnaire.md.

Phase 1: Market Research

Use this phase for greenfield projects or when the user wants current market input.

Deliver:

a short competitor and market summary
current technology signals that affect stack choice
useful open-source references
a brief statement of market differentiation

If the user explicitly skips research, record the skip in state instead of blocking the workflow.

For execution details, see agents/market-research.md.

Phase 2: Tech Stack

Negotiate the stack one layer at a time.

Rules:

recommend first, then explain
present the main alternative(s)
wait for confirmation before moving to the next layer
record every confirmed decision
generate ADRs when a material architecture choice is locked in

End this phase with a confirmed stack table or structured object.

Use:

agents/tech-stack-advisor.md
references/stacks.md
```
references/stacks/
```
for variant-specific stack notes

Phase 3: PRD and Architecture

This phase creates the planning contract for the rest of the project.

Required outputs:

```
docs/PRD.md
```
```
docs/ARCHITECTURE.md
```

Support outputs may also be initialized here if needed by the scaffold:

```
AGENTS.md
```
and synchronized
```
CLAUDE.md
```
```
docs/adr/
```
```
docs/gitbook/
```

Rules:

the PRD defines milestones, requirements, acceptance criteria, and out-of-scope items
the Architecture document defines structure, dependency direction, data flow, error handling, testing strategy, and worktree strategy
if the milestone count is too large, reduce to a clear MVP cut before execution starts

The user review surface here is the PRD, the Architecture, and the resulting milestone shape.

Use:

agents/prd-architect.md
references/prd-template.md
references/architecture-template.md

Phase 4: Scaffold

Goal: produce a clean, runnable baseline that matches the confirmed stack and documents.

The scaffold should include, as required by the project type:

monorepo workspace placeholders and Harness program files
Harness runtime files
```
AGENTS.md
```
and
```
CLAUDE.md
```
docs skeletons
CI/CD
baseline Harness program and test structure
scripts needed to enter
```
EXECUTING
```

Do not bootstrap product frameworks such as Next.js, Tauri, or platform SDKs during Phase 4. Those are implemented later inside milestone tasks. What matters here is that the Harness program, orchestration runtime, monorepo shape, and milestone/task flow are ready.

Use:

agents/scaffold-generator.md
agents/execution-engine.md for stack-specific scaffold details
scripts/harness-setup.ts

Phase 5: Execution

All real delivery happens here.

Milestone Contract

Each PRD milestone becomes one execution milestone
Each execution milestone gets its own branch and worktree
Milestone completion requires code, docs, and gate validation to agree
The user should mainly see milestone status, risk, and MVP progress

Task Contract

Each task maps back to PRD acceptance criteria
Each task has a clear Definition of Done
Target size: usually completable within 4 hours and about 5 touched files or fewer
Each task lands as exactly one Atomic Commit

Task types:

Type	Purpose	Required output
`TASK`	Standard implementation work	Code + validation + Atomic Commit
`SPIKE`	Time-boxed investigation	Decision record in ADR / LEARNING

Execution Loop

Read the current
```
PRD
```
,
```
ARCHITECTURE
```
,
```
PROGRESS
```
, and runtime state
Confirm the current milestone and task
Run
```
bun .harness/orchestrator.ts
```
to determine which agent to dispatch next
UI task routing:
- Frontend Designer produces
```
docs/design/{milestone-id-lowercase}-ui-spec.md
```
  (e.g.
```
m1-ui-spec.md
```
  )
- Execution Engine implements the task
- Design Reviewer validates:
```
bun .harness/orchestrator.ts --review
```
- Commit message includes
```
Design Review: ✅
```
Non-UI task routing:
- Execution Engine implements the task
- Code Reviewer validates:
```
bun .harness/orchestrator.ts --code-review
```
- Commit message includes
```
Code Review: ✅
```
Run the task checklist and
```
bun harness:validate --task
```
Create one Atomic Commit
Update
```
docs/PROGRESS.md
```
and runtime state
Continue only when the task gate passes

Milestone Merge

When all tasks in a milestone are complete (status: REVIEW):

Complete the Milestone Review Checklist (GitBook, CHANGELOG, API docs)
From the main worktree, run
```
bun harness:autoflow
```
to auto-compact and merge the REVIEW milestone
Manual fallback: run
```
bun harness:merge-milestone M[N]
```
from the main worktree; milestone compact now runs inside the merge command
If more milestones remain in the same delivery version, autoflow continues there
If the current delivery version is fully merged, the workflow stops at deploy review; update the main PRD / Architecture, then run
```
bun harness:stage --promote V[N]
```
Only use
```
bun harness:advance
```
after the final delivery version is fully merged and no deferred stages remain

Progress Reporting

Report progress using:

current milestone
current task
checklist result
percentage or task count complete
next task
blocker, if any

Keep these reports concise. The default report is milestone and task progress, not a full file changelog.

For the deeper execution rules, read:

agents/execution-engine.md
agents/frontend-designer.md
agents/design-reviewer.md
references/worktree-workflow.md

Phase 6: Validation and Closeout

Run final validation only after the milestone ledger is actually complete.

Required outcomes:

all required milestone gates pass
final phase validation passes
the PRD and shipped scope still match
public-facing closeout artifacts are generated as needed

The final user-facing completion report should summarize:

completed milestones
remaining backlog or deferred scope
validation result / Harness score
recommended next work

Use agents/harness-validator.md and agents/context-compactor.md.

Minimum Guardrails

These are the non-negotiable rules that stay active throughout the workflow:

```
docs/PRD.md
```
is the source of truth for implementation scope
feature work does not land directly on
```
main
```
or
```
master
```

dependency direction is

types -> config -> lib -> services -> app

no secrets or
```
.env
```
material enter the repo
blocking forbidden patterns must be removed before milestone completion
UI tasks must go through the design loop
```
AGENTS.md
```
and
```
CLAUDE.md
```
stay identical
files that exceed the project size limit should be split or rewritten quickly

Full gate and guardian details live in references/gates-and-guardians.md.

Guardians G2-G10 are automatically enforced by git hooks, Claude Code hooks, and Codex CLI hooks installed during scaffold. See references/hooks-guide.md

Read Only What You Need

Prefer progressive disclosure:

Discovery prompts: references/discovery-questionnaire.md
State model and phase orchestration: agents/orchestrator.md
Market research workflow: agents/market-research.md
Stack negotiation: agents/tech-stack-advisor.md
PRD / Architecture generation: agents/prd-architect.md
Scaffold completion: agents/scaffold-generator.md
Execution details: agents/execution-engine.md
Validation and score: agents/harness-validator.md
Code quality review: agents/code-reviewer.md
Supporting artifacts and repo inventory: references/skill-appendix.md
HTML prototype guide: references/html-prototype-guide.md
Hooks guide: references/hooks-guide.md

Expected User Interaction

Keep checkpoints simple and predictable:

confirm the discovery answers
confirm the stack
review the PRD
review the Architecture
confirm the milestone and task breakdown or the MVP cutoff
review milestone-level progress or blockers

If the user only wants to review milestone, task, architecture, and PRD, default to exactly that.

Command Surface

Common runtime commands:

bash

bun harness:advance                         # Advance to the next phase (runs gate checks)
bun harness:validate --phase <PHASE>        # Validate a specific phase gate
bun harness:validate --task T[ID]           # Validate a specific task
bun harness:validate --milestone M[N]       # Validate a specific milestone
bun harness:guardian                        # Run guardian scan
bun harness:compact                         # Generate context snapshot
bun .harness/orchestrator.ts                # Dispatch the next agent (status/next also work)
bun .harness/orchestrator.ts --review       # Dispatch Design Reviewer (UI tasks)
bun .harness/orchestrator.ts --code-review  # Dispatch Code Reviewer (non-UI tasks)
bun harness:merge-milestone M[N]           # Merge a REVIEW milestone into main, clean up worktree
bun harness:hooks:install                   # Restore local Harness files, then re-install git hooks, Claude Code settings, and Codex CLI config
bun harness:add-surface --type=<TYPE>       # Add a new project surface (e.g. api, android-app)
bun harness:audit                           # Full audit: guardians, phase gate, workspace, docs drift
bun harness:sync-docs                       # Synchronize managed documentation files

harness-engineering-orchestrator

NPX Install

Tags

SKILL.md Content

Harness Engineering and Orchestrator

Overview

Changes in v1.3.0

Primary Review Surface

Orchestrator Contract

Pacing Discipline

Mandatory Checkpoints

Runtime Path

Existing Codebase Hydration

Phase 0: Discovery

Phase 1: Market Research

Phase 2: Tech Stack

Phase 3: PRD and Architecture

Phase 4: Scaffold

Phase 5: Execution

Milestone Contract

Task Contract

Execution Loop

Milestone Merge

Progress Reporting

Phase 6: Validation and Closeout

Minimum Guardrails

Read Only What You Need

Expected User Interaction

Command Surface