Claude Engineering Skills
Lbstrydom/claude-engineering-skills
Loop plan-audit-fix com 3 modelos de IA, memória arquitetural e QA automatizado
Ver no GitHubSuite 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-skills1 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
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):
| Command | What it does |
|---|---|
npm run arch:refresh | Incremental: re-extract changed files, copy-forward the rest |
npm run arch:refresh:full | Full rebuild from scratch |
npm run arch:render | Generate docs/architecture-map.md (Mermaid + flat tables) |
npm run arch:drift | Compute drift score for active snapshot |
npm run arch:duplicates | List top cross-file duplicate clusters (refactor targets) |
npm run security:refresh | Re-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:
| Command | What 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 reconcile | Fold candidates + gap assessments + hand-curated .requirements/overrides.json into .requirements/ledger.json |
node scripts/requirements.mjs index | Print the active requirements index |
node scripts/requirements.mjs render | Render 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.
| Skill | Purpose |
|---|---|
| plan | Unified planner — auto-detects backend/frontend/full-stack scope, lazy-loads the right principle set |
| audit-plan | Iteratively audit a plan with GPT + Gemini final gate (max 3 rounds, rigor-pressure stop) |
| audit-code | Multi-pass code audit, R2+ ledger suppression, debt capture, Gemini final review |
| cycle | End-to-end orchestrator: plan → audit-plan → impl gate → audit-code → persona-test → ux-lock → ship |
| explain | Synthesises arch-memory + git history + AGENTS.md principles to answer "why is this here?" |
| ux-lock | Generates 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-test | Drives a browser as a persona against a live URL → P0–P3 findings + qualitative debrief; results auto-correlate with audit findings |
| ship | Pre-push quality gate; warns on open persona-test P0s + missing regression specs |
| brainstorm | Concept-level multi-LLM thinking partner; user-driven manual convergence |
| ai-context-management | Keeps 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 are | How 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 Palette | Cmd/Ctrl+Shift+P → Run Task → Skills: List all (also Skills: Detail for one skill, Skills: Search, Skills: Open SKILLS-INDEX.md) |
| Plain terminal | npm run skills:help (or npm run skills:help -- <name>, npm run skills:help -- --search "<term>") |
| Just browsing | docs/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)
- GPT audits in 5 focused passes
- Claude triages each finding — accept, challenge, or defer
- GPT deliberates on challenges — sustain, overrule, or compromise
- Fixes applied, then R2+ re-audits with suppression of resolved findings
- Gemini 3.1 Pro independent final review (catches blind spots in the GPT-Claude loop)
- Debt review triggers when deferred findings reach critical mass
- 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:
| Component | What it does |
|---|---|
| Thompson Sampling | Selects best-performing prompt variant per pass (bandit arms) |
| FP Tracker | Tracks recurring false positives with exponential decay; auto-suppresses patterns with <15% acceptance |
| Meta-Assessment | Every ~4 runs: evaluates FP rate, severity calibration, convergence speed; recommends prompt changes |
| Prompt Evolution | Creates experimental prompt variants, tests them via bandit, promotes winners |
| Debt Review | Clusters deferred findings by file/principle/recurrence; ranks refactor candidates by leverage |
| User-Impact Reward | Bandit 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:
- Plan-time —
/planconsults the index in Phase 0.5; near-duplicates appear as a "Neighbourhood considered" callout - Ad-hoc-fix time —
UserPromptSubmithook auto-fires on intent verbs (fix,add,implement, etc.) and prepends a consultation callout to Claude's context - Audit-time —
/audit-code --scope=fullinlines the full symbol catalogue - Drift sweep — weekly GH workflow opens a sticky issue when cosine-similar symbol pairs cluster
- Render — committed
docs/architecture-map.mdwith 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
| Platform | Skill location | Invoke |
|---|---|---|
| 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 terminal | N/A | node scripts/audit-loop.mjs |
Environment Variables
| Variable | Required | Purpose |
|---|---|---|
OPENAI_API_KEY | Yes | GPT auditing |
GEMINI_API_KEY | No | Gemini final review + Flash context briefs |
ANTHROPIC_API_KEY | No | Claude Opus fallback + Haiku purpose summaries |
AUDIT_DB_URL | No | Postgres DSN for the cloud learning store (Supabase pooler or self-hosted). Unset → local-only mode |
AUDIT_DB_SSL_MODE | No | require (default) / no-verify (Supabase poolers) / disable |
SUPABASE_AUDIT_SERVICE_ROLE_KEY | For arch-memory | Required for npm run arch:refresh* (writes to symbol-index tables) |
META_ASSESS_INTERVAL | No | Run meta-assessment every N audits (default 4) |
ARCH_RENDER_MAX_SYMBOLS | No | Cap on symbols pulled into the rendered map (default 50000) |
ARCH_DRIFT_SCORE_THRESHOLD | No | Drift score above this is RED (default 20) |
PERSONA_TEST_SUPABASE_URL + PERSONA_TEST_SUPABASE_ANON_KEY | No | Persona-test session memory |
PERSONA_TEST_APP_URL | No | Default app URL for /persona-test list |
PERSONA_TEST_REPO_NAME | No | Repo 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
.envfiles 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