# Recursive Communicator

> Auto-activates when managing agent-to-agent communication for validation

- **Type:** Skill
- **Install:** `agentstack add skill-matteocervelli-llms-recursive-communicator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [matteocervelli](https://agentstack.voostack.com/s/matteocervelli)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [matteocervelli](https://github.com/matteocervelli)
- **Source:** https://github.com/matteocervelli/llms/tree/main/.archive/claude-v1/skills/recursive-communicator

## Install

```sh
agentstack add skill-matteocervelli-llms-recursive-communicator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## Purpose

The **recursive-communicator** skill provides structured protocols for managing recursive communication loops between the validation orchestrator, validation specialists, and the main feature implementer agent. It handles failure notifications, fix requests, re-validation triggers, and loop termination to ensure validation issues are resolved systematically.

## When to Use

This skill auto-activates when you:
- Communicate validation failures to the main agent
- Request fixes from the main agent for validation issues
- Trigger re-validation after main agent fixes
- Manage recursive fix loops (failure → fix → re-check → repeat)
- Track iteration counts in recursive communication
- Prevent deadlocks in recursive loops
- Escalate unresolvable validation issues
- Log communication history for traceability

## Provided Capabilities

### 1. Failure Communication
- **Structured Failure Reports**: Format validation failures for main agent
- **Detailed Error Information**: Include file locations, line numbers, error messages
- **Suggested Fixes**: Provide specialist recommendations for resolving issues
- **Priority Tagging**: Mark critical vs. non-critical failures
- **Context Preservation**: Include all relevant context for debugging

### 2. Fix Request Management
- **Clear Fix Requests**: Explicitly request main agent to fix specific issues
- **Action Items**: Provide actionable list of fixes needed
- **Deadline Awareness**: Track iteration limits (max 5)
- **Fix Verification**: Confirm when main agent completes fixes
- **Re-validation Triggering**: Signal specialists to re-check after fixes

### 3. Re-validation Coordination
- **Re-check Signals**: Trigger specialist re-validation after fixes
- **Iteration Tracking**: Increment and track iteration counts
- **Status Updates**: Communicate re-validation status to all parties
- **Loop Continuation**: Determine if another iteration needed
- **Loop Termination**: Identify when to exit recursive loop

### 4. Deadlock Prevention
- **Max Iteration Limits**: Enforce maximum 5 iterations per specialist
- **Timeout Detection**: Identify stalled communication
- **Escalation Triggers**: Escalate after max iterations or timeout
- **User Intervention Requests**: Flag when human input needed
- **Graceful Degradation**: Handle unresolvable issues without blocking workflow

### 5. Communication Logging
- **Message History**: Log all communication between agents
- **Iteration History**: Track all iterations with timestamps
- **Fix History**: Document all fixes attempted
- **Status Transitions**: Log status changes (failed → fixing → re-checking → passed)
- **Audit Trail**: Maintain complete communication audit trail

## Usage Guide

### Step 1: Detect Validation Failure

When a validation specialist reports failure:

```markdown
**Validation Failure Detected**

**Specialist**: test-runner-specialist
**Phase**: Test Execution
**Issue**: 3 unit tests failing

**Failure Details**:
- test_validation_coordinator.py::test_sequential_invocation - AssertionError
- test_validation_coordinator.py::test_failure_tracking - KeyError
- test_validation_coordinator.py::test_workflow_completion - AttributeError

**Coverage**: 73.2% (target: ≥80%)

**Action Required**: Activate recursive-communicator skill
```

### Step 2: Format Failure Report

Use communication-protocol.md and message-templates.md to format structured report:

