vibe-fork

A Claude Code skill for sequential translation of a known-working upstream codebase to a new substrate — e.g. C kernel → Rust kernel, PyTorch C++ → Rust ML framework, COBOL → Java.

It installs a 4-agent loop, two PreToolUse hooks, a route table, and a binding goal.md contract that together prevent the most common failure mode: the agent reads the upstream once, hand-waves the "vibe" of it, writes plausible-looking target-language code that compiles but silently diverges from upstream on edge cases (NaN propagation, overflow, broadcasting, dtype promotion, error sentinel values).

The fix is mechanical discipline: every translation unit goes through a read → write → verify → commit loop where verification is adversarial (a critic agent hunts divergence) and the divergence pin is a failing test, not prose.

When to use

• "I want to vibe fork PyTorch into Rust"
• "Let's translate Linux + grsec to Rust"
• "Port this Python lib to Go"
• "Set up the same agent-loop scaffolding as the other project"

When NOT to use

• Greenfield projects with no upstream to translate (use /design or /feature instead)
• Standalone library work where there's nothing to port from
• Documentation-only or tooling-only projects

Install

Clone this repo somewhere persistent and symlink the skill into ~/.claude/skills/:

git clone <this-repo> ~/src/vibe-fork
ln -s ~/src/vibe-fork/vibe-fork ~/.claude/skills/vibe-fork

Claude Code picks up the skill on next launch. Trigger it by saying "vibe fork", "translate X to Y", "port codebase", or invoking /vibe-fork.

Bootstrap into a new project

cd /path/to/new-project   # must be a git repo
bash ~/.claude/skills/vibe-fork/bootstrap.sh

The script is idempotent — existing files are skipped, not overwritten. It lays down:

1. .claude/agents/ — the four acto-* agent specs
2. tooling/translate-discipline.py + tooling/anti-pattern-gate.py — PreToolUse hooks
3. tooling/translate-routes.toml — route table starter
4. goal.md — the binding contract (customize placeholders)
5. .design/00-index.md — design-doc index
6. .claude/settings.json — hook registration

After bootstrap: customize goal.md, customize the hook constants (UPSTREAM_ROOT, TARGET_CRATE_PREFIXES), add your first route, and begin the loop on your first translation unit.

What's inside

The four agents

Agent	Role	Tools
acto-doc-author	Writes design docs that ADAPT to existing code. No Edit on production.	Read, Write, Bash, Grep, Glob
acto-builder	Ships cross-cutting infrastructure with a pre-declared file manifest.	Read, Edit, Write, Bash, Grep, Glob
acto-critic	Hunts semantic divergence. Writes FAILING tests pinning each divergence. Never fixes.	Read, Write, Bash, Grep, Glob
acto-fixer	Applies the MINIMAL fix for ONE pinned divergence. Never bundles.	Read, Edit, Write, Bash, Grep, Glob

The loop: builder → critic → (fixer → critic)* → next unit. Every builder/fixer dispatch is followed by a critic. No exceptions.

The two hooks

• translate-discipline.py — gates Edit/Write on routed target files. Requires that in the SAME session the agent has Read (1) goal.md, (2) at least one upstream file from the route, and (3) the route's design doc. Per-worktree state at .crosslink/.translate-reads.json.
• anti-pattern-gate.py — blocks todo!() / unimplemented!() / unreachable!(), .unwrap() / .expect() outside #[cfg(test)], panic!() in production, module-root #![allow], and silent CPU↔GPU round trips.

The route table

tooling/translate-routes.toml maps every target file to its upstream source(s) and design doc — the single source of truth the hook reads to enforce "read before write". Files without a matching route are blocked until one is added.

The 8-step loop

1. Read the target file
2. Read every upstream file in the route
3. Read the design doc (or dispatch acto-doc-author if missing)
4. File an issue / plan comment listing upstream cites and verification ops
5. Write the implementation — no stubs, no todo!(), no vocabulary-only shipping
6. Update the ## REQ status table in the module's //! doc-comment (SHIPPED or NOT-STARTED — two states only)
7. Run the gauntlet: per-crate tests, parity/conformance ops, clippy -D warnings, fmt check
8. Commit with the structured message (upstream files opened, design doc read, REQ status, verification results)

Full reference in vibe-fork/SKILL.md.

Repo layout

vibe-fork/
  SKILL.md              # full skill specification (loaded by Claude Code)
  bootstrap.sh          # idempotent installer for new projects
  templates/
    goal.md             # binding-contract template with placeholders
    agents/             # the four acto-* agent specs
    tooling/            # the two hooks + route-table starter

Provenance

Derived from two production deployments that share the same architecture:

• ferrotorch — PyTorch C++ → Rust ML framework
• Rookery-Kernel — Linux 7.1 + grsec C → Rust kernel

The harness is language-and-target-agnostic. Substrate-specific rules go in goal.md's "Anti-drift rules" section, which the user customizes per translation.

License

See LICENSE.