convez.ai
SkillProdutividadeAvançado
faridjafarlee

Recon — Orquestrador de Reconhecimento de Codebase

faridjafarlee/recon

Reconhecimento multi-fase de codebase com subagentes e gates entre fases

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill que decompõe análise e desenvolvimento de código em fases gerenciadas (map → hunt → fix → optimize), rodando subagentes especializados em paralelo com gates de segurança. Mapeia arquitetura, audita código, sugere features e executa refatorações em worktrees isoladas, tudo controlado por um agente pai no Claude Code.

Instalação

$npx convez-ai faridjafarlee/recon

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

Casos de uso

  • Auditar e mapear arquitetura de codebases complexos em paralelo
  • Executar refatorações e correções de bugs com TDD em worktrees isoladas
  • Planejamento e execução de features seguindo especificações do zero ao deploy

Veredito

Ferramenta sólida e opinionada para times que trabalham com Claude Code e querem orquestração rigorosa de análise e desenvolvimento. Exige disciplina na instalação de dependências (Superpowers, Web Design Guidelines) e fluxo git bem estabelecido; retorno é alto para grandes refatorações e auditorias especializadas.

README

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

recon

An orchestrator of subagents for spec-driven development — packaged as a plugin for Claude Code.

recon decomposes work into specs and plans, then fans it out across purpose-built subagents — read-only auditors plus write-gated, worktree-isolated implementers. It maps and audits a codebase and drives spec-driven feature work (brainstorm → spec → plan → parallel build) end to end, with a human gate between every phase.

The main Claude Code session is the parent: it drives the phases and fans out read-only worker subagents (one per area). The only worker that writes code is the implementer, which runs in an isolated git worktree, is test-gated, and whose commits the parent cherry-picks back as separate commits. Nothing touches your default branch.

Heads-up: as a plugin, the skill is namespaced. The trigger is /recon:recon (not /recon), and subcommands follow it: /recon:recon pentest, /recon:recon suggest, etc.


Install

Recommended companions (install first):

  • Superpowers — recon's workflows lean on superpowers:* skills throughout (brainstorming, writing-plans, test-driven-development, using-git-worktrees, finishing-a-development-branch). Install it so those chains work:

    /plugin marketplace add obra/superpowers-marketplace
    /plugin install superpowers@superpowers-marketplace
    
  • Web Design Guidelines (Vercel Labs) — a live-source UI design-principles audit (/web-interface-guidelines) that /recon:recon redesign leans on. Install via the skills CLI:

    npx skills add vercel-labs/agent-skills
    
  • Vizzly CLI (optional) — visual-regression TDD for /recon:recon redesign. With it, the designer reviews pixel diffs with metadata and approve/reject; without it, recon falls back to plain Playwright before/after screenshots. Install (Node 22+): npm i -g @vizzly-testing/cli, then vizzly init and vizzly tdd start.

Then recon:

/plugin marketplace add faridjafarlee/recon
/plugin install recon@recon

Then reload (or restart the session) so the skills + agents register:

/reload-plugins

Update

When new changes are pushed, pull them with:

/plugin marketplace update recon

(The plugin is unversioned on purpose — every push is an update. Run the command above to fetch the latest commit.)


What it does

#PhaseWhat it doesOutput
1Setupdetect stack, capture test baseline, partition the repo into areas (seeded from .understand-anything/domain-graph.json if present)area list
2Mapone recon:mapper per area (parallel, read-only) → architecture map.recon/ARCHITECTURE.md
3Huntone recon:hunter per area + recon:refactoring-auditor + recon:threat-scout (read-only) → evidenced candidates; the parent re-reads each cited line before recording.recon/ISSUES.md, .recon/OPTIMIZATIONS.md
4Fixapplies selected ISSUES.md defects via parallel recon:implementers in worktrees: root-cause → TDD reproduce → fix → full-suite regression → verifier → dossier → cherry-pickcommits + .recon/fixes/<id>/
5Optimizeapplies selected OPTIMIZATIONS.md refactorings/perf, behavior-preserving: characterization tests where coverage is thin → refactor → identical test outcomes → perf gain check → verifier → dossier → cherry-pickcommits + .recon/fixes/opt-<n>-<slug>/

Drive the full pipeline with /recon:recon — the parent stops at a gate between each phase for your review/approval. You can stop after any phase (e.g. map + hunt only).

Subcommands

