Handoff Pack Generator

Purpose

Generate well-structured prompts ("Handoff Packs") for delegating scoped work to Gemini, ensuring clear instructions, verifiable acceptance criteria, and parseable output format.

When to Use

• Called by gemini-delegation agent after user approves delegation
• User wants to manually generate a handoff prompt
• Need to create a fix-up prompt after failed verification

Handoff Pack Structure

A complete Handoff Pack has these sections:

1. Session Context

# Gemini Handoff Pack

## Session Context
- **Delegated By**: Claude Cloud Agent
- **Delegation ID**: [YYYYMMDD-HHMMSS-hash]
- **Project**: [repo name]
- **Branch**: [current branch]

2. Scope Definition

## Allowed Scope

**You may ONLY modify these paths:**

src/features/user/.ts src/features/user/**/.test.ts

**You may NOT:**
- Modify files outside the allowed scope
- Change function signatures or public APIs
- Delete existing functionality
- Add new dependencies
- Modify configuration files

3. Task Instructions

## Task Instructions

**Objective**: [Clear, specific, measurable objective]

**Context**: [Why this work is needed, background info]

**Pattern to Follow**:

```typescript
// === BEFORE ===
export function calculateTotal(items: Item[]): number {
  return items.reduce((sum, item) => sum + item.price, 0);
}

// === AFTER ===
/**
 * Calculates the total price of all items.
 * @param items - Array of items with price property
 * @returns Total price as a number
 */
export function calculateTotal(items: Item[]): number {
  return items.reduce((sum, item) => sum + item.price, 0);
}

Apply this pattern to:

• All exported functions in scope
• Skip private/internal functions (no export keyword)
• Preserve existing JSDoc if present (don't duplicate)

### 4. Acceptance Criteria

```markdown
## Acceptance Criteria

Before reporting completion, ALL of these must pass:

```bash
# TypeScript compilation (required)
npx tsc --noEmit

# Linting (required)
npm run lint
# OR: pnpm lint
# OR: yarn lint

# Tests (if applicable)
npm test -- --passWithNoTests
# OR: pnpm test
# OR: yarn test

Success means:

• Zero TypeScript errors
• Zero lint errors (warnings acceptable)
• All tests pass (or none affected)

If any fail:

1. Fix the issue
2. Re-run the check
3. Only report when ALL pass

### 5. Output Format

```markdown
## Required Output Format

When complete, provide this EXACT format:

```markdown
## Gemini Completion Report

### Delegation ID
[same ID from Session Context]

### Files Modified
- `path/to/file1.ts` - Added JSDoc to 3 functions
- `path/to/file2.ts` - Added JSDoc to 5 functions
- `path/to/file3.ts` - Added JSDoc to 2 functions

### Commands Run
- `npx tsc --noEmit` - ✅ Passed
- `npm run lint` - ✅ Passed
- `npm test` - ✅ Passed (or N/A)

### Diff Summary

src/features/user/service.ts | 45 +++++++++++++++++++++ src/features/user/types.ts | 12 ++++++ src/features/user/utils.ts | 18 +++++++++ 3 files changed, 75 insertions(+)

### Notes
[Any decisions made, edge cases encountered, or observations]

### Escalations (if any)
[Items that need Cloud review - unclear patterns, security concerns, etc.]

### 6. Guardrails

```markdown
## Guardrails

⚠️ **STOP and report as Escalation** if you encounter:

1. **Unclear patterns** - Need architectural decision
2. **Business logic changes** - Beyond scope of delegation
3. **Security-sensitive code** - Auth, crypto, validation, secrets
4. **Breaking changes** - Would change public API behavior
5. **Cross-cutting concerns** - Changes ripple outside scope
6. **Dependency changes** - Package.json modifications needed

**How to escalate:**

```markdown
### Escalations
1. **File**: `src/features/user/auth.ts`
   **Issue**: Contains password hashing logic - security sensitive
   **Recommendation**: Skip this file, let Cloud handle

2. **Pattern unclear**: `src/features/user/legacy.ts`
   **Issue**: Mixed export styles, unclear which to document
   **Recommendation**: Clarify pattern before proceeding

Do NOT guess on escalation items. Report and skip.

## Instructions

### Generating a New Handoff Pack

**Input required:**
- Task description
- Scope (file patterns)
- Triage score (for context)
- Acceptance commands (auto-detected or specified)

**Process:**

1. **Detect project type:**
```bash
# Check for package.json
if [ -f "package.json" ]; then
  PKG_MANAGER="npm"
  [ -f "pnpm-lock.yaml" ] && PKG_MANAGER="pnpm"
  [ -f "yarn.lock" ] && PKG_MANAGER="yarn"
