---
name: port-application
description: >
  Port, translate, or migrate source code from one programming language to another
  using a structured pipeline: inventory → translate → evaluate → fix, looping until
  100% accuracy. Supports any language pair (C→C#, Python→Rust,
  Java→Kotlin, JavaScript→TypeScript, etc.). Use this skill whenever the user wants to
  port, migrate, translate, convert, or rewrite code from one language to another — even
  if they don't say "port" explicitly. Phrases like "rewrite this in Rust", "convert to
  TypeScript", "migrate from Java to Kotlin", "translate this C code to C#" should all
  trigger this skill.
argument-hint: <source path or project description>
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
---

# Port Application — Source Code Porting Pipeline

You are orchestrating a multi-phase porting pipeline that translates source code from
one programming language to another. The pipeline runs: **Port → Evaluate → Fix → Loop**
until every file scores 100%.

The methodology prioritizes **accuracy over elegance** — an ugly-but-faithful port beats
a clean-but-wrong one. The original source code is always the single source of truth.

## CRITICAL: Autonomous Execution — HARD CONSTRAINT

This pipeline runs **autonomously to completion**. After Phase 0 (user interview), the
pipeline is a single uninterruptible operation. You MUST NOT stop, pause, present results,
or ask the user anything until every file scores 100% and final reports are generated.

The full sequence is one continuous execution:

1. Phase 0: Discovery & Configuration (ONLY phase with user interaction)
2. Phase 1: Port ALL file groups
3. Phase 2: Evaluate ALL ported files
4. Phase 3: Fix any files scoring < 100, then loop back to Phase 2
5. Repeat Phase 2→3 until every file hits 100%
6. Generate final reports (markdown + HTML)
7. ONLY NOW present results to the user

### Self-Check Gate

**Before generating ANY text output after a phase completes, ask yourself:**
> "Am I about to end my turn, ask a question, or present a summary as if the work is done?"
> If YES → **STOP. Do not output that text.** Instead, immediately begin the next phase.

Phase completions are **transitions**, not conclusions. Print a one-line status and
immediately spawn the next subagent. Never print a summary table or completion message
that treats a phase as a stopping point.

### Anti-Pattern — DO NOT DO THIS

The following is an example of **exactly the wrong behavior** that has occurred in past runs.
Do NOT produce output like this:

```
❌ WRONG — This is what you must NEVER do:

Phase 1 (Port) Complete!
[big summary table]
Would you like me to proceed to Phase 2 (Evaluate)?
```

This is wrong because it treats Phase 1 completion as a stopping point. The correct behavior is:

```
✅ CORRECT — This is what you must do:

Phase 1 complete — 32 files ported. Starting Phase 2 (Evaluate), launching auditor for Group 1...
[immediately spawn auditor subagent — no pause, no question, no waiting]
```

### The Rule

**After Phase 0, your next message to the user may ONLY be the final report.** Between
phases, you may print brief one-line transition status updates, but you must NEVER:
- Ask "shall I proceed?", "should I continue?", "would you like me to..."
- Present a summary table as if the work is complete
- End your turn without immediately starting the next phase
- Treat any phase completion as a natural stopping point

### Completion Definition — When You Are Actually Done

The pipeline is complete ONLY when ALL of these are true:
1. **Every** file group has been evaluated at least once (no unevaluated groups)
2. **Every** file group has an auditor score of 100
3. The project **builds** successfully (zero compiler errors)
4. The project **runs** without crashing (if it has an entry point)
5. The final report and HTML dashboard have been generated

If ANY of these are false, you are NOT done. Do not generate a final report, do not
present results, do not mention "remaining work." Instead, keep iterating.

A final report that contains a "Remaining Work" section means you stopped too early.
There is no such thing as "remaining work" in a completed port — everything is done
or you are still in the pipeline.

### No Retry Limit — ZERO

There is **no retry limit**. Not 10, not 5, not any number. Keep iterating Evaluate→Fix
until the score reaches 100 and the build passes. If you find yourself thinking "I've
tried enough times" or "this is good enough at 95%" — that thought is wrong. Continue.

The only valid reason to stop iterating on a file is: **auditor score = 100 AND build passes**.

