Skip to content

README.md

Latest commit

 

History

History
175 lines (131 loc) · 6.95 KB

README.md

File metadata and controls

175 lines (131 loc) · 6.95 KB

Claude Code Workflow Kit

A structured Claude Code workspace that enforces an Opus-plans, Sonnet-executes workflow — with context protection, code graph navigation, and browser automation built in.

How It Works

Role Model Responsibility
Worker Sonnet 4.6 Executes tasks — writes code, edits files, runs tools
Advisor Opus 4.7 Architects plans, reviews when worker is blocked

The workflow:

  1. You give a task
  2. Sonnet calls Opus for a detailed plan
  3. Sonnet presents the plan to you for approval
  4. You approve → Sonnet executes step by step
  5. Sonnet blocked → Opus re-plans → you approve again
  6. You reject the re-plan → Opus finds a different strategy

Prerequisites

  • Node.js 18+ — nodejs.org
  • Python 3.10+ — python.org
  • Claude Code — npm install -g @anthropic-ai/claude-code

Setup

Run this in any project directory:

npx claude-workflow-kit

That's it. The command:

  • Copies .claude/, CLAUDE.md, .mcp.json, and setup scripts into your project
  • Merges .gitignore entries
  • Installs MCP servers: context-mode, code-review-graph, playwright-cli

Then open the project in Claude Code:

claude .

The advisor is pre-configured to Opus in .claude/settings.json — no manual setup needed.

Update global install:

npm install -g claude-workflow-kit@latest

Update an existing project (overwrites .claude/, CLAUDE.md, .mcp.json with latest):

claude-workflow-kit --force

If MCP installs fail: npx claude-workflow-kit --skip-mcp copies files only. Then install manually:

npm install -g context-mode
pip install code-review-graph && code-review-graph install --platform claude-code

Verify It Works

After running npx claude-workflow-kit and opening the project in Claude Code:

/context-mode:ctx-doctor    # all checks should show [x]
/context-mode:ctx-stats     # shows context savings for the session

Then build the code graph (required for code review tools):

code-review-graph build

What You Get

MCP Servers

Server What it does
context-mode Sandboxes tool output so large results never flood your context window — up to 98% reduction
code-review-graph Builds a persistent map of your codebase so Claude reads only what matters — 6.8× fewer tokens on reviews
context7 Fetches up-to-date library docs on demand
repomix Packs codebases into AI-optimized format for analysis
playwright-cli Browser automation and UI testing

Slash Commands (Skills)

Command What it does
/build-graph Build or rebuild the code-review-graph knowledge graph for this project
/caveman Ultra-compressed communication mode — ~75% fewer tokens
/review-mood Set reviewer persona (strict / lenient / paranoid) for all reviews
/review-changes Structured code review with change detection and impact analysis
/debug-issue Systematic debugging using graph-powered code navigation
/explore-codebase Navigate and understand codebase structure via the knowledge graph
/refactor-safely Plan and execute safe refactoring using dependency analysis
/debrief Communication retrospective — honest analysis of where session went wrong
/save-debrief Extract debrief findings and save as feedback memory
/git-profile Set or show a local git identity for the current repo
/playwright-cli Automate browser interactions and generate Playwright tests

Rules Summary (from CLAUDE.md)

  • Plan before acting — Opus plans, you approve, then Sonnet executes
  • Execute strictly — no scope creep, no improvisation
  • Escalate when blocked — Sonnet stops and consults Opus after 2 failed attempts
  • Surface plan changes — revised plans are always shown to you for approval
  • No silent decisions — ambiguity gets a question, not an assumption
  • Flag your source — Sonnet distinguishes verified facts from training knowledge
  • Graph-first agents — all parallel agents (review, debug, explore, refactor, security) query the code graph before reading any file. Run /build-graph if the graph is missing.

What's in This Repo

.
├── CLAUDE.md                  # Workflow rules auto-loaded by Claude Code
├── README.md                  # This file
├── CONTRIBUTING.md            # How to contribute
├── package.json               # npm package (enables npx claude-workflow-kit)
├── bin/
│   └── init.js                # npx entry point — copies files + installs MCP servers
├── setup.sh                   # MCP install script (Mac/Linux)
├── setup.ps1                  # MCP install script (Windows)
├── .mcp.json                  # MCP server config (context-mode, context7, repomix, code-review-graph)
├── .gitignore
├── .gitignore-template        # Entries merged into user projects by npx command
├── docs/
│   ├── SETUP.md               # Install guide for each tool
│   ├── TOOLKIT.md             # What each tool does and why
│   ├── DECISIONS.md           # Architecture decision log
│   ├── LIMITS.md              # Known limits and failure modes
│   └── WATCHLIST.md           # Tools under evaluation
└── .claude/
    ├── settings.json          # Project-scoped Claude Code settings
    ├── mcp-wrappers/          # Cross-platform npx wrappers for MCP servers
    └── skills/                # Slash commands (caveman, debrief, git-profile, playwright-cli…)

Why This Workflow — The 4D Framework

This environment is built around the 4D Framework for AI Fluency (Dakan & Feller). Each rule in CLAUDE.md maps to one of the four competencies:

D What it means Where it lives in this workflow
Delegation Deciding what humans vs AI should do Opus architects, Sonnet executes, you approve — roles are explicit and never blurred
Description Communicating clearly with AI Rule 5: no silent decisions, ambiguity gets a question not an assumption
Discernment Critically evaluating AI output Rules 1 & 4: every plan is shown to you before execution; plan changes need re-approval
Diligence Using AI responsibly and transparently Rule 6: Sonnet flags whether it's drawing from verified source or training knowledge

Note: Description and Diligence are primarily human competencies. The rules above support them — but the user is accountable for prompting clearly and for the final output.

Contributing

This is a template. Fork it, adapt the CLAUDE.md rules to your team's workflow, and commit your changes. Keep .claude/settings.local.json out of git (it's already in .gitignore) — that's where personal preferences live.