Docs

Core concepts

A goal is split into capabilities. For each capability the planner offers items to reuse or buy, plus a build option. It then searches for the plans no other plan beats on quality, cost and risk, and recommends one. This page defines each piece and shows real numbers.

Items and kinds

An item is anything reusable that has a link, a licence and optionally a price. Every item has a kind. (The self-hosted node calls an item a block; its identifiers, such as blk_ ids and the /api/blocks route, keep that name.)

On the hosted app an item is a listing, named owner/slug, and the catalog is what users have published or imported. On a node, an item id is blk_ followed by 16 hex characters, derived from the seller's key and the item name. Items come from two places: sellers who publish them (the bundled examples are published this way when you run seed), and free items the node finds online with --online (GitHub, the MCP registry, Hugging Face and any MCP servers you configured). Online finds are unsigned and free, and keep their origin.

Capabilities

The planner turns your goal into a set of capabilities: short tags for the jobs the finished thing must do. By default it matches words in your goal against a fixed taxonomy of 23 capabilities and keeps the best eight. English words are matched whole. Simplified Chinese terms are matched as substrings, for 22 of the 23 capabilities (ui-design has no Chinese terms yet). With --llm it asks Claude to split the goal instead, and may use tags outside the list.

Sellers declare capabilities on their items using the same tags. An item that declares the capability a requirement needs is a stronger match than one found only by text: when any candidate for a requirement declares it, only the declaring items are considered. The keyword planner is deliberately simple. If a goal is phrased unusually, check the requirements in the output before trusting the plan.

Quality, cost and risk

Each option for a requirement gets three numbers. Quality and risk run from 0 to 1. Cost is in US dollars.

Quality, higher is better

Quality is a weighted average of the signals an item has. Signals it lacks are left out, not counted as zero. An item with no signals scores 0.4: below average, never zero. On the hosted app the signals come from the listing: reviews, stars (including GitHub stars), downloads, the test pass rate, the date of the last update and archived status. On a node they come from the item and from attestations.

Three penalties then multiply the score, so they can only lower it and a missing signal changes nothing. Known vulnerabilities take off 20% per critical or high advisory and 4% per other one, at most 50% in total. For code kinds (repo, skill, harness, mcp_server), staleness multiplies by 0.6 plus 0.4 times freshness, where freshness is 1 within 90 days of the last update and falls in a straight line to 0 at four years. An archived item is multiplied by 0.7. Nothing in the hosted catalog or in the node's own discovery supplies scorecard, dependents or vulnerability counts yet. They apply when an item carries them.

The quality of a plan option is then scaled by how well the item fits the requirement (its text relevance, and whether it declares the capability). Seller-supplied signals are claims until someone verifies them. See Trust and verification.

Cost, lower is better

Cost is the sum of the prices of paid items, plus an estimate for each step you build. The default build estimate is $8.00 of agent tokens per missing piece. It is an estimate of your own agent's spend, not a charge by ReuseForge.

Risk, lower is better

Risk adds up named causes and is capped at 1:

The total is kept between 0 and 1. The rows from vulnerabilities down apply only when the item has that signal.

The Pareto plan

A plan picks one option per requirement. Its quality and risk are the averages over its steps, and its cost is the total. Plan A dominates plan B when A is at least as good on all three and strictly better on at least one. The Pareto front is every plan inside your budget that no other plan dominates. The planner searches this exactly, not by sampling, and returns up to 12 plans from the front.

The command line prints only the recommended plan. The whole front is the pareto_front field of the JSON that POST /api/plan returns on a node, and the hosted planner shows it as a chart. Because every plan on the front is a real trade-off, you choose how much to pay for quality. The recommended plan maximises quality minus 0.15 times risk, and breaks ties toward the cheaper plan.

Here is the front for the goal RAG chatbot over my PDF invoices with a dashboard and crypto checkout with no budget set, using only the bundled seed data (python -m repoblock seed). Your numbers will differ with other items.

Set a budget of 16 and only plan E fits. Set 10 and nothing fits: the planner says No plan fits the budget. Raise the budget or drop a requirement. It never quietly exceeds the budget.

Shared items are paid once

One item can cover several requirements. In the table above, the checkout kit declares both payments and crypto-payments. Plan B uses it for both and pays $15 once, so the plan costs $15 + $12 = $27, not $42. The escrow order (test mode) lists each paid item once, and the basket shows it once.

Build from a paper

Every requirement also gets a build option, which is how a plan fits a small budget or covers something nobody sells. With --online, each build step carries up to two arXiv papers as blueprints. Without it there is no blueprint, and the step scores lower on quality and higher on risk. The step is priced at the build estimate. Nobody is paid for it inside ReuseForge: it is work for your own agent.

python -m repoblock brief "voice assistant that sends telegram alerts" --budget 30 --online

brief prints a document for a coding agent. It lists what is already covered (integrate, do not rebuild), what must be built with its blueprint links and rough budget, MCP servers worth giving the agent, and the rules: ship with tests, record the licence of everything you use, and publish the finished piece back as an item. The last rule is what makes the next buyer's plan cheaper. ReuseForge writes the brief. Running the build is up to your agent.

Glossary

Last updated: 2026-11-03