Claude Code Workflow

A complete, opinionated Claude Code workflow. 23 skills, 10 hooks, 29 guides, 7 tools, a routing table, and an operating model you can install in one command.

This isn’t a tutorial or a library. It’s a working configuration – built over a year of daily use – that you can copy into your own setup and adapt.

What’s New in v3

v2 (April 2026) shipped the full skill/hook/guide system. v3 ships three months of what daily use did to it – including the parts that reversed:

• Usage honesty. The skill-usage log now has enough data to say what actually gets used (see What Actually Gets Used below). The verdict reshaped this release: session-lifecycle ritual and dialectic review carry the workflow; many of the specialist one-shot skills mostly don’t get invoked.
• RESOLVER.md – a routing table mapping task descriptions to skill invocations and content types to filing destinations. The single biggest structural addition since v2: with 20+ skills, “what should I invoke” and “where does this fact go” became decisions worth making deterministic. Includes a formal ≥2-sightings promotion gate for candidate rules.
• A reversed rule. v2’s Scope Discipline told Claude to push back on ambitious plans and suggest smaller increments. Real usage showed the agent’s underscoping instinct is the bigger failure mode. The section now defaults to continuation – and documents its own reversal, because a workflow repo that only ships rules that survived unchanged is lying by omission.
• Mid-Session Hygiene – new CLAUDE.md section: /rewind over appended corrections, /clear at task-type boundaries, steered /compact at ~60% instead of riding into auto-compaction, and diagnose-before-abandoning for off-track sessions.
• 16 new guides – including hook self-testing, verify-before-deploy, data-before-code, subagent severity calibration, prose de-AI-ism, native HTML/CSS charts, and pre-publish critical response. Several encode rules promoted only after the same failure was sighted twice or more in real sessions.
• 4 new skills – /distill (extract rules from your corrections), /sessions (find/resume past sessions), /check-resolvable (audit orphaned config), /autoresearch (bounded autonomous optimization). Plus --council mode for /dialectic-review and a deterministic scope gate in /plan-task.
• Hook bugfix release + test harness. Two rounds of adversarial review (a solo pass in July, then a full multi-agent dialectic on the v3 diff itself) found the v2 hooks had silent no-op failure modes (bare python on python3-only systems), bypasses (chained commands, multi-target rm -rf, flag-order variants), and false positives (git push origin my-feature-branch matching a -f pattern, git add .gitignore matching git add .). All fixed, with a test harness (hooks/test-hooks.sh) covering all 10 hooks, and deploy.sh now verifies post-install that the hooks actually fire rather than failing open silently. The defect lists are honest history: nearly every bug would have been caught by the repo’s own doctrine applied to itself — including the second round’s finding that the first round’s fixes landed in one file but not its siblings.

Quick Start

Tier 1: Just the operating model.

cp CLAUDE.md ~/.claude/CLAUDE.md   # back up any existing ~/.claude/CLAUDE.md first

Edit the Platform Notes and Interaction Style sections to match your setup. This single file changes how Claude approaches every task. One caveat: this CLAUDE.md is written for the full install. On its own, its skill references (/dialectic-review etc.), its ~25 situational-guide pointers, and the RESOLVER.md routing mandate all point at files you won’t have — the Decision Quality Gates have an explicit no-skills fallback, but the guide pointers will just be dead references Claude learns to skip. Tier 1 is a preview of the operating model, not a working subset; the working system is Tier 2.

Tier 2: Full install (recommended).

git clone https://github.com/griffinhilly/claude-code-synthesis /tmp/claude-workflow
bash /tmp/claude-workflow/deploy.sh

deploy.sh copies CLAUDE.md, RESOLVER.md, skills/, commands/, hooks/, guides/, and tools/ into ~/.claude/, backs up any of your files it would overwrite (to ~/.claude/.deploy-backup-/), and — critically — registers the hooks in ~/.claude/settings.json. Hooks only fire if registered there; copying the files alone does nothing. It asks before overwriting an existing CLAUDE.md, and if you already have a settings.json it prints the hook block for you to merge by hand.