CommandWhat it does
/recon:recon test-frontendBrowser audit of the running app via the read-only recon:frontend-auditor (Playwright). Records [frontend] findings; offers a scoped Fix pass.
/recon:recon pentestAuthorized, non-destructive active API red-team via recon:pentester (loopback default; pre-dispatch gating of every state-changing/install probe). Confirmed vulns get a request/response PoC.
/recon:recon suggestThe recon:suggester (Opus) proposes ≥10 codebase-specific features grounded in the Map → you select → recon:planner writes parallelizable sub-plans → optional build.
/recon:recon plan "<task>"The recon:planner decomposes an arbitrary task (greenfield OK) into a general plan → you approve → detailed parallel sub-plans → optional build.
/recon:recon fixFront door to the Fix engine on selected ISSUES.md findings (auto-runs the Hunt first if missing).
/recon:recon optimizeFront door to the Optimize engine on selected OPTIMIZATIONS.md findings (auto-runs the Hunt first if missing).
/recon:recon redesignImprove the app's UI/visual design: recon:design-reviewer audits the running app (source + Playwright) → writes .recon/design.md + an improvement plan → you select → parallel recon:designers implement each in a worktree, gated by visual-regression TDD → cherry-pick back.

Subagents & orchestration

recon is a parent + workers system. The parent is your Claude Code session: it never edits source itself — it drives the phases, dispatches subagents, independently re-verifies their findings, owns every write to .recon/ and the work branch, and stops at a human gate between phases. Each worker is a single-purpose subagent with a tight tool allowlist. All workers are read-only on your source except the two write-enabled builders (implementer and designer), which write only inside their own isolated git worktrees.

Workers are spawned through the Agent tool by their plugin-namespaced type (recon:mapper, recon:hunter, …). The fill-in prompt for each lives in skills/recon/reference/dispatch-prompts.md; the severity rubric + finding format in reference/conventions.md; the output skeletons in reference/artifact-templates.md. Workers return structured notes only — they never write the deliverables; the parent does, after re-reading each cited file:line.

The roster

SubagentModelSource accessDispatched inRole
recon:mapperOpusread-onlyPhase 2 (Map) — one per area, parallelReads one area; returns purpose, entry points, key files, data flow, dependencies, risk leads → ARCHITECTURE.md.
recon:hunterOpusread-onlyPhase 3 (Hunt) — one per area, parallelAudits one area for defects + improvement leads → candidate findings.
recon:refactoring-auditorOpusread-onlyPhase 3 — once, repo-wideScans for code smells using its bundled refactoring catalog → OPTIMIZATIONS.md.
recon:threat-scoutOpusread-onlyPhase 3 — once, repo-wideTargeted threat-model hunt of the highest-risk bug classes for this kind of app.
recon:verifierSonnetread-onlyPhase 4/5 + engine — on risky changesIndependently re-checks a change before cherry-pick → APPROVE / APPROVE-WITH-NOTES / REJECT.
recon:frontend-auditorOpusread-only (drives a browser)/recon:recon test-frontendExercises the running app's user flows via Playwright → client-side findings.
recon:pentesterOpusread-only on source, active on the network/recon:recon pentestAuthorized, non-destructive API red-team → PoC-proven vulnerabilities.
recon:suggesterOpusread-only/recon:recon suggestIdeates ≥10 codebase-specific features grounded in the Map.
recon:plannerOpusread-onlysuggest / plan / fix / optimizeDecompose mode: a task → a general plan. Detail mode: items → per-item sub-plans + a file-overlap parallelization map.
recon:implementerSonnetwrites — only inside its own git worktreeexecution engine (fix/optimize/feature)One per sub-plan; implements, tests against the baseline, makes one commit.
recon:design-reviewerOpusread-only (drives a browser)/recon:recon redesignAudits the frontend's design (source + Playwright) across 3 levels → .recon/design.md + a prioritized improvement plan.
recon:designerSonnetwrites — only inside its own git worktreeexecution engine (design)One per design sub-plan; implements a visual change, verifies via visual-regression TDD (Vizzly/Playwright), makes one commit. Runs its own dev server + headless capture.

How a run flows

