# Meta-Prompts (HOPs) — MORPH-SPEC v3.0

Higher-Order Prompts (HOPs) are Handlebars-powered prompt templates that generate consistent, context-rich system prompts for agent spawning. Instead of writing prompts from scratch each time, HOPs inject standards, mission context, and role definitions automatically.

---

## HOP Categories

### 1. Squad Leaders (`squad-leaders/`)

Prompts for orchestrating domain squads. Use when spawning the head of a multi-agent squad.

| HOP ID | File | Use Case |
|--------|------|----------|
| `hop-backend-squad` | `backend-squad.md` | .NET backend squad with dotnet-senior as lead |
| `hop-frontend-squad` | `frontend-squad.md` | Blazor or Next.js frontend squad |

### 2. Parallel Workers (`parallel-workers/`)

Prompts for P-Thread agents working in isolation.

| HOP ID | File | Use Case |
|--------|------|----------|
| `hop-parallel-worker` | `parallel-worker.md` | Individual domain worker in a parallel squad |
| `hop-parallel-coordinator` | `parallel-coordinator.md` | Coordinator managing multiple parallel workers |

### 3. Generic HOPs (`hops/`)

General-purpose prompt wrappers.

| HOP ID | File | Use Case |
|--------|------|----------|
| `hop-wrapper` | `hop-wrapper.md` | Wrap any agent prompt with standard context injection |
| `hop-retry` | `hop-retry.md` | Retry a failed task with per-attempt strategy hints |
| `hop-validation` | `hop-validation.md` | Spawn a validation agent for specific validator types |

### 4. Validators (`validators/`)

Prompts for checkpoint and pre-commit validation agents.

| HOP ID | File | Use Case |
|--------|------|----------|
| `hop-checkpoint-validator` | `checkpoint-validator.md` | Run full checkpoint validation (architecture, security, etc.) |
| `hop-pre-commit-validator` | `pre-commit-validator.md` | Pre-commit hook validation agent |

### 5. Fusion (`fusion/`)

Prompts for F-Thread fusion workflows.

| HOP ID | File | Use Case |
|--------|------|----------|
| `hop-fusion-agent` | `fusion-agent.md` | One of N agents in a fusion run |
| `hop-fusion-aggregator` | `fusion-aggregator.md` | Aggregates N fusion results into the best output |

---

## Rendering HOPs

### CLI

```bash
# List all available HOPs
morph-spec hop list

# Render a HOP to stdout
morph-spec hop render hop-backend-squad \
  --variables '{"AGENT_ID":"dotnet-senior","MISSION":"Implement auth API","FEATURE_NAME":"user-auth"}'

# Render and save to file
morph-spec hop render hop-backend-squad output.md \
  --variables '{"AGENT_ID":"dotnet-senior","MISSION":"Implement auth API"}'
```

### Programmatic (Node.js)

```javascript
import { renderHOP, listAvailableHOPs } from './src/lib/hop-composer.js';
import { join } from 'path';

const frameworkRoot = join(process.cwd(), 'framework');

// List HOPs
const hops = listAvailableHOPs(frameworkRoot);
console.log(hops); // [{ id, type, file, description }, ...]

// Render a HOP
const prompt = renderHOP('hop-backend-squad', {
  AGENT_ID: 'dotnet-senior',
  MISSION: 'Implement user authentication',
  FEATURE_NAME: 'user-auth',
  SPEC_SUMMARY: 'JWT auth with BCrypt, Supabase JWT validation',
  TASKS: '- T001: User entity\n- T002: AuthService\n- T003: AuthController',
  DELIVERABLES: 'Entities/User.cs, Services/AuthService.cs, Controllers/AuthController.cs',
  CONSTRAINTS: 'IDbContextFactory, no direct DbContext injection'
}, { frameworkRoot });
```

---

## Variable Reference

### Standard Variables (auto-injected)

| Variable | Source | Example |
|----------|--------|---------|
| `{{FEATURE_NAME}}` | CLI arg | `user-auth` |
| `{{DATE}}` | System | `2026-02-19` |
| `{{TIMESTAMP}}` | System | `2026-02-19T10:00:00Z` |
| `{{STACK}}` | config.json | `Blazor` |

