Claude Config - Hybrid Configuration for Claude Code + ClaudeKit

A comprehensive configuration repository that combines ClaudeKit, custom agents/commands, and Claude Code official features for an optimal AI-assisted development workflow.

Quick Start

Installation

Prerequisites: Node.js 22.14+ Check version: node --version | Install: https://nodejs.org ⚠️ Recommended: Claude Code Max plan

Install claudeflow globally via your preferred package manager:

npm

npm install -g @33strategies/claudeflow

yarn

yarn global add @33strategies/claudeflow

pnpm

pnpm add -g @33strategies/claudeflow

Setup

After installation, run the setup command:

claudeflow setup

Choose your installation mode:

1) Global - Install to ~/.claude/ (available in all projects)
2) Project - Install to ./.claude/ (this project only)

Quick decision:

Solo developer or want commands everywhere? → Global mode
Team project or want version control? → Project mode
Both? → You can do both! They work together via configuration hierarchy.

The setup will:

Check prerequisites (Node.js 22.14+, npm, Claude Code CLI)
Verify ClaudeKit installation (installed automatically as dependency)
Copy custom workflow commands to your chosen location
Set up configuration files
Run ClaudeKit setup

Optional but recommended: simple-task-master is already included for enhanced task tracking:

stm list --pretty --tag feature:<slug>

This enables /spec:decompose and /spec:execute to automatically track tasks.

What This Repository Provides

This repository implements a layered configuration approach:

ClaudeKit Foundation (installed via npm) - 30+ agents, 20+ commands, 25+ hooks
Custom Extensions (this repo) - Domain-specific agents and workflow commands
Official Claude Code Features - Built-in capabilities and plugin system

All three layers work together seamlessly in Claude Code.

Key Features

ClaudeKit (npm package)

30+ specialized agents (TypeScript, React, Testing, Database, DevOps, etc.)
20+ workflow commands (/git:commit, /spec:create, /research, etc.)
25+ intelligent hooks (file-guard, linting, testing, checkpoints)
Automated quality assurance and error prevention

Custom Extensions (this repo)

4 custom workflow commands:
- /ideate: Structured ideation with comprehensive documentation
- /ideate-to-spec: Transform ideation into validated specification
- /spec:feedback: Post-implementation feedback with interactive decisions
- /spec:doc-update: Parallel documentation review based on specs
4 enhanced spec command overrides (replace ClaudeKit versions):
- /spec:create: Detects output path and creates specs in feature directories
- /spec:decompose: Incremental mode preserves completed work, tags STM tasks
- /spec:execute: Session resume capability with implementation tracking
- /spec:migrate: Migrates existing specs to feature-directory structure
Complete end-to-end workflow from ideation to deployment
Example configurations for teams and individuals
Uses ClaudeKit's 30+ agents for specialized tasks
Task tracking: Integrates with simple-task-master (stm) - use stm list --pretty --tag feature:<slug> to track progress

Official Claude Code Features

5-tier configuration hierarchy
Project-level .claude/ directories
CLAUDE.md context files
MCP server integration
Plugin system

Verify Installation

Check that everything is set up correctly:

claudeflow doctor

This diagnostic command checks:

Node.js version (need 22.14+)
npm availability
Claude Code CLI installation
ClaudeKit installation
.claude/ directory structure
Command files presence

Troubleshooting

"Command not found: claudeflow"

Ensure npm global bin is in your PATH
Try: npm list -g @33strategies/claudeflow
Reinstall: npm install -g @33strategies/claudeflow

"ClaudeKit not found"

ClaudeKit should install automatically as a dependency
Manual install: npm install -g claudekit
Verify: claudekit --version

"Commands not loading in Claude Code"

Run: claudeflow doctor
Verify files exist in ~/.claude/commands/ (global) or ./.claude/commands/ (project)
Restart Claude Code

Installation Issues

Run the diagnostic command for detailed information:

claudeflow doctor

Migration from install.sh

If you previously used the bash script installation:

Uninstall old version:

# Global installation
rm -rf ~/.claude

# OR Project installation
rm -rf .claude

Install via npm:
```
npm install -g @33strategies/claudeflow
```

Run setup:

# Global (if you used install.sh user)
claudeflow setup --global

# OR Project (if you used install.sh project)
claudeflow setup --project

Verify installation:
```
claudeflow doctor
```

