Claude Code Setup & Workflow Rules

One-stop setup repo for AI-assisted coding with Claude Code and Codex CLI.

Mental Model

• Rules are always-on constraints and routing hints. Keep them short and use them as an index.
• Skills are selected from their descriptions. Descriptions should say when to use the skill and when not to.
• Commands expand prompts. They can reference skill paths to bias selection, but they do not directly call skills.

Quick Start

# 1. Clone the repo
git clone https://github.com/YOUR_USERNAME/ai-toolkit.git ~/opt/code/ai-toolkit
cd ~/opt/code/ai-toolkit

# 2. Install dependencies (claude, codex, tmux, node)
./setup.sh

# 3. Link configs to ~/.claude/
./install.sh

# 4. Start coding
claude

What Gets Installed

Tools (via setup.sh)

Tool	Purpose
Node.js	Runtime for CLI tools
Claude Code	Anthropic's AI coding assistant
Codex CLI	OpenAI's AI coding tool
tmux	Terminal multiplexer
git	Version control

Configuration (via install.sh)

File	Purpose
~/.claude/CLAUDE.md	Global instructions (auto-generated from config/CLAUDE.md)
~/.claude/commands/	Custom slash commands
~/.claude/skills/	Repo-managed Claude skills
~/.codex/skills/<skill>	Repo-managed Codex skill links

Claude Code 2.1.x Features Used

Feature	Purpose
Task subagents	Explore, Plan, general-purpose for specialized work
Task tracking	TaskCreate/Update/List for progress visibility (optional)
Plan mode	EnterPlanMode/ExitPlanMode for structured planning
Native tools	Read, Grep, Glob instead of bash equivalents

Repository Structure

