FAQ - Frequently Asked Questions

Common questions and answers about Claude Craft.

Installation

What are the minimum requirements?

Requirements depend on the install method:

NPX (recommended) — only 2 requirements:

Node.js 22+ (Node 24 recommended — Active LTS)
Claude Code v2.1.97+

Makefile / shell scripts — additional requirements:

yq v4+ (Mike Farah's version, not the Python yq) — for YAML processing
Bash — for installation scripts
Git — for version control
Docker (recommended) — for running project commands

yq is not needed when using npx. If you see "yq: command not found" during npx install, you are likely using the wrong installation path.

See Prerequisites for complete details.

How do I install Claude Craft?

Quickest method (NPX, zero-prompt auto-detection):

bash

npx @the-bearded-bear/claude-craft install ~/my-project --auto

NPX with explicit stack:

bash

npx @the-bearded-bear/claude-craft install ~/my-project --tech=symfony --lang=en

Team config sync (from shared URL):

bash

npx @the-bearded-bear/claude-craft install ~/my-project --from=https://your-org/claude-craft-config.yaml

Alternative (Makefile):

bash

git clone https://github.com/TheBeardedBearSAS/claude-craft.git
cd claude-craft
make install-symfony TARGET=~/my-project

How do I uninstall Claude Craft?

bash

# Minimal removal
rm -rf .claude/ CLAUDE.md .bmad/ ralph.yml

# With backup first (recommended)
cp -r .claude/ .claude.backup/
rm -rf .claude/ CLAUDE.md .bmad/ ralph.yml

This removes all Claude Craft files. Your project code is untouched.

How do I reduce token consumption?

Install RTK (Rust Token Killer) to reduce token usage by 60-90%:

bash

make install-rtk
# or
/common:setup-rtk

RTK intercepts terminal commands and compresses their output before it reaches the LLM context window.

Can I install multiple technologies?

Yes! Run multiple install commands or use the YAML configuration:

bash

make install-symfony TARGET=~/project
make install-react TARGET=~/project

Or with YAML:

yaml

modules:
  - path: "."
    tech: [symfony, react]

How do I update an existing installation?

bash

make install-symfony TARGET=~/project OPTIONS="--update"
# or
./Dev/scripts/install-symfony-rules.sh --update ~/project

How do I completely reinstall?

bash

make install-symfony TARGET=~/project OPTIONS="--force --backup"

Configuration

Where is the configuration file?

Project-level: ~/my-project/.claude/CLAUDE.md
Index: ~/my-project/.claude/INDEX.md
Context triggers: ~/my-project/.claude/context.yaml

How do I customize the project context?

Edit .claude/CLAUDE.md or run:

/common:setup-project-context

How do I change the documentation language?

Use the --lang or RULES_LANG option during installation:

bash

make install-symfony TARGET=~/project RULES_LANG=fr

Available: en, fr, es, de, pt

What's the difference between CLAUDE.md and INDEX.md?

CLAUDE.md: Minimal config loaded automatically (~200 tokens)
INDEX.md: Quick reference loaded on demand via @ (~1,300 tokens)
references/: Full documentation loaded explicitly

Commands

How do I list all available commands?

In Claude Code:

/help

Or see Commands Reference.

What's the difference between `/common:` and `/symfony:` commands?

/common: - Transversal commands for any technology
/symfony:, /react:, etc. - Technology-specific commands

How do I create a custom command?

Add a markdown file to .claude/commands/{namespace}/:

markdown

---
description: What this command does
argument-hint: <arg1> [arg2]
---

# My Custom Command

Instructions for Claude...

Why isn't my command appearing?

Check file extension is .md
Check YAML frontmatter is valid
Restart Claude Code session

What is the `/btw` command?

/btw (by the way) is a quick question command for low-effort queries without context switching. It uses minimal context and low thinking effort, making it ideal for:

Quick lookups
Syntax checks
Brief explanations
Simple fact checks

Example:

/btw What's the syntax for async/await in Python?

What is `/proactive`?

/proactive is an alias for /loop (added in v2.1.105+). It has the same behavior as /loop, running Claude iteratively until task completion.

How do I manage hooks interactively?

Use the /hooks command to:

View all active hooks
Enable/disable specific hooks
Test hook configurations
Debug hook execution

How do I reload plugins or skills?

Two distinct commands (v2.1.157+):

/reload-plugins — rechargement des plugins MCP et extensions. À utiliser après modification de la configuration MCP ou installation d'un nouveau plugin.
/reload-skills — rescan des fichiers de skills sans redémarrer la session. À utiliser après ajout ou modification d'un skill dans .claude/skills/.

Avant v2.1.157, seul /reload-plugins existait. Si /reload-skills n'est pas disponible, redémarrer la session Claude Code.

Why aren't `/sprint:` or `/gate:` commands available?

Ces commandes font partie de la couche Project qui nécessite une installation séparée :

bash

make install-project TARGET=.
# ou
npx @the-bearded-bear/claude-craft install . --include-project

Sans cette étape, les namespaces /sprint:, /gate:, et /project: n'existent pas. L'installation par défaut installe uniquement les namespaces /common:, /workflow:, /team:, /qa:, /uiux: et les namespaces technologiques.

De même, /bmad:init n'existe pas — utiliser /workflow:init qui est la commande correcte installée.

What happens when a stream stalls?

Claude Code v2.1.105+ includes a 5-minute timeout with automatic retry. If a stream stalls, the session automatically resumes without user intervention.

Agents

How do I invoke an agent?

Use the @ mention:

@api-designer Help me design a REST API
@symfony-reviewer Review this code

Can I use multiple agents together?

Yes:

@tdd-coach @react-reviewer Help me TDD this component

How do I create a custom agent?

Add a markdown file to .claude/agents/:

markdown

---
name: my-agent
description: Expert in X. Use when Y.
---

# My Agent

## Identity
...

## Capabilities
...

BMAD Framework

What is BMAD?

BMAD (Build, Measure, Analyze, Deliver) is Claude Craft's project management framework with:

9 specialized agents (pm, ba, architect, po, sm, dev, qa, ux, bmad-master)
Status-based story routing
5 quality gates
Batch processing

How do I start using BMAD?

bash

# Initialize workflow in your project (commande correcte)
/workflow:init

# Check sprint status (nécessite make install-project TARGET=.)
/sprint:status

Il n'existe pas de commande /bmad:init. La commande correcte est /workflow:init. Les commandes /sprint:* et /gate:* nécessitent l'installation de la couche Project (voir la question ci-dessus).

How do I use the Kanban Board?

bash

# Ouvrir dans le navigateur
npx @the-bearded-bear/claude-craft kanban --open

# Démarrer le serveur local (port 3141)
npx @the-bearded-bear/claude-craft kanban

Le Kanban ingère .bmad/sprint-status.yaml en lecture seule — pas de modification de données. Le tableau est vide si le fichier sprint-status.yaml n'existe pas (nécessite make install-project TARGET=. pour le cycle BMAD v6 complet).

Tableau vide malgré l'installation ? Vérifier le format du fichier — voir TROUBLESHOOTING.md.

What are the quality gates?

Gate	Threshold	Purpose
PRD Gate	≥80%	Vision → PRD
Tech Spec Gate	≥90%	PRD → Tech Spec
Backlog Gate	INVEST 6/6	Tech Spec → Backlog
Sprint Ready	100%	Backlog → Sprint
Story DoD	100%	Dev → Done

See BMAD Practical Guide.

Ralph Wiggum

What is Ralph Wiggum?

Ralph Wiggum is a continuous AI agent loop that runs Claude iteratively until:

All Definition of Done (DoD) validators pass
Maximum iterations reached
Circuit breaker triggers

How do I use Ralph?

bash

/common:ralph-run "Implement user authentication"
# or
npx @the-bearded-bear/claude-craft ralph "Fix the login bug"

What DoD validators are available?

Validator	Description
`command`	Run shell commands (tests, lint)
`output_contains`	Check output for patterns
`file_changed`	Verify files were modified
`hook`	Integrate with quality-gate.sh
`human`	Manual approval

Can I run sprints overnight?

Yes! Use the team-sprint command with Ralph mode:

bash

/team:sprint --ralph-mode "Sprint 3" --overnight --max-stories 5

This will:

Process up to 5 stories
Auto-recover from transient errors
Escalate blocking issues
Stop at 6am or when limits are reached

Note: /common:ralph-sprint was removed in v6.0. See Migration Guide.

Workflow

What workflow tracks are available?

Track	Setup Time	Best For
Quick Flow	< 5 min	Bug fixes, hotfixes
Standard	< 15 min	New features
Enterprise	< 30 min	Platforms, migrations

How do I start a workflow?

/workflow:init              # Auto-detect
/workflow:init --quick      # Bug fix mode
/workflow:init --enterprise # Full methodology

What are the workflow phases?

Analyze - Research and exploration (Enterprise only)
Plan - Generate PRD, personas, backlog
Design - Tech spec, architecture, ADRs
Implement - Sprint development with TDD/BDD

Fast Mode

What is Fast Mode?

Fast Mode (v2.1.36+) delivers up to 2.5x faster output for Opus 4.8 with the same capabilities. Toggle with /fast.

How much does Fast Mode cost?

Mode	Input	Output
Standard	$5/M	$25/M
Fast	$30/M	$150/M

When to use Fast Mode with Claude Craft?

Use for interactive work (code review, debugging). For batch operations (team-sprint, team-audit), standard mode is more cost-effective.

Coût tokens BMAD

Combien de tokens consomme un workflow BMAD ?

Disclaimer : Les estimations ci-dessous sont indicatives. La consommation réelle dépend de la taille du projet, du nombre d'agents invoqués, du modèle (Opus vs Sonnet vs Haiku), et des options RTK activées. Relevé basé sur des sessions réelles en juin 2026.

Track BMAD	Tokens estimés (sans RTK)	Tokens estimés (avec RTK)	Coût indicatif Sonnet 4-6
Quick Flow (hotfix, bug)	~5 000	~2 000	~$0.02
Standard (nouvelle feature)	~15 000–25 000	~6 000–10 000	~$0.05–$0.10
Enterprise (plateforme)	~40 000–60 000	~16 000–24 000	~$0.15–$0.25
`/team:audit --sequential`	~20 000–35 000	~8 000–14 000	~$0.08–$0.14
`/qa:recette` (story unique)	~8 000–15 000	~3 000–6 000	~$0.03–$0.06

RTK = /common:setup-rtk (55-65% de réduction). Voir docs/RTK-ANALYSIS.md.

Avec Opus 4.8 (recommandé pour les phases de planification et review), multiplier par ~5 le coût par token. Utiliser /model opusplan pour le tiering dynamique Opus (planning) / Sonnet (exécution).

Usage mensuel typique pour une équipe de 3 développeurs : 5-10 sprints Standard + 2 audits = ~200 000–400 000 tokens = $1–2/mois avec RTK + Sonnet comme modèle de base.

Grille de prix & routage modèle par tâche (juin 2026)

Modèle	ID canonique	Prix in/out (par M tokens)	Router vers (type de tâche)
Haiku 4.5	`claude-haiku-4-5-20251001`	$1 / $5	`/effort low` — lookups, classification, reviewers, sous-agents simples
Sonnet 5	`claude-sonnet-5`	$2 / $10 intro (→ $3 / $15 au 2026-08-31)	`/effort medium` — implémentation standard, tâches agentiques, exécution sprint, modèle sous-agent par défaut. Sorti 2026-06-30, comble l'écart avec Opus 4.8
Sonnet 4.6 (prédécesseur)	`claude-sonnet-4-6`	$3 / $15	Toujours valide ; remplacé par Sonnet 5 comme Sonnet courant
Opus 4.8	`claude-opus-4-8`	$5 / $25	`/effort high`/`xhigh` — architecture, ADR, migrations, raisonnement complexe

Leviers de coût (cumulables) : prompt caching −90 % sur l'input mis en cache (ENABLE_PROMPT_CACHING_1H, actif par défaut), Batch API −50 % in/out pour les traitements asynchrones de masse, RTK 55-90 % sur les outputs CLI, CLAUDE_CODE_SUBAGENT_MODEL=sonnet pour les sous-agents non typés.
Précédence modèle : model: du frontmatter d'agent > CLAUDE_CODE_SUBAGENT_MODEL > modèle de session. Les 11 reviewers model: haiku restent sur Haiku même si SUBAGENT_MODEL=sonnet.
⚠️ Fable 5 / Mythos 5 suspendus (export-control US, 2026-06-12) : ne pas les router ; agents créatifs → Opus 4.8 / Sonnet 4.6.

Token Optimization

How do I reduce token usage?

Use RTK (Rust Token Killer) for 55-65% savings:

bash

/common:setup-rtk

This configures:

RTK CLI proxy (60-90% savings on dev commands)
Sub-agent model optimization (CLAUDE_CODE_SUBAGENT_MODEL=sonnet)
PostToolUse output filter hook
PreCompact context preservation hook

What is Auto Mode?

Auto Mode (v2.1.94+, Team plans) is an AI permission classifier that replaces manual confirmations:

Automatically approves safe operations (reads, tests)
Blocks risky operations (bulk deletions, exfiltration)
Falls back to manual mode after 3 consecutive blocks

Where are hook templates?

Ready-to-use templates in .claude/templates/hooks/:

output-filter.json — PostToolUse for compressing large CLI outputs
pre-compact.json — PreCompact for preserving context before compaction
context-reinject.json — SessionStart for re-injecting context after compaction

What are the new hook events in recent Claude Code versions?

8 new events added (24 total): PostCompact, StopFailure, TaskCreated, CwdChanged, FileChanged, PermissionDenied, Elicitation, ElicitationResult. Plus conditional if field (v2.1.85) and PreCompact blocking (v2.1.105).

Troubleshooting

"yq: command not found"

Install yq v4:

bash

brew install yq      # macOS
sudo apt install yq  # Ubuntu

Make sure it's Mike Farah's version:

bash

yq --version
# Should show: yq (https://github.com/mikefarah/yq/)

"Permission denied" on scripts

bash

chmod +x Dev/scripts/*.sh
# or
make fix-permissions

Commands not recognized in Claude Code

Restart Claude Code session
Verify files are in .claude/commands/
Check YAML frontmatter syntax

Installation fails with "directory not found"

Create the directory first:

bash

mkdir -p ~/my-project
make install-symfony TARGET=~/my-project

Files overwritten unexpectedly

Use --preserve-config to keep your customizations:

bash

make install-symfony TARGET=~/project OPTIONS="--force --preserve-config"

See Troubleshooting Guide for more solutions.

Project Management

How do I create a user story?

/project:add-story EPIC-001 "As a user, I want..."

How do I track sprint progress?

/sprint:status
/project:board

How do I run a TDD sprint?

/sprint:dev next

Integration

Does Claude Craft work with other AI tools?

Yes! Use the web bundles:

bundles/chatgpt/ - For ChatGPT
bundles/claude/ - For Claude Projects
bundles/gemini/ - For Gemini Gems

Can I use MCP servers?

Yes, Claude Craft includes MCP templates:

bash

# Copy MCP templates
cp .claude/mcp/* ~/.claude/mcp/

Available: Context7, GitHub, PostgreSQL, Slack

Does it work in monorepos?

Yes! Use YAML configuration:

yaml

projects:
  - name: "my-monorepo"
    root: "~/Projects/my-monorepo"
    modules:
      - path: "frontend"
        tech: react
      - path: "backend"
        tech: symfony

Migration

How do I migrate from v3 to v4?

See Migration Guide.

What breaks in v4?

Main changes:

TCL (Tiered Context Loading) structure
BMAD v6 format changes
Some command renames

Can I use v3 and v4 side by side?

Not recommended. Migrate projects one at a time.

Best Practices

What's the recommended workflow for a new feature?

Start with /workflow:init
Use @api-designer for API design
Generate code with /symfony:generate-crud
Write tests with @tdd-coach
Review with @symfony-reviewer
Validate with /common:pre-commit-check

How often should I run audits?

Pre-commit: Always (/common:pre-commit-check)
Full audit: Weekly or before releases
Security audit: Before each release

Should I commit the .claude folder?

Yes! The .claude/ folder should be committed to version control so all team members use the same rules and commands.

Contributing

How do I add a new technology?

Use the command:

/common:add-technology "nextjs"

This generates all files for 5 languages.

How do I report a bug?

Open an issue on GitHub

Can I contribute translations?

Yes! Translations are in Dev/i18n/{lang}/. PRs welcome!

FAQ - Frequently Asked Questions ​

Installation ​

What are the minimum requirements? ​

How do I install Claude Craft? ​

How do I uninstall Claude Craft? ​

How do I reduce token consumption? ​

Can I install multiple technologies? ​

How do I update an existing installation? ​

How do I completely reinstall? ​

Configuration ​

Where is the configuration file? ​

How do I customize the project context? ​

How do I change the documentation language? ​

What's the difference between CLAUDE.md and INDEX.md? ​

Commands ​

How do I list all available commands? ​

What's the difference between /common: and /symfony: commands? ​

How do I create a custom command? ​

Why isn't my command appearing? ​

What is the /btw command? ​

What is /proactive? ​

How do I manage hooks interactively? ​

How do I reload plugins or skills? ​

Why aren't /sprint:* or /gate:* commands available? ​

What happens when a stream stalls? ​

Agents ​

How do I invoke an agent? ​

Can I use multiple agents together? ​

How do I create a custom agent? ​

BMAD Framework ​

What is BMAD? ​

How do I start using BMAD? ​

How do I use the Kanban Board? ​

What are the quality gates? ​

Ralph Wiggum ​

What is Ralph Wiggum? ​

How do I use Ralph? ​

What DoD validators are available? ​

Can I run sprints overnight? ​

Workflow ​

What workflow tracks are available? ​

How do I start a workflow? ​

What are the workflow phases? ​

Fast Mode ​

What is Fast Mode? ​

How much does Fast Mode cost? ​

When to use Fast Mode with Claude Craft? ​

Coût tokens BMAD ​

Combien de tokens consomme un workflow BMAD ? ​

Grille de prix & routage modèle par tâche (juin 2026) ​

Token Optimization ​

How do I reduce token usage? ​

What is Auto Mode? ​

Where are hook templates? ​

What are the new hook events in recent Claude Code versions? ​

Troubleshooting ​

"yq: command not found" ​

"Permission denied" on scripts ​

Commands not recognized in Claude Code ​

Installation fails with "directory not found" ​

Files overwritten unexpectedly ​

Project Management ​

How do I create a user story? ​

How do I track sprint progress? ​

How do I run a TDD sprint? ​

Integration ​

Does Claude Craft work with other AI tools? ​

Can I use MCP servers? ​

Does it work in monorepos? ​

Migration ​

How do I migrate from v3 to v4? ​

What breaks in v4? ​

Can I use v3 and v4 side by side? ​

Best Practices ​

What's the recommended workflow for a new feature? ​

How often should I run audits? ​

Should I commit the .claude folder? ​

Contributing ​

How do I add a new technology? ​

How do I report a bug? ​

FAQ - Frequently Asked Questions

Installation

What are the minimum requirements?

How do I install Claude Craft?

How do I uninstall Claude Craft?

How do I reduce token consumption?

Can I install multiple technologies?

How do I update an existing installation?

How do I completely reinstall?

Configuration

Where is the configuration file?

How do I customize the project context?

How do I change the documentation language?

What's the difference between CLAUDE.md and INDEX.md?

Commands

How do I list all available commands?

What's the difference between `/common:` and `/symfony:` commands?

How do I create a custom command?

Why isn't my command appearing?

What is the `/btw` command?

What is `/proactive`?

How do I manage hooks interactively?

How do I reload plugins or skills?

Why aren't `/sprint:` or `/gate:` commands available?

What happens when a stream stalls?

Agents

How do I invoke an agent?

Can I use multiple agents together?

How do I create a custom agent?

BMAD Framework

What is BMAD?

How do I start using BMAD?

How do I use the Kanban Board?

What are the quality gates?

Ralph Wiggum

What is Ralph Wiggum?

How do I use Ralph?

What DoD validators are available?

Can I run sprints overnight?

Workflow

What workflow tracks are available?

How do I start a workflow?

What are the workflow phases?

Fast Mode

What is Fast Mode?

How much does Fast Mode cost?

When to use Fast Mode with Claude Craft?

Coût tokens BMAD

Combien de tokens consomme un workflow BMAD ?

Grille de prix & routage modèle par tâche (juin 2026)

Token Optimization

How do I reduce token usage?

What is Auto Mode?

Where are hook templates?

What are the new hook events in recent Claude Code versions?

Troubleshooting

"yq: command not found"

"Permission denied" on scripts

Commands not recognized in Claude Code

Installation fails with "directory not found"

Files overwritten unexpectedly

Project Management

How do I create a user story?

How do I track sprint progress?

How do I run a TDD sprint?

Integration

Does Claude Craft work with other AI tools?

Can I use MCP servers?

Does it work in monorepos?

Migration

How do I migrate from v3 to v4?

What breaks in v4?

Can I use v3 and v4 side by side?

Best Practices

What's the recommended workflow for a new feature?

How often should I run audits?

Should I commit the .claude folder?

Contributing

How do I add a new technology?

How do I report a bug?