convez.ai
SkillSegurançaAvançado
lesaathvik24

Protos Harness

lesaathvik24/protos-harness

Guardrails + coach interativo para parar de aprovar código às cegas

Ver no GitHub
InicialPluginScore · de 0 a 100

Suite de hooks, agentes e skills production-grade para Claude Code que bloqueia vazamentos de secrets, comandos perigosos e commits ruins. Inclui vibezombie, um coach em tempo real que interrompe o vibecoding automático forçando decisões arquiteturais conscientes antes de gerar código.

Instalação

$npx convez-ai lesaathvik24/protos-harness

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

Casos de uso

  • Prevenir vazamento de secrets e credenciais em commits
  • Bloquear execução de comandos perigosos durante desenvolvimento
  • Forçar decisões arquiteturais conscientes antes de coding automático
  • Evitar degradação de compreensão do codebase com vibecoding

Veredito

Ferramenta madura (v0.2+) que endereça um problema real: developers aprovando código IA sem entender decisões. vibezombie é inovador — usa PreToolUse hooks para forçar escolha arquitetural antes da execução, não depois. Recomendado para equipes que querem rigor sem sacrificar velocidade.

README

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

Protos Harness

License: MIT test-hooks Version Claude Code

v0.3 — actively building. The seven guardrail hooks are battle-tested; community skills and agents are curated. vibezombie is the first original skill built for this harness — now with technical-only forks, "it-depends" conditional reveals, and a cross-session learner model. The reason you're probably here. See below.

A Claude Code harness for developers who want guardrails, not training wheels. Seven production-grade hooks that block secrets, dangerous commands, and bad commits — plus vibezombie, a realtime coach that stops you vibecoding on autopilot, 23 curated skills, and two purpose-built agents.


🚧 sobr/ — the standalone agent runtime (in progress)

This harness is also the spec for sobr — a from-scratch, glass-box AI coding-agent runtime (TypeScript + Bun) that owns its own loop over the Claude API (and any OpenAI-compatible API like GPT or DeepSeek). It absorbs the hook layer into typed validators and turns vibezombie into an in-runtime teach mode: fork/trivial tools, an unskippable write gate, and a cross-session learner profile. Weeks 1–3 of 4 are built (core loop, glass-box trace + policy engine, teach mode); 162 tests, tsc clean. See sobr/README.md, the spec in plan.md, and phase-by-phase progress in phases/.


vibezombie — your AI is quietly making you a worse developer

Vibecoding makes you a zombie. This skill makes you choose.

You've felt it. The agent writes the code, you skim it, you hit accept, you move on. Ship after ship — and somehow you understand the codebase less than when you started. That's not coding. That's approving.

Every other "fix" runs after the fact: a quiz, a Feynman doc, an "explain what you just did" prompt you'll never reopen. vibezombie runs in the moment.

The instant the agent hits a real decision — where state lives, sync vs async, which seam to cut — it stops. It shows you the actual options for your codebase (not textbook ones), each with its real tradeoff. You pick. Then it builds. You don't get the code until you make the call.

And it can't quietly skip the lesson: PreToolUse gates block any edit the agent didn't first account for, reject a plan that skipped the stack fork, and strip career/popularity bias out of the options. No silent decisions. You're the navigator now, not the rubber stamp.

/vibezombie on L2

FORK — where should the new filter's state live?
  1) colocate in the component   simplest; lost on unmount, not shareable
  2) lift to the existing store  shareable; more wiring, store grows
  3) new store slice             clean isolation; boilerplate for one flag
> you pick → agent reveals the expert call & why → then it builds

Stakes dial (set once, changeable anytime):

LevelForks onFor
L1architecture only (data model, sync vs async, auth) — ~1–3 per featureoccasional teaching moments
L2 (default)+ module boundaries, error strategy, key library/API choicesactually leveling up
L3+ idiom-level forks (this construct vs that)deliberate study sessions

Modes: Reveal (default — after you pick, the agent states the expert call in ≤2 sentences) · Hard (/vibezombie on L3 hard — you must justify your pick first; the agent checks your reasoning).

It forks on tech, not your goals. It never asks why you want to build the thing — that's yours. Scope comes first as a plain question ("where does it run", what to build); the stack it forces is a separate fork with bare options — never fused into one ("Web (React/Next.js)" is banned). It interrupts only for real engineering calls (stack, storage, data model, sync/async), and the options are neutral — real tradeoffs stated flat, none pre-sold or trapped, with a gate that hard-blocks any career or popularity phrasing that leaks into an option (so neutrality holds even when your CLAUDE.md is full of personal context). The reveal maps the full tradeoff across the axes that matter (perf · ecosystem fit · ship speed · learning · hiring), and when the honest answer is "it depends" it names the deciding factor or threshold (e.g. *expected users: `<100 / 100–10k /

