mindit

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

mindit is an open-source skills pack for AI design tools. It walks any design through eight forces every decision has to balance and produces a scored, structured artifact for each one.

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

npm install -g usemindit
usemindit add claude-code

Works with Claude Code, Claude Desktop (via MCP), Cursor, Codex, Cline, and any tool that reads SKILL.md.

---

What's new in v2

• CLI: usemindit add, init, list, lint, mcp
• MCP server: usemindit mcp exposes all eleven skills as MCP tools over stdio
• Decision-graph linter: usemindit lint validates artifacts in .mindit/decisions/ against the JSON schema, surfaces broken dependencies, catches orphan files
• Multi-tool installer: One command installs into Claude Code, Cursor, Codex, or Cline

---

The eight forces

Every design decision balances eight competing pressures. mindit names them, scores them, and tells you which one is the weakest in any design.

Force	The question it asks
Clarity	Can a stranger read the intent in five seconds?
Continuity	Does this fit the system that already exists?
Constraint	What hard limits is this honoring?
Consequence	What does this foreclose? What does it open?
Context	Who, when, where, on what device, in what state?
Cost	Build time, complexity, support burden, debt
Confidence	What evidence stands behind this?
Correctability	If we're wrong, how reversible is it?

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.

---

The eleven skills

Eight force skills, three meta skills:

Skill	What it produces
/mindit-clarity	Hierarchy, labeling, affordance, density, distinguishability score
/mindit-continuity	Convention, component, naming, state, visual alignment score
/mindit-constraint	Accessibility, technical, legal, brand, platform, time-budget score
/mindit-consequence	Reversibility, foreclosure, data, lock-in, second-order score
/mindit-context	Audience, device, state, journey, environment score
/mindit-cost	Build, support, maintenance, debt, TCO score
/mindit-confidence	Evidence type, freshness, breadth, mechanism, triangulation score
/mindit-correctability	User undo, system rollback, detection, blast radius, gating score
/mindit-audit	All eight forces. Bottleneck identified. Top three findings.
/mindit-premortem	Imagine it failed. Surface the failure modes. Rank by severity.
/mindit-trace	Walk the decision graph backward and forward through .mindit/decisions/.

---

The CLI

$ usemindit --help

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

  Usage
    usemindit <command> [options]

  Commands
    init           Create a .mindit/decisions directory in the current project
    add   <tool>   Install skills into an AI tool (claude-code, cursor, codex, cline, claude-desktop)
    list           List the eleven skills and their descriptions
    lint  [path]   Validate decision artifacts in .mindit/decisions/
    mcp            Start the mindit MCP server on stdio

usemindit init

Creates .mindit/decisions/ in your project with a README. This is where skill artifacts get written. Commit the directory; it's your decision graph.

usemindit add <target>

Installs the eleven skills into wherever your AI tool reads them.

usemindit add claude-code            # project-local: ./.claude/skills/
usemindit add claude-code --global   # user-global:   ~/.claude/skills/
usemindit add cursor                 # writes to ./.cursor/rules/
usemindit add codex                  # writes to ./.codex/skills/
usemindit add cline                  # writes to ./.clinerules/
usemindit add claude-desktop         # prints the MCP config snippet
usemindit add --path ~/Downloads/x   # copy to any directory

Flags: --global, --dry-run, --force, --path <dir>.

usemindit list

Prints the eleven skills with their descriptions. Use --verbose for full descriptions.

usemindit lint

Validates .mindit/decisions/ against the schema. Checks performed:

1. Every .json parses
2. Every .json validates against decision.schema.json
3. Every .json has a .md sibling (and vice versa)
4. Every id field matches its filename
5. Every depends_on reference resolves to an existing artifact

Exit codes: 0 clean · 1 errors · 2 warnings only.

usemindit mcp

Starts the MCP server on stdio. Twelve tools available: the eleven skills as mindit_clarity, mindit_continuity, etc., plus mindit_schema which returns the JSON Schema.

For Claude Desktop, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "mindit": {
      "command": "npx",
      "args": ["usemindit", "mcp"]
    }
  }
}

---

What mindit produces

Every skill writes two files to .mindit/decisions/:

1. A markdown artifact for humans to read.
2. A JSON artifact that conforms to schemas/decision.schema.json — queryable by tools, diff-able in git, traceable through the graph.

Example output from /mindit-clarity on a pricing page:

{
  "id": "clarity-20260511-pricing-hero",
  "skill": "mindit-clarity",
  "subject": { "name": "Pricing page hero", "type": "screen", "location": "example.com/pricing" },
  "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."
    }
  ],
  "open_questions": [
    "What audience segment is this hero designed for — first-time visitors or returning evaluators?"
  ],
  "created_at": "2026-05-11T10:14:00Z",
  "version": "2.0.0"
}

---

Install

# Global install (recommended for the CLI)
npm install -g usemindit
usemindit add claude-code

# Or local install
npm install usemindit
npx usemindit add claude-code

Then in any AI tool that supports the skills convention:

/mindit-clarity Review the hero on https://example.com/pricing
/mindit-audit Review my checkout flow. Audience is repeat customers on mobile.
/mindit-trace Why are we using three tiers instead of four?

---

The anti-pattern registry

Each force ships with a registry of named failure modes — anti-patterns.yaml in the force's directory. 64 named patterns total, each with a symptom, an example, a fix, and a severity. When a skill matches a pattern, the finding includes the slug. You can grep your decision graph for any pattern to see how often it appears.

A sample: 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).

---

Repository layout

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 registry, 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
└── docs/
    └── index.html              landing page

---

Tests

npm install
npm test

44 tests across schema validation, anti-pattern fixtures, CLI integration, lint behavior, and MCP server roundtrips.

---

How mindit is different

Most design-thinking frameworks give you a stack of layers, a set of questions, or a vocabulary. They are valuable, and they are also stateless: you run them, get a markdown, lose context.

mindit makes four concrete additions:

1. Scoring. Every force has a 0–100 score per artifact. Not for ranking designs, but for surfacing which force is weakest in a given design.
2. Anti-pattern registry. Named failure modes per force. Findings carry slugs. Greppable.
3. Decision graph. Artifacts reference each other via depends_on. mindit-trace walks the graph backward and forward.
4. Tooling. A CLI for installation and validation. An MCP server. A schema-based linter. Tests on every commit.

The skill files are plain markdown. The output schema is plain JSON. You can use mindit without buying into any platform.

---

License

MIT. See LICENSE.

Fork it. Adapt it. Use it inside your team. Build your own forces on top of it. No attribution required.

---

Disclaimer

mindit is one lens, not the only lens. Scores are heuristics, not verdicts. A high score does not mean a design is good. A low score does not mean a design is bad. Always have a human read the output before acting on it. See DISCLAIMER.md.

---

Built by Dragoon0x.