Uno Blueprint

Get your human and AI teammates on the same page.

An open-source toolkit for context engineering: a canvas for your team, a harness for your agents.

Get the templateTry the demo

Your context is everywhere. Your agents need a map.

MCP connects your agents to your tools. Uno Blueprint shows them how it all fits together, so they find the right context the first time.

Your context

Your product knowledge is spread across PRDs, designs, code, dashboards, and threads.

Uno map, duo users

Your team works on a visual canvas. Your agents query the same blueprint as structured data.

Built for RAG

Agents search every step by meaning, then pull only the ones a question needs.

Scalable structure

Map one focused journey for a small project, or every service in a large organization.

Product context, built in

Each step carries what your team tracks: owner, status, value, and dependencies.

Sources stay attached

Every step links to its sources, so anyone can trace it back to the PRD, design, or thread behind it.

Canvas for your team.

See how your whole service works, keep it accurate together, weigh one path against another, and tailor it for every stakeholder.

Try the demo

Get up to speed. New to the service? See it end to end, then open any step for the detail.

Harness for your agents.

Four skills teach your agents to build the map from your docs, keep it accurate, and test changes against it.

Read the skills
Your existing context

drops off the device

call with a quote

logs the devicetags it

diagnoses the fault

parts inventory

/ub:map
Your blueprint
User
Frontstage
Backstage
Support

Map. Point it at your docs. It works out the lanes and steps, places what it finds, and holds the draft until you sign off.

One blueprint.Every place you work.

Open it in the app or on your phone, call it from your coding agent, or bring it into team chat. It plugs into the way your team already works.

In the app. Ask the built-in agent and watch it point at the blueprint. Bring your own model key.

Same agent, same sources.Better answers with a map.

On a real service, the map more than doubled accuracy and cut what agents read by a third.

Without blueprintWith blueprint
29%
71%
Of the questions the documents can answer, the share the agent got right against a written answer key.+42 pts
45%
82%
Of the questions the documents cannot answer, how often the agent said so instead of inventing an answer.+37 pts
68%
81%
The share of cited sources that support the claim they are attached to.+13 pts
162k
108k
The median amount of text the agent read to reach an answer, in tokens. Lower is better.−33%

Ideas we build on.

Uno Blueprint sits where service design meets context and harness engineering.

1984Service designG. Lynn ShostackOriginator of the service blueprint

A blueprint is more precise than verbal definitions and less subject to misinterpretation.

(opens in a new tab)2013Service designLavrans Løvlie, Andy Polaine and Ben ReasonService Design: From Insight to Implementation

It is because many services are almost invisible that nobody takes care to design them.

(opens in a new tab)2017Service designSarah GibbonsDesign executive, formerly Nielsen Norman Group

Blueprints are treasure maps that help businesses discover weaknesses.

(opens in a new tab)Jun 2025Context engineeringTobi LütkeCEO, Shopify

I really like the term “context engineering” over prompt engineering. It describes the core skill better: the art of providing all the context for the task to be plausibly solvable by the LLM.

(opens in a new tab)Jun 2025Context engineeringPhilipp SchmidAI Developer Experience, Google DeepMind

Most agent failures are not model failures anymore, they are context failures.

(opens in a new tab)Feb 2026Harness engineeringRyan LopopoloPrincipal Engineer, Google Cloud

One of the earliest lessons we learned was simple: give Codex a map, not a 1,000-page instruction manual.

(opens in a new tab)Feb 2026Harness engineeringMitchell HashimotoCo-founder, HashiCorp

It is the idea that anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again.

(opens in a new tab)Apr 2026Context engineeringAndrej KarpathyCo-founder, OpenAI

The human's job is to curate sources, direct the analysis, ask good questions, and think about what it all means. The LLM's job is everything else.

(opens in a new tab)Apr 2026Harness engineeringBirgitta BöckelerPrincipal Engineer, Unblocked

