House of Quality

An interactive House of Quality (the first QFD matrix) with every formula written down, a diagonalised view that finds the modules and couplings in a design, a work-items view that checks "done" against your own tests, a spreadsheet generator with live formulas, and an MCP server, so an AI agent can build, fill, read and export the house through tools.

Three ways in:

It was built to run a real product review: sixteen stakeholder needs against twenty measurable characteristics, with gates, tickets and a weekly version of record. This repository is the generic version of that tool, with a small sample house (a commuter travel mug) so you can see every part working before you load your own.

For AI agents: the MCP server

mcp/server.js is a Model Context Protocol server over stdio. Any MCP client (Claude Code, Claude Desktop, Cursor, or your own script on the SDK) connects to it and gets the whole house as tools. The tools call the same web/hoq-core.js the page calls, so an agent and a person editing the page always get the same numbers.

git clone https://github.com/jerlandson-supernova/house-of-quality && cd house-of-quality && npm install
claude mcp add hoq -- node "$PWD/mcp/server.js" --file ./house.json

Then, in Claude Code:

You: Build a House of Quality for our new kettle. Interview me for the needs.

The agent calls house_new, asks who the stakeholders are, records each need in your words with its source through need_set, asks you for the importance of each one (it is not allowed to guess), adds the measurable characteristics with a unit, a direction and a target through characteristic_set, proposes each room cell out loud and sets them in one go with relationships_set_many, records the trade-offs with roof_set, and reads the empty rows and columns back to you from house_validate.

You: What should we build first?

The agent reads house_priorities for the top five and the gates, house_diagonal for the modules and the build order, and house_items once the tickets are in. house_export writes the dated TSV, the version of record, and house_draw a picture you can paste anywhere.

What the agent gets

Plus the resources hoq://house, hoq://report and hoq://drawing.svg, and a qfd_session prompt that walks the agent through a session in the right order. With --file, every change is saved to that JSON file, so the page can open the same file and the person can keep editing where the agent left off.

The rules an agent must keep are in docs/agent.md: needs come from stakeholders in their own words, importance is theirs to set, a characteristic has a unit, gates are never ranked, a board status is a claim, and the dated TSV is the version of record. npm test builds a house through the server and checks what comes back.

Related MCP server: ironcalc-mcp

Screenshots

The House: roof, room, right wall and basement, with the top five and the gates in the strip above it. Click any cell, dot or diamond.

The Diagonal view: the same room reordered so the relationships gather along the diagonal; the blocks are the modules, the dashed cells the couplings, and the tiles give the coupling verdict.

Work items: each item's share of the house, its board status, due date and effort, and your own test verdict read against the status.

The Input tab: load the sample, open or drop JSON or CSV files, paste JSON, edit the lists in place, download JSON, CSV or the dated TSV.

The same house drawn as SVG by node tools/hoq.js svg, which is also what the page's Download SVG, HOQ.draw() and the MCP server's house_draw produce:

What you get

Quick start

1. Open web/index.html. The sample house appears.

2. Click cells in the House: blank → △ 1 → ○ 3 → ● 9. Click the dots to set importance; type today and goal on the right wall; click a roof diamond. The basement, the charts and the Diagonal tab recompute.

3. Go to Input. Either edit the needs and characteristics in the tables, or open your own files: a house.json, or any of needs.csv, characteristics.csv, matrix.csv, roof.csv, items.csv (headers in docs/data-format.md; examples/csv/ has a filled set).

4. Download JSON to keep the house; Download TSV for the dated version of record you send around; Download the CSV files to keep it in a repository.

Everything you type stays in your browser's local storage until you download it. The page never sends anything anywhere.

The command line

node tools/hoq.js validate examples/sample-house.json     # errors and warnings
node tools/hoq.js report   examples/sample-house.json     # weights, ranks, gates, diagonal order, items, progress
node tools/hoq.js tsv      examples/sample-house.json     # writes sample-house-YYYY-MM-DD.tsv
node tools/hoq.js csv      examples/sample-house.json out/   # the five CSV files
node tools/hoq.js from-csv out/ house.json                # back to one JSON file

Add --gap to report or tsv to weight each need by importance × (goal ÷ today) instead of importance alone.

Draw a house from a JSON file

Two script tags and one call, for a wiki page, a report or a dashboard:

<script src="hoq-core.js"></script>
<div id="hoq"></div>
<script>HOQ.draw('#hoq', 'house.json', { reduce: true });</script>

reduce hides the rows and columns that take part in no relationship, so a big house reads small; symbols: false prints 9 3 1 instead of ● ○ △; mode: 'gap' weights by importance × (goal ÷ today). The same option is on the page as "Rows and columns: With relationships only", and on the command line as node tools/hoq.js svg house.json out.svg --reduce. Hiding never changes a number: weights, shares and ranks are always computed over the whole house.

The workbook

pip install openpyxl
python3 tools/make_xlsx.py examples/sample-house.json sample.xlsx

The workbook's inputs are the coloured cells (importance, today, goal, the room, the roof, difficulty); weighted importance, shares, ratios and ranks are formulas, so the sheet recalculates when the inputs change. The Diagonal sheet links every cell to the HoQ sheet and recomputes its measures, but its order and blocks are fixed at generation; re-run the script after large edits. The script runs node tools/hoq.js diag for the order; without node it skips that sheet.

The method in one paragraph

Write down what the stakeholders need, each with its source and an importance from 1 to 5. Write down the measurable characteristics the design must hit, each with a unit, a direction and a target. Rate every pair 9, 3, 1 or blank. Mark the characteristics that help or fight each other in the roof. Score where each need stands today against its goal. Read the basement: which characteristics carry the weight, and which are must-pass gates that should never be traded against features. Reorder the room along its diagonal to see the modules and the couplings between them. Link each characteristic to the work items that will deliver it, and read the board's status against your own tests. Send the dated TSV as the version of record. The long version, with the mistakes we made, is docs/method.md.

Repository layout

web/            index.html (the page), hoq-core.js (the formulas and the drawing), sample-house.js (the sample, loaded by the page), embed.html (HOQ.draw example)
mcp/            server.js (the MCP server), test-client.js (its test)
tools/          hoq.js (command line), make_xlsx.py (workbook)
examples/       sample-house.json and the same house as five CSV files
docs/           method, formulas, data format, diagonalization, agent (the MCP tools and the rules for an agent)

The page, the CLI, the drawing and the workbook need nothing installed beyond node (and python with openpyxl for the workbook). Only the MCP server has dependencies: npm install fetches the MCP SDK.

web/sample-house.js is generated from examples/sample-house.json with node tools/hoq.js sample-js examples/sample-house.json web/sample-house.js.

License

MIT. See LICENSE.