v2.0.0 · MIT licensed · 44 tests passing

AI skills that find the design decisions you didn't make.

mindit walks any design through eight forces every decision has to balance. Each force is its own skill. Each run produces a scored, structured artifact you can commit to your repo and grep six months later.

Layers gives you a thinking framework. mindit gives you eight numbers, a CLI, and an MCP server.

terminal
# one global install, one-command setup npm install -g usemindit usemindit add claude-code

01New in v2

v1 was skills + schema. v2 is everything that makes them actually usable across tools, validatable across time, and inspectable when something goes wrong.

Shipped
  • cli usemindit add, init, list, lint, mcp
  • mcp Eleven skills exposed as MCP tools over stdio (plus a mindit_schema tool)
  • lint Schema validation, depends_on resolution, orphan detection
  • install Multi-tool support: Claude Code, Claude Desktop, Cursor, Codex, Cline
  • tests 44 tests covering schema, fixtures, CLI, lint behavior, MCP roundtrips

02The eight forces

Every design decision balances eight competing pressures. mindit names them and scores each one. A finished design has a force profile; lopsided profiles fail. A design at 90 Clarity and 20 Correctability hasn't been thought through, it's been polished.

01Clarity
Can a stranger read the intent in five seconds?
02Continuity
Does this fit the system that already exists?
03Constraint
What hard limits is this honoring?
04Consequence
What does this foreclose? What does it open?
05Context
Who, when, where, on what device, in what state?
06Cost
Build, support, maintenance, debt — what's the lifetime bill?
07Confidence
What evidence stands behind this?
08Correctability
If we're wrong, how reversible is it?

03The eleven skills

Eight skills for the eight forces, plus three meta skills that combine them.

/mindit-clarity
Hierarchy, labeling, affordance, density, distinguishability, first-glance test.
/mindit-continuity
Convention alignment, component reuse, naming, state, visual alignment.
/mindit-constraint
Accessibility, technical, legal, brand, platform, time-budget.
/mindit-consequence
Reversibility, path foreclosure, data implications, lock-in, second-order effects.
/mindit-context
Audience, device, state, journey position, environmental fit.
/mindit-cost
Build complexity, support burden, maintenance, debt, marketing cost, TCO.
/mindit-confidence
Evidence type, freshness, breadth, mechanism, triangulation.
/mindit-correctability
User undo, system rollback, detection latency, blast radius, pre-commit gates.
/mindit-audit
Runs all eight forces. Identifies the bottleneck. Bottleneck score, not average.
/mindit-premortem
Imagine it failed three months from now. Surface failure modes. Rank by severity.
/mindit-trace
Walk the decision graph in .mindit/decisions/ backward and forward.

04What it produces

Every skill writes two files to .mindit/decisions/: a markdown artifact for humans, and a JSON artifact that conforms to the decision schema. Diff-able in git. Queryable by tools. Traceable through the graph.

.mindit/decisions/clarity-20260511-pricing-hero.json
{ "id": "clarity-20260511-pricing-hero", "skill": "mindit-clarity", "subject": { "name": "Pricing page hero", "type": "screen" }, "force": "clarity", "score": 51, "criteria": [ { "name": "Hierarchy", "score": 32, "weight": 0.25 }, { "name": "Labeling", "score": 71, "weight": 0.20 }, { "name": "Affordance", "score": 60, "weight": 0.20 }, { "name": "Density", "score": 80, "weight": 0.15 }, { "name": "Distinguishability", "score": 55, "weight": 0.10 }, { "name": "First-glance test", "score": 25, "weight": 0.10 } ], "findings": [ { "severity": "high", "anti_pattern": "buried-primary-action", "summary": "Pricing tiers sit below the fold; hero is a stock photo.", "fix": "Move the three-tier comparison above the fold." } ], "created_at": "2026-05-11T10:14:00Z", "version": "2.0.0" }

05Anti-pattern registry

Each force ships with a registry of named failure modes. 64 patterns across 8 forces, each with a symptom, an example, a fix, and a severity. When a finding matches a pattern, the slug goes in the artifact — so you can grep your decision graph for any anti-pattern.

  • buried-primary-action · clarity
  • one-off-component · continuity
  • accessibility-afterthought · constraint
  • one-way-door · consequence
  • desktop-prototype · context
  • snowflake-feature · cost
  • n-of-one · confidence
  • big-bang-launch · correctability

06Install

One command. Most AI tools that read the SKILL.md convention pick the skills up automatically once the CLI has placed them.

terminal
# global install, project-local skill placement npm install -g usemindit usemindit add claude-code # or install once, use via npx npx usemindit add claude-code # supported targets: usemindit add claude-code # ./.claude/skills/ usemindit add cursor # ./.cursor/rules/ usemindit add codex # ./.codex/skills/ usemindit add cline # ./.clinerules/ usemindit add claude-desktop # prints MCP config snippet