Note: Your existing STM tasks will be preserved. The migration only affects the installation method, not your feature work or task data.

Package Security

claudeflow is published with npm provenance attestations and SLSA Level 2 compliance. All releases are built and published via GitHub Actions with cryptographic verification.

For details on verifying package authenticity, supply chain security, and security best practices, see docs/SECURITY.md.

Update Management

claudeflow checks for updates automatically once per week (every 7 days). This check runs in the background and doesn't block command execution.

Manual update check:

npm outdated -g @33strategies/claudeflow

When updates are available, you'll see a notification:

╭───────────────────────────────────────────────────╮
│                                                   │
│   Update available: 1.3.0                        │
│   Current version:  1.2.0                        │
│   Run: npm install -g @33strategies/claudeflow   │
│                                                   │
╰───────────────────────────────────────────────────╯

To update:

# npm
npm update -g @33strategies/claudeflow

# yarn
yarn global upgrade @33strategies/claudeflow

# pnpm
pnpm update -g @33strategies/claudeflow

Document Organization

All documents related to a feature are organized in a single directory:

specs/
└── <feature-slug>/
    ├── 01-ideation.md          # Ideation and research
    ├── 02-specification.md     # Validated specification
    ├── 03-tasks.md             # Task breakdown
    ├── 04-implementation.md    # Implementation summary
    └── 05-feedback.md          # Post-implementation feedback log

Benefits:

All related documents in one place
Clear lifecycle progression (01 → 02 → 03 → 04)
Easy to find and navigate
Git-friendly tracking
STM tasks tagged with feature:<slug> for filtering

Example:

specs/add-user-auth-jwt/
├── 01-ideation.md          # Created by /ideate
├── 02-specification.md     # Created by /ideate-to-spec → /spec:create
├── 03-tasks.md             # Created by /spec:decompose
├── 04-implementation.md    # Created by /spec:execute
└── 05-feedback.md          # Created by /spec:feedback (after testing)

Repository Structure

claudeflow/ (@33strategies/claudeflow npm package)
├── package.json                      # npm package metadata
├── bin/
│   └── claudeflow.js                 # CLI entry point
├── lib/
│   ├── setup.js                      # Installation logic
│   └── doctor.js                     # Diagnostic command
├── scripts/
│   └── verify-files.js               # Pre-publish file verification
│
├── .claude/                          # Custom configuration (distributed in package)
│   ├── commands/                     # Custom slash commands
│   │   ├── ideate.md                 # Structured ideation workflow
│   │   ├── ideate-to-spec.md         # Transform ideation to spec
│   │   └── spec/
│   │       ├── create.md             # Enhanced spec creation
│   │       ├── decompose.md          # Incremental task breakdown
│   │       ├── execute.md            # Session-aware implementation
│   │       ├── feedback.md           # Post-implementation feedback
│   │       ├── doc-update.md         # Documentation review
│   │       └── migrate.md            # Spec structure migration
│   ├── settings.json.example         # Example configuration
│   └── README.md                     # Component documentation
│
├── .claude-plugin/                   # Plugin metadata
│   └── plugin.json                   # Package metadata
│
├── templates/                        # Configuration templates
│   ├── project-config/               # Project-level templates
│   │   ├── settings.json             # Team settings
│   │   ├── settings.local.json.example
│   │   ├── CLAUDE.md                 # Project instructions
│   │   ├── CLAUDE.local.md.example
│   │   └── .gitignore.example
│   └── user-config/                  # User-level templates
│       ├── settings.json             # Personal global settings
│       └── CLAUDE.md                 # Personal preferences
│
├── docs/                             # Documentation
│   ├── DESIGN_RATIONALE.md          # Design validation & best practices
│   └── ...
│
├── .github/
│   └── workflows/
│       └── release.yml               # CI/CD automation
├── .releaserc.json                   # Semantic-release config
├── .npmignore                        # Package exclusion rules
├── LICENSE                           # MIT License
├── CHANGELOG.md                      # Version history (auto-generated)
└── README.md                         # This file

Understanding the Hybrid Approach

Three-Layer Architecture

┌─────────────────────────────────────┐
│  Layer 3: Custom (This Repo)        │  ← Domain-specific agents & commands
├─────────────────────────────────────┤
│  Layer 2: ClaudeKit (npm)           │  ← 30+ agents, 20+ commands, 25+ hooks
├─────────────────────────────────────┤
│  Layer 1: Claude Code (Official)    │  ← Base CLI, plugin system, MCP
└─────────────────────────────────────┘

