rpk-developer

name	rpk-developer
description	The development workflow for rpk packages — the four-directory model, rpk init effects, and when to use stage vs install vs update. Trigger when a coding agent is developing an rpk-packaged project, when asking "where do I edit files?", "how do I test my changes?", or "what does rpk init do?". Use this BEFORE rpk-author when starting development on an existing package.

rpk-developer

The development workflow skill — understanding where files live, where to edit them, and how changes flow from development to installed package.

rpk 2.4 note (FEAT-030): the bare repo at $SELF_REPO/<pkg> is the canonical state for every package. The "source worktree" under ~/.local/src/<pkg> is optional and only exists when a developer explicitly materializes one via rpk source <pkg> [<dir>]. Consumer flow (rpk import → rpk install → rpk update) never touches ~/.local/src/. References below to "rpk stage" remain valid as the legacy verb (kept for back-compat); prefer rpk source <pkg> [<dir>] in new automation. The user can run rpk migrate once after upgrading from 2.3.x to clean up legacy source clones that are no longer needed.

When to use

• A coding agent is working on a project that uses rpk packaging
• The user asks "where do I edit files for this package?"
• The user asks "how do I test my changes before releasing?"
• The user asks "what does rpk init actually do?"
• Before rpk-author when starting work on an existing package
• After rpk-author when scaffolding is complete and development begins

The four-directory model

Rpk uses four distinct directories for each package. Understanding their roles is critical for correct development workflow.

~/Projekte/<project>/              # 1. Dev clone — EDIT HERE
         │
         └─git push local master→  ~/.local/var/lib/repo/<project>/  # 2. Bare repo (hub)
                                                │
                                                └─rpk stage→  ~/.local/src/<project>/  # 3. Worktree (staged)
                                                         │
                                                         └─rpk package→  ~/.local/pkg/<project>-<ver>/  # 4. Bundle

1. Dev clone: ~/Projekte/<project>/

Purpose: Where you edit source code, write tests, commit changes.

• This is a regular git clone, typically under ~/Projekte/ or similar
• Edit files here using your editor, IDE, or coding agent
• Commit with standard git add, git commit
• Push to bare repo with git push local master (or git push origin master)

Key rule: NEVER run rpk package or rpk install from here. These commands require a staged worktree.

2. Bare repo: ~/.local/var/lib/repo/<project>/

Purpose: The synchronization hub between dev clones and worktrees.

• Created by rpk init or manually via git clone --bare
• Never edit files here directly
• Acts as the "local remote" — dev clones push here, worktrees pull from here
• Named local in git remotes (e.g., git push local master)

Key rule: Think of it as a read-only sync point. All changes come from dev clones.

3. Worktree: ~/.local/src/<project>/

Purpose: The staged checkout where packaging runs.

• Created by rpk stage <project> from the bare repo
• Contains a clean checkout of the bare repo at a specific ref
• rpk package <project> runs .rpk/package from here
• rpk patch/minor/major <project> commits version bumps here

Key rule: NEVER edit files here manually. Always edit in the dev clone, then push to bare and re-stage. Manual edits will be overwritten on next rpk stage.

4. Bundle: ~/.local/pkg/<project>-<version>/

Purpose: The installable package artifact.

• Created by rpk package <project> <version> from the worktree
• Contains the built/installed files ready for stow
• rpk install <project> symlinks this into ~/.local/ hierarchy

Key rule: Never modify bundles directly. Rebuild with rpk package to update.

When to use each command

Command	Runs from	Effect
rpk init	Dev clone	Creates .rpk/identity, .rpk/spec, commits, pushes to bare
rpk stage <project>	Anywhere	Creates worktree at ~/.local/src/<project>/ from bare
rpk package <project> <ver>	Anywhere	Builds bundle from worktree (must be staged first)
rpk install <project>	Anywhere	Symlinks bundle into ~/.local/
rpk update <project>	Anywhere	Pulls worktree from bare, packages, installs
rpk patch/minor/major	Dev clone preferred	Bumps version in worktree, commits, pushes to bare