Prefer manual installation? Copy the five directories the same way (mkdir -p ~/.claude/skills && cp -r /tmp/claude-workflow/skills/* ~/.claude/skills/, and likewise for commands, hooks, guides, tools), then register the hooks in ~/.claude/settings.json using the template inside deploy.sh.

Tier 3: Let Claude do it. Tell Claude Code: “Clone https://github.com/griffinhilly/claude-code-synthesis and set up my config based on it.”

New to all of this? Start with three. After installing, use just /plan-task, /dialectic-review, and /wrapup for your first week, and add more as the workflow proves itself. (Our own usage log says those — plus the doctrine in CLAUDE.md — carry most of the value; see What Actually Gets Used.) The full set below is a menu, not a curriculum.

What’s In Here

CLAUDE.md – The Operating Model

The behavioral contract that governs every session. Defines leverage doctrine (human decides, Claude executes), plan-first protocol, scope discipline, agent principles, dialectic reviews, implementation behavior, mid-session hygiene, security safeguards, the COMP documentation system, and workflow evolution rules. See the Key Ideas section below for highlights.

RESOLVER.md – The Routing Table

Task descriptions → skill invocations; content types → filing destinations. Consulted before invoking a skill on an ambiguous task or writing any cross-project memory. Also holds the when-to-make-a-new-skill checklist and the ≥2-sightings promotion gate that keeps single-occurrence “lessons” from accumulating as permanent doctrine.

skills/ – 23 Slash Commands

Skills live in skills//SKILL.md directories (installed to ~/.claude/skills/) and encode multi-step workflows as single invocations. They range from lightweight wrappers (brainstorm, premortem) to complex multi-agent protocols (dialectic-review, debug, bug-hunt).

commands/ – 7 Workflow Commands

Commands are user-invocable slash commands that handle session lifecycle and prompt formatting. Unlike skills (which are task-specific), commands are workflow infrastructure – session start/end, commit preparation, plan review, context pruning.

hooks/ – 10 Event Hooks

Every hook is covered by hooks/test-hooks.sh, a harness that feeds each of the 10 hooks the same JSON the Claude Code harness would send and asserts the exact allow/block/notice exit code — including regression cases for every bypass and false positive found in review. Run it after any hook edit (see guides/hook-self-test.md). Note the delivery mechanics it encodes: on PreToolUse/PostToolUse, exit-0 output never reaches the model (it surfaces at most in the user-facing transcript); a warning only reaches the model via PostToolUse exit 2 (non-blocking notice), which is how the three reminder hooks work. And know the failure mode: if no working python3/python is on PATH, the hooks fail OPEN — deploy.sh checks for this at install time.

tools/ – 7 Utilities

guides/ – 29 On-Demand Reference Docs

Guides load on-demand when triggered by specific situations. This keeps CLAUDE.md lean while making deep knowledge available when needed.

examples/data-pipeline/ – Working Example

A complete data enrichment pipeline demonstrating these patterns in action: step-based pipeline runner with dry-run and skip flags, LLM batch categorization with taxonomy normalization, verify-and-merge cycles, and semantic search over enriched data.

What Actually Gets Used

This repo ships a log-skill-usage.sh hook precisely so this question has an answer. Four months of logged invocations (165 entries, April–July 2026) from the config this repo is a snapshot of:

Honest readings of that last row:

1. Session lifecycle + adversarial review are the workflow. The two dominant skills are the ritual bookend (/wrapup compounds knowledge into COMP files every session) and the decision stress-tester. If you install only two skills, install those.
2. Wrappers get absorbed. /premortem, /tradeoff, /red-team, /brainstorm are thin wrappers around /dialectic-review modes — usage flows to the parent skill. That’s the design working, not failing.
3. Some zeros are real. /ship, /verify, /implement, /learn genuinely get skipped: their behaviors partially migrated into CLAUDE.md doctrine (verify-before-done, operationalize-every-fix) that fires without explicit invocation. A skill whose content graduates into always-on doctrine is a success that looks like a failure in the log.
4. Measurement has holes. The hook only logs invocations routed through the Skill tool; auto-triggered skills and some earlier months aren’t captured. Treat the log as strong signal, not census.

The meta-lesson we’d offer anyone building a big config: instrument first, prune second. We’d have guessed wrong about half of this table.

The COMP System

Every project maintains 4 files that keep Claude Code effective across sessions:

The key insight: separate behavioral instructions (CLAUDE.md) from human orientation (ORIENT.md) from accumulated knowledge (MEMORY.md) from direction (PLAN.md). Each file has a different audience, change frequency, and purpose.

Key Ideas Worth Highlighting

Orchestrator-first mindset. The session agent shouldn’t do everything itself. Before any task, assess: handle directly, delegate to a subagent, or route to MCP? This is the single biggest lever for productivity with Claude Code.

Dialectic reviews. For important decisions, don’t ask Claude “what should I do?” Instead, spawn opposing agents – one argues FOR, one argues AGAINST – with a referee to synthesize. Four modes cover different needs: adversarial review, ideation, tradeoff comparison, and premortem.

Structured debugging (4-phase). Evidence before hypotheses. Hypotheses before reproduction. Reproduction before fix. Each phase has a hard gate requiring a written artifact. Prevents the “just try random fixes” loop that wastes unbounded time.

Three-fix escalation. If a fix has been attempted 3 times and the problem persists, STOP. Don’t try a fourth. The approach or architecture is likely wrong. Escalate to the human.

Subagent distrust. Implementation subagents are assumed unreliable until verified. The /implement skill mandates post-execution validation by a fresh-context subagent that doesn’t share the implementer’s assumptions.

Confidence-scored planning. Plans identify where confidence is lowest and dispatch targeted research to weak sections before implementation begins. Adapted from Compound Engineering’s ce-plan.

Knowledge compounding. The /learn skill captures structured learnings (gotchas, patterns, decisions, bug fixes) as searchable JSONL. Knowledge from one project informs the next. The /retro skill turns recurring patterns into permanent rules or new skills.

Progressive disclosure. Don’t dump everything into CLAUDE.md. Keep it lean with trigger rules (“when X happens, read guide Y”). The guides load on-demand, keeping always-loaded context small and token costs low.

Forcing specificity. “Use version control” is not a useful lesson. “Commit data pipeline changes separately from visualization changes so rollbacks are clean” is. Every encoded rule and learning must reference concrete experience.

Compaction-safe artifacts. Claude Code conversations get compressed as they grow. Important outputs should be written to files immediately, not left in conversation history. The post-compact-reminder.sh hook re-injects session context after compaction events.

Operationalize every fix. When a bug is found and fixed, don’t stop. Write tests that catch that bug and the whole class of similar bugs. Check for other instances. Update instructions if the bug reveals a workflow gap. Every bug is a learning opportunity.

Evals before specs. Define how you’ll evaluate success before writing the spec. The progression – evals, spec, plan, implement, verify – produces better outcomes than plan, implement, “does this look right?”

Human gates in pipelines. Data enrichment workflows aren’t fully automatable. Making the interruptible workflow explicit – with named steps, skip flags, and resume points – is better than pretending it’s a straight-through pipeline.

The virtuous circle. Use your tools to improve your tools. Extract patterns from past sessions into skills or guides, apply them to new projects, refine based on results. The workflow improves itself through use.

The promotion gate. A lesson observed once goes to candidate-rules.md, not to permanent doctrine. Only a second real sighting promotes it (bug-classes, security items, and explicit user requests skip the gate). This is the difference between a CLAUDE.md that compounds and one that silts up with rules that never fire. Several v3 rules carry their promotion history inline — “promoted after the second real incident of X” — as evidence they earned their place.

Latent vs deterministic. Every workflow step is either model judgment (synthesis, fuzzy classification) or code (counting, joining, thresholding). Putting deterministic work in latent space is the most common agent-design mistake. Wherever a spec names a number, that step should be code. RESOLVER.md itself is this principle applied to skill routing.

Mid-session hygiene. Context is a resource you manage mid-flight, not just at session boundaries: /rewind failed approaches out of context instead of appending corrections, /clear at task-type boundaries, steer /compact manually at ~60% rather than riding into auto-compaction at ~90%.

Recommended Workflow

The 9-step flow from /start to /prune, covering a complete session lifecycle:

1. /start – Load context, review state, plan the session
2. /prompt or /plan-task – Convert a rough idea into structured instructions (use /plan-task for bigger efforts)
3. /review-plan – Stress-test the plan before building (triggers dialectic for complex plans)
4. /implement – Execute the plan with subagent validation
5. /verify – Check that outputs are complete, consistent, and nothing was silently skipped
6. /review – QA against success criteria
7. /ship – Pre-commit readiness check, stage files, commit
8. /wrapup – Update COMP files, check skill health, audit context bloat
9. /prune – Periodically trim context bloat (monthly or when /wrapup flags it)

Not every session uses all 9 steps. A quick bug fix might be /start, /debug, /ship, /wrapup. A planning session might be /start, /plan-task, /review-plan, /wrapup. Use judgment — and note that What Actually Gets Used shows our own sessions rarely invoke steps 4-7 explicitly anymore; their checks migrated into always-on CLAUDE.md doctrine. The 9 steps are the full ceremony; the lived workflow is closer to steps 1-2, doctrine doing 4-7 implicitly, then 8.

Updating and Uninstalling

Update: pull the repo and re-run deploy.sh. It overwrites same-named shipped files (so customize under different filenames) and leaves everything else alone; it asks before touching your CLAUDE.md.

Uninstall: delete the installed files — the skills, commands, guides, hooks, and tools listed in the tables above — from ~/.claude/, and remove the hook entries from ~/.claude/settings.json.

Standing on the Shoulders of Giants

This workflow didn’t emerge in a vacuum. Most ideas were shaped by things read, bookmarked, and experimented with. Here’s where the concepts come from.

Agent Architecture and Orchestration

• Boris Cherny (@bcherny) – Creator of Claude Code. His tips thread on how the Claude Code team uses the tool differently than most people was foundational. His insight about separate context windows and test-time compute directly shaped the orchestrator-first and subagent delegation patterns.
• @systematicls – Their reply about context windows (“aggressively clear them when doing your work, and you can have your own code review agents by building a new context window”) crystallized the fresh-eyes-for-review principle.
• @doodlestein – Their observation that the Unix tool approach (“focused, composable functional units that can be used in isolation or as part of a larger pipeline”) is the best model for AI agents directly influenced how the delegation templates are structured.
• Simon Willison (@simonw) – His Agentic Engineering Patterns guide is the most rigorous public treatment of coding agent best practices. Many of the implementation behavior rules reflect patterns he documented.

Source Frameworks: Superpowers, gstack, Compound Engineering

• Jesse Vincent (@obra) – Superpowers: methodology-as-code with 14 skills and zero infrastructure. Key adoptions: 4-phase structured debugging (systematic-debugging), red flag language detection (verification-before-completion), TDD enforcement, three-fix escalation rule, and psychology-based agent persuasion using Cialdini’s influence principles.
• Garry Tan (@garrytan) – gstack: virtual engineering team with 31 skills. Key adoptions: persistent browser daemon architecture (ref system over CSS selectors), learn skill for knowledge capture, cross-model review concept (generalized here to cross-role dialectic), and the plan-exit review pattern. The careful/freeze/guard hooks and office-hours forced specificity influenced our hook and guide design.
• Every Inc / Nathan Baschez – Compound Engineering: knowledge compounds over time. Key adoptions: ce-compound knowledge compounding (simplified to JSONL-based /learn), ce-review 18-reviewer confidence-gated system (simplified to single-reviewer with structured dimensions), ce-plan confidence scoring for plans, and the discoverability check (verifying that captured knowledge is actually findable by agents).

For the full mapping of what was adopted from each framework, what was skipped, and why, see guides/reference-repo-comparison.md.

CLAUDE.md and Context Management

• Todd Saunders (@toddsaunders) – His insight about rewriting CLAUDE.md from scratch every few weeks, and understanding that CLAUDE.md occupies a “high-dimensional vector space” of possible starting coordinates, shaped the quarterly CLAUDE.md health review.
• @mstockton – Their reply expanding on Todd’s point about CLAUDE.md being the first file loaded into context helped crystallize the progressive disclosure pattern.
• Pawel Huryn (@PawelHuryn) – His post about tracking domain vs procedural knowledge became the knowledge-type separation in the context efficiency guide.
• @koylanai – Their hook ideas table (18 practical hook ideas) is the best starting point for building your own Claude Code hooks.

Structured Prompting and XML Tags

• Anthropic’s prompting documentation – The principle that Claude processes tagged content (XML) differently than prose comes directly from Anthropic’s engineering practices.
• @ihtesham2005 – Their thread on Anthropic’s internal prompting docs was the catalyst for the “prefer structured over prose” rule.
• @Austen – Their post that “the closer you can get to structured/executable formats, the better” reinforced this as a hard rule.

Test-First Bug Fixing, Operationalization, and Multi-Agent Review

• @tangming2005 – Their post about the “single biggest improvement to my CLAUDE.md” – writing a reproduction test before fixing – is almost verbatim the test-first bug fixing rule.
• @doodlestein – Their “Agent Coding Life Hack” is the direct source of “operationalize every fix.” Their broader work on the “virtuous circle” shaped the Workflow Evolution section.
• @danpeguine – Their implementation of @systematicls’s method using Hunter, Skeptic, and Referee agents was the direct inspiration for the dialectic review pattern and the /bug-hunt skill.
• Kyle Mathews (@kylemathews) – His Hegelian dialectic skill with its hostile auditor phase (Phase 6 validation) inspired the --audit flag in /dialectic-review.
• Riley Ralmuto (@RileyRalmuto) – Their polyclaude plugin with 6 named perspectives (including Temporal and User Advocate) informed the recommended --lens values.
• Danielle Fong (@DanielleFong) – Her concept of an epistemic claims hook that catches unverified assertions inspired epistemic-guard.sh.

Plan-First and Scope Discipline

• @doodlestein – Their posts about the planning process (“everyone gives short shrift to this part for some reason, and it’s THE difference”) shaped the plan-first protocol.
• Garry Tan (@garrytan) – His /plan-exit-review skill directly inspired the review-plan skill.
• Arvid Kahl (@arvidkahl) – His advice to “shift-tab into planning mode, and mention ‘do deep research on best practices’” reinforced plan-first as a hard default.
• Aakash Gupta (@aakashgupta) – His observation about building hundreds of working prototypes instead of writing PRDs shaped the “keep planning brief, start executing” style.

Human-AI Leverage and Division of Labor

• Ethan Mollick (@emollick) – His advice to “collect your hard problems and good ideas now, they will get more valuable” captures the leverage doctrine’s human role perfectly.
• Francois Chollet (@fchollet) – His framing of agentic coding as machine learning influenced how the orchestrator-first principle thinks about the human’s role.

Code Quality and Anti-Over-Engineering

• Andrej Karpathy (@karpathy) – His observation that “agents bloat abstractions, have poor code aesthetics, are very prone to copy pasting” is exactly why the implementation behavior section emphasizes boring solutions.
• @andrewmccalip – Their point about the “specific disease in engineering” where we “treat time as though it’s free” reinforced naive-then-optimize.
• @garybasin – His complexity cleanup skill (“derive, don’t store; make wrong states impossible”) operationalizes the anti-over-engineering principle.

Overnight Autonomous Runs

• @witcheer – Their post about running autoresearch overnight (“9PM to 6AM, 35 experiments, zero intervention”) was the direct inspiration for the overnight runner.
• @archiexzzz – Their deep dive into autoresearch informed the batch mode vs resume mode distinction.
• Anthropic’s scheduled tasks (@trq212) – The official feature handles the simple case; the overnight runner handles usage limit retries, batch checkpointing, and multi-session resume.
• @elvissun – Their bash pre-check gate pattern (bash checks preconditions, only invokes the LLM when action is needed) achieving ~95% token reduction directly shaped guides/event-driven-agents.md.
• @affaan-m – Their everything-claude-code repo (27 agents, 64 skills) contributed the loop-operator stall detection pattern documented in the event-driven agents guide.

Evals-First, Agent Steering, and Skill Design

• @synopsi – Their post about evolving from plan-implement-review to evals-first is the source of the “evals before specs” principle.
• Yishan Wong (@yishan) – His insight that “saying ‘remember to do X’ is unreliable” but presenting a possibly-wrong claim triggers corrective behavior shaped “corrective framing over reminders.”
• @doodlestein – Their work on the “Agent Flywheel” (“skills are a LOT more than just markdown files”) is the foundational influence on treating skills as compressed expertise.

After-Action Reviews and Premortem

• Emmet Penney (@NukeBarbarian) – His Ignatius skill, built on the Ignatian Pedagogical Paradigm, shaped the after-action review process and cumulative learning pattern.
• Gary Klein – The premortem technique (imagine failure, work backwards) is from Klein’s naturalistic decision-making research, popularized by Kahneman in Thinking, Fast and Slow.

Community

• OpenClaw (via @MillieMarconnni) – The open-sourced Claude Code setup that won an Anthropic hackathon validated the idea that configurations are worth packaging and sharing.
• @gvp324377 – Their division of AI users into “people who use AI to tell them they are right” vs “people who use AI to tell them all the ways they could be wrong” is the philosophical foundation of the anti-sycophancy rule.

Libraries

• sentence-transformers by Nils Reimers and Iryna Gurevych – the semantic search backbone in the data pipeline example.
• all-MiniLM-L6-v2 – the default embedding model. 22M params, 384-dim, runs on CPU.
• Pipeline runner pattern draws from Luigi (Spotify) and Prefect, simplified to a single file.

Tools

• Claude Code by Anthropic – the AI coding assistant this workflow is built for.

Build Your Own Bookmark Archive

The data pipeline example in this repo was originally built to archive and search bookmarks. The attributions section above? Every single source was found by running semantic search over archived bookmarks – python search.py "agent orchestration pattern" --top-k 5.

If you want to do the same thing with your own bookmarks, see guides/bookmark-archive.md for the full walkthrough: HAR capture, extraction, media download, AI image descriptions, LLM categorization, semantic search. Total cost is roughly $1-3 in API credits for ~2,000 bookmarks.

Your bookmarks are a curated signal of what you found valuable. This pipeline turns that signal into a searchable knowledge base.

License

MIT – use however you want.