How They Work Together

Feature	Claude Code	ClaudeKit	This Repo
Agents	Built-in agents	typescript-expert, react-expert, database-expert, etc. (30+)	Uses ClaudeKit agents
Commands	`/init`, `/plugin`	/git:commit, /spec:create, /research, etc. (20+)	/ideate, /ideate-to-spec, /spec:doc-update + overrides for /spec:create, /spec:decompose, /spec:execute, /spec:migrate
Hooks	Hook system	file-guard, typecheck-changed, lint-changed, etc. (25+)	Uses ClaudeKit hooks via settings.json
Config	.claude/ hierarchy	Integrates with .claude/	Custom commands in .claude/

Configuration Hierarchy

Claude Code uses a 5-tier precedence system:

Enterprise policies (highest) - IT-managed, cannot be overridden
CLI arguments - Temporary session overrides
Local settings (.claude/settings.local.json) - Personal, gitignored
Project settings (.claude/settings.json) - Team, committed
User settings (~/.claude/settings.json) - Personal global defaults

Available Components

Custom Commands (This Repo)

/ideate

Structured ideation workflow that enforces complete investigation for any code-change task (bug fix or feature). Produces comprehensive ideation documentation including:

Intent & assumptions
Pre-reading log
Codebase mapping
Root cause analysis (for bugs)
Research findings
Clarification questions

Usage: /ideate Fix chat UI auto-scroll bug when messages exceed viewport height

/ideate-to-spec

Transform an ideation document into a validated, implementation-ready specification. This command:

Reads and synthesizes the ideation document
Interactively gathers decisions from the user
Creates a detailed specification using /spec:create
Detects and resolves open questions interactively
Validates it with /spec:validate
Presents a summary with next steps

Interactive Question Resolution: After creating the specification, the system automatically:

Detects unanswered questions in the "Open Questions" section
Presents each question with context and options
Records answers in strikethrough format (audit trail)
Re-validates and loops until all questions resolved
Shows progress: "Question 3 of 12"
Supports multi-select for questions requiring multiple choices
Detects external edits to prevent data loss
Backward compatible (skips if no questions exist)
Re-entrant (skips already-answered questions)
Save-as-you-go for recoverability

Usage: /ideate-to-spec specs/<slug>/01-ideation.md

Example with Questions:

/ideate-to-spec specs/my-feature/01-ideation.md
# → Creates specification
# → System detects 5 open questions
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Question 1 of 5
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Package Manager Support
# → User selects: npm, yarn, pnpm (all three)
# → Spec updated with strikethrough answer
# → Continues with questions 2-5
# → Final summary shows 5 questions resolved

Answer Format (Audit Trail):

Questions are marked as resolved using strikethrough format:

Before:

1. **ClaudeKit Version Compatibility**
   - Option A: Pin exact version
   - Option B: Use caret range

After:

1. ~~**ClaudeKit Version Compatibility**~~ (RESOLVED)
   **Answer:** Use caret range (^1.0.0)
   **Rationale:** Automatic updates, test compatibility in CI/CD

   Original context preserved:
   - Option A: Pin exact version
   - Option B: Use caret range

This format provides a complete audit trail showing both the original question and the final decision.

/spec:feedback

Process ONE specific piece of post-implementation feedback from testing or usage. This command:

Validates prerequisites (implementation must exist)
Prompts for detailed feedback description
Explores relevant code with targeted investigation
Optionally consults research-expert for solution approaches
Guides through interactive decisions (implement/defer/out-of-scope)
Updates spec changelog for "implement now" decisions
Creates STM tasks for deferred feedback
Logs all decisions in 05-feedback.md

Integrates with incremental /spec:decompose and resume /spec:execute for seamless iteration.

Usage: /spec:feedback specs/my-feature/02-specification.md

/spec:doc-update

Review all documentation to identify what needs to be updated based on a new specification file. Launches parallel documentation expert agents to review each doc file for:

Deprecated content
Content requiring updates
Missing content for new features

Usage: /spec:doc-update specs/text-generator-spec.md

Enhanced Spec Commands (Overrides)

These commands override ClaudeKit's versions with enhanced feature-directory organization and STM integration:

/spec:create

Enhanced version that detects output paths and organizes specs in feature directories. Creates specs in specs/<slug>/02-specification.md format.