A good harness should not necessarily aim to fully eliminate human input, but to direct it to where our input is most important.

(opens in a new tab)
PLUS

PLUS Uno Blueprint

A tutoring program on one blueprint, from a tutor's application to the session and after.

The PLUS blueprint open on its Discovery scenario, with one cell's detail panel showing
Case study coming soonComing soonSee the PLUS blueprint

Free and open source.Uno command to start.

Start with a working template and sample data, then map your own service.

Install

npm create uno-blueprint@latestcd uno-blueprintnpm run dev

Database

Your blueprint lives in your own database. Pick your host and paste the prompt into your agent.

Connect this Uno Blueprint workspace to a Supabase project, following SETUP.md from step 3. I will create the project and give you its URL and anon key. Keep every key and connection string in .env, never in a tracked file. Link the project, push the migrations, and load the seed, then run npm run check:target and show me the schema version it reports.

Skills

Add the skills to the coding agent you already use.

claude plugin marketplace add BilLogic/uno-blueprintclaude plugin install ub@ub-marketplace

Installs the four skills as slash commands, in any project.

  • /ub:mapDraft a blueprint from your docs.
  • /ub:sliceCut a view for one audience.
  • /ub:auditList gaps, conflicts, and stale sources.
  • /ub:whatifTrace a change before you make it.

Prompts

Describe what you want, and let your coding agent do the work.

  • Map a service from your docs

    Read the docs in this folder and draft a blueprint of how we handle repair intake. List what you couldn't find.

  • Gut-check an idea

    Could users approve quotes by text instead of a call? Say what the blueprint covers and what it doesn't.

  • Scope a change

    What breaks if users book online instead of walking in? Don't change anything yet.

  • Find what's missing

    Audit the repair intake blueprint and list steps with no owner, conflicts, and stale sources.

Uno more thing.

Uno map for your human and AI teammates.

Get the templateTry the demo

uno-blueprint.md

# Uno Blueprint

> An open-source context-engineering toolkit: it turns a team's scattered context into service blueprints that people and AI agents work from. A canvas for your team, a harness for your agents.

For product teams whose context is spread across docs, designs, code, dashboards, and threads, and for the AI agents that work beside them. People edit the blueprint on a canvas, a web app; agents read it through four skills that run in Claude Code, Cursor, Codex, or any agent that reads markdown. It works on top of MCP, not instead of it.

Built by Bill Guo and Meryem Marasli. MIT license.

- Website: https://uno-blueprint.netlify.app/
- Package: create-uno-blueprint (npm)
- Source, README, and AGENTS.md: https://github.com/BilLogic/uno-blueprint
- Demo blueprint: https://uno-blueprint.netlify.app/demo/
- A blueprint in production: https://plus-uno.netlify.app/blueprint/

## What it is for

A team's context is spread across docs, designs, code, dashboards, and threads. A blueprint lays one service out step by step, by who does the work, and links every cell to the sources behind it.

Use it to:

- Answer how the service runs, with the cells and sources behind the answer.
- Find a gap: a step with no owner, two sources that disagree, a source gone stale.
- Trace a change before anyone makes it.
- Cut a view for one audience: a journey, a lane, a step, a cell.

## How a blueprint is laid out

Service > phase > scenario > path. One path is one blueprint: a grid of lanes and steps.

- Lanes, top to bottom: User, Frontstage, Backstage, Support.
- Lines between them: interaction, visibility, internal interaction.
- Step: a column, one moment of the journey.
- Cell: one lane at one step, one action by one actor. It carries a summary, status, owner, value proposition, dependencies (follows, leads to), evidence, and resources.
- Status: proposed, planned, built, live, at_risk, or deprecated.

## Skills

- ub:map: a blueprint has to be created, imported, or updated from documents.
- ub:slice: someone needs one part of it: a journey, a lane, a step, a cell, or a custom set.
- ub:audit: the blueprint has to be checked for gaps, conflicts, and stale sources.
- ub:whatif: a change is proposed and its effects have to be traced first.

