convez.ai
AgenteProdutividadeAvançado
anton-haskevych

Spec-Driven: Painel de Experts para Revisão de Specs e Código

anton-haskevych/spec-driven

Painel de 7 agents experts para spec review, code review e debugging

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent que orquestra um painel de 7 especialistas Claude para validar especificações técnicas, revisar código, pesquisar contexto e debugar. Implementa um workflow completo de desenvolvimento orientado a specs: preparação, criação de specs, revisão paralela com agents especializados, implementação rastreada e handoff de sessões.

Instalação

$npx convez-ai anton-haskevych/spec-driven

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
2
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 1 dia
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Validar especificações técnicas antes de implementação
  • Revisar código e arquitetura com múltiplas perspectivas em paralelo
  • Documentar decisões técnicas e aprendizados durável ao longo do desenvolvimento
  • Rastrear progresso de features em fases com status e checkpoints

Veredito

Ferramenta robusta e opinada para equipes que querem rigor em spec-driven development. A orquestração de múltiplos agents em paralelo e o rastreamento de estado (ledger, research, reviews) são sofisticados, mas exigem disciplina no uso e compreensão do workflow — ideal para projetos estruturados, não para exploração rápida.

README

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

spec-driven

A spec-driven development toolkit for Claude Code. Write specifications first, review them with an expert panel, then implement with confidence.

The workflow

Prep → Create → Review → Implement → Update → Handoff → Resume → ...

This plugin gives you the complete lifecycle:

StepWhat you doWhat the plugin provides
Prep/spec prep my-featurePre-spec reconnaissance. Align on the real change, scaffold the folder + a ≤30-line product-brief.md (business only, no code), then fan out adaptive recon waves (read-only Explore agents) across two lenses — implementation (seam, reuse, blast radius, tests) then craft (naming, fixtures, extraction-for-reuse) — locking ground truth into research/. One hard stop — right after the brief.
Create/spec my-featureInteractive spec creation — decisions, wireframes, API contracts, per-phase plans. Consumes prep's brief + research when present; otherwise cold-discovers.
Review/spec my-feature + "review"Fully autonomous: 5 expert agents evaluate the spec in parallel, findings are synthesized, written to immutable reviews/<date>.md, applied to the spec + ledger, and committed as one [review] commit — no prompts. Only contradictions and rethink verdicts wait for you, recorded as open decision ledger entries
Update/spec my-feature + "update"Checks off sub-items inside phase entries, captures durable learnings as ledger entries, updates the code map
Status/spec my-feature statusPrint a 4-column phase snapshot — Phase, Status (✅ done / 🟡 WIP (x/y) / 🟢 active / ⬜ pending), Delivers, Work — without the resume briefing. active is reserved for the first unchecked phase; later unchecked phases are pending. Work falls back to N/A if the phase has no implementation guidance. Format is a markdown table — never cards or vertical lists.
Handoff/spec my-feature + "handoff"Reflects on the session and redirects findings: durable learnings → ledger, pending state → in-flight.md. Commits and signals.
Resume/spec my-featureTwo-stage. Stage A: prints the status table, reads in-flight.md if present, suggests the next chunk, halts. Stage B (only on confirmation): loads stable references + the active phase entry + filtered ledger + scoped code-map, then hands off to execute mode.
Execute(entered automatically from Resume Stage B)Inner work loop. Decompose the chunk into testable units, run red→green→commit per unit, update the phase entry's sub-checkboxes, add ledger entries for durable learnings, and trigger /spec handoff before hitting ~75% of the context budget.

No arguments required for the feature name — the /spec skill infers it from conversation context. Sub-commands (prep, create, resume, review, update, handoff, status, list) can lead or trail the feature name: /spec resume my-feature, /spec my-feature resume, or /spec resume (alone, with the feature inferred from context) all work.

Why prep first

A spec is only as good as the facts under it. Writing technical.md and phase plans straight from a customer ask bakes in assumptions — the wrong gate, a reinvented mechanism, an unseen blast radius. Prep front-loads the grounding: a frozen ≤30-line business brief becomes the contract, then read-only Explore agents fan out in adaptive waves — each wave aimed by the last one's findings at whatever's still unknown — until the codebase ground truth is locked into research/ — across two lenses: implementation (where the change lives, what to reuse, blast radius) and craft (naming, test fixtures, extraction-for-reuse), so the result reads like the codebase wrote it. Only then does /spec create write the spec, citing verified file:line facts instead of guesses. The single human checkpoint sits where it matters most: right after the brief, before any token is spent on recon.

Why two-stage resume

A non-trivial spec carries hundreds of KB across design.md, technical.md, ledger entries, and per-phase plans. Loading all of it on every /spec resume burns 100K+ tokens before any work starts.

Stage A reads only progress.md and per-phase Goal/Implementation lines — same materials as /spec status. The user sees the full picture (table + suggested next chunk) and decides what to work on. Stage A renders bullets, not paragraphs — every line earns its place, and there's no magic-word CTA: any natural confirmation ("yep", "go ahead", "do this phase") triggers Stage B. Stage B then loads the focused subset relevant to that decision and hands off to execute mode, which runs the per-unit TDD loop and watches the context budget so the session ends cleanly via /spec handoff before the window fills up.

The review panel

When you trigger a review, 5 agents launch in parallel:

AgentCentral questionWhat it catches
principal-engineerIs this fundamentally right?Wrong-layer fixes, premature abstractions, tech debt traps
integration-architectHow does this fit?Boundary violations, data flow breaks, blast radius
adversarial-testerWhat will break?Edge cases, lifecycle state leaks, concurrency, null guards
code-quality-reviewerHow does this affect code quality?God objects, duplicated logic, testability gaps
prior-art-reviewerDoes the system already do this?Reinvented wheels, grandfathered decisions, hand-built defenses an existing mechanism makes structurally unnecessary, misplaced ownership

