convez.ai
SkillDesenvolvimento WebAvançado
Lbstrydom

Claude Engineering Skills

Lbstrydom/claude-engineering-skills

Loop plan-audit-fix com 3 modelos de IA, memória arquitetural e QA automatizado

Ver no GitHub
BomPluginScore · de 0 a 100

Suite de skills de pair-programming com IA que integra planejamento, auditoria multi-modelo (Claude, GPT, Gemini) e testes de UX para automação completa do ciclo de desenvolvimento. Inclui memória arquitetural para detectar duplicação de código e gate de qualidade pré-push com testes e linting.

Instalação

$npx convez-ai Lbstrydom/claude-engineering-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
0
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 1 dia
Versão
—
Issues abertas
3
Contribuidores
2

Casos de uso

  • Planejar e auditar features com múltiplos LLMs em paralelo
  • Detectar duplicação de código e drift arquitetural antes de commits
  • Validar comportamento de apps em produção com personas reais (Playwright)
  • Automatizar gate de qualidade pré-push (test, lint, commit, push)

Veredito

Ferramenta robusta para times que já praticam pair-programming e querem elevar QA com automação multi-modelo. Requer familiaridade com CLI e integração com VS Code/Cursor; a curva de aprendizado é alta, mas o ROI em menos bugs e refatoração é tangível. Recomendado para projetos médio-grandes com ritmo de deploy frequente.

README

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

Claude Engineering Skills

A bundle of AI-pair-programming skills for planning, auditing, testing, and shipping code. Works with Claude Code, VS Code Copilot, Cursor, Windsurf, and any terminal.

Three-model audit loop (Claude plans/codes, GPT audits, Gemini reviews) with adaptive learning, real-user persona testing against live URLs, and an architectural-memory layer that catches duplicate-function drift before code gets written.

Quick Reference

Slash commands (Claude Code / Copilot / Cursor):

When you want to…Command
Design a feature (auto-detects backend / frontend / full-stack)/plan <task>
Run the whole feature flow on autopilot/cycle <task>
Iterate on a plan with GPT + Gemini (max 3 rounds)/audit-plan <plan-file>
Audit code against its plan (multi-pass + Gemini final)/audit-code <plan-file>
QA a deployed app as a persona (Playwright + P0–P3)/persona-test "<persona>" <url>
Lock a fix's behaviour with a Playwright spec/ux-lock <commit-or-description>
Pre-push quality gate (test + lint + commit + push)/ship
"Why is this code shaped this way?"/explain <file:line>
Brainstorm with multiple LLMs (you drive convergence)/brainstorm <topic> (add --with-gemini)
Sync AGENTS.md / CLAUDE.md across all AI agents/ai-context-management audit
Bootstrap or add to per-repo security memory (incident log)/security-strategy bootstrap · /security-strategy add-incident

Architectural-memory (terminal):

CommandWhat it does
npm run arch:refreshIncremental: re-extract changed files, copy-forward the rest
npm run arch:refresh:fullFull rebuild from scratch
npm run arch:renderGenerate docs/architecture-map.md (Mermaid + flat tables)
npm run arch:driftCompute drift score for active snapshot
npm run arch:duplicatesList top cross-file duplicate clusters (refactor targets)
npm run security:refreshRe-parse docs/security-strategy.md and refresh the security_incidents Supabase index (auto-runs post-push from /ship)

Requirements layer (terminal) — a materialized view of the codebase's de-facto invariants, surfaced to /audit-code as a rubric:

CommandWhat it does
node scripts/requirements.mjs extract --files <a,b,…> [--runs N]Extract de-facto requirements from the given files (LLM ×N, merged) → .requirements/candidates.json + gaps.json
node scripts/requirements.mjs reconcileFold candidates + gap assessments + hand-curated .requirements/overrides.json into .requirements/ledger.json
node scripts/requirements.mjs indexPrint the active requirements index
node scripts/requirements.mjs renderRender the ledger as a human-readable map → docs/requirements-map.md (Mermaid pie + grouped tables)

Once .requirements/ledger.json exists, /audit-code automatically injects in-scope invariants as a rubric. See .requirements/README.md.

Workflow:

Full cycle (one command):       /cycle <task>     ← runs everything end-to-end

Atomic chain:
  /plan → /audit-plan → (you implement) → /audit-code → /persona-test → /ux-lock → /ship

Side-channels (anytime):
  /brainstorm   — second opinion with OpenAI/Gemini, manual convergence
  /explain      — read-only context synthesis from arch-memory + git
  Arch-memory   — auto-fires on UserPromptSubmit when prompt contains "fix" /
  consult hook    "add" / "implement" etc. — catches drift before it lands

Architecture

See docs/architecture-map.md — generated index of every symbol in this repo, grouped by domain, with Mermaid diagrams. Regenerated on /ship or via npm run arch:render.

Quick Start