ai-toolkit/
├── setup.sh                # Install tools (run once)
├── install.sh              # Link configs to ~/.claude/
├── PROJECT_TEMPLATE.md     # Template for project documentation
├── build/                  # Generated by install.sh (path-resolved copies)
│   ├── config/             # Resolved config/CLAUDE.md
│   └── commands/           # Resolved command files
├── config/
│   └── CLAUDE.md           # Source template (uses {{TOOLKIT_DIR}} placeholders)
├── rules/
│   ├── universal.md        # Core principles (loaded first)
│   ├── orchestration.md    # Multi-agent workflow rules
│   ├── model-assignment.md # Provider-neutral model/effort tiers
│   ├── context-management.md   # Context depth thresholds and checkpoint protocol
│   ├── rule-maintenance.md     # How to strengthen, update, or extract rules
│   ├── investigation.md    # Debugging & root cause
│   ├── ci-evidence.md      # CI signals are summaries — open the artifact behind them
│   ├── rca-writeups.md     # Root-cause write-up structure
│   ├── implementation.md   # Code development
│   ├── api-boundary-defense.md # Validation at API boundaries
│   ├── testing.md          # Test strategy
│   ├── troubleshooting.md  # Emergency recovery
│   ├── resource-management.md  # Worktrees, Docker, heavy tasks
│   ├── preset-environments.md  # Preset staging/prod envs, credentials, VPN reachability
│   ├── code-review.md      # Review guidelines
│   ├── complexity-gate.md  # Complexity classification and fast-path
│   ├── review-gate.md      # Review gate output contract
│   ├── scoring.md          # Review scoring scale
│   ├── severity.md         # Finding severity levels
│   ├── stop-rules.md       # Universal stop conditions for iterative loops
│   ├── shortcut-api.md     # Shortcut REST API routing hint
│   └── input-detection.md  # Route ticket/issue inputs to Shortcut or GitHub
├── skills/                  # Directory skills with SKILL.md; references load lazily (see skills/README.md for anatomy)
│   ├── planning/            # Technical planning — plan-implementation, iterate-review, finalize, feedback-classify
│   ├── pm/                  # Product management — create-feature-brief, plan-milestones, review-feature-brief, decompose-epic
│   ├── plan-review/         # Plan-reviewer lenses — architecture, backend, frontend, implementation
│   ├── review/              # Code/PR reviewer orchestration + lenses — local-review, pr-review, classify-diff, adversarial
│   ├── feedback/            # PR feedback response — triage comments, fix approved items, post replies
│   ├── pr-watch/            # Watch-and-fix loop for an open PR — CI to green + incoming comments, with escalation
│   ├── debug/               # Diagnostic umbrella — investigate-change, review-rca, check-existing-fix, CI gather/classify/fix/verify
│   ├── reflection/          # Memory capture, review/prune, failure postmortems, rule promotion
│   ├── qa/                  # QA — triage-bug, validate-fix, assess-impact, analyze/expand/execute-use-cases, file-bug
│   ├── testing/             # Test-harness work — create/update suites, review tests + test plans
│   ├── preflight/           # Pre-work environment checks — worktree setup + app-runnable env prep
│   ├── cherry-pick/         # Cherry-pick workflow — investigate, gate, plan, apply, adapt, validate, batch-sequence
│   ├── agent-setup-maintainer/ # Maintains commands, skills, rules, and agent workflow docs
│   ├── action-gate/         # Shared proceed/stop decision helper
│   ├── implement-change/    # Focused implementation
│   ├── reporting/           # Structural rules + per-command summary/checkpoint templates
│   ├── metrics-emit/        # Telemetry skill — final command-complete event
│   ├── archive-project-file/ # Archive lifecycle command
│   ├── shortcut/            # Shortcut REST fetch/report helpers
│   ├── superset-local/      # Superset-specific local stack + Playwright helpers
│   ├── preset-rbac-setup/   # Seed canonical RBAC test users on a staging workspace via the Manager API
│   └── workstreams/         # Post-parallel-implementation fan-in and merge sequencing
├── hooks/
│   ├── prevent-project-commit.sh  # Block unsafe git flags and local workflow state commits
│   ├── pre-push-validate.sh       # Run repo-pinned ruff + targeted pytest on commits about to be pushed
│   ├── check-resources.sh         # Warn on constrained resources before tests
│   ├── check-plan-drift.sh        # Warn at turn end when PLAN.md outpaces PROJECT.md
│   ├── agent-setup-edit-reminder.sh # Remind to load agent-setup-maintainer on agent-setup edits
│   └── test-prevent-project-commit.sh # Smoke tests for the git safety hook (not a productive hook)
├── extensions/
│   └── pgm/                 # Program management (optional, install with --with-pgm)
│       ├── commands/         # /create-status-report, /create-velocity-report
│       ├── skills/           # pgm-comms.md
│       ├── rules/            # pgm.md (org-specific context)
│       └── install.sh        # Extension installer
├── install-hooks.sh          # Install hooks into settings.json (optional)
└── commands/
    ├── start.md            # Start or resume session
    ├── fix-bug.md          # End-to-end bug workflow
    ├── create-feature.md   # End-to-end feature workflow
    ├── create-tests.md     # Create the first meaningful tests
    ├── update-tests.md     # Improve an existing test suite
    ├── run-test-plan.md    # Execute a reviewed validation plan
    ├── test-pr.md          # Manual PR testing via Playwright browser
    ├── fix-ci.md           # Diagnose and safely fix CI failures
    ├── review-code.md      # Local review + autofix loop
    ├── review-pr.md        # Review GitHub PRs
    ├── address-feedback.md # Address PR feedback
    ├── reflect.md               # Memory management — add, list, review, prune, propose rules
    ├── create-pr.md             # Generate PR title + description from diff/commits
    ├── review-code-adversarial.md # Red-team review for security and edge cases
    ├── custom-skills-info.md    # Print toolkit reference card
    ├── checkpoint.md            # Save workflow state, log progress, or full save-and-clear
    ├── verify.md                # Run tests on changed files
    ├── review-plan.md           # One-off plan review with iteration
    ├── complete-project.md      # Project capstone summary
    ├── metrics.md               # Workflow metrics summary
    ├── show-cost.md             # Token usage and cost summary
    ├── optimize-cost.md         # Usage pattern analysis and recommendations
    ├── check-resources.md       # Local environment capacity check
    └── toolkit-doctor.md        # Structural health check

Slash Commands

Core Workflow

Command	Purpose
/start	Start session - load rules, check PROJECT.md
/fix-bug	End-to-end bug workflow with QA triage, RCA, implementation, and validation
/create-feature	End-to-end feature and planned refactor workflow with PM and developer planning

Quality & Testing