Usage: /spec:create Add user authentication with JWT tokens

/spec:decompose

Enhanced version with incremental mode that detects changelog updates and creates only new tasks while preserving completed work. Extracts feature slugs and tags all STM tasks with feature:<slug> for filtering. Creates task breakdown in specs/<slug>/03-tasks.md with re-decompose metadata.

Usage: /spec:decompose specs/add-user-auth/02-specification.md

Incremental Mode: Automatically detects when spec changelog has been updated after feedback and creates only new tasks for changes.

/spec:execute

Enhanced version with session resume capability that continues from previous progress. Reads implementation summary to skip completed tasks, resume in-progress work, and append new session history. Creates/updates specs/<slug>/04-implementation.md with cross-session context.

Usage: /spec:execute specs/add-user-auth/02-specification.md

Resume Mode: Automatically detects previous sessions and skips completed work, maintaining full implementation history.

Session Continuity: When you run /spec:execute multiple times on the same spec, it reads 04-implementation.md to understand what work has already been completed. This allows you to:

Work on large features across multiple sessions without re-doing completed tasks
Return to implementation after testing/feedback cycles
Maintain a complete history of all sessions (Session 1, Session 2, etc.)
Seamlessly integrate feedback workflow: implement → test → /spec:feedback → /spec:decompose (incremental) → /spec:execute (resume)

Track Progress: stm list --pretty --tag feature:add-user-auth (replaces removed /spec:progress)

/spec:migrate

Migrates existing specs from flat structure to feature-directory structure. Moves specs, tasks, and ideation docs into organized specs/<slug>/ directories and tags STM tasks.

Usage: /spec:migrate

ClaudeKit Agents (30+)

Build Tools: webpack-expert, vite-expert

Languages: typescript-expert, typescript-build-expert, typescript-type-expert

Frontend: react-expert, react-performance-expert, nextjs-expert, css-styling-expert, accessibility-expert

Testing: testing-expert, jest-testing-expert, vitest-testing-expert, playwright-expert

Database: database-expert, postgres-expert, mongodb-expert

DevOps: docker-expert, github-actions-expert, devops-expert, git-expert

Specialized: ai-sdk-expert, nestjs-expert, kafka-expert, loopback-expert, nodejs-expert

Utilities: code-search, linting-expert, refactoring-expert, code-review-expert, research-expert

ClaudeKit Commands (20+)

Git Workflow: /git:status, /git:commit, /git:checkout, /git:push, /git:ignore-init

Specifications: /spec:validate

Note: This repo overrides /spec:create, /spec:decompose, /spec:execute with enhanced versions
Enhanced versions add feature-directory organization and STM task tagging
/spec:migrate is a custom addition for migrating existing specs
Use stm list --pretty --tag feature:<slug> to track progress (replaces removed /spec:progress)

Quality: /code-review, /validate-and-fix

Research: /research

Development: /create-command, /create-subagent

Checkpoints: /checkpoint:restore

Hooks: /hook:disable, /hook:enable, /hook:status

ClaudeKit Hooks (25+)

PreToolUse: file-guard (protects sensitive files)

PostToolUse: typecheck-changed, lint-changed, check-any-changed, test-changed, codebase-map-update, check-comment-replacement

Stop: create-checkpoint, check-todos, typecheck-project, lint-project, test-project, self-review

UserPromptSubmit: thinking-level, codebase-map

Standard Workflow

This repository implements a complete end-to-end workflow for feature development:

┌─────────────────────────────────────────────────────────────────┐
│                    IDEATION PHASE                               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                   /ideate <task-brief>
                   (Custom Command)
                              │
                    Creates ideation doc
                    with research & analysis
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   SPECIFICATION PHASE                           │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
          /ideate-to-spec <ideation-doc>
          (Custom, calls /spec:create & /spec:validate)
                              │
              Creates validated specification
                              │
                              ▼
            /spec:decompose <spec-file>
            (Custom Override - uses stm if installed)
                              │
              Breaks spec into tasks
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  IMPLEMENTATION PHASE                           │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
            /spec:execute <spec-file>
            (Custom Override - uses stm if installed)
                              │
              Implements tasks
                              │
                              ▼
       stm list --pretty --tag feature:<slug>
              (Track progress)
                              │
        View task status and completion
                              │
                   ┌──────────┴──────────┐
                   │                     │
              Not Finished          Finished
                   │                     │
                   └──────────┬──────────┘
                              │
                              ▼
                    Manual Testing
                              │
                   Discover issues or
                   improvement opportunities
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     FEEDBACK PHASE                              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
           /spec:feedback <spec-file>
           (Custom Command - one item at a time)
                              │
            Process feedback item:
            • Code exploration
            • Optional research
            • Interactive decisions
                              │
                   ┌──────────┴──────────┬────────────┐
                   │                     │            │
              Implement Now           Defer     Out of Scope
                   │                     │            │
        Update spec changelog    Create STM task     Log only
                   │                     │            │
                   ▼                     │            │
       /spec:decompose (incremental)    │            │
                   │                     │            │
       /spec:execute (resume)           │            │
                   │                     │            │
                   └──────────┬──────────┴────────────┘
                              │
                   More feedback items? (repeat)
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    COMPLETION PHASE                             │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
               /git:commit
               (ClaudeKit Command)
                              │
              Commits implementation
                              │
                              ▼
           /spec:doc-update <spec-file>
           (Custom Command)
                              │
        Reviews & updates documentation
                              │
                              ▼
               /git:commit
               (ClaudeKit Command)
                              │
           Commits doc updates
                              │
                              ▼
               /git:push
               (ClaudeKit Command)
                              │
            Pushes to remote
                              │
                              ▼
                          DONE! 🎉

Key Workflow Steps

Ideation → Comprehensive investigation and research
Specification → Validated, implementation-ready spec with interactive question resolution
Decomposition → Tasks broken down with dependencies (uses stm if installed, tags with feature:<slug>)
Implementation → Iterative execution with stm task tracking via stm list --pretty --tag feature:<slug>
Feedback → Process post-implementation feedback with structured decisions (implement/defer/out-of-scope)
Completion → Documentation updates and git workflow

Note: Phase 2 (Specification) now includes automatic open questions resolution to ensure specs are implementation-ready before decomposition begins.

Usage Examples

Complete Workflow Example

# Step 1: Start with ideation
/ideate Add user authentication with JWT tokens
# → Creates: specs/add-user-auth-jwt/01-ideation.md
#   Includes: investigation, research, clarifications

# Step 2: Transform to validated specification
/ideate-to-spec specs/add-user-auth-jwt/01-ideation.md
# → User makes decisions interactively (Step 2: ideation clarifications)
# → System creates specification via /spec:create
# → System detects and resolves open questions (Step 6: interactive resolution)
# → All questions answered interactively with progress tracking
# → Specification re-validated until complete
# → Summary includes both ideation decisions AND resolved spec questions
# → Creates: specs/add-user-auth-jwt/02-specification.md (validated & complete)

# Step 3: Break down into tasks
/spec:decompose specs/add-user-auth-jwt/02-specification.md
# → Creates: specs/add-user-auth-jwt/03-tasks.md
# → Creates STM tasks tagged with feature:add-user-auth-jwt

# Step 4: Start implementation
/spec:execute specs/add-user-auth-jwt/02-specification.md
# → Implements tasks incrementally, updating stm status

# Step 5: Check progress (can run anytime during implementation)
stm list --pretty --tag feature:add-user-auth-jwt
# → Shows: completion %, current phase, task status
#   Note: This replaces the removed /spec:progress command

# Step 6: Continue implementing (loop back to step 4 if needed)
/spec:execute specs/add-user-auth-jwt/02-specification.md

# Step 7: Final progress check (should show 100%)
stm list --pretty --tag feature:add-user-auth-jwt

# Step 8: Implementation summary created automatically
# → Creates: specs/add-user-auth-jwt/04-implementation.md

# Step 9: Manual testing (discover feedback items)
# Test the implemented feature manually
# Identify bugs, improvements, or missing functionality

# Step 10: Process feedback (repeat for each feedback item)
/spec:feedback specs/add-user-auth-jwt/02-specification.md
# → Interactive workflow:
#   1. Describe feedback item
#   2. Code exploration
#   3. Optional research
#   4. Make decision:
#      - Implement Now: Updates spec changelog
#      - Defer: Creates STM task for later
#      - Out of Scope: Logs decision only

# Step 11: If "Implement Now" was chosen, run incremental decompose
/spec:decompose specs/add-user-auth-jwt/02-specification.md
# → Incremental mode: preserves completed tasks, creates only new ones

