claude-scaffold

# claude-scaffold

**A Claude Code infrastructure layer for ML and AI engineers — one repo that makes Claude a disciplined engineering partner across all your projects.**

Clone once. Deploy to any project in one command. Update all projects whenever you improve the config — every project stays in sync automatically.

[![CI](https://github.com/pyramidheadshark/claude-scaffold/actions/workflows/ci.yml/badge.svg)](https://github.com/pyramidheadshark/claude-scaffold/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/claude-scaffold?label=npm&color=blue)](https://www.npmjs.com/package/claude-scaffold)
[![npm downloads](https://img.shields.io/npm/dm/claude-scaffold?color=blue)](https://www.npmjs.com/package/claude-scaffold)
![Jest Tests](https://img.shields.io/badge/Jest-350%20tests-brightgreen)
![Python Tests](https://img.shields.io/badge/Python-57%20tests-blue)
![Skills](https://img.shields.io/badge/skills-20-orange)
![Python](https://img.shields.io/badge/python-3.11%2B-blue)
![Node](https://img.shields.io/badge/node-18%2B-green)
![License](https://img.shields.io/badge/license-MIT-lightgrey)

![Demo](docs/demo.gif)

---

## The Concept

Most Claude Code setups are per-project and drift apart. claude-scaffold is a **central infrastructure layer** that you own and deploy everywhere.

```
claude-scaffold  ← you configure this once
      │
      ├── deploy → project-a/.claude/
      ├── deploy → project-b/.claude/
      └── deploy → project-c/.claude/

Later: npx claude-scaffold update --all
      → all three stay in sync with zero manual work
```

You can ask Claude directly to handle this:
> *"Deploy claude-scaffold to my new project with the fastapi-developer profile"*
> *"Update all registered projects to the latest infra version"*

Claude reads this README, runs the CLI, and wires everything up. No manual config copy-pasting.

---

## Why claude-scaffold?

### Before vs After

**Before:** every project has its own CLAUDE.md copied from memory, hooks are not synchronized, each project drifts toward different standards. When you improve your workflow, you update one project — the rest stay stale.

**After:** one source of truth. `npx claude-scaffold update --all` propagates every improvement to all registered projects simultaneously. Claude reads the same discipline everywhere.

### Why not just copy a CLAUDE.md?

A single CLAUDE.md copy works for one project. claude-scaffold adds:
- **Sync mechanism** — `update --all` keeps every project in sync with one command
- **Skill injection** — 18 domain skills loaded automatically per prompt, not as a single monolithic file
- **Profile system** — different CLAUDE.md per role (ML engineer, FastAPI dev, AI developer, fullstack)
- **Hook infrastructure** — session tracking, onboarding, quality checks, all wired automatically

---

## Quick Start

```bash
# Interactive wizard — asks profile, language, CI, deploy target
npx claude-scaffold init /path/to/my-project

# One-liner with profile
npx claude-scaffold init /path/to/my-project --profile ml-engineer --lang en
```

Profiles: `ml-engineer` · `ai-developer` · `fastapi-developer` · `fullstack`
Languages: `en` · `ru`

```bash
# Edit session context after deploy
code /path/to/my-project/dev/status.md

# Keep all projects in sync
npx claude-scaffold status        # show all registered projects + version drift
npx claude-scaffold update --all  # sync all outdated projects
npx claude-scaffold update /path  # sync a single project
```

> Python deploy alternative (no npm required): [docs/INTEGRATION.md](docs/INTEGRATION.md)

---

## Advanced: Org Profiles (Teams)

For teams with shared conventions — infrastructure topology, naming rules, internal links — org profiles add an organization-specific CLAUDE.md layer on top of scaffold core. This layer survives `update --all` and is updated independently.

```bash
# Deploy with org profile (team-specific CLAUDE.md)
npx claude-scaffold init /path/to/repo --profile ai-developer --org-profile techcon-ml --org-type ml-pipeline

# List available org profiles and types
npx claude-scaffold list-org-profiles

# Update CLAUDE.md in all org repos (reads org-profiles/<org>/repos.json)
npx claude-scaffold update-org-profile --org techcon-ml

# Override repo list explicitly
npx claude-scaffold update-org-profile --org techcon-ml --repos /path/a,/path/b
```

Org profiles live in `org-profiles/<org-name>/` in the scaffold repo. They are gitignored by default — internal org data stays private.

---

## What It Does

On every Claude Code prompt, the hook automatically:
1. Injects `dev/status.md` — your project's current state and next steps
2. Detects planning intent and reminds to enter plan mode
3. Matches the prompt against 20 skill rules (keywords + changed files)
4. Injects up to 2 additional relevant skills into `system_prompt_addition`

Skills bring domain knowledge: FastAPI patterns, RAG pipelines, LangGraph graphs, CI/CD configs, test-first workflow — injected only when needed, compressed if large.

---

## Components

### 20 Skills

| Skill | Triggers On |
|---|---|
| `python-project-standards` | **Always loaded** (always_load: true) |
| `critical-analysis` | hypothesis, experiment, bottleneck, рефактор, подход, метрик (≥2 keywords, priority=0) |
| `fastapi-patterns` | FastAPI, routers, endpoints, Pydantic |
| `htmx-frontend` | HTMX, Jinja2 templates, server-side rendering |
| `ml-data-handling` | pickle, ONNX, Parquet, S3, artifacts |
| `multimodal-router` | PDF, DOCX, video, image analysis, Gemini |
| `langgraph-patterns` | langgraph + state/graph/node (min 2 keywords) |
| `rag-vector-db` | Qdrant, pgvector, embeddings, chunking, RAG |
| `nlp-slm-patterns` | Presidio, spaCy, Ollama, vLLM, PII |
| `predictive-analytics` | sklearn, MLflow, Optuna, feature engineering |
| `experiment-tracking` | MLflow, model registry, log_metric, experiment |
| `data-validation` | pandera, great expectations, schema validation |
| `infra-yandex-cloud` | terraform + yandex/docker (min 2 keywords) |
| `test-first-patterns` | pytest, BDD, Gherkin, fixtures, coverage |
| `github-actions` | `.github/workflows/*.yml`, CI/CD jobs |
| `claude-api-patterns` | anthropic SDK, tool_use, MessageCreate |
| `prompt-engineering` | system_prompt, few_shot, chain-of-thought, eval |
| `database-migration-safety` | alembic, migration, schema, upgrade/downgrade (≥2 keywords) |
| `supply-chain-auditor` | dependency, CVE, audit, pip install, vulnerable (≥2 keywords) |
| `design-doc-creator` | *Meta — manual only, not auto-loaded* |
| `skill-developer` | *Meta — manual only, not auto-loaded* |

### 8 Agents

`design-doc-architect` · `test-architect` · `multimodal-analyzer` · `code-reviewer` · `infra-provisioner` · `refactor-planner` · `project-status-reporter` · `debug-assistant`

### 4 Commands

`/init-design-doc` · `/new-project` · `/review` · `/dev-status`

### 6 Hooks

| Hook | Event | Action |
|---|---|---|
| `skill-activation-prompt.js` | UserPromptSubmit | Inject status.md + matched skills + plan-mode reminder |
| `session-safety.js` | PreToolUse | Classify Bash commands (CRITICAL/MODERATE/SAFE), create git snapshots |
| `session-start.js` | SessionStart | Detect platform (win32/unix), inject Windows rules, onboarding |
| `session-checkpoint.js` | PostToolUse | Auto-checkpoint at plan approval or every 50 tool calls |
| `post-tool-use-tracker.js` | PostToolUse | Log tool calls to `.claude/logs/` |
| `python-quality-check.js` | Stop | Run ruff + mypy at session end |

### Session Safety

`session-safety.js` watches every Bash command Claude executes and classifies it as CRITICAL, MODERATE, or SAFE based on patterns in `destructive-patterns.json`.

On every **CRITICAL** command (`git reset --hard`, `rm -rf`, `DROP TABLE`, `curl | bash`, etc.) the hook creates a **git tag recovery point** before the operation runs:

- First snapshot: `claude/s-{session8}`
- Second snapshot in same session: `claude/s-{session8}-2`
- Restore: `git reset --hard claude/s-{ses

[truncated…]