name: harness-workflow description: Use when planning or running this C++/MSVC Harness framework: reading AGENTS.md and docs/*.md, discussing implementation scope, creating or updating phases/index.json, phases/{task}/index.json, phases/{task}/stepN.md, or invoking scripts/execute.py for staged Codex execution.

Harness Workflow

Overview

Use this skill to turn a user-approved task into small, self-contained Harness steps that another Codex session can execute reliably. Keep every step grounded in repository docs, C++/MSVC constraints, TDD, and executable acceptance criteria.

Workflow

Read AGENTS.md and relevant files under docs/, especially docs/PRD.md, docs/ARCHITECTURE.md, and docs/ADR.md.
Discuss unresolved product or technical decisions with the user before writing phase files.
When the user asks for an implementation plan, draft steps and get approval before creating files.
Create or update phases/index.json, phases/{task-name}/index.json, and one phases/{task-name}/stepN.md per step.
Run the phase with python scripts/execute.py {task-name} when asked to execute it. Use --push only when the user asks to push.

Step Design Rules

Scope each step to one layer or module. Split steps when multiple modules would otherwise change together.
Make every step self-contained. Do not rely on prior conversation; include all required context and file paths.
Force context gathering. Each step must tell Codex which docs and previous outputs to read before editing.
Specify interfaces and signatures, not full implementations, unless exact code is required for a constraint.
Put core invariants directly in the step: idempotency, numerical conventions, data integrity, API contracts, or other non-negotiables.
Use executable acceptance criteria such as python scripts/validate_workspace.py, not abstract statements.
For C++ behavior changes, require tests first and name the expected test file or test executable.
Name steps with kebab-case slugs such as project-setup, core-types, or solver-validation.

Phase Files

Create or update phases/index.json:

{
  "phases": [
    {
      "dir": "0-mvp",
      "status": "pending"
    }
  ]
}

Create phases/{task-name}/index.json:

{
  "project": "FESA Harness",
  "phase": "<task-name>",
  "steps": [
    { "step": 0, "name": "project-setup", "status": "pending" },
    { "step": 1, "name": "core-types", "status": "pending" },
    { "step": 2, "name": "validation-path", "status": "pending" }
  ]
}

Rules:

project comes from AGENTS.md.
phase matches the task directory name.
steps[].step starts at 0.
Initial status is always pending.
Do not add timestamps when creating files. scripts/execute.py records created_at, started_at, completed_at, failed_at, and blocked_at.

Step Template

# Step {N}: {name}

## 읽어야 할 파일

먼저 아래 파일들을 읽고 프로젝트의 아키텍처와 설계 의도를 파악하라:

- `/AGENTS.md`
- `/docs/ARCHITECTURE.md`
- `/docs/ADR.md`
- {previously created or modified files}

이전 step에서 만들어진 코드를 꼼꼼히 읽고, 설계 의도를 이해한 뒤 작업하라.

## 작업

{Concrete instructions with file paths, interfaces, signatures, and rules.}

## Tests To Write First

- {Exact C++ or Python test file and behavior to add before implementation.}

## Acceptance Criteria

```bash
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py

검증 절차

위 AC 커맨드를 실행한다.
아키텍처 체크리스트를 확인한다:
- ARCHITECTURE.md 디렉토리 구조를 따르는가?
- ADR 기술 스택을 벗어나지 않았는가?
- AGENTS.md CRITICAL 규칙을 위반하지 않았는가?
- C++ 변경에는 관련 테스트가 존재하는가?
결과에 따라 phases/{task-name}/index.json의 해당 step을 업데이트한다:
- 성공: "status": "completed", "summary": "산출물 한 줄 요약"
- 3회 수정 시도 후 실패: "status": "error", "error_message": "구체적 에러 내용"
- 사용자 개입 필요: "status": "blocked", "blocked_reason": "구체적 사유" 후 중단

금지사항

JavaScript/TypeScript/npm fallback을 추가하지 마라. Reason: 이 Harness는 C++/MSVC 전용이다.
기존 테스트를 깨뜨리지 마라.


## Execution And Recovery

Run:

```bash
python scripts/execute.py {task-name}
python scripts/execute.py {task-name} --push

scripts/execute.py creates or checks out feat-{task-name}, injects AGENTS.md and docs/*.md into each prompt, carries completed step summaries forward, retries failed steps up to three times, separates code and metadata commits, and records timestamps.

If a step is error, set it back to pending and remove error_message after fixing the cause. If a step is blocked, resolve blocked_reason, set it back to pending, remove blocked_reason, and rerun.

4.9 KiB Raw Blame History