convez.ai
AgenteAutomaçãoAvançado
qneyrat

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 GitHub
InicialPluginScore · de 0 a 100

Kit 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/minas

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

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.
  • /clarify runs 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:

  1. Threshold — resolves clarify.ambiguityThreshold (default 0.2) and prints it.
  2. Explore first — detects greenfield vs brownfield via minas-explore; never asks you a fact the code already reveals.
  3. Topology — enumerates 1–6 independent components and locks the list.
  4. Interview loop — each round targets the weakest (component, dimension) pair (Goal / Constraints / Success-criteria / Context), asks one question, then scores via minas-clarify-scorer and reports the ambiguity table.
  5. Challenge modes — Contrarian (round 4+), Simplifier (round 6+), Ontologist (round 8+ if still ambiguous), once each.
  6. Crystallize — assembles the spec in context once ambiguity ≤ threshold.
  7. ExitPlanMode — presents the spec for approval. On approval, writes specs/clarify-{slug}.md and hands off to minas-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.

AgentModelRole
minas-explorehaikuread-only codebase recon (cites path:line)
minas-clarify-scoreropusweighted ambiguity scoring (strict JSON)
minas-planneropus3–6 step implementation plan
minas-executorsonnetimplements the approved plan, no re-scope
minas-reviewersonnetpre-PR quality gate (proposes, doesn't rewrite)
minas-debuggersonnetroot-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 different defaultMode, 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
Ver o original no GitHub

Bom para

Relacionados