# Claude Craft — AI-First TDD Framework for Cursor IDE
# Generated from https://github.com/TheBeardedBearSAS/claude-craft
# Version: 8.0.1 | Last updated: 2026-04-17

---

## Core Framework

# Claude-Craft - Multi-Technology Framework

**Version:** 8.13.0 | **Languages:** en, fr, es, de, pt

A comprehensive AI-assisted development framework for Claude Code with 11 technology stacks, 31 specialized agents (+39 infra agents on-demand), 125 commands across 15 namespaces, and BMAD v6 project management.

---

## Supported Technologies (2026)

| Stack | Version | Architecture | Key Patterns |
|-------|---------|--------------|--------------|
| **.NET / C#** | 10 LTS / C# 14 | Clean Architecture | CQRS, MediatR (ou alternative), EF Core |
| **Symfony / PHP** | 8.1 / PHP 8.4+ | Clean Architecture | DDD, Hexagonal, API Platform, HTTP-less apps, JsonStreamer |
| **Flutter / Dart** | 3.44 / Dart 3.12 | Clean Architecture | BLoC v9, Riverpod 3, Material 3, Impeller |
| **React** | 19.2 + Compiler 1.0 | Feature-based | Hooks, Zustand, React Query, Server Components |
| **React Native** | 0.86 (New Architecture) | Feature-based | Navigation 7, Reanimated 4, TurboModules |
| **Angular** | 22 | Domain-driven | Signals, Signal Forms (stable), Zoneless par défaut, OnPush défaut, httpResource (TS 6) |
| **Vue.js** | 3.5+ (3.6 beta Vapor) | Composition API | Pinia 3, Vue Router 5, Vite 8, Vitest, Alien Signals |
| **Laravel** | 13.x / PHP 8.3+ (8.5 recommandé) | Clean Architecture | Actions, Pest 4, Sanctum, AI SDK, Passkey |
| **Python** | 3.14+ | Clean Architecture / Hexagonal | FastAPI, async/await, Pydantic, free-threading, JIT |
| **PHP** | 8.5 (Property Hooks 8.4+) | Clean Architecture | PSR-12, PHPStan Level 10, Pest 4 |
| **Paperclip** | 2026.609.0 | Two-layer (control plane + adapters) | Node.js 22+, TypeScript, Vitest, PostgreSQL, governance-first |

### Technology Quick Links

| Technology | Reference | Commands |
|------------|-----------|----------|
| C# / .NET | `@.claude/references/csharp/` | `/csharp:*` |
| Symfony / PHP | `@.claude/references/symfony/CLAUDE.md` | `/symfony:*` |
| Flutter / Dart | `@.claude/references/flutter/CLAUDE.md` | `/flutter:*` |
| React | `@.claude/references/react/` | `/react:*` |
| React Native | `@.claude/references/react-native/` | `/reactnative:*` |
| Angular | `@.claude/references/angular/` | `/angular:*` |
| Vue.js | `@.claude/references/vuejs/` | `/vuejs:*` |
| Laravel | `@.claude/references/laravel/` | `/laravel:*` |
| Python | `@.claude/references/python/` | `/python:*` |
| PHP | `@.claude/references/php/` | `/php:*` |
| Paperclip | `@.claude/references/paperclip/` | `/paperclip:*` |
| **Svelte** _(community)_ | `@.claude/references/svelte/CLAUDE.md` | — |

> **Note:** Svelte/SvelteKit is **community-maintained** and hors-scope officiel. Voir `.claude/references/svelte/CLAUDE.md` pour le disclaimer complet.

See `@.claude/INDEX.md` for condensed checklists and patterns.

---

## Available Commands (15 namespaces, 125 commands)

Core: `/common:*`, `/workflow:*`, `/team:*`, `/qa:*`, `/uiux:*` | Tech: `/symfony:*`, `/react:*`, `/flutter:*`, `/python:*`, `/angular:*`, `/vuejs:*`, `/laravel:*`, `/reactnative:*`, `/csharp:*`, `/php:*`, `/paperclip:*` | Infra (via `@devops-engineer`): Docker 29.5.3 (CVE-2026-33997), Coolify v4.1.2, K8s 1.36.1, OpenTofu 1.12.1, Ansible 2.21.0, FrankenPHP 1.12.4 (CVE-2026-45062 patched), PgBouncer 1.25.2 (CVE-2026-6664/6665/6666/6667 patched) | Project: `/sprint:*`, `/gate:*`, `/project:*`

