convez.ai
SkillProdutividadeAvançado
MastSystems

mast: Desenvolvimento Orientado a Especificação

MastSystems/mast-skills

Indexe intenção de código em specs compiláveis; agentes herdam contexto, CI detecta drift

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework de spec-driven development que indexa a intenção do código em arquivos `.mspec` estruturados e compiláveis. Transforma a especificação em um artefato de repositório durável, permitindo que agentes de IA herdem contexto entre sessões e CI detecte automaticamente desvios entre código e contrato.

Instalação

$npx convez-ai MastSystems/mast-skills

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
4
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 3 meses
Versão
v0.19.0
Issues abertas
1
Contribuidores
1

Casos de uso

  • Manter especificações sincronizadas com código via CI/linting automático
  • Permitir que agentes de IA reutilizem contexto entre múltiplas sessões
  • Documentar regras de negócio com rastreabilidade de implementação

Veredito

Solução sofisticada para o problema real de amnésia de sessão em agentes IA e documentação que envelhece. Requer adoção de gramática nova (`.mspec`) e integração em pipeline de CI, mas oferece valor substancial em equipes que valorizam intent-driven development e memory durável entre iterações.

README

A tradução para o português deste README ainda está na fila.

mast

Code review tells you what changed. mast tells you what was supposed to change.

Your AI agents have amnesia. Every session starts from zero: re-read the code, re-infer the intent, re-decide things your team already decided. And the one thing an agent can never recover by reading code is what the code is supposed to do — code records what is; the supposed to lives in heads, chat threads, and closed PRs, exactly the places a fresh session can't reach.

mast closes that gap by indexing your codebase's intent into the repo itself, as spec files in a real specification language. The corpus compiles into a typed graph; agents query it instead of re-reading files. From then on, every session — human or agent — starts already briefed, and CI fails by name when code and contract drift apart. Installation is two slash-commands; mining your first corpus is one sentence (both below).

What indexing your codebase buys you

You don't hand-write this index, and your team doesn't maintain it by diligence. /mast:mine drafts it from the code as it actually is; agents keep it current in the same PRs, through the same lint gate; CI keeps it honest. Spec docs rot because nothing checks them — here everything checks them.

  • Intent becomes a repo artifact. One .mspec file per feature, one rule per paragraph, every active rule pinned to the code that satisfies it. "Was it supposed to do that?" stops being archaeology.
  • Drift becomes a failing build. Rules pin real file paths; rule-to-rule citations are content-pinned in a lockfile. Move the file and mast lint check fails, naming the spec; change the cited text and the pin flags the drifted rule.
  • Every agent session inherits the index. The corpus is durable memory with a query surface — the ramp-up that used to cost a context window of re-reading costs three commands (below).

Why not Kiro, or a folder of markdown?

Spec-driven development is the right instinct — but a markdown spec is prose, and prose is invisible to tooling. Nothing parses it, so nothing can check it, and the only way an agent can use it is to read all of it and hope it's still true. Kiro-class tools structure the workflow, but the spec artifact is still a document an agent reads whole — no compiler, no canonical form, no typed graph to query, no CI drift gate — and it lives inside one vendor's IDE. A .mspec corpus is a plain repo artifact any tool can lint. Here is a real rule from the worked example, a small double-entry ledger:

Targets
  $apply @file=src/accounts/service.ts#apply

Rule R3.overdraft-rejected [active $apply accounts.AccountService.apply]
  Given a source account without sufficient funds
  When the debit is applied
  Then {accounts.AccountService} throws InsufficientFunds and no credit or journal entry is written
    MUST no_overdraft: a debit that would make the balance negative MUST be rejected
    SHOULD audit_log: a rejected overdraft emits a structured audit event to the audit log
    success.overdraft_422: transferring more than the source balance returns HTTP status `422`

