From 18296a1944532c7db8ee8953d2257f9d0644ae08 Mon Sep 17 00:00:00 2001 From: "KOKO\\Mimi" Date: Wed, 12 Aug 2026 15:27:32 +0900 Subject: [PATCH] docs: align Harness step execution guidance --- .agents/skills/harness/SKILL.md | 30 ++++++++++++++++++-- .codex/skills/fesa-cpp-msvc-tdd/SKILL.md | 36 ++++++++++++++++-------- docs/SOLVER_AGENT_DESIGN.md | 26 ++++++++++++++++- docs/implementation-plans/README.md | 32 +++++++++++++++++++-- 4 files changed, 107 insertions(+), 17 deletions(-) diff --git a/.agents/skills/harness/SKILL.md b/.agents/skills/harness/SKILL.md index 49519ee..0f5627b 100644 --- a/.agents/skills/harness/SKILL.md +++ b/.agents/skills/harness/SKILL.md @@ -7,6 +7,23 @@ description: Use when planning agentic implementation phases, creating phases/in 이 프로젝트는 Harness 프레임워크를 사용한다. 아래 워크플로에 따라 작업한다. +## 필수 읽기와 실행 소유권 + +계획, phase 파일 생성, 또는 Executor 실행 전 `AGENTS.md`, +`docs/HARNESS.md`, `docs/HARNESS_WORKFLOW.md`를 읽는다. Step을 구현할 때는 +`.codex/hooks.json`, phase index, Executor가 선택한 현재 `stepN.md`도 읽는다. + +| 책임 | 소유자 | +|---|---| +| branch, pending Step 선택, retry, timestamps, commits, advancement | Executor (`scripts/execute.py`) | +| Executor-selected current Step의 작업과 해당 Step의 `status` 및 `summary` / `error_message` / `blocked_reason` payload | Implementation Agent | +| PreToolUse interception과 Stop whole-project validation | `.codex/hooks.json`으로 등록된 hooks | + +Hook은 자동으로 작동한다. `scripts/hooks/pre_tool_use.py` 또는 +`scripts/hooks/stop_validation.py`를 수동 실행해 등록된 hook의 대체물로 사용하지 않는다. +계획 승인은 Executor 실행 권한이 아니다. `scripts/execute.py`는 별도의 명시적 사용자 +요청에서만 실행한다. + ## A. 탐색 `AGENTS.md`와 `docs/` 하위 문서(PRD, ARCHITECTURE, ADR 등)를 읽고 프로젝트의 기획, @@ -42,6 +59,9 @@ description: Use when planning agentic implementation phases, creating phases/in 사용자가 초안을 승인한 후에만 다음 파일을 생성한다. +Planning Agent는 초안을 만들고 승인받아 planning files만 materialize한다. planning +Agent는 Step을 선택하거나 실행하지 않는다. + ### D-1. `phases/index.json` 여러 task를 관리하는 top-level 인덱스다. 이미 존재하면 `phases` 배열에 새 항목을 @@ -136,10 +156,11 @@ MSBuild.exe MyProject.sln /m /p:Configuration=Debug /p:Platform=x64 1. Acceptance Criteria command를 실행한다. 2. ARCHITECTURE 디렉터리 구조를 따르는지 확인한다. 3. ADR 기술 스택과 `AGENTS.md` CRITICAL 규칙을 확인한다. -4. 결과에 따라 task index의 해당 step을 갱신한다. +4. 결과에 따라 task index의 Executor-selected current Step만 갱신한다. - 성공: `status`를 `completed`로 바꾸고 한 줄 `summary` 기록 - - 수정 3회 후 실패: `status`를 `error`로 바꾸고 `error_message` 기록 + - 실행을 계속할 수 없는 오류: `status`를 `error`로 바꾸고 `error_message` 기록 - 사용자 개입 필요: `status`를 `blocked`로 바꾸고 `blocked_reason` 기록 후 중단 + - retry, timestamp, commit, 다음 Step 선택과 advancement는 Executor가 기록한다. ## 금지사항 @@ -149,6 +170,11 @@ MSBuild.exe MyProject.sln /m /p:Configuration=Debug /p:Platform=x64 ## E. 실행 +별도의 명시적 사용자 요청이 있고 approved planning files가 materialize된 경우에만 +Executor를 시작한다. Implementation Agent는 Executor가 선택한 current `stepN.md` 하나만 +`RED -> observed failure -> minimal GREEN -> focused/full VERIFY` 순서로 수행하고 다음 +Step을 시작하지 않는다. + ```bash python scripts/execute.py {task-name} python scripts/execute.py {task-name} --push diff --git a/.codex/skills/fesa-cpp-msvc-tdd/SKILL.md b/.codex/skills/fesa-cpp-msvc-tdd/SKILL.md index f6f2937..00011a8 100644 --- a/.codex/skills/fesa-cpp-msvc-tdd/SKILL.md +++ b/.codex/skills/fesa-cpp-msvc-tdd/SKILL.md @@ -14,26 +14,38 @@ Read these first: - `AGENTS.md` - `docs/SOLVER_AGENT_DESIGN.md` - `docs/implementation-plans/README.md` +- `docs/HARNESS.md` +- `docs/HARNESS_WORKFLOW.md` - `docs/build-test-reports/README.md` - `docs/corrections/README.md` - `docs/implementation-plans/-implementation-plan.md` - Related requirements, formulation, numerical review, I/O definition, and reference model documents +For Harness implementation, also read `.agents/skills/harness/SKILL.md`, +`.codex/hooks.json`, the materialized phase indexes, and the Executor-selected current +`stepN.md`. + ## Workflow 1. For planning, use the project-local `harness` skill to convert upstream documents into a - user-approved multi-Step draft. Create `phases/` files only after approval and never run the - executor without a separate explicit request. -2. For implementation, follow `RED -> GREEN -> VERIFY`. -3. RED: write the planned unit, integration, parser/I/O, or reference-comparison test first. -4. RED: run the targeted test and verify the expected failure before production code. -5. GREEN: implement the minimum C++17/MSVC-compatible code needed for the task. -6. VERIFY: run the targeted command, then the full MSVC build/test commands resolved from `.harness/config.json` or the Harness defaults. -7. For C++ production changes, require a related C++ test file in the same patch or already present. -8. Treat PreToolUse as a test-file-existence guardrail, not proof that RED was observed. Record the RED and GREEN commands and results in the implementation report. -9. Let Stop perform the final whole-project MSVC build/test before the Step ends. -10. For failure triage, classify as `configure | compile | link | test | reference-comparison | harness | environment | upstream-contract`. -11. Fix implementation-owned failures only and keep changes traceable to the implementation plan. + user-approved multi-Step draft. Materialize only planning files after approval; planning never + selects or runs a Step. Run `scripts/execute.py` only after a separate explicit user request. +2. For implementation, require the approved plan, materialized phase files, and the + Executor-selected current `stepN.md`. Do not start another pending Step. +3. Execute the current Step as `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`. + Update only its Codex-owned `status` plus `summary`, `error_message`, or `blocked_reason`. + The Executor owns branch, pending-Step selection, retry, timestamps, commits, and advancement. +4. Hooks are automatic through `.codex/hooks.json`: PreToolUse intercepts before edits and Stop + performs whole-project validation. Do not manually run their entry points as substitutes. +5. RED: write the planned unit, integration, parser/I/O, or reference-comparison test first. +6. RED: run the targeted test and verify the expected failure before production code. +7. GREEN: implement the minimum C++17/MSVC-compatible code needed for the task. +8. VERIFY: run the targeted command, then the full MSVC build/test commands resolved from `.harness/config.json` or the Harness defaults. +9. For C++ production changes, require a related C++ test file in the same patch or already present. +10. Treat PreToolUse as a test-file-existence guardrail, not proof that RED was observed. Record the RED and GREEN commands and results in the implementation report. +11. Let Stop perform the final whole-project MSVC build/test before the Step ends. +12. For failure triage, classify as `configure | compile | link | test | reference-comparison | harness | environment | upstream-contract`. +13. Fix implementation-owned failures only and keep changes traceable to the implementation plan. ## Output Contract diff --git a/docs/SOLVER_AGENT_DESIGN.md b/docs/SOLVER_AGENT_DESIGN.md index 985618f..cd4d399 100644 --- a/docs/SOLVER_AGENT_DESIGN.md +++ b/docs/SOLVER_AGENT_DESIGN.md @@ -18,6 +18,21 @@ - 모든 기능은 tolerance 기준을 명시하고, 기준을 만족할 때만 배포 후보가 된다. - Harness 운영은 `docs/HARNESS_WORKFLOW.md`의 계획, 독립 Step 실행, PreToolUse/Stop 검증 계층을 따른다. +## Harness Step 실행 계약 + +계획과 구현 Agent는 작업 전 `docs/HARNESS.md`와 `docs/HARNESS_WORKFLOW.md`를 읽는다. +Implementation Planning Agent는 multi-Step 초안을 사용자에게 승인받은 뒤 planning files만 +materialize하며 Step을 선택하거나 실행하지 않는다. Executor는 별도의 명시적 사용자 요청으로 +`scripts/execute.py`를 실행할 때 branch, pending Step 선택, retry, timestamps, commits, Step +advancement와 phase status를 소유한다. + +Implementation Agent는 approved plan, materialized phase files, Executor-selected current +`stepN.md`만 사용해 `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`를 완료하고 +다음 Step을 시작하지 않는다. Agent가 쓸 수 있는 Harness metadata는 current Step의 `status`와 +`summary`, `error_message`, `blocked_reason` payload뿐이다. `.codex/hooks.json`이 PreToolUse +interception과 Stop whole-project validation을 자동 실행하므로 hook entry point를 수동 실행해 +대체하지 않는다. 세부 schema와 recovery 절차는 `docs/HARNESS_WORKFLOW.md`를 따른다. + ## 전체 Agent 구성 ### Coordinator Agent @@ -159,19 +174,28 @@ Directory와 filename은 제공된 값을 그대로 사용한다. Reference Mode 필수 절차: - 구현 계획 요청에서 project-local `$harness` skill을 사용한다. +- `docs/HARNESS.md`와 `docs/HARNESS_WORKFLOW.md`를 읽고 multi-Step 초안만 사용자에게 + 제시한다. - 한 Step은 하나의 layer/module만 다루고 각 Step에 prerequisite file, TDD RED/GREEN/VERIFY, 정확한 MSVC/CMake/CTest command와 금지사항을 포함한다. - Step 초안을 먼저 사용자에게 제시한다. 승인 전에는 `phases/` 파일을 생성하지 않는다. -- Harness executor 실행은 별도 사용자 요청이 있을 때만 수행한다. +- 승인 후에는 planning files만 materialize하고 Step 선택/실행은 하지 않는다. Harness executor + 실행은 별도 사용자 요청이 있을 때만 수행한다. ### Implementation Agent C++ 코드를 구현하는 Agent이다. 책임: +- `docs/HARNESS.md`, `docs/HARNESS_WORKFLOW.md`, materialized phase files와 + Executor-selected current `stepN.md`를 읽고 현재 Step만 수행한다. - 테스트를 먼저 작성하고 실패를 확인한다. - 정식화와 I/O schema에 맞춰 최소 구현을 작성한다. - C++17 이상, MSVC, CMake, CTest 환경에서 동작하도록 구현한다. - 불필요한 일반화나 speculative abstraction을 피한다. +- current Step의 `status`와 `summary`, `error_message`, `blocked_reason`만 기록한다. + branch, retry, timestamp, commit, advancement는 Executor에 맡긴다. +- `.codex/hooks.json`으로 자동 등록된 PreToolUse와 Stop을 사용하며 hook script를 수동 + 검증 대체물로 실행하지 않는다. 주요 산출물: - C++ source/header 변경 diff --git a/docs/implementation-plans/README.md b/docs/implementation-plans/README.md index 1ffe944..7ad380c 100644 --- a/docs/implementation-plans/README.md +++ b/docs/implementation-plans/README.md @@ -5,7 +5,21 @@ Implementation Planning Agent는 승인된 요구조건, 연구 브리프, 정식화, 수치 리뷰, I/O 정의와 lightweight reference-case inventory를 C++/MSVC 구현 전 TDD 작업계획으로 변환한다. Project-local `$harness`를 사용해 multi-Step 초안을 먼저 제시하고 사용자가 -승인한 뒤에만 `phases/` planning files를 생성한다. +승인한 뒤에만 `phases/` planning files를 생성한다. 계획과 구현 전에 +`docs/HARNESS.md`와 `docs/HARNESS_WORKFLOW.md`를 읽는다. + +## Harness 실행 handoff + +Planning Agent는 draft -> explicit user approval -> planning files만 수행하며 Step을 +선택하거나 실행하지 않는다. 별도의 명시적 사용자 요청이 있어야 Executor +(`scripts/execute.py`)가 branch, pending Step, retry, timestamps, commits, advancement와 phase +status를 소유한다. + +Implementation Agent는 approved plan, materialized phase indexes, Executor-selected current +`stepN.md` 하나만 사용한다. current Step에서 `RED -> observed failure -> minimal GREEN -> +focused/full VERIFY`를 완료하고 다음 Step을 시작하지 않는다. Agent는 current Step의 `status` +및 `summary`, `error_message`, `blocked_reason` payload만 쓴다. `.codex/hooks.json`의 +PreToolUse와 Stop은 자동으로 실행되며 hook entry point를 수동 실행해 대체하지 않는다. 기본 파일명은 `docs/implementation-plans/-implementation-plan.md` 형식을 사용한다. 각 문서는 Implementation Agent가 먼저 작성해야 할 실패 테스트, 최소 구현 순서, CMake/CTest 등록 계획, acceptance traceability를 제공해야 한다. @@ -21,7 +35,9 @@ Implementation Planning Agent는 승인된 요구조건, 연구 브리프, 정 - `.harness/config.json` 또는 자동 감지 기본값에서 해석되는 MSVC build/test 명령과 feature-specific command를 명시한다. - 한 Step을 하나의 layer/module로 제한하고 prerequisite files, RED/GREEN/VERIFY, exact acceptance commands와 구체적 금지사항을 포함한다. -- 사용자 승인 전에는 `phases/` 파일을 만들지 않고, 별도 요청 없이는 `scripts/execute.py`를 실행하지 않는다. +- 사용자 승인 전에는 `phases/` 파일을 만들지 않고, 승인 뒤에도 planning files만 + materialize한다. 별도 요청 없이는 `scripts/execute.py`를 실행하지 않으며 Step을 + 선택하거나 실행하지 않는다. 수행하지 않는다: - C++ 코드를 구현하지 않는다. @@ -146,6 +162,18 @@ MSVC build/test를 다시 확인하며, 구현 보고서의 RED 실패 증거를 User approval is required before materializing this draft under `phases/`. +## Executor Handoff + +- Executor authorization: separate explicit user request for `scripts/execute.py`. +- implementation input: approved plan, materialized phase indexes, and Executor-selected current + `stepN.md`. +- implementation recipe: `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`. +- metadata ownership: Implementation Agent records only the current Step `status` plus `summary`, + `error_message`, or `blocked_reason`; Executor records branch, pending-Step selection, retry, + timestamps, commits, advancement, and phase status. +- hooks: `.codex/hooks.json` automatically invokes PreToolUse and Stop; never manually run hook + entry points as substitutes. + ## Open Issues - ```