# 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](PREREQUISITES.md) 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](COMMANDS.md).

### 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?

1. Check file extension is `.md`
2. Check YAML frontmatter is valid
3. 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](TROUBLESHOOTING.md#kanban-board-empty).

### 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](BMAD-PRACTICAL-GUIDE.md).

---

## 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:
1. Process up to 5 stories
2. Auto-recover from transient errors
3. Escalate blocking issues
4. Stop at 6am or when limits are reached

> **Note:** `/common:ralph-sprint` was removed in v6.0. See [Migration Guide](MIGRATION-v6.md).

---

## 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?

1. **Analyze** - Research and exploration (Enterprise only)
2. **Plan** - Generate PRD, personas, backlog
3. **Design** - Tech spec, architecture, ADRs
4. **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**.

---

## 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

1. Restart Claude Code session
2. Verify files are in `.claude/commands/`
3. 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](TROUBLESHOOTING.md) 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](MIGRATION-v4.md).

### 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?

1. Start with `/workflow:init`
2. Use `@api-designer` for API design
3. Generate code with `/symfony:generate-crud`
4. Write tests with `@tdd-coach`
5. Review with `@symfony-reviewer`
6. 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](https://github.com/TheBeardedBearSAS/claude-craft/issues)

### Can I contribute translations?

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

---

## Still have questions?

- Check [Troubleshooting](TROUBLESHOOTING.md)
- Read [Full Documentation](COMMANDS-FULL-REFERENCE.md)
- [Open a GitHub issue](https://github.com/TheBeardedBearSAS/claude-craft/issues)