version: "1.0.1" name: forward-port description: 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. metadata: internal: true

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:

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

Related

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