What rpk init does

When you run rpk init in a dev clone:

1. Creates .rpk/identity: Package name and type
2. Creates .rpk/spec: Package metadata (dependencies, etc.)
3. Commits all .rpk/ files: Single "init" commit
4. Pushes to bare repo: Creates ~/.local/var/lib/repo/<project>/ if needed

This is a one-time setup for new packages. After init, you edit .rpk/ files directly and commit them as normal code changes.

Development workflow (edit → stage → test → release)

Making code changes

1. Edit in dev clone (~/Projekte/<project>/)
2. Commit normally: git add -A && git commit -m "fix: something"
3. Push to bare: git push local master
4. Re-stage or update:
   • For quick testing: rpk update <project> (pulls worktree, builds, installs)
   • For versioned release: rpk patch <project> then rpk update <project>

Testing without installing

To test .rpk/package changes without creating a new version:

# From dev clone, push changes to bare
git push local master

# Re-stage the worktree
rpk stage <project>

# Build into temp prefix
cd ~/.local/src/<project>
./configure --prefix=/tmp/test-pkg
make install
ls /tmp/test-pkg/

Testing install scripts

After rpk package <project> <version>:

# Debug the install script
bash -x ~/.local/pkg/<project>-<version>/.rpk/install

# Or dry-run the stow
stow -n -d ~/.local/pkg -t ~/.local <project>-<version>

Branch coordination

The dev clone and bare repo must agree on the default branch:

• Dev clone: Check with git branch --show-current or git remote show local
• Bare repo: Check with git --git-dir=~/.local/var/lib/repo/<project> branch

If they disagree, rpk doctor will warn. Fix by:

# From dev clone
git push local --set-upstream master master

Or update the bare repo's HEAD:

git --git-dir=~/.local/var/lib/repo/<project> symbolic-ref HEAD refs/heads/master

Common mistakes

Editing the worktree directly

Wrong:

cd ~/.local/src/<project>
vim bin/rpk    # Changes will be lost on next stage!

Right:

cd ~/Projekte/<project>
vim bin/rpk
git commit -am "fix: something"
git push local master
rpk update <project>

Running package from dev clone

Wrong:

cd ~/Projekte/<project>
rpk package <project> 2.1.0    # Error: no worktree

Right:

cd ~/Projekte/<project>
rpk stage <project>            # Create worktree first
rpk package <project> 2.1.0    # Now works

Forgetting to push before staging

Wrong:

cd ~/Projekte/<project>
# Made commits...
rpk stage <project>    # Stage gets old version from bare!

Right:

cd ~/Projekte/<project>
# Made commits...
git push local master   # Sync bare first
rpk stage <project>    # Now stage gets latest

For coding agents

When a coding agent works on an rpk-packaged project:

1. Always ask: Is this project rpk-packaged? Check for .rpk/ directory at repo root.

2. Edit in dev clone: Make all code changes in ~/Projekte/<project>/ or wherever the user's repo lives. Never edit ~/.local/src/<project>/.

3. Push before stage: After committing, git push local master before running rpk stage or rpk update.

4. Use rpk update for testing: The fastest loop is:

   • Edit in dev clone
   • Commit + push to bare
   • rpk update <project> (pulls worktree, builds, installs)

5. Use rpk patch/minor/major for releases: These bump version in worktree, commit, and push. Then rpk update to install.

6. Check INSTALL_PREFIX: If testing install scripts, use a temp prefix to avoid clobbering the user's environment.

Related skills

• rpk-author: Scaffolding .rpk/ for new packages
• rpk-version: Bumping rpk's own version (meta-package)

See also

• man rpk for full command reference
• docs/PACKAGING.md for package authoring details
• .rpk/identity for package name and type