git clone https://github.com/Lbstrydom/claude-engineering-skills.git
cd claude-engineering-skills
node setup.mjs

The wizard configures API keys, installs all skills globally, and sets up a git hook for auto-updates. Re-run git pull anytime to get updates.

To install into a specific repo (Copilot/Cursor/Agents support):

node scripts/install-skills.mjs --local --target /path/to/your/repo --force

Skills

All skills support JS/TS and Python (FastAPI, Django, Flask) with automatic stack detection.

SkillPurpose
planUnified planner — auto-detects backend/frontend/full-stack scope, lazy-loads the right principle set
audit-planIteratively audit a plan with GPT + Gemini final gate (max 3 rounds, rigor-pressure stop)
audit-codeMulti-pass code audit, R2+ ledger suppression, debt capture, Gemini final review
cycleEnd-to-end orchestrator: plan → audit-plan → impl gate → audit-code → persona-test → ux-lock → ship
explainSynthesises arch-memory + git history + AGENTS.md principles to answer "why is this here?"
ux-lockGenerates Playwright e2e specs that lock fixes' public DOM contracts (role, aria, data-testid — not CSS classes); verify-mode grades a plan against live impl
persona-testDrives a browser as a persona against a live URL → P0–P3 findings + qualitative debrief; results auto-correlate with audit findings
shipPre-push quality gate; warns on open persona-test P0s + missing regression specs
brainstormConcept-level multi-LLM thinking partner; user-driven manual convergence
ai-context-managementKeeps AGENTS.md / CLAUDE.md aligned across Claude / Copilot / Cursor / Windsurf

Deprecated aliases (kept for muscle memory): /plan-backend and /plan-frontend → /plan with scope hint; /audit-loop → /cycle (chained) or atomic /audit-plan / /audit-code.

Cross-skill data flow: every skill writes to a shared Supabase store via scripts/cross-skill.mjs. Plans link to audit runs (plan_id); ux-lock's Playwright specs link to source findings; persona-test P0/P1s become bandit reward labels; ship logs gate outcomes. See views: audit_effectiveness, unlocked_fixes, regression_saves, ship_gate_effectiveness.

Discovering skills (cheatsheet /skills)

Don't memorise every skill — surface them on demand. The /skills skill reads SKILL.md frontmatter directly (so the listing can never drift) and renders a compact reference. Five entry points:

Where you areHow to invoke
Claude Code (CLI / VS Code extension)/skills, /skills <name>, /skills --search "<term>"
GitHub Copilot Chat (VS Code, JetBrains)/skills (auto-generated .github/prompts/skills.prompt.md shim)
Cursor / Windsurf Chat/skills (same prompt-files convention)
VS Code Command PaletteCmd/Ctrl+Shift+P → Run Task → Skills: List all (also Skills: Detail for one skill, Skills: Search, Skills: Open SKILLS-INDEX.md)
Plain terminalnpm run skills:help (or npm run skills:help -- <name>, npm run skills:help -- --search "<term>")
Just browsingdocs/SKILLS-INDEX.md — auto-generated by npm run skills:index

Three-Model Audit Architecture

Claude/Copilot (plans + implements)
    ↓
GPT (5 parallel passes: structure, wiring, backend, frontend, sustainability)
    ↓ deliberation: accept / challenge / compromise
Gemini 3.1 Pro (independent final review: bias, consensus, missed issues)
    ↓
Adaptive learning (bandit arms, FP tracker, meta-assessment, prompt evolution)
  1. GPT audits in 5 focused passes
  2. Claude triages each finding — accept, challenge, or defer
  3. GPT deliberates on challenges — sustain, overrule, or compromise
  4. Fixes applied, then R2+ re-audits with suppression of resolved findings
  5. Gemini 3.1 Pro independent final review (catches blind spots in the GPT-Claude loop)
  6. Debt review triggers when deferred findings reach critical mass
  7. Meta-assessment periodically evaluates audit-loop quality, recommends prompt changes

CLI entry point (when not in an AI skill orchestrator):

node scripts/audit-loop.mjs code docs/plans/X.md            # Full orchestrated loop
node scripts/openai-audit.mjs code docs/plans/X.md          # GPT audit only
node scripts/gemini-review.mjs review <plan> <transcript>   # Gemini review only

Scope control: default audits only git-changed files. Override with --scope full, --exclude-paths 'vendor/**', or a .auditignore file.

Learning System

The audit loop gets smarter over time:

ComponentWhat it does
Thompson SamplingSelects best-performing prompt variant per pass (bandit arms)
FP TrackerTracks recurring false positives with exponential decay; auto-suppresses patterns with <15% acceptance
Meta-AssessmentEvery ~4 runs: evaluates FP rate, severity calibration, convergence speed; recommends prompt changes
Prompt EvolutionCreates experimental prompt variants, tests them via bandit, promotes winners
Debt ReviewClusters deferred findings by file/principle/recurrence; ranks refactor candidates by leverage
User-Impact RewardBandit also rewards findings that /persona-test later confirmed in a live browser

