DOC23_REPROMPT_SYSTEM_ADDENDUM (1).md
Current Specs/DOC23/DOC23_REPROMPT_SYSTEM_ADDENDUM (1).md
ELNOR REPO READER TEXT MIRROR
Original path: Current Specs/DOC23/DOC23_REPROMPT_SYSTEM_ADDENDUM (1).md
Source repo: /Users/OpenClaw1/Elnor/Elnor Specs
Git branch: main
Git commit: dbaa25962edc11ab30e8d4ca1715f9ae5bf77331
Generated: 2026-06-09T01:23:58.539Z
---
# DOC23 Red Line — Sequential Re-Prompt System
**Date:** 2026-05-01
**Affects:** §3.2.1 (step.agent_task), §3.2.8 (step.coding), §6.5.2 (agent task execution), §6.5.8 (coding execution), §4.5 (output popups), §4.8 (validation)
**Status:** Draft addendum for compilation into DOC23 R3.2
---
## 1. Summary
Agent task and coding modules gain a `re_prompts` field — an ordered list of follow-up prompts dispatched sequentially in the same session after the primary response. This replaces the underspecified `iteration_limit` completion mode and subsumes `tests_pass` (the agent executes tests itself when instructed via a re-prompt).
---
## 2. Schema Changes
### 2.1 `step.agent_task` — AgentTaskModuleConfig (§3.2.1)
Add two fields:
```ts
// Added to AgentTaskModuleConfig
re_prompts: string[] // Ordered follow-up prompts. Default: [] (empty — single-turn, current behavior).
// Each string is a follow-up prompt dispatched in sequence in the same Gateway session.
// Max 10 entries.
separate_outputs: boolean // Default: false.
// When true, per-response output ports appear alongside data_out (see §5).
```
### 2.2 `step.coding` — CodingAgentAssignment (§3.2.8)
Add `re_prompts` to the per-agent assignment, not the module:
```ts
// Modified CodingAgentAssignment (existing fields unchanged)
CodingAgentAssignment {
role: string
agent_config: AgentConfig
acp_profile_id: string | null
instruction_override: string | null
re_prompts: string[] // Per-agent follow-up prompts. Default: [].
// Dispatched in the agent's ACP session after it signals completion.
// Each prompt is a new turn in the same ACP session —
// the agent retains full workspace state, file access, and terminal.
// Max 10 entries per agent.
}
```
### 2.3 `step.coding` — CodingModuleConfig (§3.2.8)
Remove `iteration_limit` completion mode. Remove `tests_pass` completion mode. Remove `test_command` field.
**Before:**
```ts
completion_mode: "agent_signals" | "tests_pass" | "iteration_limit"
test_command: string | null
```
**After:**
```ts
completion_mode: "agent_signals" // Sole completion mode. Agent signals done, then re_prompts execute.
// test_command: REMOVED — agent runs tests itself when instructed via re_prompt
// iteration_limit: REMOVED — replaced by explicit re_prompts with content
```
`max_iterations` remains as a safety cap on total agent turns (prevents runaway sessions). It is NOT a completion trigger.
`capture_test_results` remains but changes meaning: when true, EC captures the last `test_results_out` from whatever tests the agent ran during its session (agent-initiated, not EC-initiated). If the agent didn't run tests, sentinel payload emits as before.
---
## 3. Execution Flow
### 3.1 Agent Task Execution — §6.5.2 Modification
Replace step 5 (the final step in current spec) with:
```
5. PRIMARY DISPATCH:
Dispatch assembled CIL prompt to Gateway → receive response_0
Store response_0.
6. RE-PROMPT LOOP:
FOR i = 0 TO re_prompts.length - 1:
a. Dispatch re_prompts[i] as a new user turn in the SAME Gateway session.
- The session already contains: the full CIL-assembled context from step 4,
the primary instruction, response_0, and any prior re-prompt exchanges.
- The re-prompt text is the ONLY content in this turn — no re-injection of
data_in, context_in, instruction_in, or chain history. The session has all
of that from the first turn.
b. Receive response_{i+1}. Store it.
7. ASSEMBLE OUTPUT:
a. responses = [response_0, response_1, ..., response_N]
b. Merge all responses into one ContextBundle for data_out (see §4.1).
c. Attach source_session_key from this session to the output ContextBundle.
d. IF separate_outputs enabled: emit per-response ports (see §5).
e. IF named outputs configured: extract named outputs from the LAST response only.
8. EMIT:
- data_out: merged ContextBundle (always emits)
- Per-response ports (if separate_outputs = true)
- Named output ports (if configured, from last response only)
- signal_out: fires HERE, after all re-prompts complete
- receipt_out: includes re_prompt_count in metadata
```
**Key behaviors:**
- `signal_out` fires after the LAST re-prompt response, not after the primary response.
- Chain history for downstream modules records ONE entry: the merged output from `data_out`. Not N separate entries.
- If `session_mode: "continue"` is set on the next module, it continues after the full re-prompt chain — seeing the complete conversation.
- If `session_persist: true`, the stored session key reflects the session after all re-prompts.
### 3.2 Coding Module Execution — §6.5.8 Modification
Per-agent re-prompts execute after each agent signals completion, within that agent's ACP session:
**Single-agent flow:**
```
1. Open ACP session for the agent.
2. Dispatch assembled instruction.
3. Agent works iteratively (reads, edits, runs, tests) until it signals done.
4. RE-PROMPT LOOP for this agent:
FOR i = 0 TO agent.re_prompts.length - 1:
a. Dispatch agent.re_prompts[i] as a new turn in the SAME ACP session.
- The agent retains full workspace state: all files, terminal history,
installed packages, environment variables.
- The re-prompt is the only new content.
b. Agent works iteratively on the re-prompt until it signals done again.
5. Capture artifacts (diff, files, summary, test results).
6. Close or park session per session_style.
```
**Multi-agent sequential flow:**
```
FOR EACH agent in agents (array order):
1. Open ACP session for this agent.
2. Dispatch instruction (with handoff_instruction from prior agent if applicable).
3. Agent works until done.
4. RE-PROMPT LOOP for this agent (same as single-agent step 4).
5. Capture this agent's artifacts.
6. Close or park session.
After all agents complete:
7. Assemble combined output from all agents' artifacts.
8. Emit all output ports. signal_out fires here.
```
**Multi-agent review_chain flow:**
```
Agent A (builder) works until done → A's re_prompts execute → capture A's output
Agent B (reviewer) works until done → B's re_prompts execute → capture B's output
If B's response = revision: send feedback to A → A works again → A's re_prompts execute → capture → B reviews again → B's re_prompts execute → etc.
Cycle repeats until B approves or max_rounds reached.
After chain completes:
Assemble combined output. Emit all ports. signal_out fires.
```
**Each agent's re-prompts run WITHIN that agent's portion of the workflow.** A's re-prompts complete before B receives A's output. B's re-prompts complete before the review decision is evaluated.
---
## 4. Output Handling
### 4.1 Merged Output Format — `data_out`
All responses concatenated into ONE ContextBundle:
```ts
// data_out ContextBundle.content structure:
{
merged_content: string, // All responses concatenated with separators (see format below)
response_count: number, // Total responses (1 + re_prompts.length)
has_re_prompts: boolean, // true if any re-prompts were configured
}
```
**Text format of merged_content:**
For agent_task (text responses):
```
{response_0}
───── Re-prompt 1 ─────
{response_1}
───── Re-prompt 2 ─────
{response_2}
```
For coding (the merged_content is a combined summary):
```
═══ {agent.role}: {agent_name} ═══
{agent_summary}
───── Re-prompt 1 ─────
{agent_reprompt_1_response}
───── Re-prompt 2 ─────
{agent_reprompt_2_response}
═══ {agent_2.role}: {agent_2_name} ═══
{agent_2_summary}
───── Re-prompt 1 ─────
{agent_2_reprompt_1_response}
```
### 4.2 Named Outputs Interaction
If the module has named outputs ("📄 Analysis", "📄 Summary"), they extract from the LAST response only. The last response is the refined product. Intermediate responses are working states.
CIL's naming instruction (which tells the agent to label outputs matching the named port labels) is injected in the LAST re-prompt turn, appended to the user's re-prompt text:
```
{user's re-prompt text}
When producing your final output, label the following sections clearly:
- 📄 Analysis
- 📄 Summary
```
If there are no re-prompts, CIL injects naming instructions in the primary dispatch as it does today (no change from current behavior).
---
## 5. Separate Response Outputs
When `separate_outputs: true` on `step.agent_task`:
The module gains dynamic output ports alongside its standard ports:
```ts
// Dynamic ports — appear when separate_outputs = true
"original_out" // response_0 only
"reprompt_1_out" // response_1 only (labeled with re_prompt text preview if short)
"reprompt_2_out" // response_2 only
...
"reprompt_N_out" // response_N only
```
Each port emits its individual response as a separate ContextBundle.
`data_out` still emits the merged version. Both are available simultaneously.
**Port labels:** If the re-prompt text is short (≤30 chars), use it as the port label: `📄 "Review your work"`. Otherwise use `📄 Re-prompt 1`, `📄 Re-prompt 2`, etc.
**When separate_outputs is unchecked:** Dynamic ports disappear. Any cables wired to them produce validation warning `validation.dangling_cable` (existing DOC23 behavior for removed ports).
**Coding module:** `separate_outputs` is NOT available on step.coding. Coding outputs are structured (diff, files, summary, test results) and represent final workspace state, not individual text responses. Per-agent splitting would require a different output model that doesn't fit the re-prompt pattern.
**Output popup (§4.5) additions for agent_task when separate_outputs = true:**
```ts
// Added to agentTaskOutputChoices (dynamic, only when separate_outputs = true)
{id:"original_out", label:"Original Response", desc:"Response to primary instruction only", color:c.accent},
{id:"reprompt_1_out", label:"Re-prompt 1", desc:"Response to first follow-up", color:c.cyan},
// ... one per configured re-prompt
```
---
## 6. Detail Panel UX
### 6.1 Agent Task — Re-Prompt Section
Appears below the Instruction section, above Named Outputs:
```
─── Re-Prompts ─────────────────────────
Sequential follow-up prompts in the same
session. Each fires after the prior response.
┌──────────────────────────────────────┐
│ 1. [✕] │
│ ┌──────────────────────────────────┐ │
│ │ Review your work above. What did │ │
│ │ you miss? What could be │ │
│ │ stronger? │ │
│ └──────────────────────────────────┘ │
│ 📎 Attach files │
├──────────────────────────────────────┤
│ 2. [✕] │
│ ┌──────────────────────────────────┐ │
│ │ Incorporate your review into a │ │
│ │ final consolidated version. │ │
│ └──────────────────────────────────┘ │
│ 📎 Attach files │
└──────────────────────────────────────┘
[+ Add Re-Prompt]
☐ Send responses to separate outputs
```
**Interaction:**
- **[+ Add Re-Prompt]:** Appends a new empty text area. Max 10.
- **[✕]:** Removes the re-prompt. Remaining items renumber.
- **Drag handle (left edge):** Reorder re-prompts.
- **📎 Attach files:** Same attachment picker as the primary instruction. Attachments are included in that specific re-prompt's turn only.
- **Separate outputs checkbox:** When checked, per-response output ports appear in the output popup.
### 6.2 Coding Module — Per-Agent Re-Prompts
Re-prompts appear within each agent's config card, below instruction_override:
```
─── Agent 1: builder ───────────────────
Agent: [claude-code ▾]
Role: [builder ]
Instruction Override:
┌──────────────────────────────────┐
│ Implement the API endpoint per │
│ the spec provided. │
└──────────────────────────────────┘
Re-Prompts:
┌──────────────────────────────────┐
│ 1. [✕] │
│ ┌──────────────────────────────┐ │
│ │ Review your implementation. │ │
│ │ Check for edge cases, error │ │
│ │ handling, and spec │ │
│ │ compliance. List issues. │ │
│ └──────────────────────────────┘ │
├──────────────────────────────────┤
│ 2. [✕] │
│ ┌──────────────────────────────┐ │
│ │ Fix every issue you found. │ │
│ │ Run the tests and confirm │ │
│ │ everything passes. │ │
│ └──────────────────────────────┘ │
└──────────────────────────────────┘
[+ Add Re-Prompt]
─── Agent 2: reviewer ──────────────────
Agent: [claude-code-review ▾]
Role: [reviewer ]
Instruction Override:
┌──────────────────────────────────┐
│ Review the code for quality, │
│ security, and performance. │
└──────────────────────────────────┘
Re-Prompts:
┌──────────────────────────────────┐
│ 1. [✕] │
│ ┌──────────────────────────────┐ │
│ │ Reconsider your review. Are │ │
│ │ there issues you missed? │ │
│ └──────────────────────────────┘ │
└──────────────────────────────────┘
[+ Add Re-Prompt]
```
Same interaction as agent task: add, remove, reorder, max 10 per agent.
---
## 7. Interaction with Existing Features
### 7.1 Session Continuity (Addenda A §A9)
Re-prompts do not change session continuity behavior. The module opens one session (or continues a prior session per `session_mode`), executes all re-prompts within it, and attaches the session key to `data_out`. The next module with `session_mode: "continue"` sees the full conversation including all re-prompts.
`session_persist: true` stores the session key after all re-prompts complete. On re-activation (revision loop), the module continues the same session — which already contains the full re-prompt history. The re-prompts execute again in the continued session, producing a new round of responses.
### 7.2 Experiments (Addenda A §A2)
Each variant activation includes the full re-prompt chain. The ComparisonBundle carries the variant's merged `data_out` (all responses). The experiment does not need to know about re-prompts — they are internal to the module activation.
If the experiment overrides instruction via `instruction_override`, only the PRIMARY instruction is overridden. Re-prompts are unchanged unless the experiment uses `config_overrides: { re_prompts: [...] }` to change them explicitly.
### 7.3 Judge (Addenda A §A3)
The judge evaluates `data_out` — the merged output. If `separate_outputs` is enabled and individual response ports are wired to the judge's `target_in` or `comparison_in`, the judge evaluates whichever response is wired. No special handling needed.
### 7.4 DOC24 Context Injection (Addenda A §A8)
DOC24 context injection happens once at the start of the module activation, before the primary dispatch. Re-prompts do NOT trigger additional DOC24 injections. The context is already in the session from the first turn.
### 7.5 Chain History
The module produces ONE chain history entry: the merged `data_out`. Downstream modules see one predecessor output. This prevents the context duplication that would occur if re-prompts were implemented as separate modules wired together.
### 7.6 Coding Multi-Agent Coordination
Re-prompts and multi-agent coordination (sequential, parallel, review_chain) are independent. Re-prompts are per-agent and execute within each agent's session, within that agent's phase of the coordination workflow.
For **parallel** coordination: all agents work simultaneously, each in their own ACP session. Each agent's re-prompts execute within that agent's session after it signals done. The module waits for ALL agents (including their re-prompts) before combining output and emitting.
For **review_chain**: Agent A's re-prompts complete before Agent B receives A's output for review. Agent B's re-prompts complete before the review decision (approve/revise) is evaluated. If revision: A receives feedback, A works, A's re-prompts execute, then B reviews again, B's re-prompts execute, etc.
---
## 8. Applicability
| Module Type | Re-Prompts | Location | Notes |
|---|---|---|---|
| `step.agent_task` | ✅ | Module-level `re_prompts: string[]` | Primary use case. |
| `step.coding` | ✅ | Per-agent `CodingAgentAssignment.re_prompts: string[]` | Per-agent re-prompts within ACP sessions. |
| `step.agent_review_gate` | ✅ | Module-level `re_prompts: string[]` | Reviewer can do multiple assessment passes. |
| `step.red_team` | ✅ | Module-level `re_prompts: string[]` | Red teamer can do multiple adversarial passes. |
| `step.panel` | ❌ | — | Panel has its own multi-turn discussion model. |
| `step.judge` | ❌ | — | Judge has structured scoring pipeline. |
| `step.transform` | ❌ | — | Single-call operations. |
| `step.claim_extractor` | ❌ | — | Single-call extraction. |
---
## 9. Migration from Removed Completion Modes
### 9.1 `tests_pass` Migration
**Before (R3.1):**
```ts
completion_mode: "tests_pass"
test_command: "npm test"
max_iterations: 3
```
**After (R3.2):**
```ts
completion_mode: "agent_signals"
agents: [{
role: "builder",
agent_config: { ... },
re_prompts: [
"Run the tests for this project. If any tests fail, fix the issues and run the tests again. Repeat until all tests pass or you've attempted 3 fix cycles."
]
}]
```
The agent uses its native code execution capability (OpenClaw) to run the tests, read the output, and fix failures. EC does not orchestrate the test loop — the agent manages it.
### 9.2 `iteration_limit` Migration
**Before (R3.1):**
```ts
completion_mode: "iteration_limit"
max_iterations: 3
```
**After (R3.2):**
```ts
completion_mode: "agent_signals"
agents: [{
role: "builder",
agent_config: { ... },
re_prompts: [
"Review your implementation for completeness and correctness.",
"Address any remaining issues and finalize."
]
}]
```
Each re-prompt has specific content instead of "keep working."
---
## 10. Validation Codes
| Code | Sev | Trigger |
|---|---|---|
| `validation.reprompt_empty` | error | Re-prompt entry with empty string |
| `validation.reprompt_too_many` | warning | More than 10 re-prompts on a module (agent_task) or agent (coding) |
**Removed validation codes:**
- `validation.coding_test_command_required` — removed (test_command field removed)
---
## 11. SSE Events
| Event | Payload |
|---|---|
| `task.agent_task.reprompt_dispatched` | `{ module_id, reprompt_index, reprompt_count }` |
| `task.agent_task.reprompt_response` | `{ module_id, reprompt_index, token_count }` |
| `task.coding.agent_reprompt_dispatched` | `{ module_id, agent_role, reprompt_index }` |
| `task.coding.agent_reprompt_response` | `{ module_id, agent_role, reprompt_index }` |
These events enable the canvas to show progress: "Re-prompt 2/3..." on the module badge during execution.
---
## 12. Storage
No new storage paths required. Re-prompt config is part of the module definition (stored in the task graph). Re-prompt responses are part of the run output (stored in the existing run record). No separate re-prompt artifacts.
---
## 13. DOC23 Compilation Points
| Section | Change |
|---|---|
| §3.2.1 | Add `re_prompts: string[]` and `separate_outputs: boolean` to AgentTaskModuleConfig |
| §3.2.3 | Add `re_prompts: string[]` to AgentReviewGateConfig |
| §3.2.7 | Add `re_prompts: string[]` to RedTeamModuleConfig |
| §3.2.8 | Add `re_prompts: string[]` to CodingAgentAssignment. Remove `iteration_limit` and `tests_pass` from completion_mode enum. Remove `test_command` field. Update `max_iterations` description (safety cap only, not completion trigger). Update `capture_test_results` description. |
| §4.5 | Add dynamic per-response output ports to agent_task output popup (when separate_outputs = true) |
| §4.8 | Add `validation.reprompt_empty`, `validation.reprompt_too_many`. Remove `validation.coding_test_command_required`. |
| §6.5.2 | Insert re-prompt loop between primary dispatch and output assembly. Update signal_out timing. |
| §6.5.8 | Insert per-agent re-prompt loop after agent completion signal. Remove tests_pass and iteration_limit execution flows. |
| §12.2 | Add 4 SSE events for re-prompt progress |
| §13.4 | Add re-prompt section to agent_task and coding detail panels |
| Appendix B | Update agent_task and coding rows |