07The CLI

Five commands. Zero config. Everything you need to install, list, validate, and serve mindit.

usemindit init
Create .mindit/decisions/ in the current project, ready to receive artifacts.
usemindit add <tool>
Install the eleven skills into Claude Code, Cursor, Codex, Cline, or an arbitrary path.
usemindit list
Print the eleven skills and what each one analyzes.
usemindit lint [path]
Validate every decision artifact against the schema and the decision graph.
usemindit mcp
Start the mindit MCP server on stdio. Twelve tools available.
a normal day
$ usemindit init ✓ Created .mindit/decisions/ in /home/dragoon/my-project $ usemindit add claude-code ✓ Installed 19 files into Claude Code Path: /home/dragoon/my-project/.claude/skills # now invoke a skill in your AI tool: # /mindit-clarity Review the hero on https://example.com/pricing # a decision artifact gets written to .mindit/decisions/ $ usemindit lint ✓ All clean. # or surfaces specific issues

08Lint your decision graph

Skills produce artifacts. Artifacts reference each other. Over months, that graph drifts. usemindit lint catches the drift before it becomes a mystery.

Checks performed on every .mindit/decisions/ artifact:

  • Every JSON file parses
  • Every JSON file validates against schemas/decision.schema.json
  • Every JSON has a markdown sibling (and vice versa)
  • Every id field matches its filename
  • Every depends_on reference resolves to an existing artifact
usemindit lint output
$ usemindit lint mindit lint /home/dragoon/my-project/.mindit/decisions 3 artifacts scanned ✗ consequence-20260511-deletion.json depends_on reference "research-20260301-deletion-interviews" not found in this decision graph ! cost-20260308-onboarding.json Missing companion markdown file (expected cost-20260308-onboarding.md) Summary: 1 error, 1 warning

Exit code 0 means clean, 1 means errors, 2 means warnings only. Wire it into your CI.

09MCP server

Run usemindit mcp to expose all eleven skills as MCP tools over stdio. Compatible with Claude Desktop, Cursor's MCP support, and any other MCP client.

Twelve tools advertised: mindit_clarity, mindit_continuity, ..., mindit_audit, mindit_premortem, mindit_trace, plus mindit_schema which returns the JSON Schema for client-side validation.

~/Library/Application Support/Claude/claude_desktop_config.json
{ "mcpServers": { "mindit": { "command": "npx", "args": ["usemindit", "mcp"] } } }

Restart Claude Desktop. The eleven mindit tools appear in your tool list. Cursor, Cline, and other MCP clients work the same way — point them at npx usemindit mcp.

10Repository layout

usemindit/
usemindit/ ├── README.md, DISCLAIMER.md, LICENSE ├── package.json ├── bin/ │ └── usemindit.js # CLI entry point ├── src/ │ ├── cli/ # init, add, list, lint, help │ ├── mcp/server.js # MCP server (stdio) │ └── lib/ # skills loader, targets, colors ├── schemas/ │ └── decision.schema.json ├── skills/ │ ├── mindit-clarity/ SKILL.md + anti-patterns.yaml │ ├── mindit-continuity/ SKILL.md + anti-patterns.yaml │ ├── mindit-constraint/ SKILL.md + anti-patterns.yaml │ ├── mindit-consequence/ SKILL.md + anti-patterns.yaml │ ├── mindit-context/ SKILL.md + anti-patterns.yaml │ ├── mindit-cost/ SKILL.md + anti-patterns.yaml │ ├── mindit-confidence/ SKILL.md + anti-patterns.yaml │ ├── mindit-correctability/ SKILL.md + anti-patterns.yaml │ ├── mindit-audit/ SKILL.md │ ├── mindit-premortem/ SKILL.md │ └── mindit-trace/ SKILL.md └── test/ ├── schema-validation.test.js ├── anti-pattern-fixtures.test.js ├── cli.test.js ├── lint.test.js └── mcp.test.js

11How mindit differs from Layers

Layers is a thinking framework: seven layers, three zones, nine markdown files. It's good. mindit is a different tool with four concrete additions.

Scoring per force, not just prose

Every force gets a 0–100 score per artifact. Not for ranking designs against each other. For surfacing which force is weakest in a given design. A 90/20 profile fails at the 20.

Anti-pattern registry

64 named failure modes. Findings carry slugs. Greppable across your decision graph.

Decision graph

Artifacts reference each other through depends_on. mindit-trace walks the graph backward and forward. Decisions accumulate; the team's reasoning becomes legible six months later.

Tooling

A CLI for one-command installation across five AI tools. An MCP server for tools that prefer that integration. A schema-based linter to catch graph drift over time.

Both are MIT, both work with the SKILL.md convention. You can use both at the same time.