After all 5 return, the review-synthesizer combines findings: deduplicates, classifies signal (consensus / unique-insight / contradiction), marks mitigation findings superseded by accepted substitutions, and assigns enforcement mechanisms.

The review then finishes itself: spec corrections are applied directly, cross-phase learnings become ledger entries, contradictions and fundamental-rethink verdicts become open decision entries (recorded, not resolved), and everything lands in a single [review] <spec-name>: <slug> commit. The run ends with a compact report — what was found, what was applied, and what (if anything) needs your judgment.

Standalone agents

AgentRoleWhen to use
deep-research-analystComprehensive researchBefore creating a spec — gathers info from multiple sources
debuggerRoot-cause diagnosisDuring implementation — traces to the originating defect, never modifies code

Included skills

SkillUsed byPurpose
specYou (via /spec)The core spec lifecycle — prep, create, review, update, status, resume, execute, handoff
code-quality-reviewcode-quality-reviewer agentDeep quality review framework
structural-principlescode-quality-reviewer agentMechanism vs business logic classification, size gates

The spec skill ships an engineering-principles reference (skills/spec/principles.md) that execute mode loads at the start of every chunk. 18 rules covering self-documenting code, hard size caps (function < 50 lines, file < 250 lines), extract-on-second-use with mandatory unit tests, frontend layered separation (with backend deferring to project-specific rules), and the rest of the engineering hygiene the workflow enforces.

Install

/plugin marketplace add anton-haskevych/spec-driven
/plugin install spec-driven

Spec file structure

Each spec lives in docs/specs/<feature-name>/. The layout separates stable reference (brief, design, technical), thin index (progress), per-phase detail (phases folder), forward-propagating learnings (ledger), and ephemeral state (in-flight):

docs/specs/<feature-name>/
├── CLAUDE.md               # metadata + relationship to code
├── product-brief.md        # business intent (≤30 lines, no code) — by prep
├── design.md               # stable reference — problem, decisions, UX
├── technical.md            # stable reference — contracts, architecture
├── progress.md             # thin index: phase list + checkboxes + pointers
├── pr-opening.md           # PR-readiness gate: spec state + pre-PR checks (not a phase)
├── code-map.md             # load-bearing files inventory
├── in-flight.md            # ephemeral pending work (on-demand)
├── phases/                 # per-phase detail (see below)
│   ├── phase-1-<slug>.md   #   flat file — small phase
│   └── phase-8-<slug>/     #   folder — complex phase with supplementary files
│       ├── plan.md
│       └── ...
├── reviews/                # on-demand — dated YYYY-MM-DD-<slug>.md, immutable
├── research/               # on-demand — dated YYYY-MM-DD-<slug>.md, immutable
└── ledger/                 # forward-propagating learnings
    ├── INDEX.md            # warm cache — one row per entry with [applies-to] tag
    └── <kind>-<slug>.md    # kinds: gotcha, principle, domain, decision, workaround, …

The ledger model

The ledger holds small files, each one a durable learning that forward-propagates across phases. Entries are tagged with applies-to: scopes ([general], [phase 5+], [phase 6, 7], [general, load-bearing]) and indexed in ledger/INDEX.md as the warm cache. When resuming work, the skill filters the index by the active phase's scope and opens only the relevant entries — so a new session never has to scan the whole ledger or read a bloated progress file.

Per-phase shape

Every phase lives in its own entry inside phases/. Small phases are flat .md files. Complex phases are folders containing plan.md plus supplementary files (tier breakdowns, sub-plans, wireframes, fixture notes). A phase can start as a flat file and be promoted to a folder later, when it outgrows single-file scale. progress.md points at each phase with a direct path, so resume always knows where to go.

Phases are code-only — verification lives in pr-opening.md

A phase is a unit of code that ships and leaves the tree functional and tested. Verification, manual QA, and opening the PR are not phases — a "Phase 5 — Verification" is a smell. They live in pr-opening.md, a per-spec gate with two sections: a Spec state (<20 lines: phases done/left, branch, PR link, suggested PR split) kept current by execute/handoff, and Pre-PR checks — checkboxes scoped to the subprojects the spec touches (backend tests, frontend lint+compile, feature e2e, …), ticked before the draft PR opens, never straight to main. Sub-checkboxes inside a phase are each sized to one TDD commit (red → change → green → commit).

Handoff redirects the brain dump

The handoff "brain dump" that reflects on a session — business decisions, problems encountered, reasoning behind approach changes — is not appended to progress.md. Instead it's redirected: durable learnings become ledger entries (decision-*, gotcha-*, principle-*, domain-*), and ephemeral "pick up from here" state goes to in-flight.md. Nothing gets lost; nothing bloats.

Legacy specs

Specs created before this layout are auto-detected (by the absence of ledger/INDEX.md) and read via a legacy fallback path. Update mode never appends new session logs to a legacy progress.md, and can opportunistically create a ledger/ folder on request so old specs can incrementally adopt the new model.

Customization

Project-specific overrides

Create .claude/agents/<agent-name>.md or .claude/skills/spec/ in your project to override any agent or skill with a project-specific version. Project-level definitions (priority 3) automatically override plugin definitions (priority 5).

Example: your project's .claude/agents/adversarial-tester.md can include domain-specific entity states, lifecycle patterns, and common bug references.

Taxonomy

The plugin ships with a generic taxonomy (status, scope, area, domain). To customize for your project, create .claude/taxonomy.md with your own controlled vocabulary — the spec skill will pick it up automatically.

Priority order

Project (3) > User (4) > Plugin (5)

License

Apache 2.0

Ver o original no GitHub

Bom para

Relacionados