That's a full grammar, not a template: the [active $apply ...] chip is a checkable lifecycle state (pending → active → amended → retired) anchored to a real function; MUST / SHOULD / MAY are linter-enforced normative prefixes; success.<name> is a falsifiable oracle a test can implement. Specs also carry Define/Exports for an importable vocabulary, spec-wide Invariants, and inheritance via extends.

  • Vagueness doesn't compile. The prefix carries the obligation, so hedging in the body is a hard error: SHOULD fast: checkout completes within 2s compiles; SHOULD fast: checkout should complete quickly does not.
  • One canonical form. The formatter is idempotent and mandatory. Agents write specs through the same gate you do — parse → lint → canonical format, or nothing hits disk.
  • Errors teach. Every lint finding is one of 124 explainable codes; mast explain <code> gives meaning, example, and remedy, so agents self-correct instead of looping.
  • Specs are data, not documents. Because they parse, they can be queried, cross-linked, and diffed semantically — which is what makes the graph below possible.

A markdown spec is a promise. A .mspec is a contract with a compiler behind it.

Why a graph beats reading files

Parsing the corpus yields more than files: every spec, rule, invariant, definition, domain, and component becomes a node in one typed graph, connected by deps, extends, cites, and connects edges. That changes the information gain per token spent. Grep answers "where does this string appear?" and hands you whole files to read; the graph answers the question you actually had, and hands back exactly the nodes involved. Both of these run on the ledger example:

$ mast describe cited-by transfer-funds R2    # which rules elsewhere cite this rule?
idempotent-transfer.R1  →  transfer-funds.R2

One line — not three files skimmed to find it. Optional .march / .mtypes files put your architecture in the same graph, and the edges are typed against a declared vocabulary (the ledger declares Handles over http, Calls and Persists in-process) — so walking the topology means walking named, linted relationships, not guessed ones:

$ mast graph api.Api --edge connects          # what does the API handler touch?
accounts.AccountService
accounts.AccountStore
ledger.EntryStore
ledger.IdempotencyStore
ledger.TransferService

Some questions are transitive — mast spec read read-journal --with-blocked-by walks the whole dependency closure to answer "what must ship before this can?" — which no amount of file reading answers reliably.

Fresh session, instant context

This is where the language and the graph pay off together. An agent starting cold doesn't rebuild context by reading — it queries:

mast describe stats                              # corpus shape: what's active, pending, draft
git diff --name-only | mast list scope --file -  # the specs this session's work touches
mast spec read transfer-funds --with-rules       # the full contract for the feature at hand

Three commands, a few hundred tokens of typed output (describe stats on the ledger is ~25 lines), and the session knows what the code is supposed to do, what governs the current diff, and what's unfinished — context that would otherwise cost a crawl through source and stale docs at the start of every session. The corpus is the durable memory; the graph is its index; the context window stays free for the actual task.

Installation

In Claude Code:

/plugin marketplace add MastSystems/mast-skills
/plugin install mast@mastsystems

The first time a skill needs the mast binary, the right prebuilt for your host (Linux x86-64, macOS Intel, macOS Apple Silicon) is downloaded, SHA-256 verified, and cached. Other hosts fall back to a local cargo build.

Index your codebase in five minutes

  1. Install (above), then open your repo in Claude Code.
  2. mast doctor reports where the repo stands and the single next command. Or just say "get me started with mast" (/mast:start).
  3. Mine the index. Say "mine this codebase for specs" (/mast:mine): it drafts specs, architecture, and vocabulary from the code as it actually is — as reviewable proposals, never silent writes. Greenfield instead? "create a spec for <feature>" (/mast:spec).
  4. Gate it. mast lint check validates the whole corpus; errors fail, advisory warnings don't — the ledger example passes even with open: markers on its draft specs. In CI, add --strict to make every warning a failure, stale citation pins included.

The complete worked example — the double-entry ledger quoted above, with its full spec corpus and architecture graph — ships in examples/ledger.

The skills

Talk to Claude normally; skills trigger on intent, or explicitly as /mast:<name>.

SkillWhat it's for
startFirst-session onboarding: detects project state and routes you.
mineDraft a spec corpus from an existing codebase.
specRead, create, or patch specs — a hook blocks raw file edits, so every write passes parse → lint → format first.
orientTour the corpus; answer "which spec governs this file?"
dag-planTurn a spec into a phased implementation plan with parallel lanes.
checkPre-push verification, CI-failure diagnosis, corpus health audit.
guideWhat's next, what's ready to ship, what's blocked.

Everything the plugin does goes through the mast binary; mast --help is the full query surface. Install the plugin, say "mine this codebase for specs", and your next session starts already briefed.

MIT licensed.

Ver o original no GitHub

Bom para

Relacionados