Command	Purpose
/create-tests	Standalone test-only workflow for creating the first meaningful tests in an area
/update-tests	End-to-end workflow for improving an existing suite, verifying it, and reviewing it
/run-test-plan	Standalone validation workflow that derives or reviews a test plan, executes it, and summarizes findings
/test-pr	Manual PR testing via Playwright browser against a running local app
/fix-ci	Diagnose CI failures, apply safe fixes, and stop before commit
/review-code	Adaptive team review: code quality + architecture + test check + optional second opinion
/review-code-adversarial	Adversarial red-team with optional second opinion
/review-plan	One-off plan review with fresh reviewers to 8/10
/verify	Run tests on changed files and report verification strength

Review & Branch Workflows

Command	Purpose
/review-pr	Adaptive team PR review: patterns, tests, architecture, RCA, auto-approve
/address-feedback	Investigate PR comments, fix valid items, post replies
/watch-pr	Babysit an open PR: loop CI to green and auto-handle incoming comments, escalating what needs judgment
/cherry-pick	Plan, order, and safely apply one or more cross-branch cherry-picks (skill — also auto-triggers on natural-language requests)
/create-pr	Generate PR title + description from diff, commits, and PROJECT.md

Project State

Command	Purpose
/checkpoint	Save workflow state to PROJECT.md (also for quick progress logs and full save-and-clear)
/complete-project	Generate a project capstone summary when work wraps up
/archive-project-file	Move completed phases to PROJECT_ARCHIVE.md (skill — also auto-triggers when archive intent is detected)

Cost & Metrics

Command	Purpose
/show-cost	Token usage and cost summary for the current session
/optimize-cost	Usage pattern analysis and cost-reduction recommendations
/metrics	Aggregate workflow metrics from .claude/metrics.jsonl

Environment

Command	Purpose
/check-resources	Local environment capacity check — running containers, stale ones, headroom verdict

Reflection & Memory

Command	Purpose
/reflect	Add a memory — capture workflow patterns, preferences, knowledge
/reflect list	Show all memories with type, description, and staleness
/reflect review	Assess memories for accuracy, staleness, and duplication
/reflect prune	Remove outdated or redundant memories
/reflect propose-rule	Extract a recurring pattern into a draft rule

Extension (PGM)

Command	Purpose
/create-status-report	Create a live program health report (install with --with-pgm)
/create-velocity-report	Create a historical velocity report (install with --with-pgm)

Toolkit Maintenance

Command	Purpose
/toolkit-doctor	Validate symlinks, build output, imports, path portability, and README accuracy
/custom-skills-info	Print reference card of all commands with gates

The agent-setup-maintainer skill activates automatically when you edit any agent-setup file (skills, commands, rules, CLAUDE.md, hooks) — see hooks/agent-setup-edit-reminder.sh.

Claude's built-in /review is still available for review-only output; /review-code is the repo-standard wrapper when you want fix + verify loops.

Review Workflows

Code Reviews

/review                     # Claude built-in review for uncommitted changes
/review --branch main       # Review changes against main
/review --commit abc123     # Review specific commit
/review-code                # Wrap built-in /review with local fix + verify loop

Use /review when you want review output only. Use /review-code when you want the repo-standard wrapper: review, fix, validate, and re-review until clean.

Feature Planning

/create-feature "bulk edit dashboards"
/create-feature sc-12345
/create-feature https://github.com/owner/repo/issues/123

/create-feature owns the full planning loop:

• PM planning is conditional and iterates to 8/10 when scope or milestones need it
• Developer planning iterates to 8/10 with shared reviewers from skills/
• The internal finalize-plan skill is the last cold-read before implementation continues automatically

Standalone Validation

/run-test-plan ./docs/test-plan.md
/run-test-plan sql-lab
/run-test-plan https://github.com/owner/repo/pull/123

/run-test-plan owns the standalone QA validation loop:

• derive or normalize a compact runnable matrix
• iterate it with review-testplan until it reaches 8/10 or blockers stop execution
• execute it through QA helpers and summarize findings locally

Plan Review

/review-plan                # Review PLAN.md or PROJECT.md-referenced plan with all applicable reviewers
/review-plan --pm           # Include PM brief review

/review-plan is standalone plan quality review — the same fresh-reviewer loop as /create-feature step 4, without the full workflow.

PR Feedback Analysis

/address-feedback 123       # Address review comments for PR 123
/address-feedback <pr-url>  # Address review comments by URL
/address-feedback 123 --draft  # Local only, don't post