# Step 12: Resume implementation for new tasks
/spec:execute specs/add-user-auth-jwt/02-specification.md
# → Resume mode: skips completed work, implements new feedback tasks

# Step 13: Repeat steps 9-12 until all feedback is addressed

# Step 14: Commit implementation
/git:commit
# → Creates conventional commit with changes

# Step 15: Update documentation
/spec:doc-update specs/add-user-auth-jwt/02-specification.md
# → Parallel agents review all docs
# → Identifies outdated content and missing docs

# Step 16: Commit documentation updates
/git:commit

# Step 17: Push to remote
/git:push

# All documents for this feature are now in: specs/add-user-auth-jwt/
# ├── 01-ideation.md
# ├── 02-specification.md
# ├── 03-tasks.md
# ├── 04-implementation.md
# └── 05-feedback.md

Quick Start (Skip Ideation)

If you already know what you need:

# Start directly with spec creation
/spec:create Add user authentication with JWT tokens

# Then follow steps 3-11 above

Migrating Existing Specs

If you have specs in the old flat structure:

# Migrate all existing specs to new structure
/spec:migrate

# This will:
# - Move specs/*.md to specs/<slug>/02-specification.md
# - Move specs/*-tasks.md to specs/<slug>/03-tasks.md
# - Move docs/ideation/*.md to specs/<slug>/01-ideation.md
# - Tag STM tasks with feature:<slug>
# - Generate migration report

Updating Documentation After Implementation

# After implementing a feature via a spec
/spec:doc-update specs/add-user-auth-jwt/02-specification.md

# This will:
# - Launch parallel documentation expert agents
# - Review all docs for outdated content
# - Identify missing documentation for new features
# - Provide prioritized recommendations

Configuration

Project Setup (Team)

cd your-project

# Initialize with ClaudeKit + custom config
./path/to/claude-config/install.sh project

# Customize settings
cp .claude/settings.json.example .claude/settings.json
# Edit .claude/settings.json for team

# Add to git
echo ".claude/settings.local.json" >> .gitignore
echo "CLAUDE.local.md" >> .gitignore
git add .claude/ CLAUDE.md .gitignore
git commit -m "Add Claude Code configuration"

Personal Setup (Global)

# Install to ~/.claude
./path/to/claude-config/install.sh user

# Customize personal settings
cp ~/.claude/settings.json ~/.claude/settings.local.json
# Edit ~/.claude/settings.local.json for personal preferences

Settings Management

Team Settings (.claude/settings.json - committed):

{
  "permissions": {
    "allow": ["Read", "Edit", "Bash(git:*)"],
    "deny": [".env", "**/*.key", "secrets/"]
  },
  "hooks": {
    "PreToolUse": [{
      "matcher": "Read|Edit|Write",
      "hooks": [{"type": "command", "command": "claudekit-hooks run file-guard"}]
    }]
  }
}

Personal Overrides (.claude/settings.local.json - gitignored):

{
  "environmentVariables": {
    "EDITOR": "code"
  }
}

Maintenance

Update ClaudeKit

# Check for updates
npm outdated -g | grep claudekit

# Update to latest
npm update -g claudekit

Update Custom Configuration

# Pull latest from this repo
cd path/to/claude-config
git pull origin main

# Re-run installation to update
./install.sh project

Validate Configuration

# Validate agents
claudekit lint-agents

# Validate commands
claudekit lint-commands

# List all components
claudekit list agents
claudekit list commands

# Check hook status
claudekit-hooks status

# Profile hook performance
claudekit-hooks profile

Best Practices

1. Security First

Always enable file-guard hook
Never commit secrets to .claude/settings.json
Use environment variable references: "API_KEY": "${API_KEY}"
Keep .env files gitignored

2. Team Collaboration

Commit .claude/settings.json and CLAUDE.md to git
Gitignore .claude/settings.local.json and CLAUDE.local.md
Document custom agents and commands in README
Use PR reviews for configuration changes

3. Performance

Profile hooks regularly: claudekit-hooks profile
Keep UserPromptSubmit hooks under 10k characters
Use *-changed hooks for fast feedback
Use *-project hooks sparingly (slow but comprehensive)

4. Agent Management

Start with 10-15 most relevant agents
Add more as needed
Remove unused agents to reduce context overhead
Document agent purposes in .claude/agents/README.md

5. Context Optimization

Keep CLAUDE.md focused and concise
Use file references instead of embedding code
Enable codebase-map hook for project structure
Break large tasks into smaller steps