**Failure Report Structure**:
```markdown
## Validation Failure Report

**Report ID**: VFR-{issue-number}-{specialist-name}-{iteration}
**Generated**: [YYYY-MM-DD HH:MM:SS]
**Issue**: #{issue-number} - [Feature Name]
**Specialist**: [Specialist Name]
**Phase**: [Validation Phase]
**Iteration**: [Current] / [Max (5)]

---

### Failure Summary

**Status**: ❌ FAILED
**Failure Type**: [Test Failures / Quality Issues / Security Vulnerabilities / E2E Failures]
**Severity**: [Critical / High / Medium / Low]
**Impact**: Blocks progression to [Next Phase]

---

### Detailed Failures

#### Failure 1: [Test/Issue Name]
- **File**: [File path]
- **Line**: [Line number]
- **Error Type**: [AssertionError / TypeError / SecurityError / etc.]
- **Error Message**:
  ```
  [Full error message from specialist]
  ```
- **Context**: [Additional context about the failure]

#### Failure 2: [Test/Issue Name]
- **File**: [File path]
- **Line**: [Line number]
- **Error Type**: [Error type]
- **Error Message**:
  ```
  [Full error message]
  ```
- **Context**: [Additional context]

[... Additional failures ...]

---

### Suggested Fixes

#### Fix for Failure 1
**Recommendation**: [Specialist's suggestion for fixing the issue]
**Approach**: [Specific steps or code changes needed]
**Priority**: [Critical / High / Medium / Low]

#### Fix for Failure 2
**Recommendation**: [Specialist's suggestion]
**Approach**: [Specific steps]
**Priority**: [Priority level]

[... Additional fix suggestions ...]

---

### Required Actions

**Main Agent (@feature-implementer-main):**
1. Review failure details above
2. Implement suggested fixes (or alternative approach)
3. Verify fixes locally (if possible)
4. Signal completion to validation orchestrator
5. Await re-validation

**Expected Timeline**: [Estimated time to fix]
**Escalation**: If fixes cannot be completed, escalate to user

---

### Re-validation Plan

**After Fix Completion**:
1. Validation orchestrator will re-invoke [Specialist Name]
2. Specialist will re-run [Tests/Checks]
3. IF pass: Proceed to [Next Phase]
4. IF fail: Iteration [Current+1] / [Max (5)]
5. IF max iterations exceeded: Escalate to user intervention

---

**Sent by**: Validation Orchestrator (recursive-communicator skill)
**Awaiting**: Main Agent Fix Completion
```

### Step 3: Send Failure Report to Main Agent

Communicate failure report to @feature-implementer-main:

**Communication Protocol**:
```markdown
### Sending Failure Report

**To**: @feature-implementer-main
**From**: @validation-orchestrator (via recursive-communicator)
**Type**: Validation Failure Report
**Priority**: [High/Medium/Low based on severity]

**Message**:
---
@feature-implementer-main: Validation failure detected during [Phase] validation.

[Full Failure Report from Step 2]

Please review and fix the above issues. Signal completion when ready for re-validation.
---

**Status**: Sent
**Timestamp**: [YYYY-MM-DD HH:MM:SS]
**Awaiting Response**: Yes
```

### Step 4: Wait for Main Agent Fix

Monitor main agent activity:

**Waiting State**:
```markdown
### Awaiting Main Agent Fix

**Current Status**: Waiting for Fix
**Specialist**: [Specialist Name] (paused)
**Iteration**: [Current] / [Max (5)]
**Time Elapsed**: [MM:SS since failure report sent]
**Timeout**: 30 minutes (escalate if exceeded)

**Main Agent Actions Expected**:
- [ ] Review failure report
- [ ] Analyze failure root causes
- [ ] Implement fixes
- [ ] Verify fixes locally (optional)
- [ ] Signal completion to validation orchestrator

**Monitoring**:
- Check main agent status every 2 minutes
- Log any main agent communications
- Detect timeout if >30 minutes without response
```

**Timeout Handling**:
```markdown
IF time_elapsed > 30 minutes WITHOUT main agent response:
  1. Log timeout event
  2. Send reminder to main agent
  3. IF still no response after reminder (5 minutes):
     a. Escalate to user intervention
     b. Flag as "unresponsive"
     c. Await user decision (abort / manual fix / extend timeout)
```

### Step 5: Receive Fix Completion Signal

When main agent signals fix completion:

**Fix Completion Confirmation**:
```markdown
### Main Agent Fix Completed

**Received From**: @feature-implementer-main
**Timestamp**: [YYYY-MM-DD HH:MM:SS]
**Fix Duration**: [MM:SS from failure report to completion]

**Main Agent Report**:
[Summary of fixes implemented by main agent]

**Fixes Applied**:
- Fix 1: [Description of fix]
- Fix 2: [Description of fix]
- [... Additional fixes ...]

**Verification**:
- [ ] Main agent confirmed fixes applied
- [ ] Files modified: [List of changed files]
- [ ] Ready for re-validation

**Next Action**: Trigger re-validation (Step 6)
```

### Step 6: Trigger Re-validation