Do NOT lower the acceptance threshold. Do NOT accept files below 100 using your own
judgment. The rubric already accounts for inherent language differences — platform
replacements are noted but not heavily penalized. A faithful port CAN and MUST reach 100.
If the auditor keeps scoring below 100 for things you believe are correct translations,
fix the auditor's concerns anyway — the auditor is the authority, not your intuition.

## Setup

1. Parse the project description from: `$ARGUMENTS`
2. Scan the `port-results/` directory for existing folders. Determine the next project
   number (start at `001` if none exist).
3. Generate a slug: `<NNN>-<short-kebab-name>` (e.g., `001-wolf3d-csharp-port`).
4. Create: `port-results/<slug>/`
5. Proceed to Phase 0.

---

## Phase 0 — Discovery & Configuration

Before any porting, gather configuration. Auto-detect as much as possible, then confirm
with the user via **AskUserQuestion**.

### Auto-Detection

1. **Source language**: Detect from file extensions in the source path.
   `.c/.h` → C, `.py` → Python, `.java` → Java, `.js` → JavaScript, `.rs` → Rust, etc.
2. **Project name**: Derive from the source directory name.
3. **File list**: Scan the source path for all source files.
4. **Target framework**: Infer a sensible default from the target language:
   - C# → `.NET 8`
   - Rust → `Cargo / Rust 2024 edition`
   - Java → `JDK 21`
   - Kotlin → `Kotlin 2.0 / JVM`
   - TypeScript → `Node.js 22 / ESM`
   - Go → `Go 1.22`
   - Python → `Python 3.12`

### User Interview

Use **AskUserQuestion** with up to 4 questions per round. Every question must include
a "Use auto-detected default" option so the user can skip.

**Round 1 — Core Settings:**

| Question | Auto-Detect | Fallback |
|----------|-------------|----------|
| Source language | From file extensions | Ask user |
| Target language | From $ARGUMENTS if mentioned | Ask user |
| Source path | From $ARGUMENTS | Ask user |
| Target output path | `<source-dir>-<target-lang>/` | Ask user |

**Round 2 — Project Details (if needed):**

| Question | Auto-Detect | Fallback |
|----------|-------------|----------|
| Original project name | Directory name | Ask user |
| Port project name | `<project>.<TargetLang>` | Ask user |
| Target framework | From target language table above | Ask user |
| Platform abstraction layer | None if not applicable | Ask user |

Stop interviewing as soon as the user selects "Skip" or all values are known.

### Save Configuration

Write `port-results/<slug>/request.md`:

```markdown
# Port Request

## Configuration
- **Source Language**: {SOURCE_LANG}
- **Target Language**: {TARGET_LANG}
- **Original Project**: {ORIGINAL_PROJECT_NAME}
- **Source Path**: {SOURCE_PATH}
- **Port Project**: {PORT_PROJECT_NAME}
- **Port Path**: {PORT_PATH}
- **Target Framework**: {TARGET_FRAMEWORK}
- **Platform Layer**: {PLATFORM_LAYER}
- **Build Command**: {BUILD_COMMAND}
- **Run Command**: {RUN_COMMAND or "N/A"}

## Source Files
{FILE_LIST with file sizes}

## File Groups
{Groups of 2-3 related files that will be ported together}

## Original Request
{$ARGUMENTS}
```

### File Grouping

Group source files into batches of 2-3 related files:
- Header + implementation files together (e.g., `.h` + `.c`)
- Interface + implementation (e.g., `.java` interface + impl)
- Files that heavily reference each other (check imports/includes)
- Standalone files can be grouped by functional similarity

List the groups and total count before proceeding.

---

## Phase 1 — Port (per file group)

For each file group, spawn a **pa-porter** subagent:

> **Role**: Source code porter ({SOURCE_LANG} → {TARGET_LANG})
>
> **Original project**: {ORIGINAL_PROJECT_NAME}
> **Source path**: {SOURCE_PATH}
> **Port project**: {PORT_PROJECT_NAME}
> **Port path**: {PORT_PATH}
> **Target framework**: {TARGET_FRAMEWORK}
> **Platform layer**: {PLATFORM_LAYER}
>
> **Source files to port**:
> {List of files in this group with their full contents}
>
> **Type mapping rules**:
> {Language-specific type mapping — see references/porting-phases.md}
>
> **Instructions**: Read `references/porting-phases.md` Phase 1 — Porter section.
> Follow those instructions exactly. Write the ported files to {PORT_PATH}.
> Also write the inventory checklist to `port-results/<slug>/inventories/{filename}-inventory.md`.
>
> **Working directory**: {cwd}

