name: agent-handoffs description: Agent parameter passing, memory files, and data handoffs between agents

Agent Parameter Passing Guidelines

Core Principle

Agents are workflow-agnostic. They perform specific tasks regardless of which workflow invokes them.

Workflows pass parameters to agents to tell them:

Which workflow is running
What files to read (input)
What files to write (output)
Any workflow-specific context

Standard Parameters

All agents that work with memory files MUST accept these parameters:

interface AgentParameters {
  workflow: string;      // "create-module" | "add-operation" | "update-module"
  moduleId: string;      // "github-github" | "amazon-aws-s3"
  inputFile?: string;    // File to read from (optional if agent doesn't need input)
  outputFile: string;    // File to write to
}

Memory Path Construction

CRITICAL: Always use absolute paths for .localmemory to avoid issues when working from different directories.

# Get project root (choose method based on context)
PROJECT_ROOT="$(git rev-parse --show-toplevel)"

# Standard pattern - ALWAYS use absolute paths
MEMORY_PATH="${PROJECT_ROOT}/.claude/.localmemory/${workflow}-${moduleId}"

# Examples (where PROJECT_ROOT is your project's absolute path):
# ${PROJECT_ROOT}/.claude/.localmemory/create-module-github-github/
# ${PROJECT_ROOT}/.claude/.localmemory/add-operation-github-github/
# ${PROJECT_ROOT}/.claude/.localmemory/update-module-amazon-aws-s3/

For Bash Scripts

# Method 1: Using git (preferred if in git repo)
PROJECT_ROOT="$(git rev-parse --show-toplevel)"

# Method 2: Using script location (if you know the script depth)
PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"

# Always construct absolute paths
MEMORY_PATH="${PROJECT_ROOT}/.claude/.localmemory/${workflow}-${moduleId}"

For Agents (invoked by Claude)

Agents should always receive or construct absolute paths. When constructing paths in agent responses, use the working directory from the environment.

Reading Input Files

# Agent receives parameters
WORKFLOW="create-module"
MODULE_ID="github-github"
INPUT_FILE="phase-01-discovery.json"

# Get project root and construct absolute paths
PROJECT_ROOT="$(git rev-parse --show-toplevel)"
MEMORY_PATH="${PROJECT_ROOT}/.claude/.localmemory/${WORKFLOW}-${MODULE_ID}"
INPUT_PATH="${MEMORY_PATH}/${INPUT_FILE}"

# Read data
PRODUCT_PACKAGE=$(jq -r '.productPackage' "${INPUT_PATH}")
MODULE_PACKAGE=$(jq -r '.modulePackage' "${INPUT_PATH}")

Writing Output Files

# Agent receives parameters
OUTPUT_FILE="phase-02-scaffolding.json"

# Get project root and construct absolute paths
PROJECT_ROOT="$(git rev-parse --show-toplevel)"
MEMORY_PATH="${PROJECT_ROOT}/.claude/.localmemory/${WORKFLOW}-${MODULE_ID}"
OUTPUT_PATH="${MEMORY_PATH}/${OUTPUT_FILE}"

# Ensure directory exists
mkdir -p "${MEMORY_PATH}"

# Write data
cat > "${OUTPUT_PATH}" <<EOF
{
  "phase": 2,
  "name": "Module Scaffolding",
  "status": "completed",
  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  ...
}
EOF

Agent Documentation Structure

❌ Wrong (Workflow-Specific)

## Responsibilities
- Create module structure for new modules
- Read from phase-01-discovery.json
- Write to phase-02-scaffolding.json

✅ Correct (Workflow-Agnostic)

## Responsibilities
- Create module directory structure
- Read parameters from input file
- Validate generated structure
- Write results to output file

## Required Parameters
- workflow: Workflow type
- moduleId: Module identifier
- inputFile: File containing parameters
- outputFile: File to write results

## Input File Structure
Expected fields in input file:
- productPackage: Product package name
- modulePackage: Module package name
- serviceName: Service name

Invocation Examples

From Workflow Documentation