Full reference: [Commands](../docs/COMMANDS.md) | [CLI Reference](../docs/CLI-REFERENCE.md)

---

## Available Agents (31 specialized + 39 infra on-demand)

**Common** (20): `@api-designer`, `@database-architect`, `@devops-engineer`, `@performance-auditor`, `@refactoring-specialist`, `@tdd-coach`, `@uiux-orchestrator`, `@ui-designer`, `@ux-ergonome`, `@accessibility-expert`, `@research-assistant`, `@ralph-conductor`, `@security-auditor`, `@data-analyst`, `@migration-specialist`, `@cost-optimizer`, `@chaos-engineer`, `@devex-engineer`, `@mlops-engineer`, `@observability-engineer` | **Tech Reviewers** (11): `@{symfony,flutter,react,python,angular,laravel,vuejs,reactnative,csharp,php,paperclip}-reviewer` | **Infrastructure** (39): Docker, Coolify, K8s, OpenTofu, Ansible, Hcloud, PgBouncer, FrankenPHP — see [Agents](../docs/AGENTS.md) | **Project** (2): `@product-owner`, `@tech-lead`

Full reference: [Agents](../docs/AGENTS.md)

---

## BMAD v6 Framework

| Track | Setup | Phases | Best For |
|-------|-------|--------|----------|
| **Quick Flow** | < 5 min | Implement only | Bug fixes, hotfixes |
| **Standard** | < 15 min | Plan -> Design -> Implement | New features |
| **Enterprise** | < 30 min | Analyze -> Plan -> Design -> Implement | Platforms |

**Quality Gates:** PRD >=80% | Tech Spec >=90% | INVEST 6/6 | Sprint Ready 100% | Story DoD 100% | Spec Alignment >=85%

**Status Routing:** `backlog -> ready-for-dev -> in-progress -> review -> done` (any -> `blocked`)

**TDD Phases:** Red -> Green -> Refactor

---

## Ralph Wiggum

Continuous AI loop that runs Claude until task completion: `/common:ralph-run "task"`

**DoD Validators:** `command` | `output_contains` | `file_changed` | `hook` | `human`

## QA Recette

Automated acceptance testing via Chrome. **Golden Rule:** A fixed bug should NEVER reappear.

```bash
/qa:recette --scope=story --id=US-001      # Test a story
/qa:recette --scope=sprint --id=Sprint-3    # Test a sprint
/qa:recette --resume=REC-20260130-143022    # Resume session
```

**Prerequisites:** Chrome extension v1.0.36+ | Claude Code with `--chrome` or `/chrome`

> BMAD roles (bmad-master, pm, ba, architect, po, sm, dev, qa, qa-recette, ux) are integrated into workflow and sprint commands, not standalone agent files.

---

## Docker Requirement

**Always use Docker for commands to abstract from local environment.**

```bash
docker compose exec app php bin/console ...
docker compose exec app ./vendor/bin/phpunit
```

---

## Skills

`/solid-principles`, `/testing`, `/security`, `/git-workflow`, `/documentation`, `/kiss-dry-yagni`, `/workflow-analysis`, `/parallel-worktrees`, `/atomic-tasks`, `/design-md-convention`, `/architect`, `/debug-methodical`, `/socratic-brainstorm`, `/ecosystem-tools` — loaded on demand from `.claude/skills/`

## AI-First Development (Karpathy)

See `@.claude/rules/23-karpathy-principles.md` — 3 principles: **state assumptions explicitly**, **minimal code (no speculation)**, **surface confusion**. Apply to all LLM-assisted code. Extends rule 05 (KISS/DRY/YAGNI).

## Design System Convention

Projects with UI should include a root `DESIGN.md` file (template: `.claude/templates/DESIGN.md.template`). Skill `design-md-convention` and agents `@ui-designer`/`@ux-ergonome` auto-load it for consistent UI generation.

---

## Documentation

| Document | Description |
|----------|-------------|
| [Quickstart](../docs/QUICKSTART.md) | 5-minute getting started |
| [Prerequisites](../docs/PREREQUISITES.md) | Required dependencies |
| [CLI Reference](../docs/CLI-REFERENCE.md) | Full CLI documentation |
| [Commands](../docs/COMMANDS.md) | All commands |
| [Agents](../docs/AGENTS.md) | All agents |
| [FAQ](../docs/FAQ.md) | Common questions |
| [Troubleshooting](../docs/TROUBLESHOOTING.md) | Problem solving |
| [Ecosystem](../docs/ECOSYSTEM.md) | Third-party token/context/review tools |