After the porter finishes — **immediately start Phase 2** (this is not optional):
1. Verify the ported files exist at {PORT_PATH}
2. Read the inventory checklist
3. Print a ONE-LINE transition: "Group N ported (X files). Starting evaluation..."
4. **Spawn the auditor subagent in the same turn** — do NOT end your turn here

---

## Phase 2 — Evaluate (per file group) — NO PAUSE BEFORE THIS

You must arrive here directly from Phase 1 in the same turn. If you are reading this
after completing Phase 1, you should already be spawning the auditor — not asking the user.

Spawn a **pa-auditor** subagent:

> **Role**: Code port auditor ({SOURCE_LANG} → {TARGET_LANG})
>
> **Original project**: {ORIGINAL_PROJECT_NAME}
> **Source path**: {SOURCE_PATH}
> **Port project**: {PORT_PROJECT_NAME}
> **Port path**: {PORT_PATH}
>
> **Files to evaluate**:
> {List of original files AND their corresponding ported files — include full contents of both}
>
> **Instructions**: Read `references/porting-phases.md` Phase 2 — Auditor section.
> Follow those instructions exactly. Score each file 0-100 using the weighted rubric.
> Run two independent scoring passes and average them.
>
> **Output**: Write the evaluation to BOTH:
> - `port-results/<slug>/evaluations/{filename}-eval-{iteration}.json` (structured)
> - `port-results/<slug>/evaluations/{filename}-eval-{iteration}.md` (human-readable)
>
> **Working directory**: {cwd}

After the auditor finishes — **immediately apply Build Verification and Decision Gate** (do not stop):
1. Read the evaluation JSON
2. Extract scores and issue lists
3. Run Build & Run Verification (see below)
4. Apply the Decision Gate — spawn the fixer or move to next group **in the same turn**

### Build & Run Verification

After the auditor scores are in, attempt to **build and run** the ported project. This is
a hard requirement — code that doesn't compile cannot score 100%, regardless of the auditor's
assessment.

#### Project Scaffolding (first build only)

Before the first build attempt, set up the project scaffolding if it doesn't exist:
- Create the project file (`.csproj`, `Cargo.toml`, `build.gradle`, `tsconfig.json`, etc.)
- Add required dependencies/packages (e.g., SDL2-CS NuGet, crate dependencies)
- Ensure all ported files are included in the project
- Verify import/using statements reference the correct namespaces

This scaffolding is part of the port — do not skip it.

#### Step 1 — Detect and Verify Build Tools

Before running ANY build command, verify the toolchain is available:

```
# Check what's available — try the preferred tool first, fall back to alternatives
# Examples:
dotnet --version    # .NET
rustc --version     # Rust
javac --version     # Java
```

If the preferred build tool is **blocked by the sandbox or not installed**, immediately
try alternatives rather than reporting failure:

| Target | Preferred | Fallback 1 | Fallback 2 |
|--------|-----------|------------|------------|
| .NET / C# | `dotnet build` | `mcs` (Mono) | `csc` |
| C / C++ | `gcc`/`g++` | `cl.exe` (MSVC via vcvarsall) | `clang` |
| Rust | `cargo build` | `rustc` directly | — |
| Java | `gradle` | `mvn compile` | `javac` directly |
| TypeScript | `npx tsc` | `node --check` (syntax only) | — |
| Go | `go build` | — | — |

Record which build tool was selected in `request.md` under Build Command.

#### Step 2 — Build

Run the build command. Capture the **full** compiler output (stdout AND stderr).

| Target Framework | Build Command |
|------------------|---------------|
| .NET / C# | `dotnet build {PORT_PATH}` |
| Rust / Cargo | `cargo build --manifest-path {PORT_PATH}/Cargo.toml` |
| Java / Gradle | `gradle -p {PORT_PATH} compileJava` |
| Java / Maven | `mvn -f {PORT_PATH}/pom.xml compile` |
| TypeScript | `cd {PORT_PATH} && npx tsc --noEmit` |
| Go | `cd {PORT_PATH} && go build ./...` |
| Python | `python -m py_compile` on each file |
| C / C++ (MSVC) | `cl.exe /c /EHsc *.cpp /I{INCLUDE_PATHS}` then link |
| C / C++ (GCC) | `g++ -c *.cpp -I{INCLUDE_PATHS}` then link |