Troubleshooting

ClaudeKit Not Found

# Reinstall globally
npm install -g claudekit

# Check installation
which claudekit
claudekit --version

Agents Not Appearing

# Verify agent files
ls -la .claude/agents/

# Validate agents
claudekit lint-agents

# Restart Claude Code session

Hooks Not Running

# Check hook status
claudekit-hooks status

# Enable hooks
claudekit-hooks enable file-guard

# Verify settings.json syntax
cat .claude/settings.json | jq .

# Restart Claude Code session

Settings Not Applied

Check configuration hierarchy (local > project > user)
Restart Claude Code session
Validate JSON syntax: jq . .claude/settings.json
Check for enterprise policies overriding settings

Resources

Official Documentation

This Repository

Installation Guide - When to use user vs project installation
Setup Guide - Detailed setup instructions
Design Rationale - Design validation and best practices
Feedback Workflow Guide - Complete guide to post-implementation feedback
GitHub Issues - Report problems

Community Resources

Contributing

Contributions welcome! Please:

Follow existing patterns and structure
Test changes thoroughly
Update documentation
Submit PRs with clear descriptions

License

MIT License - feel free to use and modify for your projects.

Acknowledgments

ClaudeKit by Carl Rannaberg - Comprehensive toolkit foundation
Anthropic - Claude Code CLI and official features
Community contributors and examples

Note: This repository implements a validated, research-backed approach for managing Claude Code configuration. See research.md for detailed analysis, sources, and best practices.

Why This Approach?

vs. Git Submodules (Grok's Original Suggestion)

✅ Simpler: npm install vs. submodule complexity
✅ Standard: Familiar to all Node.js developers
✅ Easy updates: npm update -g vs. git submodule update --remote
✅ No merge conflicts with upstream
❌ Submodules add unnecessary complexity

vs. Manual Configuration

✅ Automated setup via installation script
✅ Validated configurations from research
✅ Combines best of ClaudeKit + custom + official
✅ Easy to maintain and update

vs. Plugin-Only Approach

✅ More flexible than plugins alone
✅ Can customize ClaudeKit features
✅ Works with npm-distributed tools
✅ Better for teams with specific needs

This hybrid approach provides the best of all worlds: ClaudeKit's mature foundation, your custom extensions, and official Claude Code features, all working together seamlessly.

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
.claude-plugin		.claude-plugin
.claude		.claude
.github/workflows		.github/workflows
bin		bin
docs		docs
lib		lib
scripts		scripts
specs		specs
templates		templates
.gitignore		.gitignore
.npmignore		.npmignore
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

License

kennyjpowers/claude-flow

Folders and files

Latest commit

History

Repository files navigation

Claude Config - Hybrid Configuration for Claude Code + ClaudeKit

Quick Start

Installation

npm

yarn

pnpm

Setup

What This Repository Provides

Key Features

ClaudeKit (npm package)

Custom Extensions (this repo)

Official Claude Code Features

Verify Installation

Troubleshooting

"Command not found: claudeflow"

"ClaudeKit not found"

"Commands not loading in Claude Code"

Installation Issues

Migration from install.sh

Package Security

Update Management

Document Organization

Repository Structure

Understanding the Hybrid Approach

Three-Layer Architecture

How They Work Together

Configuration Hierarchy

Available Components

Custom Commands (This Repo)

/ideate

/ideate-to-spec

/spec:feedback

/spec:doc-update

Enhanced Spec Commands (Overrides)

/spec:create

/spec:decompose

/spec:execute

/spec:migrate

ClaudeKit Agents (30+)

ClaudeKit Commands (20+)

ClaudeKit Hooks (25+)

Standard Workflow

Key Workflow Steps

Usage Examples

Complete Workflow Example

Quick Start (Skip Ideation)

Migrating Existing Specs

Updating Documentation After Implementation

Configuration

Project Setup (Team)

Personal Setup (Global)

Settings Management

Maintenance

Update ClaudeKit

Update Custom Configuration

Validate Configuration

Best Practices

1. Security First

2. Team Collaboration

3. Performance

4. Agent Management

5. Context Optimization

Troubleshooting

ClaudeKit Not Found

Agents Not Appearing

Hooks Not Running

Settings Not Applied

Resources

Official Documentation

This Repository

Community Resources

Contributing

License

Acknowledgments

Packages