Re-invoke specialist for re-check:

**Re-validation Trigger**:
```markdown
### Triggering Re-validation

**Specialist**: [Specialist Name]
**Iteration**: [Current+1] / [Max (5)]
**Previous Status**: Failed
**Current Status**: Re-checking

**Re-invocation**:
@[specialist-name] re-check [validation type] for feature #{issue-number}
Iteration: [Current+1] / [Max (5)]
Previous failures: [List of failures from previous iteration]
Fixes applied: [List of fixes from main agent]

**Expected Outcomes**:
1. **PASS**: All previous failures resolved
   - Exit recursive loop
   - Proceed to next validation phase
   - Log success with iteration count

2. **FAIL** (some/all failures persist):
   - Increment iteration count
   - Return to Step 1 (detect failure)
   - IF iteration  5: Escalate (Step 7)

**Status**: Re-validation in Progress
**Timestamp**: [YYYY-MM-DD HH:MM:SS]
```

### Step 7: Handle Re-validation Result

Process specialist re-check output:

**Result: PASS** ✅
```markdown
### Re-validation Success

**Specialist**: [Specialist Name]
**Iteration**: [Final] / [Max (5)]
**Status**: ✅ PASSED

**Previous Failures**: [Count] failures
**Current Failures**: 0 failures
**Resolution**: All issues fixed by main agent

**Iteration History**:
- Iteration 1: [X] failures
- Iteration 2: [Y] failures
- ...
- Iteration [Final]: 0 failures (PASS)

**Total Fix Time**: [HH:MM:SS across all iterations]

**Action**: Exit recursive loop, proceed to [Next Phase]
**Communication**: Notify main agent of success
**Logging**: Log successful resolution and iteration count
```

**Result: FAIL** ❌
```markdown
### Re-validation Failure (Iteration [Current] / 5)

**Specialist**: [Specialist Name]
**Iteration**: [Current] / [Max (5)]
**Status**: ❌ STILL FAILING

**Previous Failures**: [Count from previous iteration]
**Current Failures**: [Count from current iteration]
**New Failures**: [Count of new failures introduced]
**Persistent Failures**: [Count still failing]

**Analysis**:
- Failures resolved: [List]
- Failures persisting: [List]
- New failures introduced: [List]

**Decision**:
IF iteration = 5):
  ⛔ Max iterations exceeded
  ⛔ Proceed to Step 8 (escalation)
```

### Step 8: Escalate Unresolvable Issues

When max iterations (5) exceeded or timeout occurs:

**Escalation Report**:
```markdown
## Escalation: Unresolvable Validation Issue

**Escalation ID**: ESC-{issue-number}-{specialist-name}-{timestamp}
**Generated**: [YYYY-MM-DD HH:MM:SS]
**Issue**: #{issue-number} - [Feature Name]
**Specialist**: [Specialist Name]
**Phase**: [Validation Phase]
**Escalation Reason**: [Max Iterations Exceeded / Timeout / Deadlock / Other]

---

### Escalation Summary

**Status**: ⛔ UNRESOLVABLE (Requires User Intervention)
**Total Iterations**: [Max (5)]
**Total Time**: [HH:MM:SS across all iterations]
**Persistent Failures**: [Count]

---

### Iteration History

| Iteration | Failures | Fixes Applied | Result |
|-----------|----------|---------------|--------|
| 1 | [Count] | [Summary] | FAIL |
| 2 | [Count] | [Summary] | FAIL |
| 3 | [Count] | [Summary] | FAIL |
| 4 | [Count] | [Summary] | FAIL |
| 5 | [Count] | [Summary] | FAIL |

**Pattern Analysis**: [Analysis of why failures persist across iterations]

---

### Persistent Failures

[List of failures that remain unresolved after 5 iterations]

#### Failure 1: [Test/Issue Name]
- **File**: [File path]
- **Line**: [Line number]
- **Error**: [Error message]
- **Iterations Failed**: [1, 2, 3, 4, 5]
- **Fixes Attempted**:
  - Iteration 1: [Fix attempted]
  - Iteration 2: [Fix attempted]
  - ...
- **Why Unresolved**: [Analysis of why this failure persists]

[... Additional persistent failures ...]

---

### Recommended Actions

**Option 1: User Manual Fix**
- User reviews failures and provides manual fix
- Validation orchestrator re-runs after user fix
- Risk: Requires user expertise

**Option 2: Skip Validation**
- Mark validation as "failed but proceeding"
- Document known issues
- Risk: Deploy with known failures

**Option 3: Abort Feature**
- Stop implementation
- Return feature to design phase
- Risk: Wasted effort on implementation

**Option 4: Extend Max Iterations**
- Allow additional iterations (e.g., 3 more)
- Continue recursive loop
- Risk: Potentially infinite loop

---

**Escalated To**: User / Main Orchestrator
**Awaiting Decision**: [Option 1 / Option 2 / Option 3 / Option 4]
**Validation Workflow**: PAUSED

---

**Sent by**: Validation Orchestrator (recursive-communicator skill)
```