**Capture Results**:
- If the build **succeeds**: record `build_status: "pass"` in the evaluation
- If the build **fails**: capture the full compiler error output and record
  `build_status: "fail"` with `build_errors: [...]` in the evaluation

#### Step 3 — Run (if applicable)

If the project has a main entry point or executable target:
- Attempt to run it (with a short timeout, e.g., 10 seconds)
- Record whether it starts without crashing (`run_status: "pass" | "fail" | "n/a"`)
- Capture any runtime errors or crash output
- For projects without a clear entry point (libraries, etc.), set `run_status: "n/a"`

Build and run results are written to the evaluation JSON alongside auditor scores.

#### Common Build Issues (fix these directly, don't just report them)

These patterns come up repeatedly in ports. When you encounter them, fix them
inline rather than deferring to the fixer:

| Issue | Cause | Fix |
|-------|-------|-----|
| Type redefinition (C2011) | Same type defined in multiple headers | Add include guards or `#pragma once` |
| Missing forward declarations | Target language is stricter about declaration order | Add forward declarations at top of file |
| Implicit conversion errors | Target language requires explicit casts | Add explicit casts matching original intent |
| Wrong include paths | Package manager puts headers in different locations | Check actual installed path, update `#include` |
| Unresolved symbols (binary data) | Original linked binary blobs (e.g., GAMEPAL.OBJ) | Extract data from original source, embed as arrays |
| 64-bit pointer truncation | Original used pointer-as-integer tricks on 32-bit | Rewrite to use index-based lookup instead of pointer casts |
| Uninitialized memory/values | Original relied on DOS memory layout | Explicitly initialize (e.g., set `mainmem = 4*1024*1024L`) |
| Name collisions | Port introduced names that conflict with stdlib/framework | Rename the port's symbol (add suffix `_t`, prefix, etc.) |

When encountering build errors, **fix them yourself in the orchestrator** if they are
scaffolding/configuration issues (wrong paths, missing project refs, include guards).
Only send code-level issues to the pa-fixer subagent.

### Decision Gate — MECHANICAL, NO JUDGMENT

For each file in the group, apply these rules **mechanically** (no user input, no
judgment calls, no "good enough" exceptions):

| Condition | Action |
|-----------|--------|
| Auditor score = 100 AND build passes | **ACCEPT** — file is done, move to next group |
| Auditor score < 100 OR build fails | **Immediately** proceed to Phase 3 (Fix) |

**There is no retry limit.** A score of 99 is not accepted. A score of 88 is not
"close enough." Only 100 AND build passes. Period.

A file group cannot be accepted while the project has build errors, even if the auditor
gave it 100%. Build errors are treated as P0 issues.

Do NOT use your own judgment to override this gate. Do NOT accept files because you
think the remaining issues are "inherent language differences." The auditor rubric
already accounts for language differences. If the auditor says it's not 100, fix it.

When **every** group is accepted (score = 100, build passes, run passes/n/a), THEN and
ONLY THEN proceed to Final Report generation. Not before. Not with "remaining work."

---

## Phase 3 — Fix (per file group, if needed)

Proceed immediately when the decision gate routes here. Do not pause.

Spawn a **pa-fixer** subagent:

> **Role**: Code port corrector ({SOURCE_LANG} → {TARGET_LANG})
>
> **Original project**: {ORIGINAL_PROJECT_NAME}
> **Source path**: {SOURCE_PATH}
> **Port project**: {PORT_PROJECT_NAME}
> **Port path**: {PORT_PATH}
>
> **Input A — Original source files**:
> {Full contents of original files}
>
> **Input B — Current ported files**:
> {Full contents of current ported files}
>
> **Input C — Evaluation report**:
> {Full contents of the evaluation JSON/markdown}
>
> **Input D — Build/Run errors** (if any):
> {Full compiler error output and/or runtime crash output. If build passed, state "Build: PASS"}
>
> **Instructions**: Read `references/porting-phases.md` Phase 3 — Fixer section.
> Follow those instructions exactly. Fix every issue, P0 first.
> **Build errors are P0** — fix compilation failures before anything else.
> Overwrite the ported files in {PORT_PATH} with the corrected versions.
> Write the changelog to `port-results/<slug>/changelogs/{filename}-changelog-{iteration}.md`.
>
> **Working directory**: {cwd}