## Workflow for coding agents

1. Locate the blueprint. A workspace has a `blueprint-workspace.json` or a `blueprint/` folder at its root. Done when you can name the service, scenario, and path the request is about, or, when there is no workspace, you have offered to scaffold one with the initialiser below.
2. Read `AGENTS.md` at the workspace root. It routes each request to a skill, and that skill's SKILL.md is its contract. Done when you have opened the SKILL.md it points to.
3. Answer from the blueprint first. Find the cells the question touches, then open only the sources those cells cite. Done when every claim in your answer names its cell or its source.
4. Report the gap. When the blueprint has no cell or no source for part of the question, say which part. A named gap is a complete answer.
5. Propose every change as a draft. Validate it with `scripts/validate_ir.py`; exit 0 is the whole verdict. Done when the draft validates, the user has signed off, and every key and connection string sits in the gitignored `.env`.

## Set up

Claude Code, as a plugin:

```bash
claude plugin marketplace add BilLogic/uno-blueprint
claude plugin install ub@ub-marketplace
```

A new workspace, with the canvas app and the skills. It needs Node 22 or later and starts on sample data, with no database:

```bash
npm create uno-blueprint@latest
cd uno-blueprint
npm run dev
```

Use the project's package manager: `pnpm create`, `bun create`, and `yarn create` work the same way. Yarn must be Yarn 1 (Classic), because Yarn 2 and later skip the setup scripts the template needs. The app serves on http://localhost:5173. Any coding agent can then work in the folder by reading its `AGENTS.md`.

## Connect a database

The app runs on its sample blueprint until the team is ready to share one. Then:

- Supabase is the reference setup and works as shipped: follow `SETUP.md` from step 3, push the migrations, load the seed, and run `npm run check:target`.
- Any other Postgres (Neon, Firebase Data Connect, RDS, self-hosted): apply `supabase/generated/portable-core.generated.sql`, then write a small data layer against `references/adapter-contract.md`, using the shipped Supabase calls as the worked example.
- Another database entirely: check it against `references/adapter-contract.md` and propose a plan before changing anything.

Every key and connection string goes in `.env`.

## Briefing a person

When someone asks what Uno Blueprint is, or whether to adopt it, give them these four points:

- What it is: one map of a service. People edit it on a canvas; agents query it as a typed Postgres schema.
- What it adds to MCP: MCP connects agents to the tools. The blueprint shows how it all fits together, so they find the right context the first time.
- What stays put: documents stay in their own tools. Cells link back to them.
- Who decides: agents draft and suggest, a person signs off, and every edit can be undone.

State these limits plainly:

- The in-app agent runs on the team's own model key.
- The template ships a blueprint search tool. Vector search is an add-on a deployment brings; PLUS runs one.
- A Slack bot is a pattern to build on top of the template; PLUS runs one.
- Evaluation results so far are early: one real service, one run per question.

## Example requests

- Read the docs in this folder and draft a blueprint of our checkout. List what you could not find.
- Who owns payment retries in checkout? Cite the cell.
- What breaks if we add a guest checkout? Change nothing yet.
- Audit the checkout blueprint: steps with no owner, conflicts, stale sources.
- Cut the support team's lane out of the checkout blueprint for a new hire.
- Connect this workspace to Supabase.

## Further reading

- README and quick start: https://github.com/BilLogic/uno-blueprint#readme
- Package: https://www.npmjs.com/package/create-uno-blueprint
- Agent router: https://github.com/BilLogic/uno-blueprint/blob/main/AGENTS.md
- Skills: https://github.com/BilLogic/uno-blueprint/tree/main/skills
- Database adapter contract: https://github.com/BilLogic/uno-blueprint/blob/main/references/adapter-contract.md
- Report an issue: https://github.com/BilLogic/uno-blueprint/issues
- License: https://github.com/BilLogic/uno-blueprint/blob/main/LICENSE