10k`*). Then it asks what you're optimizing and gives a recommendation conditioned on your answer, confirming or flagging your pick — never assuming the priority for you.

It learns you. A cross-session model (~/.claude/.vibezombie/profile.md) tracks the concepts you've demonstrably mastered and stops re-teaching them, spending interrupts on new ground and ramping difficulty as you improve. Inspect or correct it anytime with /vibezombie profile — you own the model, it's not a black box.

Receipts. Every decision is tagged and appended to ~/.claude/.vibezombie/log.md — your auditable proof that nothing passed unexamined:

# vibezombie decision log

## FORK — filter state location
- chose: lift to the existing store
- options: colocate | existing store | new slice
- expert call: existing store — state is read by two siblings, so colocation would force a lift later anyway
- TRIVIAL: rename helper var
- TRIVIAL: extract constant

Install standalone (just the skill + gate hook, none of the rest of the harness):

curl -fsSL https://raw.githubusercontent.com/lesaathvik24/protos-harness/main/install-vibezombie.sh | bash

Then restart claude and run /vibezombie. Turn it off anytime with /vibezombie off — the hooks are a no-op when inactive, so they never touch your normal work. The activation line shows the build (vibezombie v0.4.0 active) so you always know which version is loaded; skill edits take effect only after /vibezombie off then on (a running session doesn't hot-reload).

I built this because I caught myself becoming the zombie — accepting diffs I couldn't have written, on a codebase I was supposed to know. It's opt-in, it's honest about when a decision is trivial, and the log is there so you can call it out when it under-asks. If it makes you slower for the first week, that's the point.


Install

git clone https://github.com/lesaathvik24/protos-harness
cd protos-harness
bash install.sh

Or one-liner:

curl -fsSL https://raw.githubusercontent.com/lesaathvik24/protos-harness/main/install.sh | bash

Restart claude after install. The installer is non-destructive — it merges into your existing ~/.claude/settings.json, preserving your theme, effortLevel, and any other settings.

Verify installation

# 1. Hooks are present and executable
ls -la ~/.claude/hooks/
# → 8 .sh files, all rwxr-xr-x (7 guardrails + vibezombie-gate)

# 2. Hooks actually block — trigger each manually:
echo '{"content": "key = \"sk-abc123abc123abc123abc123abc\""}' | bash ~/.claude/hooks/scan-secrets.sh
# → BLOCKED: Secret pattern detected — OpenAI/Anthropic key (sk-)

echo '{"command": "rm -rf /data"}' | bash ~/.claude/hooks/dangerous-command-guard.sh
# → BLOCKED: Dangerous command detected: rm -rf /

echo '{"command": "git commit -m \"wip\""}' | bash ~/.claude/hooks/commit-message-guard.sh
# → BLOCKED: Commit message must use Conventional Commits prefix.

# 3. Agents are present
ls ~/.claude/agents/
# → builder.md  tester.md

# 4. Skills are present
ls ~/.claude/skills/ | wc -l
# → 24 (23 curated + vibezombie)

# 5. Settings are wired
cat ~/.claude/settings.json | python3 -c "import sys,json; d=json.load(sys.stdin); print(list(d.get('hooks',{}).keys()))"
# → ['PreToolUse', 'PostToolUse', 'SessionStart']

Demo

$ echo '{"command": "rm -rf /var/www"}' | bash hooks/dangerous-command-guard.sh
BLOCKED: Dangerous command detected: rm -rf /

$ echo '{"content": "API_KEY = \"sk-abc123...\""}' | bash hooks/scan-secrets.sh
BLOCKED: Secret pattern detected — OpenAI/Anthropic key (sk-)

$ echo '{"command": "git commit -m \"stuff\""}' | bash hooks/commit-message-guard.sh
BLOCKED: Commit message must use Conventional Commits prefix.
  Expected: feat|fix|refactor|docs|test|chore|style|perf|ci|build|revert
  Got: stuff

Hooks

Eight hooks wired across the Claude Code event lifecycle (seven guardrails + the vibezombie gate).

HookTriggerBehaviorType
scan-secrets.shPreToolUse: Write, EditBlocks writes containing sk-, AKIA, ghp_, ghs_, PRIVATE KEY, DATABASE_URL, hardcoded password=/secret=Blocking
dangerous-command-guard.shPreToolUse: BashBlocks rm -rf /, sudo rm, mkfs, dd if=, shutdown, reboot, diskutil eraseDisk, chmod -R 777 /Blocking
commit-message-guard.shPreToolUse: BashEnforces Conventional Commits on git commit -mBlocking
auto-lint.shPostToolUse: Write, EditRuns ruff + black for Python, prettier + eslint for JS/TS, prettier for JSON. Silent if tools missingWarn
test-impact.shPostToolUse: Write, EditRuns pytest or npm test after non-test file editsWarn
dependency-audit.shPostToolUse: BashRuns npm audit --audit-level=high or pip-audit after install commandsWarn
git-status-check.shSessionStartWarns on detached HEAD, merge conflicts, >200 modified filesWarn
vibezombie-gate.shPreToolUse: Write, EditWhile /vibezombie mode is active, blocks any edit not preceded by a logged decision (FORK or TRIVIAL). No-op when inactive. Details ↑Blocking (opt-in)

Blocking = exit 2, Claude stops and reports the violation. Warn = exit 0, prints to stderr, Claude continues.

How hooks work

Hooks are shell scripts that receive tool input as JSON on stdin. They parse the input, check for violations, and exit 0 (allow) or 2 (block).

# Test any hook manually:
echo '{"command": "rm -rf /"}' | bash hooks/dangerous-command-guard.sh

Running the test suite

bash tests/run.sh

13 fixture-based tests cover the four blocking hooks (pass and block cases), including the vibezombie gate's active/tagged/untagged states. CI runs them on every push across Ubuntu and macOS. The vibezombie skill's behavior (fork quality, conditional reveals, learner-model suppression) is covered by human-readable scenario rubrics in tests/scenarios/vibezombie/ — run live now, automatable as transcript evals later.


Agents

Two subagents. Each costs ~4× more tokens than inline work — only invoke when the task is large enough to justify it (e.g., reading 10 files to summarize, or running a full test suite where you don't want the output in your main context).

builder — implementation agent

  • Tools: Read, Edit, Write, Bash, Glob, Grep
  • Invoke: "use the builder agent to refactor the auth module"
  • Reads context, writes code, runs lint — does not run tests

tester — verification agent

  • Tools: Read, Bash, Grep, Glob
  • Invoke: "use the tester agent to verify the new API endpoints"
  • Runs tests, checks regressions, audits output — does not write production code

Disabling agents

If you're token-budget-conscious or prefer inline work:

rm ~/.claude/agents/builder.md   # disable builder
rm ~/.claude/agents/tester.md    # disable tester

Re-enable: cp agents/<name>.md ~/.claude/agents/


Skills (24 — 23 curated + 1 original)

Skills are slash-command workflows loaded on demand — they cost zero tokens when not active.

SkillInvokeWhat it does
vibezombie ⭐/vibezombieOriginal / flagship. Realtime anti-vibecoding coach — forces you to choose between grounded alternatives before code is written. Details ↑
tdd/tddTest-driven dev loop
diagnose/diagnoseDisciplined bug diagnosis: reproduce → minimise → fix → regression
prototype/prototypeThrowaway prototype to validate a design
review/reviewReview changes since a commit/branch (Standards + Spec)
qa/qaConversational QA session that files GitHub issues
triage/triageIssue triage state machine
to-prd/to-prdTurn a rough idea into a PRD
to-issues/to-issuesBreak a plan into independently-grabbable issues
grill-me/grill-meStress-test your plan against your own domain model
grill-with-docs/grill-with-docsSame, but updates CONTEXT.md + ADRs inline
design-an-interface/design-an-interfaceGenerate radically different API designs in parallel
improve-codebase-architecture/improve-codebase-architectureFind refactoring opportunities
handoff/handoffCompact conversation into a handoff doc
write-a-skill/write-a-skillBuild a new skill with proper structure
find-skills/find-skillsDiscover installable skills
edit-article/edit-articleRestructure and tighten prose
obsidian-vault/obsidian-vaultSearch and manage Obsidian notes
git-guardrails-claude-code/git-guardrails-claude-codeBlock destructive git ops via hooks
greploop/greploopIterate a PR until Greptile gives it 5/5
zoom-out/zoom-outStep back and assess the bigger picture
ubiquitous-language/ubiquitous-languageAlign code terminology with domain language
teach/teachExplain a concept or codebase area
setup-matt-pocock-skills/setup-matt-pocock-skillsInstall mattpocock skill pack

Attribution: the curated skills come from mattpocock/skills; Protos Harness bundles them for one-command install, and original authorship belongs to that project. vibezombie is original to this harness.


Project structure

protos-harness/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── .github/workflows/
│   └── test-hooks.yml          # CI runs hook tests on push/PR
├── hooks/                      # 8 bash hook scripts (7 guardrails + vibezombie-gate)
├── skills/                     # 24 skill directories (incl. original vibezombie)
├── agents/                     # builder.md + tester.md
├── scripts/
│   └── merge-settings.py       # Non-destructive settings.json merger
├── tests/
│   ├── run.sh                  # Test runner
│   └── fixtures/               # JSON input fixtures, pass-/block- naming
├── settings.json               # Reference hook config
├── install.sh                  # One-command installer (whole harness)
├── install-vibezombie.sh       # Standalone installer (just the vibezombie skill + gate)
├── LICENSE                     # MIT
├── CONTRIBUTING.md
├── CHANGELOG.md
└── README.md

Roadmap

These are next on the list — PRs welcome:

  • cost-tracker.sh — PostToolUse hook logging token delta per tool to ~/.claude/session-costs.jsonl + /cost-report skill
  • context-budget.sh — PreToolUse hook warning when session is >70% of context window
  • auto-checkpoint skill — /checkpoint commits current state with timestamp; /restore-checkpoint rolls back
  • Original (non-curated) skills written for this harness — vibezombie shipped (v0.2), with technical-only forks, conditional reveals + cross-session learner model (v0.3)
  • Optional Slack/Discord notification on blocked actions

Contributing

See CONTRIBUTING.md. TL;DR: fork, branch, add fixture-based tests for new hooks, open a PR with Conventional Commits.


License

MIT

Ver o original no GitHub

Bom para

Relacionados