port-kernel

name	port-kernel
description	Get structured porting guidance when moving a kernel between architectures. Launches sages for source and target, reads test harness.
user_invocable	true

/port-kernel — Porting Guidance

Usage

/port-kernel reduce --from wormhole --to quasar
/port-kernel pack_untilize --from blackhole --to quasar
/port-kernel eltwise_binary --from wormhole --to blackhole

What to Do

1. Parse: kernel name, source architecture, target architecture. Derive kernel_type (sfpu/math/unpack/pack) by checking which subdirectory or header prefix the kernel lives under in the source architecture.
2. Launch two tasks IN PARALLEL:

Task A — Source sage: Launch the sage for the source architecture

Agent tool:
  subagent_type: "sage-{source_arch}"
  description: "Source analysis: {kernel}"
  prompt: |
    Find the implementation of {kernel} on {source_arch}.
    Report: algorithm, function signatures, template parameters,
    key constructs (MOP, replay buffer, address modifiers),
    data format handling, dependencies.

Task B — Target sage: Launch the sage for the target architecture

Agent tool:
  subagent_type: "sage-{target_arch}"
  description: "Target conventions: {kernel}"
  prompt: |
    Find the conventions for {kernel_type} kernels on {target_arch}.
    Search for: closest existing kernel of the same type,
    file naming pattern, instruction conventions, MOP patterns,
    config write patterns, any existing partial implementation of {kernel}.

3. While sages run, read the test harness for the target architecture:

   • Search tests/sources/ for matching test files
   • Extract #ifdef ARCH_{TARGET} sections for expected function signatures when present
   • If no ARCH_{TARGET} sections exist, fall back to unguarded/common signatures in the matching test files
   • Also consult tests/helpers/include/* for target-specific declarations/helpers (especially for Quasar), and if needed inspect target arch headers directly
   • Note template parameters and argument types

4. Aggregate into structured porting guidance:

## Porting: {kernel} ({source} → {target})

### Algorithm Summary
[From source sage — what the kernel does]

### Source Implementation
[Key functions, patterns, data format handling]

### Target Conventions
[From target sage — how similar kernels are structured on target]

### API Contract (from test harness)
[Expected function signatures, template params from test files]

### Key Differences
[What changes between source and target — naming, instructions, patterns]

### Recommended Template
[Which existing target kernel to use as a starting point]

### Porting Checklist
- [ ] Function signatures match test harness expectations
- [ ] Uses target arch instruction conventions
- [ ] Init/uninit symmetry maintained
- [ ] All data format paths handled

5. Reference .claude/references/porting-guide.md for detailed methodology