fi

2. Generate delegation ID:

DELEGATION_ID="$(date +%Y%m%d-%H%M%S)-$(echo "$TASK" | md5sum | cut -c1-8)"

3. Build scope section from provided path patterns

4. Create before/after examples from existing code in scope

5. Add appropriate acceptance criteria based on project type

6. Include guardrails section (always)

Generating a Fix-Up Pack

When verification fails, generate a minimal fix-up pack:

# Gemini Fix-Up Pack

## Previous Delegation
- **Original ID**: [original delegation ID]
- **Fix-Up ID**: [new ID]

## Issues to Fix

### Issue 1: [Category]
**File**: `path/to/file.ts`
**Error**: [exact error message]
**Fix**: [specific instruction]

### Issue 2: [Category]
**File**: `path/to/file2.ts`
**Error**: [exact error message]
**Fix**: [specific instruction]

## After Fixes

Re-run verification:
```bash
npx tsc --noEmit
npm run lint

Report Format

## Fix-Up Report

### Original Delegation ID
[id]

### Issues Fixed
- Issue 1: ✅ Fixed - [what was done]
- Issue 2: ✅ Fixed - [what was done]

### Verification
- `npx tsc --noEmit` - ✅ Passed
- `npm run lint` - ✅ Passed

### Notes
[Any additional context]

## Templates

### Template: Documentation Addition

```markdown
# Gemini Handoff Pack

## Session Context
- **Delegated By**: Claude Cloud Agent
- **Delegation ID**: {{DELEGATION_ID}}
- **Project**: {{PROJECT_NAME}}

## Allowed Scope

{{SCOPE_PATTERNS}}

**You may NOT:**
- Modify files outside scope
- Change any code logic
- Modify function signatures

## Task Instructions

**Objective**: Add JSDoc documentation to all exported functions

**Pattern**:
```typescript
// BEFORE
export function myFunction(param: Type): ReturnType {

// AFTER
/**
 * Brief description of what the function does.
 * @param param - Description of parameter
 * @returns Description of return value
 */
export function myFunction(param: Type): ReturnType {

Rules:

• Only document exported functions (has export keyword)
• Keep descriptions concise (1 line for simple functions)
• Use existing code to infer parameter/return descriptions
• Preserve any existing documentation

Acceptance Criteria

npx tsc --noEmit
{{PKG_MANAGER}} run lint

Required Output Format

[Standard completion report format]

Guardrails

[Standard guardrails]

### Template: Rename/Replace

```markdown
# Gemini Handoff Pack

## Session Context
[standard]

## Allowed Scope

{{SCOPE_PATTERNS}}

## Task Instructions

**Objective**: Rename `{{OLD_NAME}}` to `{{NEW_NAME}}` across all files in scope

**What to rename:**
- Variable declarations
- Function parameters
- Object properties
- Type/interface properties
- Import/export statements
- String literals in specific contexts (specify)

**What NOT to rename:**
- Comments (unless referencing the identifier)
- String literals (unless confirmed as identifiers)
- External API calls

## Acceptance Criteria
```bash
npx tsc --noEmit  # Must pass - catches missed renames
{{PKG_MANAGER}} run lint
{{PKG_MANAGER}} test

Required Output Format

[Standard]

Guardrails

[Standard]

## Best Practices

1. **Scope narrowly** - Better to under-scope than over-scope
2. **Provide concrete examples** - Always include before/after from actual code
3. **Be explicit about boundaries** - What's allowed, what's forbidden
4. **Make acceptance criteria runnable** - Exact commands, not descriptions
5. **Require structured output** - Parseable completion reports
6. **Include escalation path** - Gemini should know when to stop

## Related Skills

- `gemini-api/caching` - For caching Gemini API calls
- `gemini-api/rate-limiting` - For managing API rate limits

## Related Agents

- `gemini-delegation` - Uses this skill to generate packs