refine the handoffs for coder and coder-agent. Improve Completion Protocol section in each.

Author: florinc

.github/agents/code-reviewer.agent.md

@@ -13,13 +13,13 @@ handoffs:
   - label: Apply Approved Remarks
     agent: coder
     prompt: |
-      Foreach remark in [REMARKS], apply only those that improve code quality without deviating from the detailed design for issue #{issue-id}
-    send: false
+      Foreach remark in report at [REVIEW_REPORT_PATH], apply only those that improve code quality without deviating from the detailed design for issue #{issue-id}
+    send: true
   - label: Fix Failing Tests
     agent: coder
     prompt: |
-      Foreach failing test in [TESTS], fix the implementation code to build and to make the tests pass for issue #{issue-id}
-    send: false
+      Foreach failing test in [TESTS_LIST], fix the implementation code to build and to make the tests pass for issue #{issue-id}
+    send: true
 ---
 
 # Code Reviewer Agent
@@ -47,29 +47,6 @@ This agent does NOT modify code — it produces structured review feedback.
 - Every remark must explain **what** is wrong and **why**
 - Suggest a fix direction without writing full implementation code
 
-## Input Variables
-- **issueId** (required): GitHub issue number — extracted via `#(\d+)`
-- **fileList** (required): List of changed files to review (provided in prompt)
-- **deviations** (optional): Deviations reported by coder (`none` or list)
-
-## Prepared Prompts
-
-```
-@code-reviewer Review the implementation for issue #[NUMBER]
-  Files: [FILE-LIST]
-  Deviations: [DEVIATIONS-OR-NONE]
-```
-
-```
-@code-reviewer Review only architecture compliance for issue #[NUMBER]
-  Files: [FILE-LIST]
-```
-
-```
-@code-reviewer Review only unit tests for issue #[NUMBER]
-  Files: [FILE-LIST]
-```
-
 ## Review Dimensions
 
 The review covers five dimensions in order. Each dimension produces remarks categorized by severity.
@@ -219,17 +196,45 @@ In case of not being able to use the skill, report a error and produce a simple
 - Does NOT run build or tests — relies on status provided by coder or reads existing results
 - Does NOT review design documents — that is done by architect and detailed-designer
 
-## Error Recovery
+## Completion Protocol
+
+After completing all review dimensions, output this block verbatim before triggering any handoff:
+
+```review-summary
+issue-id: {GitHub issue number}
+review-dimensions: {comma-separated: design-conformance | architecture | test-quality | code-quality}
+build-status: {PASS | FAIL | NOT_VERIFIED}
+test-status: {PASS | FAIL | NOT_VERIFIED}
+verdict: {APPROVED | APPROVED_WITH_REMARKS | REJECTED}
+remarks-count: {number of remarks, 0 if none}
+review-report-path: {relative path to the generated review report}
+failing-tests-count: {number of failing tests, 0 if none}
+failing-tests-list: {comma-separated list of failing tests, or NONE}
+files-reviewed: {comma-separated relative paths}
+deviations-from-design: {description or NONE}
+next-steps: {brief description of next steps}
+handoff-to: {agent-name | HUMAN}
+```
 
-**Missing design document:** Flag as 🔴 BLOCKER. Review what is possible with available documents and note reduced confidence.
 
-**File in list not found:** Flag as 🔴 BLOCKER. Note the missing file and proceed with remaining files.
+## Input Variables
+- **issueId** (required): GitHub issue number — extracted via `#(\d+)`
+- **fileList** (required): List of changed files to review (provided in prompt)
+- **deviations** (optional): Deviations reported by coder (`none` or list)
 
-**Ambiguous design specification:** Flag as 🟡 WARNING. State the ambiguity and how the implementation interpreted it.
+## Prepared Prompts
 
-**No file list provided:** Ask for the file list. Do not guess.
+```
+@code-reviewer Review the implementation for issue #[NUMBER]
+    Context: Mode=[IMPLEMENTATION_MODE], Files=[FILE-LIST], Build=[BUILD-STATUS], Tests=[TEST-STATUS], Deviations=[DEVIATIONS-OR-NONE]
+    Verify implementation matches detailed design and architectural constraints.
+```
+
+```
+@code-reviewer Review only architecture compliance for issue #[NUMBER]
+```
 
