self-fork

name	self-fork
description	Forks this repository into a git worktree, runs a separate pi agent to make changes, runs tests/build, and prepares a GitHub pull request. Use when adding or improving assistant features safely.

Self-Fork Skill

This skill describes the workflow for making self-improvements safely by working in a git worktree, running tests, and creating a PR.

Prerequisites

• Git installed and available in PATH.
• GitHub repo configured as origin.
• Git user name/email set (GIT_USER_NAME, GIT_USER_EMAIL).
• GitHub token available as GITHUB_TOKEN (for PR creation).
• gh CLI installed or use GitHub REST API with GITHUB_TOKEN.

Workflow

Important: Never delete or modify fly.toml unless explicitly asked.

0) Make sure it's working

Please ensure we have access to the repo and git is configured correctly for pulling and pushing. If not, just stop and report back the exact error.

1) Create a worktree

Use the runtime repo at /data/repo (Fly volume) so origin is available. Always create a NEW worktree/branch for each self-fork request.

# Capture branch + worktree path
ENV=$(./scripts/self-fork.sh --env)
BRANCH=$(echo "$ENV" | awk -F= '/^BRANCH=/{print $2}')
WORKTREE_DIR=$(echo "$ENV" | awk -F= '/^WORKTREE_DIR=/{print $2}')

The script prints the worktree path (under /data/worktrees).

scripts/self-fork.sh will set git identity from GIT_USER_NAME and GIT_USER_EMAIL automatically.

2) Run a separate agent instance

• Use $WORKTREE_DIR from the step above.
• Start a new agent process in the worktree directory.
• Point tools/cwd to the worktree.
• Apply the requested improvements in the worktree only.

3) Build & tests

From the worktree directory:

./scripts/build-worktree.sh
# optional test step if added later
# npm test

4) Commit changes

Important: Do not call git directly. Always use the helper scripts so SSH is configured correctly.

./scripts/git-status.sh

./scripts/git-add.sh
./scripts/git-commit.sh "Self-update: <summary>"

5) Push branch

./scripts/git-push.sh "$BRANCH"

If BRANCH is empty, git-push.sh will push the current branch.

If you must run git manually, use the wrapper:

./scripts/git.sh <git-args>

6) Commit + push + PR (single step)

From the worktree directory:

./scripts/self-fork-pr.sh "<summary>"

This runs add/commit/push and creates a PR via gh.

Cleanup

After PR creation, remove the worktree if desired:

/data/repo/scripts/git.sh worktree remove "$WORKTREE_DIR"

To garbage collect old worktrees:

./scripts/cleanup-worktrees.sh