Learning applies to both GPT audit passes and Gemini final review.

Architectural Memory

Per-repo symbol-index in Supabase (with embeddings) catches duplicate-function drift before code gets written.

Indexes: every function, class, component, hook, route, method, and exported constant — name, file path, signature, body checksum, LLM-generated 1-line purpose summary, embedding vector. Snapshot-isolated per refresh.

Catches drift via 5 surfaces:

  1. Plan-time — /plan consults the index in Phase 0.5; near-duplicates appear as a "Neighbourhood considered" callout
  2. Ad-hoc-fix time — UserPromptSubmit hook auto-fires on intent verbs (fix, add, implement, etc.) and prepends a consultation callout to Claude's context
  3. Audit-time — /audit-code --scope=full inlines the full symbol catalogue
  4. Drift sweep — weekly GH workflow opens a sticky issue when cosine-similar symbol pairs cluster
  5. Render — committed docs/architecture-map.md with Mermaid C4 diagrams per domain

Setup per consumer repo:

# Add SUPABASE_AUDIT_SERVICE_ROLE_KEY to .env, then:
npm run arch:refresh:full
git add .audit-loop/repo-id docs/architecture-map.md package.json
git commit -m "feat(arch-memory): initial index"

Cost: ~$0.50 for first full refresh of a 1000-symbol repo (Haiku purpose summaries + Gemini gemini-embedding-001). Steady-state ~$0 thanks to signature-hash caching. Per-prompt hook consultation: ~$0.0003.

Tracked in consumer repos: .audit-loop/repo-id, .audit-loop/domain-map.json (path-based domain rules), docs/architecture-map.md, package.json arch:* scripts. Synced runtime files (scripts/lib/symbol-index/*, scripts/symbol-index/*, .claude/hooks/arch-memory-check.sh) are gitignored — managed by npm run sync from the source repo.

Browser Tools

/persona-test and /ux-lock use Playwright via .mcp.json (auto-discovered by Claude Code). Required first-time install:

npx playwright install chromium

Windows users — see CLAUDE.md for the npx.cmd MCP override needed by Claude Code's process spawner.

Supported Platforms

PlatformSkill locationInvoke
Claude Code (CLI, VS Code, Desktop)~/.claude/skills/<name>//<skill-name>
VS Code Copilot.github/prompts/<name>.prompt.md/<skill-name> in Copilot Chat
Cursor.github/prompts/ or .cursor/rules//<skill-name> or terminal
Windsurf.github/prompts//<skill-name> or terminal
Any terminalN/Anode scripts/audit-loop.mjs

Environment Variables

VariableRequiredPurpose
OPENAI_API_KEYYesGPT auditing
GEMINI_API_KEYNoGemini final review + Flash context briefs
ANTHROPIC_API_KEYNoClaude Opus fallback + Haiku purpose summaries
AUDIT_DB_URLNoPostgres DSN for the cloud learning store (Supabase pooler or self-hosted). Unset → local-only mode
AUDIT_DB_SSL_MODENorequire (default) / no-verify (Supabase poolers) / disable
SUPABASE_AUDIT_SERVICE_ROLE_KEYFor arch-memoryRequired for npm run arch:refresh* (writes to symbol-index tables)
META_ASSESS_INTERVALNoRun meta-assessment every N audits (default 4)
ARCH_RENDER_MAX_SYMBOLSNoCap on symbols pulled into the rendered map (default 50000)
ARCH_DRIFT_SCORE_THRESHOLDNoDrift score above this is RED (default 20)
PERSONA_TEST_SUPABASE_URL + PERSONA_TEST_SUPABASE_ANON_KEYNoPersona-test session memory
PERSONA_TEST_APP_URLNoDefault app URL for /persona-test list
PERSONA_TEST_REPO_NAMENoRepo name for cross-referencing audit findings

Learning Store

Set AUDIT_DB_URL to a Postgres 13+ DSN to enable cloud / cross-repo persistence (debt ledger, audit history, bandit arms, FP patterns). Works against Supabase (Session pooler, port 5432), self-hosted Postgres, RDS, Neon, Railway, etc. Requires the pgvector and pg_trgm extensions.

Unset → local JSON files only, single audit session, zero cloud. See AGENTS.md → Postgres-Parity Store for the connection model + setup recipe.

Security

  • .env files are gitignored; API keys are never logged
  • Sensitive file patterns excluded from external API calls
  • All subprocess calls use execFileSync (no shell string interpolation)
  • Brainstorm topic is run through redactSecrets() before sending to providers
  • Installer verifies SHA checksums against manifest before writing files

See SECURITY.md for vulnerability reporting.

Contributing

See CONTRIBUTING.md for development setup and PR guidelines.

License

MIT — see LICENSE

Ver o original no GitHub

Bom para

Relacionados