-## Progress Reporting
-- Announce each major step: "Reading design documents...", "Reviewing contracts...", "Checking architecture compliance..."
-- Report per-dimension progress for large reviews
-- If review requires clarification, ask ONE specific question before proceeding
+```
+@code-reviewer Review only unit tests for issue #[NUMBER]
+  Files: [FILE-LIST]
+```

.github/agents/coder.agent.md

@@ -130,7 +130,24 @@ Dependency check: ✅ {verification}
 **Mode 2:** Load skill → List scenarios → Write tests → Run → Commit
 
 ### 5. Build & Verify
-`dotnet build` → `dotnet test` → report results
+
+**Run in sequence:**
+1. `dotnet build {solution-file}`
+2. `dotnet test {solution-file} --no-build`
+
+**On failure — Self-Correction Loop (max 3 iterations each):**
+
+| Failure Type | Diagnose | Fix |
+|---|---|---|
+| Compilation | Missing using/type mismatch/interface violation | Minimal targeted fix only |
+| Dependency | Missing registration/circular ref | Fix wiring, do not restructure |
+| Nullable | Null ref/annotation mismatch | Add guard or annotation |
+| Test logic | Assertion/setup/async issue | Fix impl or test, not both |
+
+- Apply build fix → rebuild → repeat up to 3 times.
+- Apply test fix → retest → repeat up to 3 times.
+- Do NOT expand scope, refactor, or modify pre-existing failing tests.
+- On 3rd failure: STOP, document all attempts, request human intervention — do not trigger handoff.
 
 ### 6. Validate
 
@@ -149,24 +166,25 @@ Dependency check: ✅ {verification}
 
 **After 3 failed fix attempts:** STOP, document all attempts, request human intervention.
 
-## Response Format
-
-```
-Mode: IMPLEMENT|UNIT TESTS (Simple|Complex Slice X/Y)
-Issue #{id} — {description}
-
-Summary: {2-3 lines}
-Design Deviations: NONE | {list with justification}
-
-Files Changed:
-Commit: "{message}"
-  - {path} ({description})
+## Completion Protocol
 
-Build: ✅|❌ ({errors} errors, {warnings} warnings)
-Tests: ✅|❌ ({passed}/{total} passed)
+Output this HANDOFF block verbatim before triggering any handoff:
 
-Verification: ✅ Critical rules | ✅ Architecture | ✅ Scope
-Next Step: {what follows}
+```
+HANDOFF_START
+issue-id #{id}
+issue-description: {description}
+implementation-mode: IMPLEMENT|UNIT TESTS (Simple|Complex Slice X/Y)
+file-list: {comma-separated relative paths of all created or modified files}
+build-status: PASS|FAIL ({errors} errors, {warnings} warnings)
+build-iterations: {number of build attempts}
+test-status: PASS|FAIL ({passed}/{total} passed)
+test-iterations: {number of test fix attempts}
+design-deviations: NONE | {list with justification}
+commits: "{comma-separated list of commits. Format: '{commit-id}: {message}', {commit-id}: {message}'}"
+next-steps: {brief description of next steps}
+handoff-to: {agent-name | HUMAN}
+HANDOFF_END
 ```
 
 ## Input Variables
@@ -178,7 +196,20 @@ Next Step: {what follows}
 
 ```
 @coder Implement issue #[NUMBER] following the detailed design specifications
+```
+
+```
 @coder [Mode: Implement] Issue #[NUMBER] - implement [FEATURE] from detailed design
+```
+
+```
 @coder [Mode: Unit Tests] Issue #[NUMBER] - create tests for implemented code
+```
+
+```
 @coder Foreach remark in [REMARKS], apply only those that improve code quality without deviating from the detailed design for issue #[NUMBER]
-@coder Foreach failing test in [TESTS], fix the implementation code to build and to make the tests pass for issue #[NUMBER]a
+```
+
+```
+@coder Foreach failing test in [TESTS], fix the implementation code to build and to make the tests pass for issue #[NUMBER]
+```