### Step 9: Log Communication History

Maintain complete audit trail:

**Communication Log Entry**:
```markdown
### Communication Log

**Entry ID**: LOG-{issue-number}-{specialist-name}-{iteration}-{timestamp}

**Participants**:
- Validation Orchestrator (@validation-orchestrator)
- Specialist (@[specialist-name])
- Main Agent (@feature-implementer-main)

**Communication Flow**:

**[Timestamp 1]** Specialist → Orchestrator: Validation failure detected
- Failures: [Count]
- Details: [Summary]

**[Timestamp 2]** Orchestrator → Main Agent: Failure report sent (Iteration 1/5)
- Report ID: VFR-{issue-number}-{specialist-name}-1
- Status: Awaiting Fix

**[Timestamp 3]** Main Agent → Orchestrator: Fix completion signal
- Duration: [MM:SS]
- Fixes: [Summary]

**[Timestamp 4]** Orchestrator → Specialist: Re-validation triggered (Iteration 2/5)
- Status: Re-checking

**[Timestamp 5]** Specialist → Orchestrator: Re-validation result (PASS)
- Status: ✅ All failures resolved
- Final iteration: 2/5

**[Timestamp 6]** Orchestrator → Main Agent: Success notification
- Status: Validation passed
- Proceed to: [Next Phase]

---

**Total Messages**: 6
**Total Iterations**: 2
**Total Duration**: [HH:MM:SS]
**Outcome**: Success
```

## Best Practices

### 1. Clear Communication
- Use structured message templates (from message-templates.md)
- Include all relevant context (files, lines, errors)
- Provide actionable fix suggestions
- Specify expected outcomes clearly

### 2. Iteration Tracking
- Always track current/max iterations
- Log every iteration with timestamp
- Document fixes attempted in each iteration
- Analyze patterns across iterations

### 3. Timeout Management
- Set reasonable timeouts (default: 30 minutes)
- Send reminders before escalation
- Log timeout events
- Escalate gracefully when timeout exceeded

### 4. Deadlock Prevention
- Enforce strict max iterations (5)
- Detect circular failures (same failure across iterations)
- Escalate when progress stalls
- Provide escape routes (skip validation, user intervention)

### 5. Comprehensive Logging
- Log all messages between agents
- Track status transitions
- Document fix attempts
- Maintain audit trail for troubleshooting

### 6. Graceful Escalation
- Provide context when escalating
- Offer multiple resolution options
- Include iteration history and analysis
- Make escalation actionable for user

## Resources

### communication-protocol.md
Comprehensive protocol for agent-to-agent communication including:
- Message formatting standards
- Communication flow patterns
- Status signaling conventions
- Timeout and escalation procedures
- Error handling protocols

### message-templates.md
Pre-defined message templates for common scenarios:
- Failure report template
- Fix request template
- Re-validation trigger template
- Success notification template
- Escalation report template
- Communication log template

## Example Usage

### Input (Validation Failure)

```markdown
**Specialist**: test-runner-specialist
**Status**: FAILED
**Failures**:
- 3 unit tests failing
- Coverage: 73.2% (target: 80%)

**Error Details**:
test_validation_coordinator.py::test_sequential_invocation - AssertionError
test_validation_coordinator.py::test_failure_tracking - KeyError
test_validation_coordinator.py::test_workflow_completion - AttributeError
```

### Output (Recursive Communication Flow)

```markdown
## Recursive Comm

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [matteocervelli](https://github.com/matteocervelli)
- **Source:** [matteocervelli/llms](https://github.com/matteocervelli/llms)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-matteocervelli-llms-recursive-communicator
- Seller: https://agentstack.voostack.com/s/matteocervelli
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.