After the fixer finishes — **immediately loop back to Phase 2** (do not stop):
1. Verify the corrected files exist
2. Read the self-audit score
3. Check for recurring issues (same issue in 2+ consecutive iterations)
4. Print a ONE-LINE status: "Fix iteration N complete (self-audit: X%). Re-evaluating..."
5. **Spawn the auditor subagent in the same turn** — do NOT end your turn here

---

## State Tracking

Maintain a running state table. Update after every phase:

```
| File           | Iteration | Phase    | Score | P0s | Build | Status       |
|----------------|-----------|----------|-------|-----|-------|--------------|
| main.c         | 1         | PORT     | —     | —   | —     | In Progress  |
| main.c         | 1         | EVALUATE | 72    | 1   | FAIL  | Below Target |
| main.c         | 1         | FIX      | 72→85 | 0   | FAIL  | Below Target |
| main.c         | 2         | EVALUATE | 89    | 0   | PASS  | Below Target |
| ...            | ...       | ...      | ...   | ... | ...   | ...          |
| main.c         | 5         | EVALUATE | 100   | 0   | PASS  | Accepted     |
```

Print the state table after each phase completes.

### Recurring Issue Detection

If the same issue appears in two consecutive evaluations with no improvement:
- Try a different fix approach — re-read the original source for context
- If still stuck after 3 attempts at the same issue, try fixing it yourself in the
  orchestrator rather than delegating to the fixer again
- Systematic patterns across files may indicate a translation rule that needs adjusting —
  fix the rule and re-apply across all affected files

### Subagent Failure Recovery

Subagents may fail due to rate limits, token limits, tool errors, or sandbox restrictions.
When this happens:

| Failure | Recovery |
|---------|----------|
| Rate limit / throttle | Wait briefly, then retry the same task |
| Token limit (file too large) | Split the file group — send fewer files per subagent |
| Tool blocked by sandbox | Try an alternative tool/approach (e.g., different compiler) |
| Subagent returns incomplete output | Re-read the partial output, then spawn a new subagent to finish |
| Subagent crashes / no output | Retry once, then attempt the task directly in the orchestrator |

**Never treat a subagent failure as a reason to stop the pipeline.** Recover and continue.

---

## Report Generation

After **every iteration** (each pass through Evaluate or Fix), generate reports.

### Markdown Report

Write `port-results/<slug>/iteration-results-{NN}.md` (zero-padded: 01, 02, ...):

```markdown
# Iteration {N} Results

**Date**: {timestamp}
**Phase**: {PORT|EVALUATE|FIX}

## Files Processed
{Table of files with scores, changes, issues}

## Score Trajectory
{For each file: previous score → current score}

## Issues Found / Fixed
{Numbered list of issues with severity}

## Function Inventory
{Table of original functions → ported methods with confidence}

## Changelog (if fix phase)
{Table of changes made}

## Remaining Issues
{Any issues not yet resolved}

## State Table
{Current state of all files}
```

### HTML Reports

Read `references/html-templates.md` for the HTML templates. Generate:

1. **`port-results/<slug>/index.html`** — Main dashboard. Regenerate after every iteration
   with latest totals, scorecard, and links to iteration reports.

2. **`port-results/<slug>/iteration-results-{NN}.html`** — Per-iteration detail page.
   Generate once per iteration. Include navigation links (prev/next/dashboard).

Build the HTML by reading the templates from `references/html-templates.md` and replacing
the placeholder tokens with actual data. Use the color coding scheme from the templates.

---

## Parallel Execution

When there are multiple file groups, process them efficiently:

- **Sequential** (default for ≤ 3 groups): Process each group through the full
  Port→Evaluate→Fix loop before starting the next. Simpler, uses less context.

- **Parallel** (for > 3 groups): Spawn porter subagents for multiple groups simultaneously
  using the Agent tool. Then evaluate results as they come in. This is faster for large
  projects.

