Menu
Re-run stack detection and skill generation. Use when stack evolved or on first run.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Craft something. Claude orchestrates, agents execute.
Start a Clean Claude agent with optional reactive links. Examples: /agent frontend-engineer, /agent frontend-engineer --link qa-engineer, /agent architect --link frontend-engineer,qa-engineer
Auto-repair with smart routing: test failures โ Dev, type errors โ Architect, spec gaps โ PO. Routes each problem to the right expert.
Set up the Clean Claude Reactive System in the current project. Configures hooks, shared state, and scripts for the multi-agent feedback loop
Bootstrap a new frontend project with craft principles: React + Vite + TypeScript + Vitest + clean architecture
Add specialized craft skills to agents. Default craft principles always active. Everything MUST respect the craft philosophy.
| name | learn |
| description | Re-run stack detection and skill generation. Use when stack evolved or on first run. |
| context | conversation |
| allowed-tools | Read, Bash, Glob, Grep, Write, Task, AskUserQuestion |
CLEAN CLAUDE CODE OF CONDUCT APPLIES โ See CLAUDE.md
- Mandatory stack: TypeScript + React + TanStack Query
- All generated skills follow Software Craft principles
- REFUSE to learn from code smells
Claude orchestrates. Architect generates skills. No separate learning agent.
/learn # Learn everything (stack + architecture)
/learn stack # Stack only (libraries)
/learn architecture # Architecture only (project patterns)
/learn <url|path> # Analyze external source (GitHub URL or folder)
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ ๐ง CLAUDE ORCHESTRATES โ NO LEARNING AGENT โ
โ โ
โ Claude does the detection (Read, Glob, Grep). โ
โ Claude spawns Architect for skills generation. โ
โ Claude spawns Architect for architecture capture. โ
โ โ
โ WHY: Detection is fast (< 5 sec, no agent needed). โ
โ Skills generation needs Architect's expertise. โ
โ Architecture capture needs Architect's judgement. โ
โ โ
โ STACK: TypeScript + React + TanStack Query (mandatory) โ
โ + additional libraries detected from package.json โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ ๐ฏ TWO TYPES OF LEARNING โ
โ โ
โ 1. STACK LEARNING (libraries) โ
โ โ Claude detects installed libraries (package.json) โ
โ โ Claude spawns Architect for CRAFT-linked skills โ
โ โ Output: specs/stack/stack-skills.md (COMMITTED) โ
โ โ
โ 2. ARCHITECTURE LEARNING (project patterns) โ
โ โ Claude analyzes existing code structure (Glob/Grep) โ
โ โ Claude validates CRAFT compliance โ
โ โ Claude spawns Architect for architecture guide โ
โ โ Output: ARCHITECTURE.md with frontmatter flag (COMMITTED) โ
โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โ ๐ซ NEVER LEARN FROM CODE SMELLS โ
โ โ
โ Claude VALIDATES code before spawning Architect: โ
โ โข Checks for `any` types โ REJECT โ
โ โข Checks for `throw` without Result โ REJECT โ
โ โข Checks for spaghetti architecture โ REJECT โ
โ โข Checks for missing tests โ WARN โ
โ โ
โ If code is NOT CRAFT-compliant โ Report issues, DON'T learn patterns โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Default behavior: stack + architecture (if code exists)
/learn
โ
โโ 1. STACK DETECTION (Claude โ Read/Glob)
โ โ Read package.json (root + workspaces)
โ โ Extract library list beyond mandatory stack
โ โ Spawn Architect for library skills
โ โ Output: specs/stack/stack-skills.md
โ
โโ 2. ARCHITECTURE DETECTION (Claude โ Glob/Grep)
โ Analyze code structure
โ VALIDATE CRAFT compliance
โ
โโ CRAFT-compliant โ Spawn Architect for architecture guide
โ โ Output: ARCHITECTURE.md
โ
โโ NOT CRAFT-compliant โ Report issues
โ List violations
โ Suggest /craft "Refactor" to fix
โ DO NOT learn anti-patterns
1. Read package.json (root)
โ IF monorepo: also read apps/*/package.json, packages/*/package.json
2. Extract ALL dependencies + devDependencies
โ Mandatory (skip in skills โ hardcoded in templates/):
react, react-dom, @tanstack/react-query, typescript
โ Additional libs to learn (project-specific):
react-router-dom, zustand, zod, tailwindcss, @tanstack/react-table,
msw, playwright, i18next, date-fns, etc.
3. Write to .clean-claude/context.json:
{
"project": {
"type": "frontend | monorepo",
"language": "typescript",
"stackGuard": "pass",
"additionalLibs": ["react-router-dom", "zustand", ...]
}
}
4. IF additional libs found โ Spawn Architect for skills:
Task(
subagent_type: "architect",
prompt: """
๐ STACK SKILLS GENERATION
## YOUR TASK
Generate CRAFT-linked skills for the project's additional libraries.
## MANDATORY STACK (ALREADY HANDLED โ DO NOT REGENERATE)
React, TypeScript, TanStack Query skills are HARDCODED in
.claude/templates/mandatory-stack-skills.md
โ Read it, COPY as-is into the FIRST section of stack-skills.md
## ADDITIONAL LIBRARIES TO DOCUMENT
[LIST from context.json additionalLibs]
## FOR EACH ADDITIONAL LIBRARY
Generate CRAFT-linked skills following the format in your agent file:
- CRAFT Principles Table
- Mandatory Patterns
- Best Practices (Official + Community)
- Anti-Patterns to AVOID
- Code Examples (โ
vs โ)
## OUTPUT
Write specs/stack/stack-skills.md:
1. FIRST section = mandatory-stack-skills.md (copied as-is)
2. THEN one section per additional library
(CRAFT rules and tool restrictions are enforced by hooks)
"""
)
1. Check if src/ exists (Glob)
โ No src/ โ Skip architecture learning
2. VALIDATE CRAFT compliance (Claude โ Grep):
CHECK 1: TypeScript Strictness
Grep(":\s*any\b|as\s+any\b", glob="*.ts,*.tsx")
โ 0 matches = โ
| matches = โ "X files use any"
CHECK 2: Error Handling
Grep("throw\s+new\b", glob="*.ts,*.tsx")
+ Grep("Result<|Either<", glob="*.ts,*.tsx")
โ Has Result/Either = โ
| Only throw = โ
CHECK 3: Architecture Layering
Glob("src/domain/**") or Glob("src/core/**")
โ Clear layers = โ
| No separation = โ ๏ธ
CHECK 4: Test Presence
Glob("**/*.test.ts") count vs Glob("src/**/*.ts") count
โ > 50% = โ
| < 50% = โ ๏ธ | 0 = โ
3. IF COMPLIANT (โ
or โ ๏ธ only):
โ Spawn Architect for architecture capture
โ Output: ARCHITECTURE.md
4. IF NOT COMPLIANT (any โ):
โ Show violations to user
โ Suggest /craft "Refactor" to fix
โ DO NOT spawn Architect for architecture guide
Task(
subagent_type: "architect",
prompt: """
๐ ARCHITECTURE CAPTURE
## YOUR TASK
Analyze the implemented code and document the architecture patterns.
## WHAT TO ANALYZE (use Read/Glob/Grep โ NEVER Bash)
- Folder structure conventions
- Naming patterns (entities, hooks, components, services)
- Layer boundaries (domain โ application โ infrastructure โ UI)
- Error handling patterns (Result<T,E> usage)
- Test organization (colocated, integration, e2e)
- Key architectural decisions
## OUTPUT
Write {SCOPE}/ARCHITECTURE.md with frontmatter:
---
clean-claude: architecture-reference
version: 1
created: [today]
updated: [today]
approved-by: user
---
Sections:
- Architecture pattern (hexagonal variant chosen)
- Folder structure convention
- Naming conventions table
- Error handling patterns (Result<T,E> examples from actual code)
- Testing patterns
- Layer dependencies diagram
- Key decisions (ADR style)
This becomes the REFERENCE for ALL future features.
(CRAFT rules and tool restrictions are enforced by hooks)
"""
)
Focus on installed libraries, skip architecture analysis.
/learn stack
โ
โโ Claude: Read package.json โ extract libs โ spawn Architect for skills
โ Output: specs/stack/stack-skills.md
Claude executes Step 1 only (see above). No architecture analysis.
Focus on extracting CRAFT-compliant patterns from existing code.
/learn architecture
โ
โโ Claude: Glob/Grep for CRAFT validation โ spawn Architect if compliant
โ Output: ARCHITECTURE.md
Claude executes Step 2 only (see above). No stack detection.
Analyze external code (GitHub repo or folder) for CRAFT patterns.
/learn https://github.com/org/repo
โ
โโ EXTERNAL ANALYSIS
โ
โโ Clone repo to temp folder (Bash: git clone --depth 1)
โ
โโ Claude validates CRAFT compliance (Grep)
โ โ
โ โโ CRAFT-compliant โ Extract patterns
โ โ โ Generate analysis report
โ โ โ List patterns worth adopting
โ โ
โ โโ NOT CRAFT-compliant โ Report issues
โ โ "This repo has X violations"
โ โ "Not recommended as reference"
โ
โโ Output: .clean-claude/external-analysis.md
IF args STARTS WITH "http" OR "https" OR "github.com":
โ External GitHub repo
โ Bash: git clone --depth 1 <url> /tmp/clean-claude-analysis
โ Analyze with Glob/Grep in temp folder
โ Cleanup: Bash: rm -rf /tmp/clean-claude-analysis
IF args IS a path (starts with "/" or "./" or relative folder name):
โ Local folder analysis
โ Analyze in place with Glob/Grep
โ DO NOT modify the external folder
1. Clone/access the source
2. Claude validates CRAFT compliance (same checks as /learn architecture):
โ Grep for `any`, `throw`, check layers, check tests
3. Write .clean-claude/external-analysis.md:
IF CRAFT-COMPLIANT:
---
# External Analysis: <repo name>
## Summary: โ
CRAFT-compliant
## Patterns Worth Adopting
## File Organization
## Recommended for: [use cases]
---
IF NOT CRAFT-COMPLIANT:
---
# External Analysis: <repo name>
## Summary: โ ๏ธ NOT CRAFT-compliant
## Violations Found (X `any`, Y `throw`, Z missing tests)
## What Can Be Learned (with caution)
## Recommendation: Do NOT use as architecture reference.
---
4. Cleanup temp folder if cloned
specs/ # COMMITTED โ
โโโ stack/
โ โโโ stack-skills.md # Library skills (mandatory + project-specific)
โโโ ...
{SCOPE}/ARCHITECTURE.md # COMMITTED โ
(architecture reference)
.clean-claude/ # GITIGNORED
โโโ context.json # Detection cache
โโโ external-analysis.md # External repo report (temporary)
Learning runs automatically at /craft Step 5b (Architect generates skills WITH the design):
/craft
โ
โโ Step 1: Detect (Claude: package.json โ context.json)
โ NO skills generated yet โ too early
โ
โโ Step 5b: Architect
โ โ
โ โโ Reads .claude/templates/mandatory-stack-skills.md (hardcoded)
โ โโ Generates skills for ADDITIONAL libs only
โ โโ Writes specs/stack/stack-skills.md
โ โโ Writes specs/design/design-v1.md
โ
โโ /learn is for MANUAL re-runs or external analysis
Use /learn only to re-run manually or analyze external sources.
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ ๐ข ENTERPRISE: /learn in Monorepo Context โ
โ โ
โ /learn scans the SCOPED workspace (from context.json): โ
โ โ
โ Monorepo: โ
โ โโโ apps/dashboard/package.json โ scoped /learn reads THIS โ
โ โโโ apps/admin/package.json โ
โ โโโ packages/ui/package.json โ shared lib, also detectable โ
โ โโโ packages/domain/package.json โ shared domain โ
โ โ
โ /learn (no scope) โ reads ROOT package.json + all workspaces โ
โ /learn (with scope) โ reads SCOPED package.json only โ
โ โ
โ Architecture reference is PER-PROJECT (not per-workspace): โ
โ โ One ARCHITECTURE.md at root or at scope level โ
โ โ ALL apps follow the SAME patterns โ
โ โ Consistency across 40+ developers โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ ๐ VALIDATION CHECKS (Claude runs these with Grep/Glob) โ
โ โ
โ CHECK 1: TypeScript Strictness โ
โ Grep(": any\\b|as any\\b", glob="*.ts,*.tsx") โ
โ โ 0 matches = โ
PASS โ
โ โ Any matches = โ FAIL ("X files use `any` type") โ
โ โ
โ CHECK 2: Error Handling โ
โ Grep("throw new\\b", glob="*.ts,*.tsx") โ
โ + Grep("Result<|Either<", glob="*.ts,*.tsx") โ
โ โ Has Result/Either = โ
PASS โ
โ โ Only throw = โ FAIL ("Uses throw instead of Result") โ
โ โ
โ CHECK 3: Architecture Layering โ
โ Glob("src/domain/**") or Glob("src/core/**") โ
โ โ Clear layers = โ
PASS โ
โ โ No separation = โ ๏ธ WARN ("No clear architecture") โ
โ โ
โ CHECK 4: Test Presence โ
โ Glob("**/*.test.ts") count vs Glob("src/**/*.ts") count โ
โ โ > 50% ratio = โ
PASS โ
โ โ < 50% ratio = โ ๏ธ WARN ("Low test coverage") โ
โ โ 0 tests = โ FAIL ("No tests") โ
โ โ
โ RESULT THRESHOLDS โ
โ โ
CRAFT-COMPLIANT: All checks pass or only warnings โ
โ โ ๏ธ PARTIALLY COMPLIANT: Warnings but no failures โ
โ โ NOT COMPLIANT: Any check fails โ
โ โ
โ Only โ
and โ ๏ธ โ patterns extracted. โ โ violation report ONLY. โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
| Command | Claude Does | Spawns | Output |
|---|---|---|---|
/learn | Read pkg, Grep validation | Architect (skills + arch) | stack-skills.md + ARCHITECTURE.md |
/learn stack | Read pkg | Architect (skills) | stack-skills.md |
/learn architecture | Grep validation | Architect (arch capture) | ARCHITECTURE.md |
/learn <url> | Clone + Grep validation | โ | external-analysis.md |
/learn <path> | Grep validation | โ | external-analysis.md |
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ ๐ซ THE LEARNING PROCESS REFUSES TO LEARN ANTI-PATTERNS โ
โ โ
โ If code is NOT CRAFT-compliant: โ
โ โ DO NOT extract "patterns" from it โ
โ โ DO NOT use it as reference for future code โ
โ โ DO NOT generate ARCHITECTURE.md โ
โ โ
โ Instead: โ
โ โ
Report all violations found โ
โ โ
Suggest /craft "Refactor" to fix โ
โ โ
Offer to help migrate to CRAFT โ
โ โ
โ CRAFT PRINCIPLES > EXISTING CODE โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