### Squad Leader Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `{{AGENT_ID}}` | Yes | Agent identifier (e.g., `dotnet-senior`) |
| `{{MISSION}}` | Yes | One-sentence mission statement |
| `{{SPEC_SUMMARY}}` | Yes | 2-5 sentence spec summary |
| `{{ADDITIONAL_LEADERS}}` | No | Domain leader list (markdown bullets) |
| `{{TASKS}}` | Yes | Task list (markdown bullets with IDs) |
| `{{DELIVERABLES}}` | Yes | Expected output files |
| `{{CONSTRAINTS}}` | No | Architecture constraints |

### Parallel Worker Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `{{THREAD_ID}}` | Yes | Unique thread identifier |
| `{{DOMAIN}}` | Yes | Domain name (backend, frontend, infra) |
| `{{ASSIGNED_FILES}}` | Yes | Files this worker owns |
| `{{SHARED_FILES}}` | No | Read-only shared context files |
| `{{TASKS}}` | Yes | Tasks assigned to this worker |

### Fusion Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `{{FUSION_INDEX}}` | Yes | Agent number (1, 2, 3...) |
| `{{TOTAL_AGENTS}}` | Yes | Total agents in fusion run |
| `{{STRATEGY}}` | Yes | Aggregation strategy |
| `{{MISSION}}` | Yes | Shared mission for all agents |

### Retry Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `{{ATTEMPT}}` | Yes | Current attempt number (1-3) |
| `{{MAX_ATTEMPTS}}` | Yes | Maximum retry count |
| `{{FAILURE_REASON}}` | Yes | Why the previous attempt failed |
| `{{ORIGINAL_TASK}}` | Yes | The task being retried |

---

## Handlebars Helpers

HOPs use Handlebars v2.0 helpers:

```handlebars
{{pascalCase FEATURE_NAME}}  → UserAuth
{{camelCase FEATURE_NAME}}   → userAuth
{{snakeCase FEATURE_NAME}}   → user_auth
{{pluralize "entity"}}       → entities
{{#if IS_BLAZOR}}...{{/if}} → Conditional blocks
```

Conditionals available in squad leader HOPs:
- `{{#if IS_BLAZOR}}` — Blazor-specific content
- `{{#if IS_NEXTJS}}` — Next.js-specific content
- `{{#if HAS_BACKEND}}` — Backend domain present
- `{{#if HAS_INFRA}}` — Infrastructure domain present

---

## HOP Composition Example

Combining HOPs for a full parallel execution:

```javascript
// 1. Render coordinator prompt
const coordinatorPrompt = renderHOP('hop-parallel-coordinator', {
  FEATURE_NAME: 'user-auth',
  SQUADS: 'backend, frontend',
  TOTAL_THREADS: '2'
}, { frameworkRoot });

// 2. Render worker prompts per domain
const backendPrompt = renderHOP('hop-parallel-worker', {
  THREAD_ID: 'thr_backend_001',
  DOMAIN: 'backend',
  ASSIGNED_FILES: 'Services/UserService.cs\nControllers/AuthController.cs',
  TASKS: '- T001: UserService\n- T002: AuthController'
}, { frameworkRoot });

const frontendPrompt = renderHOP('hop-parallel-worker', {
  THREAD_ID: 'thr_frontend_001',
  DOMAIN: 'frontend',
  ASSIGNED_FILES: 'components/LoginForm.tsx\npages/login.tsx',
  TASKS: '- T003: LoginForm\n- T004: Login page'
}, { frameworkRoot });

// 3. Spawn via Task tool
// Use backendPrompt and frontendPrompt as subagent prompts
```

---

## REGISTRY.json

All HOPs are registered in `framework/templates/meta-prompts/REGISTRY.json`:

```json
{
  "hops": [
    {
      "id": "hop-backend-squad",
      "type": "squad-leader",
      "file": "squad-leaders/backend-squad.md",
      "description": "Backend squad leader for .NET implementation",
      "variables": ["AGENT_ID", "MISSION", "SPEC_SUMMARY", "TASKS", "DELIVERABLES"]
    }
  ]
}
```

To add a custom HOP:
1. Create your `.md` file in the appropriate category folder
2. Add an entry to `REGISTRY.json`
3. Use `morph-spec hop list` to verify it appears

---

## Related

- [Thread Management](THREAD-MANAGEMENT.md) — How HOPs are used in thread spawning
- [Context Optimization](CONTEXT-OPTIMIZATION.md) — Token-efficient prompt design
- `src/lib/hop-composer.js` — Rendering engine source