For parallel execution, spawn up to 3 porter subagents at once. As each finishes,
immediately spawn its auditor. This keeps the pipeline flowing.

---

## Final Report

**GATE CHECK — Do NOT proceed past this line unless ALL of these are true:**
- [ ] Every file group has been evaluated (zero unevaluated groups)
- [ ] Every file group has auditor score = 100
- [ ] The project builds with zero errors
- [ ] The project runs without crashing (or run_status = n/a for libraries)

If any box is unchecked, go back to the pipeline. Do not generate this report.

After all files are accepted and verified, write `port-results/<slug>/final-report.md`:

```markdown
# Final Port Report: {PORT_PROJECT_NAME}

## Summary
- **Source**: {ORIGINAL_PROJECT_NAME} ({SOURCE_LANG})
- **Target**: {PORT_PROJECT_NAME} ({TARGET_LANG})
- **Framework**: {TARGET_FRAMEWORK}
- **Date**: {timestamp}

## Build & Run Status
- **Build**: {PASS/FAIL} — {build command used}
- **Run**: {PASS/FAIL/N/A} — {run command used, if applicable}
- **Build errors resolved**: {count of build errors fixed during iteration}

## Scorecard
| File | Final Score | Band | Iterations | Status |
|------|-------------|------|------------|--------|

## Score Trajectories
{For each file: iteration-by-iteration score progression}

## Critical Issues Resolved
{Most impactful bugs caught and fixed, including build/runtime errors}

## Cross-File Dependencies
{Any stubs or // DEPENDENCY comments that need wiring up}

## Statistics
- Files ported: {X}
- Average final score: {X}
- Files accepted (100%): {X}
- Files accepted first pass: {X}
- Files requiring iteration: {X}
- Total iterations: {X}
- Build errors fixed: {X}
- Final build status: {PASS/FAIL}
```

Also regenerate `index.html` with final statistics.

---

## Type Mapping Generation

For each language pair, generate appropriate type mappings. Common pairs are documented
in `references/porting-phases.md` under "Language-Specific Type Mapping Examples".

For uncommon pairs, generate the mapping by:
1. Identifying the source language's primitive types
2. Finding the closest equivalent in the target language
3. Documenting any lossy conversions or semantic differences
4. Including this mapping in the porter subagent's prompt

---

## Important Notes

- **AUTONOMOUS EXECUTION IS A HARD CONSTRAINT.** After Phase 0, the pipeline runs to
  completion without any user interaction. The ONLY time you present results to the user
  is after all files score 100%, the project builds and runs, and the final report is
  generated. If you find yourself about to ask the user a question or present a phase
  summary, you are violating this constraint — immediately start the next phase instead.
- Each subagent runs in its own context. Pass ALL necessary information (file contents,
  config, evaluation reports) directly in the delegation prompt.
- Use named subagents: **pa-porter**, **pa-auditor**, **pa-fixer**.
- The original source code is ALWAYS the single source of truth.
- Quality over speed — do not accept low scores to move faster.
- Each fix iteration should show measurable improvement. If a fix doesn't improve the
  score by at least 5 points, re-examine the approach.
- Track recurring issues across files — these may indicate a systematic translation
  error that should be fixed as a rule for all remaining files.
- All output goes to `port-results/<slug>/`.
- **ZERO retry limit. There is no maximum number of iterations.** Keep iterating
  until 100% score AND build passes. Not 10 times, not 5 times — no limit.
- When porting related files (header + implementation), port them together.
- If a subagent encounters an error, recover and continue (see Subagent Failure Recovery).
- **Phase completion = immediately start next phase. Not a stopping point.**
- **Never generate a final report with "Remaining Work."** If there is remaining work,
  you are not done — keep iterating.
- **Never accept a file below 100.** Not 98, not 95, not 88. The auditor rubric
  accounts for language differences. If the auditor says < 100, fix it.
- **Build success is mandatory.** A port that doesn't compile is not a port.

## Reference Files

- **`references/porting-phases.md`**: Detailed instructions for each phase (Porter,
  Auditor, Fixer). Subagents should read the relevant section. Contains language-specific
  type mappings.
- **`references/html-templates.md`**: HTML templates for generating the dashboard
  (index.html) and per-iteration reports (iteration-results-NN.html).