/address-feedback is action-first: investigate comments, fix valid issues, post replies. Auto-pushes and auto-posts by default.

GitHub PR Reviews

/review-pr 123              # Review PR by number
/review-pr https://github.com/owner/repo/pull/123  # Review by URL
/review-pr 123 --draft      # Local only, don't post

Workflow Rules

File	When to Read
rules/universal.md	Always (core principles)
rules/orchestration.md	When coordinating helpers, reviewers, or parallel agents
rules/context-management.md	Always (checkpoint protocol, loaded via CLAUDE.md)
rules/investigation.md	/fix-bug, /create-feature, /fix-ci when RCA matters
rules/ci-evidence.md	/fix-ci, /watch-pr, any CI triage (a check is a summary — open the artifact)
rules/rca-writeups.md	/fix-bug, /fix-ci when writing up a root cause
rules/implementation.md	/fix-bug, /create-feature, /fix-ci
rules/api-boundary-defense.md	Code that validates or trusts data crossing an API boundary
rules/testing.md	/create-tests, /update-tests, /run-test-plan
rules/troubleshooting.md	Emergency recovery
rules/resource-management.md	Always (Docker, worktrees, test workers — loaded via CLAUDE.md)
rules/preset-environments.md	/test-pr, /run-test-plan, and anything reading a Preset repo or staging env
rules/code-review.md	/review-code, /review-pr, /address-feedback
rules/complexity-gate.md	/create-feature, /fix-bug (trivial vs standard routing)
rules/review-gate.md	/review-code, /create-feature, /fix-bug (review output contract)
rules/scoring.md	Review and plan-review scoring
rules/severity.md	Classifying finding severity in reviews and QA
rules/stop-rules.md	Any iterative loop (universal stop conditions)
rules/shortcut-api.md	Commands that query Shortcut REST API
rules/input-detection.md	Commands that accept Shortcut/GitHub ticket inputs
rules/model-assignment.md	Worker dispatch and provider-neutral model/effort tiering
rules/rule-maintenance.md	/reflect propose-rule, rule editing

Hooks (optional)

Hooks enforce toolkit rules at runtime via Claude Code's hook system. They are separate from install.sh because they modify settings.json.

Hook	Event	Behavior
prevent-project-commit.sh	PreToolUse (Bash)	Blocks unsafe git flags, force-pushes to main/master, and commits of local workflow state files
check-resources.sh	PreToolUse (Bash)	Warns when running tests with constrained resources
check-plan-drift.sh	Stop	Warns at turn end when PLAN.md outpaces PROJECT.md
agent-setup-edit-reminder.sh	PostToolUse (Edit/Write/MultiEdit/NotebookEdit)	Reminds to load agent-setup-maintainer when an agent-setup file is edited

./install-hooks.sh           # Install hooks
./install-hooks.sh --remove  # Remove hooks

Updating

After pulling updates, re-run install to refresh configs:

cd ~/opt/code/ai-toolkit
git pull
./install.sh

Customization

Edit files directly in this repo - changes take effect immediately since configs are symlinked:

• Add commands: Create .md files in commands/
• Modify rules: Edit files in rules/
• Add new rules: Add .md files to rules/, re-run ./install.sh
• Re-link after edits: Re-run ./install.sh to rebuild path-resolved copies

Environment Variables

Some MCP servers require tokens. Set these in your shell profile:

export GITHUB_TOKEN="your-github-token"
export OPENAI_API_KEY="your-openai-key"  # For Codex CLI

Backup

The install.sh script automatically backs up existing configs to:

~/.claude/backup-YYYYMMDD-HHMMSS/

How It Works

User: /create-feature

Claude Code:
1. Rules auto-loaded via CLAUDE.md @-includes
2. Reads commands/create-feature.md for workflow steps
3. Builds PM and developer plans in PROJECT.md
4. Uses shared reviewers in skills/ to iterate planning to 8/10
5. Runs the internal finalize-plan skill, then continues into implementation unless a decision matters

Claude Code = workflow orchestrator, planner, and implementer Skills = focused helpers for QA, development, review, branch work, and reporting

Extensions

Extensions add domain-specific commands, skills, and rules. They are not installed by default.

Extension	Purpose	Install
extensions/pgm/	Program management reports (status, velocity)	./install.sh --with-pgm