Minas: Agent Kit de Clarificação para Claude Code
qneyrat/minas
Scored clarify phase com Socratic Q&A antes de planejar código
Ver no GitHubKit de agentes para Claude Code que implementa uma fase rigorosa de clarificação com pontuação de ambiguidade antes do planejamento e execução. Usa modo de plano nativo, subagentes isolados e skills do Claude Code, adicionando apenas um fluxo Socrático de entrevista com scoring automático para garantir especificações claras antes de qualquer código ser escrito.
Instalação
npx convez-ai qneyrat/minas1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Validar requisitos vagos antes de iniciar desenvolvimento
- Reduzir retrabalho através de especificações claras e estruturadas
- Executar agentes especializados em contextos isolados com permissões restritas
- Revisar qualidade de código antes de merge com feedback proposicional
Veredito

Minas é uma abordagem lean e bem-fundamentada para agência em Claude Code que resolve um problema real — requisitos ambíguos levando a código descartável. O sistema de pontuação de ambiguidade é elegante e o design de fluxo (explore → clarify → planner → executor → reviewer) é sólido. Recomendado para equipes que valorizam clareza de escopo e podem se beneficiar de agentes especializados com permissões granulares.
README
A tradução para o português deste README ainda está na fila.
minas
A lean, native-first agent kit for Claude Code. It rides Claude Code's built-in plan mode, subagents, skills, and permissions, and adds only the one thing the native flow is missing: a rigorous, scored clarify phase before any planning or code.
One skill, six agents, one settings file. No custom hooks, no state machine.
Why
Most agent kits reimplement, in custom hooks and state machines, capabilities
that Claude Code now ships natively — plan mode, isolated-context subagents,
skills, AskUserQuestion, permission gating. minas keeps a single thin layer
and leans on the native machinery for everything else:
- Every session starts in native plan mode (read-only) — set by
permissions.defaultMode: "plan"in.claude/settings.json. No write, edit, or mutation can happen until you approve leaving plan mode. /clarifyruns a Socratic, one-question-at-a-time loop with weighted ambiguity scoring until the idea is clear enough to plan.- The clarified spec hands off through the native ExitPlanMode gate — the approval is the bridge; there's no custom approval step.
Flow (three gates, one native approval)
[plan mode, read-only — from session start]
explore → clarify (scored Q&A loop) → ExitPlanMode (spec)
│ user approves + switches mode
▼
[out of plan mode] planner → executor → reviewer (debugger on bugs)
The whole left side is read-only: explore gathers facts, clarify interviews and
scores, and the spec is crystallized in context — nothing touches disk.
Only after you approve ExitPlanMode does the spec get written and execution begin.
The clarify gate
/clarify "<vague idea>" runs the scored interview:
- Threshold — resolves
clarify.ambiguityThreshold(default0.2) and prints it. - Explore first — detects greenfield vs brownfield via
minas-explore; never asks you a fact the code already reveals. - Topology — enumerates 1–6 independent components and locks the list.
- Interview loop — each round targets the weakest
(component, dimension)pair (Goal / Constraints / Success-criteria / Context), asks one question, then scores viaminas-clarify-scorerand reports the ambiguity table. - Challenge modes — Contrarian (round 4+), Simplifier (round 6+), Ontologist (round 8+ if still ambiguous), once each.
- Crystallize — assembles the spec in context once ambiguity ≤ threshold.
- ExitPlanMode — presents the spec for approval. On approval, writes
specs/clarify-{slug}.mdand hands off tominas-planner.
Ambiguity is 1 − Σ(dimension × weight):
- greenfield:
goal·0.40 + constraints·0.30 + criteria·0.30 - brownfield:
goal·0.35 + constraints·0.25 + criteria·0.25 + context·0.15
Agents
Each runs in its own context window with restricted tools. ACCS-style
Use when… frontmatter, OMCC-style hard-boundary bodies — every agent carries
an explicit "NOT responsible for X" boundary.
| Agent | Model | Role |
|---|---|---|
minas-explore | haiku | read-only codebase recon (cites path:line) |
minas-clarify-scorer | opus | weighted ambiguity scoring (strict JSON) |
minas-planner | opus | 3–6 step implementation plan |
minas-executor | sonnet | implements the approved plan, no re-scope |
minas-reviewer | sonnet | pre-PR quality gate (proposes, doesn't rewrite) |
minas-debugger | sonnet | root-cause debugging |
Install
Requires Node.js ≥ 20 (for the resolver) and Claude Code v2.1.129+ (for
skillOverrides; defaultMode: "plan" verified on v2.1.153).
From a local checkout, cd into your target project and run the installer:
cd /path/to/your-project
/path/to/minas/install.sh
It copies the skill, the six agents, and settings.json. If your project
already has a .claude/settings.json, it is deep-merged: your keys win on
conflicts and the privacy deny patterns are unioned, so nothing you set is lost.
Configuration (.claude/settings.json)
{
"permissions": {
"defaultMode": "plan",
"deny": ["Read(.env*)", "Read(**/credentials*)", "Read(**/*secret*)"]
},
"skillOverrides": { "minas:clarify": "on" },
"clarify": { "ambiguityThreshold": 0.2, "maxRounds": 20 }
}
defaultMode: "plan"— read-only at every session start. ⚠️ If your project already sets a differentdefaultMode, the merge preserves it, so set it to"plan"yourself to get read-only-at-boot.clarify.ambiguityThreshold— the gate; clarify won't crystallize until ambiguity drops at or below it.- org-wide managed settings can override
defaultMode.
Layout
minas/
.claude/
settings.json
skills/clarify/SKILL.md # the minas:clarify gate
agents/minas-*.md # 6 agents
specs/ # clarify outputs (written post-approval)
manifest.json # include / merge / copyIfMissing
resolve-manifest.mjs # zero-dep glob resolver
install.sh # local-source installer