---

## Quick Start

```bash
# Install Claude Craft
npx @the-bearded-bear/claude-craft install . --tech=symfony --lang=en

# Or with Makefile
make install-symfony TARGET=. RULES_LANG=en

# Start workflow
/workflow:init

# Use an agent
@tdd-coach Guide me through TDD for this feature

# Run audit
/team:audit --sequential
```

---

## Claude Code Compatibility

**Minimum Version:** 2.1.97 (CVE-2025-59536 patched) | **Recommended:** 2.1.168 (Opus 4.8 + Dynamic Workflows) — See `@.claude/COMPATIBILITY.md` for full changelog (v2.1.20+).

---

## Best Practices

See `.claude/rules/12-context-management.md` for detailed guidance.

| Practice | Description |
|----------|-------------|
| **CLAUDE.md size** | Keep under 200 lines; use `.claude/rules/` for details |
| **Use `/clear`** | Between unrelated tasks to reset context |
| **Sub-agents** | Delegate investigations to keep main context clean |
| **Verification loops** | Always provide tests/expected outputs (2-3x quality improvement) |
| **Plan Mode** | Invest in planning for complex tasks (> 3 files) |
| **Parallel worktrees** | Use `git worktree` for concurrent sessions |
| **Hooks** | CLAUDE.md = suggestions. Hooks = requirements |
| **`/memory`** | Persistent session learnings across conversations (v2.1.59+) |
| **Pointers over copies** | Use `@path` references instead of copying code into CLAUDE.md |
| **Token optimization** | Use `/common:setup-rtk` for 55-65% token savings |
| **Sub-agent model** | Set `CLAUDE_CODE_SUBAGENT_MODEL=sonnet` for cost savings |

See `.claude/templates/hooks/` for ready-to-use hook templates.

## Quick Reference Index

# Claude-Craft Rules Index

## Stack Overview (2026)

.NET 10 LTS / C# 14 | Symfony 8.1 / PHP 8.4+ | Flutter 3.44 / Dart 3.12 | React 19.2 | Angular 22 | Vue 3.5+ | Laravel 13 / PHP 8.3+ | Python 3.14+

## Architecture Layers

```
WebAPI/Presentation → Infrastructure → Application → Domain (← INWARD ONLY)
```

**Domain**: NO external deps, Value Objects, private setters | **Application**: CQRS (MediatR/alternative), DTOs, validation | **Infrastructure**: DB, external services

## Coding Standards

| Element | Convention | Always |
|---------|-----------|--------|
| Public | PascalCase | Pass `CancellationToken`, enable nullable |
| Private | _camelCase | Async suffix: `ProcessAsync` |
| Params | camelCase | Methods < 20 lines, complexity < 10 |

## SOLID + KISS/DRY/YAGNI

**SRP**: 1 reason to change | **OCP**: Extend via interfaces | **LSP**: Subtypes substitutable | **ISP**: < 5 methods/interface | **DIP**: Depend on abstractions

**KISS**: < 10 complexity | **DRY**: Extract after 3 occurrences | **YAGNI**: Only what's required

## Testing Pyramid

Unit 70% (< 1s) | Integration 20% (< 5s) | E2E 10% (< 30s) — **TDD**: RED → GREEN → REFACTOR

