handoff-pack

name	handoff-pack
description	Generates structured Handoff Pack prompts for delegating work to Gemini with clear scope, acceptance criteria, and output format requirements.

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]

### Template: Type Hardening

```markdown
# Gemini Handoff Pack

## Session Context
- **Delegated By**: Claude Cloud Agent
- **Delegation ID**: {{DELEGATION_ID}}
- **Project**: {{PROJECT_NAME}}
- **Reference Skill**: `.claude/skills/quality/type-hardening/SKILL.md`

## Allowed Scope

{{SCOPE_PATTERNS}}

**You may ONLY modify files matching these patterns.**

## Task Instructions

**Objective**: Harden types by replacing string literals with enums and narrowing `any` to specific types.

**Priority Order:**
1. Prisma Enums (most reliable)
2. Shared Types (`shared/types/`, `@shared/types`)
3. Constants (`*.constants.ts`)
4. Create new types ONLY when genuinely needed

**Check existing types FIRST:**
```bash
# Prisma enums
grep -E "^enum " backend/prisma/schema.prisma

# Shared types
find shared/types -name "*.ts" -exec grep "export type\|export interface" {} \;

# Constants
find . -name "*.constants.ts" -exec cat {} \;

Pattern - String Literals:

// ❌ BEFORE
if (user.role === 'admin')

// ✅ AFTER
import { UserRole } from '../generated/prisma/index.js';
if (user.role === UserRole.admin)

Pattern - Any Types:

// ❌ BEFORE
const data: any = response.body;

// ✅ AFTER - narrow to SPECIFIC type
const data: UserPayload = response.body;

// ❌ WRONG - unknown is cheating, not fixing
const data: unknown = response.body;  // NOT ALLOWED

Work in small batches (1-3 changes), verify after each.

Acceptance Criteria

# REQUIRED after EACH batch of changes
npx tsc --noEmit

# Before final completion
{{PKG_MANAGER}} run lint

If verification fails: STOP, report the error, do NOT proceed.

Required Output Format

## Type Hardening Report

### Delegation ID
{{DELEGATION_ID}}

### Changes Applied
| File | Line | Before | After |
|------|------|--------|-------|
| auth.service.ts | 45 | `'admin'` | `UserRole.admin` |
| user.service.ts | 89 | `any` | `UserProfile` |

### Existing Types Used
- `UserRole` from `@prisma/client`
- `UserProfile` from `shared/types/user`

### New Types Created (if any)
- None (or list with justification)

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

### Remaining Opportunities
[List any skipped items with reason]

Guardrails

⚠️ STOP and escalate if:

1. No existing type matches - need Cloud to create new type
2. Changing any would require business logic changes
3. Type is in security-critical code (auth, crypto)
4. Uncertain about correct enum value casing

⚠️ NEVER:

• Replace any with unknown (that's cheating, not fixing)
• Create types without checking existing first
• Change any business logic
• Proceed after verification failure

## 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