agentleFS
Sign inStart free
yamcodesyamcodes/arkenv/skills/forward-port/SKILL.md

forward-port

Skill147 starsChanged 23 days agoMITView on GitHub

Manually forward-ports merged dev (v0) changes to the v1 branch, adapting code to v1's package layout and changeset names. Use when a dev PR is merged and needs v1 parity, when triaging "(v1)" reconciliation issues, or when the user mentions forward-porting, dual-tracking, or dev-to-v1 porting.

  • Commits and pushes

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 5 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Skip forward-porting: when work is (v1)-only, introduces dev-only structure, or should be implemented natively on v1.

    line 18
  2. Distinctive:

    If the user did not name a PR, issue, or commit, stop and ask before writing code.

    line 34
  3. Distinctive:

    Always include "Other - I'll specify" as the last option so the user can paste a PR/issue number.

    line 39
  4. Distinctive:

    If no candidates remain, say so and ask whether to port a specific PR/issue the user has in mind.

    line 40
  5. Distinctive:

    Do not guess or auto-pick when multiple candidates exist.

    line 42
  6. Distinctive:

    Read the merged dev PR: files, tests, changeset, linked issue.

    line 46
  7. Very specific:

    Run pnpm run typecheck, pnpm run test, and package-scoped tests if localized.

    line 70

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Forward-port (dev → v1)

ArkEnv runs dual-tracking: non-breaking work lands on dev (v0) first, then is manually adapted onto v1. Never merge dev into v1 wholesale - structural differences cause severe tree conflicts.

See REFERENCE.md for the full path/package map, changeset rename table, and real port examples.

When to forward-port

Forward-port after a merged dev PR that fixes a bug, adds a non-breaking feature, or updates shared integrations.

Skip forward-porting when work is (v1)-only, introduces dev-only structure, or should be implemented natively on v1.

Quick start

gh pr view <number> --json title,mergeCommit,files
git fetch origin v1 && git checkout -b forward-port/<name> origin/v1
# adapt changes (workflow below)
pnpm run typecheck && pnpm run test
gh pr create --base v1 --title "fix: Forward-port <summary> from dev"

Workflow

0. Pick what to port (if not specified)

If the user did not name a PR, issue, or commit, stop and ask before writing code.

  1. Discover candidates - recently merged dev PRs that touch published packages and likely need v1 parity (see REFERENCE.md - discovery commands).
  2. Filter out PRs already forward-ported (v1 PR title/body mentions the dev PR, or commit message contains Forward-port).
  3. Present multiple choice via AskQuestion with up to 4 candidates. Label each option as #1234 - short title (packages touched).
  4. Always include "Other - I'll specify" as the last option so the user can paste a PR/issue number.
  5. If no candidates remain, say so and ask whether to port a specific PR/issue the user has in mind.

Do not guess or auto-pick when multiple candidates exist.

1. Gather source context

Read the merged dev PR: files, tests, changeset, linked issue. Note behavior - re-implement, don't blind cherry-pick. Map each touched package using REFERENCE.md.

2. Adapt the implementation

Key path map:

devv1
packages/cli/src/**packages/arkenv/src/**
packages/arkenv/src/** (core)packages/core/src/**
nextjs, nuxt, build, …Same paths - verify imports

Checklist:

  • Fix imports (@arkenv/cli → arkenv, core → @arkenv/core)
  • Port tests and docs/examples if the dev PR touched them
  • Preserve v1-only decisions already on the branch (see REFERENCE)

3. Port the changeset

Rename frontmatter keys: "@arkenv/cli" → "arkenv", "arkenv" (core) → "@arkenv/core". Follow the changeset skill.

4. Verify and open PR

Run pnpm run typecheck, pnpm run test, and package-scoped tests if localized. Open PR targeting v1, link the dev PR and tracking issue.

Acceptance checklist

  • Behavior matches merged dev PR
  • No dev-only paths or imports remain
  • Changeset uses v1 package names
  • Tests pass on v1 branch

Common mistakes

MistakeFix
git merge dev into v1Feature-driven manual port
Blind cherry-pickRe-implement at v1 paths
"cli" in v1 changesetRename to "arkenv"
Core change in packages/arkenv/ on v1Core is packages/core/
Using the next npm tag on v1v1 publishes @alpha / @beta / @rc

Related

  • REFERENCE.md - path map, changeset table, examples
  • changeset skill
  • CONTRIBUTING.md Use Case 4

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free