**Stacks**: xUnit/FluentAssertions (C#), Pest 4 (PHP), Vitest 4 (JS/TS), pytest 8 (Python)

## Security Essentials

Server-side validation | Parameterized queries | Secrets in vault | CSP/HSTS headers | `[Authorize(Policy)]`

## Git Workflow

**Conventional Commits**: `<type>(<scope>): <description>` — Types: feat, fix, docs, refactor, perf, test  
**Branches**: `feature/`, `fix/`, `refactor/`

## Analysis Workflow (Mandatory)

1. Understand request → 2. Read affected files + deps → 3. Document impact/risks → 4. Validate if medium/high impact → 5. TDD first

## Technology References

| Stack | Path | Key Features |
|-------|------|--------------|
| **C# / .NET** | `@.claude/references/csharp/` | Extension Members, Span<T>, Clean Architecture |
| **Symfony / PHP** | `@.claude/references/symfony/CLAUDE.md` | JSON Streamer, ObjectMapper, DDD |
| **Flutter / Dart** | `@.claude/references/flutter/CLAUDE.md` | WASM, MCP, BLoC v9, Material 3 |

## Base Rules

`workflow-analysis.md` | `solid-principles.md` | `kiss-dry-yagni.md` | `git-workflow.md` | `security.md` | `testing.md` | `documentation.md`

## Tech-Specific Guides

**C#**: architecture, coding-standards, testing, security, tooling, quality-tools, aspire  
**Symfony**: architecture, coding-standards, quality-tools, json-streamer, object-mapper  
**Flutter**: coding-standards, wasm, mcp-integration, web-performance-2026

All in `@.claude/references/<tech>/`

## QA Recette Essentials

**Prerequisites**: Chrome extension v1.0.36+ | Claude Code `--chrome` or `/chrome`

```bash
/qa:recette --scope=story --id=US-001        # Test story
/qa:recette --resume=REC-xxx                 # Resume session
/qa:fix --session=REC-xxx --severity=critical # Fix critical bugs
/qa:regression --check                       # Check Golden Rule
```

**Golden Rule**: A fixed bug should NEVER reappear → auto-generates regression tests

**Output**: `.recette/` (plans, sessions, regression, metrics, reports)

## LSP Plugins

PHP: `php-lsp` | Python: `pyright-lsp` | TS/JS: `typescript-lsp` | Dart: `dart-analyzer` | C#: `csharp-lsp`

Install: `/plugins install <name>@claude-plugins-official`

> Full docs: `@.claude/COMPATIBILITY.md` | Technology details: `@.claude/references/<tech>/`

## Essential Rules (Condensed)

### SOLID Principles
SRP | OCP | LSP | ISP | DIP — See full rules in .claude/rules/04-solid-principles.md

### KISS, DRY, YAGNI
## KISS — Keep It Simple

| Metrique | Cible | Limite |
|----------|-------|--------|
| **Cognitive Complexity** (primaire 2026) | < 7 | < 10 |
| Lignes par methode | < 10 | < 20 |
| Complexite cyclomatique | < 5 | < 10 |
| Profondeur d'indentation | 2 | 3 max |
| Parametres par methode | 3 | 4 max |

> **Cognitive Complexity** (SonarQube, ReSharper) est la metrique dominante 2026 : elle mesure la difficulte humaine de comprehension. Elle prevaut sur la stricte limite de 20 lignes. Source : [Cognitive vs Cyclomatic](https://gilles-fabre.medium.com/what-is-the-difference-between-cyclomatic-complexity-and-cognitive-complexity-a87cef0e2851).

**Regles :** Early returns (guard clauses), pas de else imbrique, nommage explicite, composition > heritage.

## DRY — Don't Repeat Yourself

### Testing
TDD: RED → GREEN → REFACTOR | Coverage >= 80% | Mutation testing

### Security
## OWASP Top 10:2025 — Essentiels

| # | Menace | Defense |
|---|--------|---------|
| 1 | Broken Access Control (inclut **SSRF** consolide) | Verifier permissions a CHAQUE requete, deny by default |
| 2 | Cryptographic Failures | TLS 1.3, **Argon2id** (128 MiB RAM, t=3-5, p=1), secrets dans vault |
| 3 | Injection | Requetes parametrees, validation/sanitization |
| 4 | Insecure Design | Threat modeling, defense in depth, rate limiting |
| 5 | Security Misconfiguration | Hardening, erreurs generiques en prod |
| 6 | **Software Supply Chain Failures** (nouveau 2025) | SLSA 1.0, SBOM (SPDX 3 / CycloneDX), Sigstore keyless signing, reproducible builds |
| 7 | **Mishandling of Exceptional Conditions** (nouveau 2025) | Logger les erreurs, ne jamais exposer la stack trace en prod |

Sources : [OWASP Top 10:2025](https://owasp.org/Top10/2025/), [Supply Chain 2026](https://kawaldeepsingh.medium.com/practical-software-supply-chain-security-2026-sboms-signing-slsa-reproducible-builds-a-0416cfac32dc).

## Regles non-negociables

### Git Workflow
Conventional Commits | GitHub Flow | Feature branches < 3 days


---

## Full Documentation

For complete documentation, visit: https://claude-craft.dev

For full rules and references:
- SOLID: .claude/rules/04-solid-principles.md
- KISS/DRY/YAGNI: .claude/rules/05-kiss-dry-yagni.md
- Testing: .claude/rules/07-testing.md
- Security: .claude/rules/11-security.md
- Git Workflow: .claude/rules/09-git-workflow.md
- Context Management: .claude/rules/12-context-management.md

**Attribution:** The Bearded CTO / Claude Craft
**License:** MIT
**Repository:** https://github.com/TheBeardedBearSAS/claude-craft
