An orchestrator, eight
agents, seventeen rules, wired by
@-includes and H2 contracts. Click any node to inspect.
Pick a flow to watch a real request thread through the graph.
—
Agents
—
Rules
—
Commands
Updated
Loading graph…
—
Nodes
Meta / orchestrator
Rule
Command
Agent / template
Skill
MCP server
Hook
Edges
routes
@-include
dispatch
trigger
How to use this setup
From first session to overnight autonomy — the exact commands, and
the tricks that make them land.
What this is, in one loop
Every piece of this setup exists to kill one specific failure mode
of coding with AI.
1
Knowledge lives in files
CLAUDE.md, path-scoped rules, and
VERIFY.md live in the repo itself. Every session
boots with the project's tribal knowledge already loaded.
kills starting from
zero every session
2
Plan before code — adversarially
/plan drafts the approach, then independent
reviewer agents attack it before a line is written.
Disagreement surfaces while it's still cheap.
kills confidently
building the wrong thing
3
Delegate to fresh contexts
The main session orchestrates; specialist subagents do the
heavy reading and building, each in a clean context window.
Only conclusions come back.
kills context rot
on long tasks
4
No claim without evidence
"Done" requires running the verification command in the same
turn and reading its output. Deploy claims require the changed
surface's real proof signal — not some pipeline's green check.
kills "should work"
shipping broken code
5
The critical rules are hooks, not prose
The rules that must never be skipped — secret scans, SQL
guards — run as code at the tool layer. They fire whether or
not anyone remembers them.
kills rules that
get skipped under pressure
6
Mistakes become rules
Every correction gets written back into the files from stage
1. The setup that starts tomorrow's session is smarter than
the one that started today's.
kills repeating the
same mistake twice
↺ back to 1
Files in, evidence out, lessons written back. Everything else is
implementation.
1. Install once
One command. Two minutes. Adds custom agents, skills, commands, and
hooks to your local ~/.claude/.
git clone https://github.com/zalogarcia/zalo-claude-code-setup ~/.claude-setup
cd ~/.claude-setup && ./install.sh
The install added ~/.claude/CLAUDE.md. Claude reads
this every conversation — it's where your
preferences live: your stack, your safety rules, your QA discipline,
your team conventions. Without it, you'd re-explain "we use
TypeScript, prefer Supabase, never force-push to main" in every new
chat. With it, Claude already knows.
code ~/.claude/CLAUDE.md
When Claude makes a mistake, tell it. The file's
Learned Mistakes section grows automatically — your
preferences sharpen over time without you maintaining a list.
For project-specific overrides, drop
.claude/CLAUDE.md in any repo. Same format, scoped to
that codebase. Project rules win over global.
What's already encoded
The starter CLAUDE.md ships with the principles that
make /plan and /autopilot behave the way
they do. A taste:
"Never push without explicit permission."
Safety boundary that makes /autopilot commit freely
but stop at the push gate. Surprise pushes break teammates and CI.
"3+ file edits → mandatory /qa-loop." Build and
typecheck catch syntax; /qa-loop catches the
integration bugs and wiring issues that static checks miss by
design.
Verification Gate Function. Every claim of "done"
requires a runnable command + its output in the same turn. "Should
work" is how broken code gets shipped — this forces evidence.
Debug from live logs first. Form hypotheses
after reading the actual error, not before. Saves the
hours wasted on theories that contradict the runtime evidence.
Plans 3+ steps go to docs/PLAN.md.
Long workflows survive /compact and context limits;
re-read after compaction to restore state.
Direct/simple approach first. Agents love to
propose queues, intermediaries, and abstractions for hypothetical
futures. This principle keeps proposals flat and obvious.
Subagent discipline. A table tells Claude when to
use safe-planner, qa-agent,
brainstorm, live-test. The main thread
orchestrates; subagents do the heavy lifting in fresh context.
Default stack. TypeScript + Supabase + Vercel.
Stops Claude from suggesting AWS Lambda when you're a Next.js
shop. Override per-project as needed.
That's a slice of what's in there. Open it. Read it. Edit it. It's
yours now.
New to Claude Code? Start here
The 20-minute on-ramp — never touched it before, up and running by
the end:
cd into any project and type claude.
That's the whole install-to-running story.
Ask a question before you hand off a task:
"explain how auth works in this codebase." Read-only,
zero risk, and you'll watch how it explores.
Then a small real fix: paste the error message
verbatim (don't paraphrase), describe the outcome
you want, and let it run the verification itself.
Graduate to /plan for anything bigger than a
one-liner.
The mental model that changes everything: brief Claude like a senior
contractor, not an intern. Give it the outcome, the constraints, and
how you'll both know it's done — never the keystrokes. If your
prompt lists implementation steps, you're doing its job; if it names
an outcome plus acceptance criteria, it does yours.
3. Ship a feature
Two terminals: one plans, one builds. You verify.
Terminal 1
Describe what you want in plain English:
/plan add a dark mode toggle to my app
Claude breaks the task down, writes a rollback-ready plan to
.claude/.plan/latest/plan.md, and pressure-tests
it through verification gates.
Terminal 1
When /plan finishes, it prints a ready-to-paste
/autopilot command. Copy it.
Terminal 2
Open a second terminal. Paste the /autopilot
command. It runs the plan on its own — implements, tests,
audits, loops until clean.
Terminal 1
When /autopilot finishes in Terminal 2, return to
your main terminal and tell Claude:
autopilot finished — verify and push when it looks good
Claude checks the work, runs tests, and waits for your push
approval. Nothing leaves your machine without your okay.
Terminal 1
Before the next task, keep your conversation lean:
/compact
4. Fix a bug
One command. Claude traces, diagnoses, fixes, validates.
Terminal 1
Describe what's broken:
/bug users get logged out randomly after checkout
Claude traces the full flow, identifies the root cause (not
just a symptom), and stops if 3 fix attempts fail — that's a
signal the architecture is wrong, not the fix.
Terminal 1
Claude applies a narrow fix at the root cause, then a QA pass
confirms the bug is gone and nothing else broke.
5. Think something through
Pressure-test an idea before you commit code to it.
Terminal 1
Describe what you're wrestling with:
/brainstorm should we move from REST to GraphQL for our public API?
Claude applies inversion ("what if the opposite were true?"),
simplification ("what would eliminate 5 steps with one
insight?"), and stress-tests at 0.1× and 10× scale. You get a
sharper view of the tradeoffs.
Terminal 1
Use the output to inform the next /plan. If you
skip this step on hard decisions, you usually pay for it
later.
6. Run QA on anything
Audit code, plans, configs — iteratively until clean. Not just
inside /autopilot — standalone too.
Terminal 1
Point Claude at the thing you want audited:
/qa-loop check the auth flow I just refactored
Claude dispatches qa-agent to find
real bugs (not theoretical ones), applies fixes for
the CRITICAL/HIGH findings, then re-dispatches the audit.
Loops until ## VERIFICATION PASSED or the
iteration cap hits.
Terminal 1
Works on anything code-shaped — components, edge functions,
migrations, config files, plans. Run it whenever "did I test
it?" matters.
7. Bring any repo up to speed
One command scaffolds a repo so every future session starts smart:
/repo-init. It scans the codebase,
actually runs the build, test, and typecheck
commands to verify them — anything it can't verify gets marked,
never guessed — and writes three files into .claude/:
CLAUDE.md — the project brief every
session auto-loads.
path-scoped rules/*.md — conventions
that activate only when you're touching matching files.
VERIFY.md — a manifest of every
deploy surface and the proof signal that a change is
actually live there.
Why VERIFY.md earns its own file: the classic failure
is claiming "deploy verified" because some pipeline went
green — while the surface you changed deploys through a different
pipeline entirely. VERIFY.md makes each surface's real
proof explicit, and the QA and /autopilot commands read
it before claiming anything is live.
/repo-init
Then review the generated files and commit them — the knowledge
survives clones and travels to teammates.
8. Run it overnight
For long-horizon work with a clear finish line — baseline cleanups,
migrations, a feature with hard acceptance criteria — hand it a goal
and go to bed. /goal takes acceptance criteria where
every criterion is a command plus an expected result:
"tsc → exit 0", "lint → 0 errors", "≥ 15 tests passing."
Numbers, not vibes — "make it cleaner" can't converge; "0 errors"
can.
Three rules for the night shift
Switch to auto-accept first. Hit
shift+tab before you leave — a permission prompt at
2am silently stalls the whole run.
Hard gates stay human. Never let an overnight run
push, deploy, or run migrations. Commits land on a local branch
you review in the morning.
A usage limit loses nothing. The goal file
persists — type continue in the morning and it
resumes against the same pinned criteria.
Morning move: ask it to grade the result against the goal file
before you read a single diff.
/goal Baseline cleanup. Behavior-preserving only.
Criteria (fresh runs, exit codes captured):
1. npx tsc --noEmit → exit 0 (baseline: 32 errors)
2. npm run lint → 0 errors (baseline: 673)
3. npm run build → stays green after every batch
4. vitest installed, ≥15 smoke tests passing
Constraints: local branch only, NEVER push or deploy.
If stuck after 3 attempts on one criterion, log it as
deferred and move on — a documented gap beats a fake pass.
Tips from a year of daily use
Earned wisdom from running this loop daily. Take what's useful,
ignore the rest.
Prompting
Lead with images when you redesign
Tell Claude what you want with examples, not just
words. Screenshots from sites you admire, references from
styles.refero.design, mood boards. Words alone leave too much room for interpretation.
Once you've locked a direction, ask Claude to write a
design manifesto — a one-pager codifying the
aesthetic. Then have it generate an HTML page with 3 design variants
based on the manifesto. View them. Pick the winner. Iterate on that
one for the actual component or page.
Push back. Ask questions.
When the plan doesn't feel right, say so. When you don't understand
the reasoning, ask. The whole point of
/plan is to surface disagreement before code
gets written — not after a refactor lands.
Most of your time should be planning, not coding. The bug you didn't
introduce is the cheapest one to fix.
Pre-authorize the fork in the road
End research and investigation prompts with what to do in each
outcome:
"find benchmarks that justify keeping these — or else drop them
all."
Claude completes the whole arc in one pass instead of stalling to
ask which way to go.
Chain the condition to the action
"Once QA is clean, commit everything.""When tests pass, update the docs." One prompt, no
babysitting between steps.
Paste, don't describe
Error messages go in verbatim. UI bugs go in as screenshots dragged
into the terminal. "I just reproduced it" beats three
paragraphs about what maybe happened.
Trust, but verify
Ask "with evidence"
Two words appended to any status question —
"with evidence" — change the nature of the answer:
instead of confidence you get command outputs, exit codes, and
counted denominators. "Prove it ran" works the same way.
Demand denominators on "all / every" claims
"All tests pass" means nothing; "612 of 612, measured by X" means
everything. A claim with no denominator was a vibe.
Stress-test what you just set up
After adding a hook, rule, or automation, restart and ask Claude to
prove it fires — trigger it deliberately and show the block or
output. Config that was never exercised is config that silently
doesn't work.
Context & sessions
Keep context low
Long conversations get worse, not better. /compact
often — between tasks, when context climbs past half, anytime focus
shifts. Better to start the next task with crisp context than grind
through a degraded one.
Compact with instructions
Don't just /compact — steer it:
/compact keep the implementation plan and current progress. And never compact mid-step; finish, checkpoint, then compact.
The ! prefix is your reality feed
! npm test, ! git status — the
! prefix runs the command in-session and drops its raw
output straight into Claude's context. The fastest way to hand it
ground truth instead of your summary of it.
Say "remember this"
Corrections and preferences can be saved to persistent memory that
survives across sessions. A mistake corrected once should never need
correcting twice.
Scale & orchestration
Ask for subagents on big jobs
Phrases like "use subagents", "research this thoroughly with
parallel agents", or "use a workflow" unlock fan-out: independent
explorations run concurrently, each with fresh context, and only the
conclusions come back to your session.
Put your strongest model where decisions cascade
Planning and diagnosis errors multiply downstream — spend your best
model there ("use the strongest model where it matters") and let
cheaper, faster models handle volume implementation and QA sweeps.
One terminal, one job
Run the planner in one terminal, the overnight goal-runner in
another, your interactive session in a third — and
/rename each right after opening it (/rename plan-dark-mode, /rename autopilot-dark-mode). Sessions don't share
context, which is exactly the point; when 3+ are running in
parallel, the tab title is the only thing that tells you which is
which.
Crank reasoning effort up
Set Claude Code's reasoning effort to high or
xhigh for anything non-trivial — planning,
debugging, refactors, architecture decisions. The default is tuned
for speed; you want depth. Slower per turn, but you spend fewer
turns total because the first answer is the right one.
Reach for low/medium only when the task is genuinely mechanical
(file renames, copy edits, one-liner config changes). Everything
else, max it out.
How each command works
Under the hood: the harnesses that make this setup powerful — and
why most agent loops break without them.
CLAUDE.md
The context preloader. Every conversation starts here.
How it works
Claude reads ~/.claude/CLAUDE.md at the start of
every conversation — before you've typed a word. It's how Claude
knows your stack (TypeScript, Supabase, Vercel), your safety rules
(never force-push, additive migrations only), your QA discipline
(run /qa-loop after 3+ file edits), and your
conventions. The setup ships a sensible default; you tailor it
over time.
The file also drives the
Self-Learning Protocol: when you correct Claude,
it appends to the "Learned Mistakes" section automatically. No
manual journal — the file gets sharper the more you use it.
Per-repo overrides live at .claude/CLAUDE.md in any
project. Project rules override global rules — same format,
narrower scope.
Why it's powerful
Without persistent global context, every new chat is a blank slate
— you re-explain your preferences, your stack, your safety
constraints, every time. CLAUDE.md closes that loop.
Combined with /compact (which lets you preserve only
high-quality context for the next task), it's the discipline that
makes long-running multi-task days actually possible. The harness
commands (/plan, /autopilot,
/bug) all read this file too — so they default to
your stack, your tests, your safety boundaries, automatically.
/plan
Plan with verification before any code runs.
How it works
/plan dispatches safe-planner to
produce a rollback-ready plan: work units, dependencies, blast
radius, and a stated verification path. The plan then goes through
two parallel verification gates —
brainstorm pressure-tests it (inversion, scale
game, meta-pattern recognition) and
outcomes-grader scores it against engineering
principles. If either flags concerns, the plan gets one revision
pass. The final output is a ready-to-paste
/autopilot command.
Why it's powerful
Most coding agents start writing code immediately. Bugs from
premature implementation are 10× more expensive than the planning
step that would've prevented them. /plan forces the
"think first, code second" discipline — without making you do the
thinking. You get a reviewable plan you can actually push back on
before any file changes.
/autopilot
Runs a plan to completion, autonomously.
How it works
Five phases:
Plan → Implement → QA loop → Commit → Push gate.
Each phase emits a completion marker (e.g.
## VERIFICATION PASSED) that the orchestrator routes
on. Implementation work units run in parallel where safe. API
failures retry with exponential backoff; a circuit breaker halts
after 3 exhaustions in the same phase to avoid burning context on
a flaky upstream.
Why it's powerful
Lets you context-switch to other work while it runs. You return to
a finished implementation, tested and ready to push. The push gate
is non-negotiable — nothing leaves your machine without your
explicit approval. No babysitting required.
/bug
Trace, diagnose, fix, validate — with a hard stop.
How it works
Four-phase systematic debugging. Phase 1
understands the symptom (reproducible, observable, scoped).
Phase 2 traces backward from the symptom through
the call stack. Phase 3 finds the root cause —
not a contributing factor — and distinguishes the two.
Phase 4 stops at 3 failed fix attempts. That stop
is a signal: the architecture allows the bug to exist, your fix
isn't wrong.
Why it's powerful
Prevents the "tried five things, none worked" spiral that wastes
hours and burns context. The 3-fix stop is a forcing function for
stepping back instead of digging deeper. You either get a
root-cause fix or a clear signal that the problem is structural.
/brainstorm
Pressure-test an idea before you commit code to it.
How it works
Applies four critical-thinking techniques:
Inversion ("what if the opposite were true?"),
Simplification cascade ("what would eliminate 5
steps with one insight?"), Scale game (designs
for 0.1× and 10× scale and names the failure mode at each), and
Meta-pattern recognition (if a problem appears in
3+ unrelated domains, it's a universal principle worth naming).
Returns sharp tradeoffs, not vague recommendations.
Why it's powerful
Hard decisions made fast almost always cost more than soft
decisions made slowly. /brainstorm gives you a
structured second opinion without a human in the loop, surfacing
the hidden assumptions you missed. Use it before any architectural
change you can't easily undo.
/qa-loop
Audit, fix, re-audit — iteratively until clean.
How it works
A revision gate with an iteration cap. Dispatches
qa-agent to find real bugs (not theoretical
concerns). Fixes the CRITICAL/HIGH findings. Re-dispatches the
audit. Loops until ## VERIFICATION PASSED or the
iteration cap (typically 3) hits. If issue counts stop decreasing
between iterations, escalates early — stalling is its own signal.
Why it's powerful
"Did I test it?" is unreliable. /qa-loop turns
testing into a closed loop — fixes don't stop until the audit
comes back clean. Catches integration bugs, wiring issues, and
logic errors that static checks (build, lint, typecheck) miss by
design. Built into /autopilot, but also runnable
standalone whenever you want focused QA on a specific change.