Programmable v4 Builder

A portable Agent Skill for turning a product idea or an existing repository into a complete, reviewable Programmable project with explicit evidence.

Maintained by Programmable · Developed in public · MIT licensed

Install · Use the Builder · Contribute · Security

Important

Release status

v0.4.0 is the latest published release. main contains the public v0.5.1 development source. Its integration on main, package version, or green CI does not make it a stable release. It does not activate Application V3 intake, Registry acceptance, deployment, or launch.

Programmable v4 Builder is an evidence-first Agent Skill. It accepts a plain idea or an existing public repository. Hooks, tokens, apps, games, services, standalone settlement systems, and mixed projects can all be modeled.

The Builder does not limit unfamiliar work to a fixed catalog. Starters and capability packs speed up repeated work; unknown ideas remain eligible for architecture review. Local checks stay separate from maintainer review, Registry acceptance, launch authority, deployment, provider support, and public availability.

Install the published release

Preview the exact published Skill before installing it:

gh skill preview 0xprogrammable/hookbuilder \
  programmable-v4-hook-builder@v0.4.0

Install the same immutable release for Codex:

gh skill install 0xprogrammable/hookbuilder \
  skills/programmable-v4-hook-builder \
  --agent codex \
  --scope user \
  --pin v0.4.0

GitHub's gh skill commands are in preview. Clean package placement has been checked for Codex, Claude Code, and GitHub Copilot; host behavior remains a separate question. See Portability and lifecycle before choosing another destination.

From the installed Skill directory, verify its package:

node scripts/verify-skill.mjs --installed

Then give your agent one clear request:

Use the Programmable v4 Builder skill. Start from this idea or repository: <idea or public GitHub URL>. Preserve the intended product, choose the smallest complete architecture, run the available checks, and prepare one exact GitHub application. Ask before any external write.

What the Builder does

Stage	Output
Understand	Preserves the stated product intent and isolates the owner choices that materially change it.
Design	Produces the smallest complete architecture, capability graph, value flow, and repository plan.
Build	Uses composable starters and capability packs without treating them as an allowlist.
Check	Runs deterministic validation, intent-fidelity checks, security boundaries, and executable evidence where available.
Bind	Closes over the exact public source repositories, commits, trees, files, and required evidence.
Prepare	Builds a local, source-bound application package and a read-only GitHub plan before any authorized write.

The Builder loads only the protocol, runtime, liquidity, service, and security material relevant to the confirmed project.

flowchart TD
  A["Idea or public repository"] --> B["Intent and material owner choices"]
  B --> C["Architecture and repository plan"]
  C --> D["Implementation and local checks"]
  D --> E["Exact source-bound application"]
  E --> F["Programmable maintainer review"]
  F -. "separate authority and evidence" .-> G["Registry acceptance"]
  G -. "separate authority and evidence" .-> H["Deployment and public availability"]

Loading

Inspect the local router on the development source:

node skills/programmable-v4-hook-builder/scripts/cli.mjs context --mode explore

Build it with us

The Builder is maintained by Programmable and developed in public. Contributions are welcome when they improve its accuracy, composability, efficiency, testability, portability, or documentation without weakening evidence bounds.

If you found or need	Start here
A reproducible defect	Open a bug report
A missing capability, source, or integration	Propose a capability
A code, documentation, template, or evaluation change	Read the contribution guide
A possible vulnerability	Report it privately

Each rule has one owning layer. Change the canonical contract and its tests instead of copying policy into several files. Pull requests should name the problem, owning layer, checks run, and remaining evidence boundary.

Evidence boundaries

A result can establish	It does not establish
A specific local check passed for exact bytes	An independent audit or a guarantee that code is safe
A package was placed and verified for one host directory	That the host selected or executed the Skill correctly
An exact GitHub application package was prepared	Maintainer acceptance, Registry activation, or launch authority
Deployment or source/runtime evidence exists	Provider indexing, quoting, simulation, execution, or public availability
A project resembles an existing Registry entry	Duplication, ineligibility, or unsafe behavior

The Builder builds and checks. It does not approve routes, execute trades, audit, deploy, list, endorse, or launch. Every external write, signature, deployment, publication, credentialed provider action, and material cost requires separate authority.

Technical contracts kept explicit on main

• Fee applicability follows the exact project graph. Zero-scope work must not invent a market, PoolKey, hook, or fee receipt.
• Each Programmable-canonical execution scope preserves the inclusive 10 bps share of executed gross quote-side swap or fill volume exactly once. Claim authority and platform administration remain separate roles.
• Fee V2 names four settlement profiles. The bundled Solidity kernel evidences only standard-amm; every other profile needs its own implementation, custody proof, tests, and review.
• Application V3 requires exact public GitHub source. Local, private, ZIP-packaged, pasted, or non-GitHub source can support exploration but remains INTEGRATION_PENDING.
• Local Launch Bundles remain unsigned and NOT_AUTHORIZED. The Registry Acceptance bridge is a bounded preflight, never Registry or production authority.

Read the canonical details in Open-World V2 architecture, Security and review, and Programmable platform boundaries.

Repository map

skills/programmable-v4-hook-builder/   canonical portable Skill
  references/                         routed knowledge, schemas, and policy
  assets/                             starters, capability packs, reference kernels
  scripts/                            deterministic tools and package tests
evals/                                adversarial agent evaluations
docs/                                 usage, architecture, security, release records
config/plugin.json                    canonical host metadata
plugins/programmable-v4-builder/      generated, byte-verified Codex payload
mcp/ and .mcp.json                    canonical Codex-only MCP companion

The portable Skill and root MCP files are canonical. Generated manifests and the Codex payload remain byte-aligned with them. See Architecture before changing package or host metadata.

Verify from source

Node.js 20 or newer is required. The repository has no npm runtime or development dependencies.

npm test
gh skill publish --dry-run

The two bundled reference fee kernels additionally use Foundry:

cd skills/programmable-v4-hook-builder/assets/reference-kernels/programmable-volume-fee-v1
forge test
cd ../programmable-volume-fee-v2
forge test

Model-backed evaluations are separate because they require provider credentials and may cost money. npm test still validates their structure; an unavailable model result or provider receipt is never treated as passed.

Documentation

Goal	Documents
Use the Builder	Agent Skill guide · GitHub application journey
Understand the system	Architecture · Open-World V2 · Knowledge routing
Extend it safely	Templates and extensions · Security and review · Contribution guide
Inspect portability and releases	Portability and lifecycle · Release gates · Release process

programmable-registry is the separate public application ledger and project archive. The Builder reads it; each project stays in its builder's own public GitHub repositories, and the platform repository remains responsible for contracts and the Explorer.

License and independence

Programmable v4 Builder is independent open-source software under the MIT License. Uniswap is a source protocol and ecosystem referenced by the Builder. This repository does not claim affiliation with or endorsement by Uniswap Labs or the Uniswap Foundation.