### Phase 2: Module Scaffolding

**Agent:** @module-scaffolder

**Invocation:**
```bash
@module-scaffolder
Parameters:
  workflow: create-module
  moduleId: github-github
  inputFile: phase-01-discovery.json
  outputFile: phase-02-scaffolding.json


### Multiple Workflows Using Same Agent

**Create Module Workflow:**
```bash
@api-architect
Parameters:
  workflow: create-module
  moduleId: github-github
  inputFile: phase-01-discovery.json
  outputFile: phase-03-api-spec.json

Add Operation Workflow:

@api-architect
Parameters:
  workflow: add-operation
  moduleId: github-github
  inputFile: operation-spec.json
  outputFile: updated-api-spec.json

Same agent, different parameters!

File Naming in Workflows

Workflows specify exact file names based on their phase structure:

Create Module:

Phase 1: phase-01-discovery.json
Phase 2: phase-02-scaffolding.json
Phase 3: phase-03-api-spec.json
etc.

Add Operation:

Step 1: operation-definition.json
Step 2: api-spec-update.json
Step 3: implementation-plan.json
etc.

Update Module:

Step 1: operations-list.json
Step 2: update-plan.json
etc.

Agent Flexibility

Agents should be flexible about input structure:

// Agent reads what it needs
const productPackage = input.productPackage;
const modulePackage = input.modulePackage;

// If field doesn't exist, agent reports error
if (!productPackage) {
  throw new Error("Required field 'productPackage' missing from input file");
}

Workflow Responsibility

Workflows are responsible for:

Creating memory directories
Passing correct parameters to agents
Ensuring output from one phase matches input expected by next phase
Orchestrating agent sequence
Error handling and recovery

Agents are responsible for:

Accepting standard parameters
Reading from specified input file
Performing their specific task
Writing to specified output file
Reporting errors if parameters/input invalid

Benefits

✅ Reusability: Same agent works across multiple workflows ✅ Testability: Agents can be tested independently with different parameters ✅ Maintainability: Agent changes don't affect workflow structure ✅ Flexibility: New workflows can use existing agents ✅ Clarity: Clear separation of concerns

Anti-Patterns

❌ Hardcoding Workflow Type

# BAD
if [ "$WORKFLOW" == "create-module" ]; then
  # Special logic for create
fi

Agents should not have workflow-specific logic. If needed, workflows should pass different parameters.

❌ Hardcoding File Paths

# BAD - Relative path
INPUT=".claude/.localmemory/create-module-${MODULE_ID}/phase-01-discovery.json"

# BAD - Hardcoded workflow
INPUT="${PROJECT_ROOT}/.claude/.localmemory/create-module-${MODULE_ID}/phase-01-discovery.json"

# GOOD - Absolute path with parameters
PROJECT_ROOT="$(git rev-parse --show-toplevel)"
INPUT="${PROJECT_ROOT}/.claude/.localmemory/${WORKFLOW}-${MODULE_ID}/${INPUT_FILE}"

Always construct absolute paths from parameters.

❌ Hardcoding Phase Numbers

# BAD
echo '{"phase": 2, ...}'

Extract phase info from parameters or workflow context if needed.

Migration Guide

Old Style (Workflow-Specific)

**File:** `.claude/.localmemory/create-{module-id}/phase-02-scaffolding.json`

Read from: `.claude/.localmemory/create-{module-id}/phase-01-discovery.json`

New Style (Workflow-Agnostic)

**Input File:** Specified by workflow (e.g., phase-01-discovery.json)
**Output File:** Specified by workflow (e.g., phase-02-scaffolding.json)

**Example Paths:**
- Input: `.claude/.localmemory/{workflow}-{moduleId}/{inputFile}`
- Output: `.claude/.localmemory/{workflow}-{moduleId}/{outputFile}`

Summary

Agents receive parameters, not hardcoded values
Workflows control file naming and sequencing
Agents work across any workflow that provides correct parameters
Clear separation: workflows orchestrate, agents execute

agent-handoffs

SKILL.md