parent (your session) ── drives phases · owns .recon/ + the work branch · gates between phases
  │
  ├─ Phase 2  Map ──▶ recon:mapper ×N            (∥, read-only) ─────────────▶ .recon/ARCHITECTURE.md
  │
  ├─ Phase 3  Hunt ─▶ recon:hunter ×N            (∥, read-only) ─┐
  │                   recon:refactoring-auditor  (∥, read-only)  ├─▶ ISSUES.md / OPTIMIZATIONS.md
  │                   recon:threat-scout         (∥, read-only) ─┘   (parent re-reads each cited
  │                                                                    file:line before recording)
  │
  └─ Phase 4/5 · suggest · plan ───────────────▶  Execution engine  ▼

     recon:planner (Opus) ──▶ detailed sub-plans + parallelization map (disjoint-file batches)
          │
          ▼  per batch — up to implConcurrency in parallel
     recon:implementer (Sonnet) ─ own git worktree ─ implement → test ≥ baseline → ONE commit
          │
          ▼
     recon:verifier (risky changes) ─▶ APPROVE / REJECT
          │
          ▼
     parent ─ cherry-picks each surviving commit back onto the work branch (separate commits, no squash)

The execution engine

Phase 4 (Fix), Phase 5 (Optimize), and the build half of suggest / plan all funnel into one engine, so there is a single, consistent way changes land:

  1. Plan — recon:planner (detail mode) turns the selected items into one sub-plan each, every sub-plan declaring the exact file set it will touch, then groups sub-plans with disjoint file sets into parallel batches (overlapping ones fall to later batches).
  2. Build, in parallel, isolated — for each batch the parent spawns one recon:implementer per sub-plan, each in its own git worktree (so concurrent builds can't collide), capped at implConcurrency. Each implementer works to a mode: fix (reproduce test → fix), optimize (characterization tests → refactor, identical outcomes, perf gain), or feature (TDD build).
  3. Gate — the parent checks each diff against its declared file set, runs recon:verifier on risky ones, and writes a per-change dossier under .recon/fixes/….
  4. Integrate — the parent cherry-picks each passing worktree commit back onto the work branch as a separate commit (no squashing), pausing on any conflict or REJECT. Never the default branch.

Safety model

  • Only one worker edits — every worker is read-only (no Edit/Write in its tools:) except recon:implementer, which writes only inside its own git worktree (never the originating/default branch or .recon/), stays within its plan's declared file set (parent-verified before cherry-pick), and makes one commit the parent cherry-picks back (no squashing).
  • Never commits to the default branch.
  • Every fix is proven — a green full suite vs the Phase-1 baseline + a reproduce test (Fix) or characterization tests with identical outcomes (Optimize). No weakening/deleting tests to pass.
  • Verifier gate on high-severity/risky changes — a REJECT blocks the cherry-pick and pauses (in both autocommit modes).
  • pentest is authorized + non-destructive only — attacks only an operator-attested, in-scope target (loopback default), runs no destructive/DoS techniques, and gates every state-changing/install action before dispatch.
  • .recon/ISSUES.md is the diagnostic deliverable — every confirmed finding is recorded in full whether or not it gets fixed.

Per-run knobs (Fix / Optimize)

  • Autocommit yes|no — asked at the start; gates whether each passing worktree commit is auto-cherry-picked or shown for your OK first.
  • implConcurrency (default 10) — max parallel implementers (read-only workers are uncapped).
  • designConcurrency (default 3) — max parallel designers in /recon:recon redesign (each runs a dev server + browser, so heavier).
  • perfRuns (default 5), perfTarget = auto|suite|bench|off — optimize-mode only; fixes don't benchmark.
  • dossier = commit (default) |gitignore.

Models

Per-agent models are in the roster above (Opus for discovery/planning, Sonnet for verifier + implementer), set via each agent's model: frontmatter. A model change takes effect only after a session reload — the agent registry is cached at session start.

Layout

recon/
├── .claude-plugin/
│   ├── plugin.json          # plugin manifest
│   └── marketplace.json     # marketplace manifest (this repo is its own marketplace)
├── skills/recon/
│   ├── SKILL.md             # the orchestrator playbook (5 phases + engine + subcommands)
│   ├── reference/           # conventions, dispatch prompts, artifact templates
│   └── knowledge/refactoring/   # code-smells + refactoring-techniques catalog
├── agents/                  # 12 workers (read-only on source; implementer + designer write only in their worktrees)
└── docs/                    # design spec + implementation plan (provenance)

Bundled files are referenced internally via ${CLAUDE_PLUGIN_ROOT} so they resolve wherever the plugin is installed.

Notes

  • After installing or updating, reload so the new agents become dispatchable (the agent registry is cached at session start).
  • The refactoring knowledge base is original prose (Fowler methodology), not copied from third-party sites.

License

MIT © Farid K. Jafarli

Ver o original no GitHub

Bom para

Relacionados