Port feature

A code port, not a copy. The feature already works somewhere else. The job is to make it work here, the way this project does things, with the lessons the source repo already paid for.

Not for ideas from apps the user does not own (use the reference-hunt skill), and not for brand new features with no source.

0. Inputs

• The feature, in one sentence. Example: "the share sheet capture", "the onboarding flow", "the streak counter".
• The source repo path. If the user did not give one, ask for it. One question, then wait. Do not guess from folder names.

Read this project's rules file (CLAUDE.md or AGENTS.md) first. It is the target. If there is none, read the code around where the feature will live and say in the summary that conventions were inferred.

1. Reach the source

• Local path: read it directly. Read only. Never edit, commit or run installs in the source repo.
• Not on this machine: use whatever code search the session has (for example gh search code --repo <owner>/<name> <symbol>, or a connected GitHub tool), or a shallow read only clone into a scratch folder. If none of that works, ask the user to clone it locally. Do not rebuild the feature from memory or guesses.

2. Read the feature end to end

Before writing anything, trace the whole feature in the source and note:

• Entry points: screens, routes, deep links, notifications, share targets.
• UI: components, styling tokens, copy, images and other assets.
• State and data: stores, hooks, local storage keys, database tables, migrations, server endpoints, background jobs.
• Dependencies: each package and its exact version, config plugins, app config entries, native code, permissions.
• Analytics and flags: events fired, feature flags, paywall or premium checks.
• Tests: unit, component and end to end tests that cover it.
• Gotchas: search the source's rules file, decisions log and commit history for anything about this feature. These are the lessons you do not want to learn twice.

Keep a file list as you go. If the trace is getting long, the feature is bigger than it looked; tell the user and offer to port it in slices.

3. Map it onto this project

Write a short port plan and show it to the user before coding. Three parts:

Changes. Each source piece and its home here. Translate, do not paste:

• Folder layout and routing (for example the source uses app/, this project uses src/app/).
• Theme, spacing and colour tokens; use this project's, not the source's.
• State and data: reuse this project's existing stores, services and helpers instead of porting the source's data layer. If the source calls a server and this project works on device (or the other way round), route through the local equivalent.
• Naming, exports, file idiom and test style from this project's conventions.
• Analytics events renamed to fit this project's event naming.

Left behind. Name each thing you are not bringing, and why:

• Secrets, API keys, DSNs, webhook URLs, env values, .env files. Never copy these. List the env var names this project will need and let the user fill them.
• The other app's name, bundle id, copy, screenshots, icons, brand colours and anything about its users or their data.
• Code the source needs only because of its own history (migrations from old versions, workarounds for bugs this project does not have).
• Parts of the feature the user did not ask for.

Gotchas carried over. Each relevant source gotcha, reworded for this project.

4. Check dependencies fit

For each package: npm view <pkg>@<version> peerDependencies and compare with this project's Expo and React Native versions before installing. For Expo packages prefer npx expo install <pkg> so the version matches the SDK. If the source pins an old version, check whether the newer one changed its API.

Flag native modules early. They mean the app leaves Expo Go and needs a prebuild and a development build. That is a step the user may have to run.

5. Build it

Port in this order, running the check command after each step:

1. Dependencies and config.
2. Data and state (or the wiring into existing stores).
3. Logic, with its unit tests ported alongside.
4. UI and navigation.
5. Analytics and flags.

Replace every piece of the other app's copy with copy written for this project. If you do not know what it should say, leave a clear placeholder and list it in the summary.

6. Port the tests

Bring the source's tests over and adapt them to this project's test setup. A test that passed in the source and fails here is a finding, not a nuisance: either the port is wrong or the assumption no longer holds. Fix the cause. Where the source had no tests for a path that matters, add one.

7. Prove it works here

• Run the check command from the rules file Settings [npm run check, or lint, typecheck and tests]. It must be clean.
• Run the app and walk the feature's main path. Use a simulator or emulator if the session can drive one; otherwise say so plainly.
• Search the changed files for the source app's name, bundle id, domains and env values. Nothing should match.
• If the feature has a user facing surface, add an item to the release checklist (RELEASE_TEST_CHECKLIST.md) with the surface, steps and expected result.

8. Record it

• Add the carried over gotchas to this project's rules file Gotchas, dated.
• If the port added a subsystem, add one line to the rules file Architecture.
• If the project keeps a features doc, add the feature there.

Summary

Finish with a short summary:

• What was ported and where it lives now.
• What changed in the translation, in a few lines.
• What was left behind and why.
• Env vars, native rebuilds or store setup the user has to do by hand.
• Copy placeholders still to write.

Good: "Ported the share sheet capture from your other app. Reused this app's on device categoriser instead of the source's server call. Carried over the gotcha about the share extension's bundle id suffix. Native module, so it needs a development build. Two copy placeholders on the empty state."

Bad: "Copied the share feature over." No convention mapping, no gotchas, no proof, and probably the other app's strings still inside.