Sharpemu nid swarm

SharpEmu NID Swarm

Use a coordinator-led pipeline. Treat a NID as an opaque dispatch key, not an implementation specification. Require behavior evidence before source changes.

Agent-harness compatibility

This is one portable Agent Skill, not a Codex-only prompt. Resolve bundled scripts and references relative to this SKILL.md, regardless of where the active harness installed it. Read references/agent-harnesses.md before first use on Claude Code or Pi; it maps skill discovery, MCP access, large-output tools, subagents, and path conventions without changing the evidence gates below.

Preserve scope

• If the user requests analysis, comparison, or a report, stop after producing evidence artifacts. Do not edit emulator source.
• If the user explicitly requests implementation, proceed through every gate below.
• If the user requests validation, inspect and test the selected branch or PR without expanding into unrelated implementation.
• Use only binaries and game data the user placed in scope. Do not redistribute firmware, game data, or proprietary decompilation.

Preflight

1. Resolve the SharpEmu repository, current branch, worktree state, remotes, and exact base SHA. Preserve unrelated local changes.
2. Read the applicable AGENTS.md, CLAUDE.md, or host-native project instruction files. Use Context Mode for logs, Ghidra exports, recursive searches, test output, and large diffs when available. Otherwise keep large output in files and use the host's filtered/searchable output facility instead of pasting it into the conversation.
3. Check KawaiiDRA bridge_status through a direct MCP tool or the host's MCP proxy, then inspect the analyzed-binary/project inventory. Prefer the JPype bridge. Treat a Ghidra project as single-writer unless concurrent writes have been proven safe.
4. Confirm the target games, firmware/generation, runtime configuration, timeouts, and baseline checkpoints. Keep large game assets out of worktrees.
5. Choose a clean, pinned integration base. Never fan out writers from a moving branch or an unreviewed dirty checkout.

Read references/sharpemu-map.md for repo paths, local game-layout cautions, and command discovery.

1. Capture and normalize

Capture the complete identity of every unresolved import:

• NID, export name if known, library/module, generation, symbol type, and importing image.
• Game/build, call count, first and representative caller RIPs, ordering, and neighboring imports.
• Arguments, stack inputs, output buffers, return checks, state changes, and failure behavior.
• Source log and reproducible run configuration.

Create one run manifest. Keep manifest and tracker writes centralized; workers return patches or summaries to the coordinator.

Resolve the bundled scripts/nid_manifest.py to an absolute path and initialize a compatible CSV manifest with:

NID_MANIFEST=/absolute/path/to/sharpemu-nid-swarm/scripts/nid_manifest.py
python "$NID_MANIFEST" \
  from-csv INPUT.csv --output MANIFEST.json --game "GAME" --base-sha "SHA"

Read references/manifest-schema.md before changing statuses or hand-editing a manifest.

2. Resolve names and group work

1. Search existing SysAbiExport registrations, Aerolib, local catalogs, firmware symbols, and trusted reference-emulator catalogs.
2. Validate candidate names with SharpEmu's name2nid() algorithm. Never claim that an unknown NID was decoded from its string.
3. Group NIDs by shared state machine, library, owner source file, types, and lifecycle. Do not create one worktree per NID by default.
4. Rank clusters using first-failure criticality, cross-game fanout, call frequency, evidence confidence, and dependency order. A fatal one-call initializer may outrank a frequent query.
5. Keep unidentified or low-confidence NIDs in a research-only cluster.

Prefer clusters such as Font lifecycle, AudioPropagation, SaveData memory, Pad effects, or small independent services. Give a shared infrastructure file exactly one owner.

3. Build reverse-engineering evidence

Use one reverse-engineering lane per binary/project and feed implementation workers immutable evidence packets.

1. Use KawaiiDRA batch decompilation, signatures, variables, xrefs, call graphs, disassembly, memory reads, and data-type tools.
2. Follow real registration or call paths. Reject adjacent-string matches and other Base64-like noise unless call-site evidence confirms them.
3. Export large results to an ignored, allowed local path. Process them with ctx_execute_file or index by path, then retrieve only relevant snippets. Do not paste full Ghidra dumps into the main thread.
4. Record binary hash, Ghidra project, function address, callers/callees, inferred signature, reads/writes, constants, error codes, state transitions, and confidence.
5. Use reference emulators as behavioral evidence. Write an independent implementation; do not paste proprietary or license-incompatible decompilation.

4. Enforce the contract gate

Do not assign implementation until the evidence packet establishes:

• Exact NID identity and library/generation context.
• Candidate export name or an explicit unknown-name state.
• Calling convention and parameter/return interpretation.
• Required output-memory writes and validation rules.
• Handle, ownership, synchronization, and lifecycle effects.
• Expected success/error codes and caller reaction.
• Confidence of at least medium, with conflicts documented.

Blind success stubs are allowed only when evidence proves the caller ignores outputs and no state changes are required. Treat initialization, handles, synchronization, GPU, filesystem, SaveData, and memory APIs as stateful until proven otherwise.

5. Delegate by subsystem

For an explicit swarm or parallel-work request, use the available subagents. Read references/agent-contracts.md before delegation.

1. Keep the primary agent as coordinator and merge owner.
2. Create or assign one isolated worktree/branch per independent subsystem cluster, all from the pinned base. Use the host's established prefix (codex/, claude/, or pi/) when one exists; otherwise use agent/nid-<cluster>. Honor any user-specified prefix.
3. Assign one writer per file. Do not let workers edit the shared manifest, integration branch, or the same Ghidra project concurrently.
4. Pipeline roles when slots are limited: reverse engineer the next cluster, implement the reviewed cluster, and verify the previous cluster.
5. Require each worker to return evidence references, changed files, tests, risks, commit SHA if committed, and unresolved questions.

6. Implement the smallest correct contract

• Inspect existing SharpEmu state and related exports before introducing new state.
• Keep SysAbiExport NID, export name, library, target generation, and handler behavior consistent.
• Reuse shared types and lifecycle objects when semantics match.
• Validate guest pointers, sizes, alignments, handles, output buffers, and error paths.
• Add direct dispatch/ABI tests and focused state-transition tests. Test aliases and duplicate registration risks.
• Do not mix speculative renderer work or unrelated cleanup into an HLE NID branch.

7. Validate and integrate

Run branch-level gates in each worktree, then merge or cherry-pick through one serialized integration queue. Run full games only from the integrated build unless separate isolated runners are available.

Minimum gates:

1. Release build with warnings reviewed.
2. Relevant unit, source-generator, shader, and HLE tests discovered from the selected base.
3. Direct NID dispatch tests, return codes, output memory, and state-transition assertions.
4. Duplicate-NID and generation/library binding audit.
5. Integration build and complete test suite.
6. Fixed multi-game matrix comparing crashes, hangs, unresolved unique NIDs/calls, new errors, checkpoints, and frame evidence.
7. Regression attribution by cluster or commit; requeue failures instead of stacking speculative fixes.

Read references/validation-gates.md before merging or reporting game-level success.

8. Deliver durable results

Return or update:

• Machine-readable manifest with status per NID.
• Evidence packets with exact source addresses and confidence.
• Cluster branches/commits and file ownership.
• Validation report with commands, exit codes, and game checkpoints.
• Remaining queue, blockers, regressions, and recommended next cluster.

Validate the manifest at handoff:

python "$NID_MANIFEST" validate MANIFEST.json
python "$NID_MANIFEST" summary MANIFEST.json