lordrance/claude-code-industrial-workbench

# Claude Code Industrial Workbench This repository is a reusable Claude Code project foundation for AI-assisted software development. It is designed to make Claude Code work inside a safer, more testable, reviewable, and production-like workflow. It is **not** a finished application. It is the scaffolding you drop in **before** you start writing application code. ## 1. What this is A starter set of AI-development guardrails for any new software project you want to build with [Claude Code](https://docs.claude.com/en/docs/claude-code). It captures the conventions, hooks, runbooks, and review gates that turn "vibe coding" into something you can ship. The tech stack of the *app you are about to build* is **not** chosen here. This template is stack-agnostic by design — pick Node, Python, Go, Rust, anything, on top of it. This is **not** a FAANG internal platform, and it is **not** SOC2 / HIPAA / PCI-ready on its own. See [`docs/ai-governance/README.md`](./docs/ai-governance/README.md) for an honest tier check. ## 2. What is included ### Core Claude Code workstation | Path | Purpose | | --- | --- | | [`CLAUDE.md`](./CLAUDE.md) | Karpathy-style guideline file (verbatim) plus one beginner-friendly sentence. Loaded as the top-level project rule. | | [`.claude/rules/`](./.claude/rules/) | Project-workflow rules that govern AI behaviour on top of `CLAUDE.md`. | | [`.claude/skills/`](./.claude/skills/) | Six local skills: `tdd`, `debug-root-cause`, `code-review`, `security-review`, `db-migration-review`, `api-contract-review`. | | [`.claude/agents/`](./.claude/agents/) | Four read-only review subagents: code, security, tests, database. | | [`.claude/hooks/`](./.claude/hooks/) | Hook scripts: block dangerous commands, list fast checks, remind final-report. | | [`.claude/settings.json`](./.claude/settings.json) | **DRAFT** hook registration — verify against your installed Claude Code version. | | [`.specify/`](./.specify/) + [`specs/`](./specs/) | Spec-Kit-style structure (lightweight fallback). Constitution + spec/plan/tasks workflow. | | [`docs/runbooks/`](./docs/runbooks/) | How-to guides — spec-driven development, skills, MCP setup, GitHub CLI, PR review gate, branch protection, manual install, manual review checklist. | | [`docs/architecture/`](./docs/architecture/) + [`docs/decisions/`](./docs/decisions/) + [`docs/security/`](./docs/security/) | Empty placeholders + security baseline + GitHub Actions hardening + Scorecard runbook. | ### Tier 1 industrial hardening (added in v0.1) | Path | Purpose | | --- | --- | | [`.github/CODEOWNERS`](./.github/CODEOWNERS) | Per-path review routing. Pairs with branch protection to make CODEOWNER review **required**. | | [`.gitattributes`](./.gitattributes) | Locks line endings to LF for text files; marks binaries; suppresses noisy lockfile diffs. | | [`.editorconfig`](./.editorconfig) | Cross-editor indent / charset / EOL defaults; per-language overrides. | | [`.tool-versions.example`](./.tool-versions.example) | Template for exact-version pinning (mise / asdf). Activate when a stack is chosen. | | [`lefthook.yml`](./lefthook.yml) + [`.scripts/`](./.scripts/) | Local pre-commit (secret-file block, JSON syntax) + commit-msg (Conventional Commits) hooks. | | [`commitlint.config.example.js`](./commitlint.config.example.js) | Drop-in commitlint config for the day Node tooling enters the project. | | [`.github/workflows/ci.yml`](./.github/workflows/ci.yml) | Generic draft CI — stack auto-detect, lint/typecheck/test only if scripts exist. Now with explicit `permissions: contents: read`. | | [`.github/workflows/security.yml`](./.github/workflows/security.yml) | Secret scan (TruffleHog) + dependency audit + Semgrep/CodeQL placeholder. | | [`.github/workflows/scorecard.yml`](./.github/workflows/scorecard.yml) | OpenSSF Scorecard — runs weekly + on PR; uploads SARIF to Security tab. | | [`.github/pull_request_template.md`](./.github/pull_request_template.md) | PR template enforcing summary, risk, rollback, checklist. | | [`.github/ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE/) | Bug / feature / question forms + chooser config. Blank issues disabled. | | [`.github/dependabot.yml`](./.github/dependabot.yml) | Dependabot draft (GitHub Actions enabled; npm / pip commented). | | [`.gitignore`](./.gitignore) | Secrets, build output, OS junk, Python/Node caches, per-session AI audit logs. | ### AI governance v0 | Path | Purpose | | --- | --- | | [`docs/ai-governance/`](./docs/ai-governance/) | Five policy documents: README, prompt-change policy, eval plan, audit-log policy, regression dataset. | | [`.claude/mcp.policy.json`](./.claude/mcp.policy.json) + [`.claude/mcp.policy.md`](./.claude/mcp.policy.md) | MCP allowlist (`context7`, `playwright`, `serena`) + rationale, review process for additions. | | [`.claude/models.policy.md`](./.claude/models.policy.md) | When to use Opus vs Sonnet vs Haiku-class; rules for sensitive areas. | | [`evals/`](./evals/) | Skeleton eval suite: `golden-tasks/` (positive cases) and `regressions/` (negative cases). No runner yet — that is v1. | | [`.claude/logs/.gitkeep`](./.claude/logs/.gitkeep) | Placeholder for per-session audit JSONL (gitignored). | ### Tier 1.5 universal engineering skeleton (added in v0.2) Stack-agnostic policy + skeleton layer. No language, no framework, no tool installed automatically. Every active workflow below is **manual** (`workflow_dispatch`) or **conditional** until a real stack lands. | Path | Purpose | | --- | --- | | [`Taskfile.example.yml`](./Taskfile.example.yml) | Universal task verbs (`setup` / `dev` / `test` / `lint` / `format` / `typecheck` / `security` / `sbom` / `scan:container` / `scan:iac` / `release` / `clean`). Each task is a placeholder; copy to `Taskfile.yml` once a stack is chosen. | | [`docs/runbooks/task-runner.md`](./docs/runbooks/task-runner.md) | Why one standard command interface; per-stack mapping examples. | | [`.devcontainer/devcontainer.example.json`](./.devcontainer/devcontainer.example.json) | DevContainer schema-valid example; no active container. | | [`docs/runbooks/devcontainer.md`](./docs/runbooks/devcontainer.md) | When to activate, which base image per stack, what NOT to put in. | | [`docs/observability/`](./docs/observability/) | OpenTelemetry policy + per-signal policy (logs / metrics / traces). Vendor-neutral. | | [`docs/feature-flags/`](./docs/feature-flags/) | OpenFeature policy + per-flag record template. Provider deferred. | | [`docs/reliability/`](./docs/reliability/) | SLO/SLI policy + YAML template + incident-response + postmortem templates. | | [`docs/release/`](./docs/release/) | SemVer + Conventional Commits release policy + changelog policy + release checklist. Release tool deferred. | | [`docs/security/sbom-policy.md`](./docs/security/sbom-policy.md) + [`.github/workflows/sbom.yml`](./.github/workflows/sbom.yml) | SBOM policy (CycloneDX/SPDX) + manual workflow (Syft-based, no-op when no manifests exist). | | [`docs/security/container-scanning.md`](./docs/security/container-scanning.md) + [`.github/workflows/container-scan.yml`](./.github/workflows/container-scan.yml) | Container-scan policy (Trivy/Grype) + manual workflow (skips cleanly when no Dockerfile). | | [`docs/security/iac-scanning.md`](./docs/security/iac-scanning.md) + [`.github/workflows/iac-scan.yml`](./.github/workflows/iac-scan.yml) | IaC-scan policy (Checkov / Trivy config) + manual workflow (skips cleanly when no IaC files). | | [`docs/security/license-compliance.md`](./docs/security/license-compliance.md) | Allowed / blocked license sets + tool selection by stack. No active scanner. | | [`presets/README.md`](./presets/README.md) | Placeholder — explains where future stack presets will live and why none exist yet. | **Important properties of this layer:** - These are **stack-agnostic policies and examples**. No `package.json`, `pyproject.toml`, `Dockerfile`, Terraform, or Kubernetes manifests were added. - Workflows are **manual or conditional**. Running them on this template produces a "nothing to scan, exiting cleanly" message — not a failure. - Real commands, real configs, and real implementations must be filled in **after** a project picks a stack. The base remains universal. ## 3. Current setup status This template is committed with **only the project-level files** above. Anything global, interactive, or per-machine is documented but **not** installed automatically: | Component | State | | --- | --- | | Karpathy-style `CLAUDE.md` | ✅ committed (verbatim, SHA256-verified) | | Project rules, skills, agents, hooks | ✅ committed | | Spec-Kit fallback structure | ✅ committed | | CI / security / Scorecard / Dependabot draft workflows | ✅ committed | | Tier 1 hardening (CODEOWNERS, EOL/editor configs, hooks, issue templates) | ✅ committed | | AI governance v0 (policies, MCP allowlist, model policy, eval skeleton) | ✅ committed | | Tier 1.5 universal engineering skeleton (Taskfile / DevContainer / observability / feature flags / reliability / release / SBOM / container & IaC scanning / license compliance / presets placeholder) | ✅ committed (stack-agnostic) | | Branch protection / rulesets on GitHub | ⚠️ **manual** — see `docs/runbooks/github-branch-protection.md` | | GitHub Actions SHA pinning | ⚠️ **planned** — patch with verified SHAs in `docs/security/github-actions-hardening.md` | | GitHub CLI (`gh`) | ⚠️ not installed on author machine — install per OS | | `uv` / `uvx` | ⚠️ not installed — needed for official Spec Kit and Serena | | Official GitHub Spec Kit | ⚠️ not initialized — fallback in use | | Context7 / Playwright / Serena MCP | ⚠️ not configured — allowed by policy, install on demand | | Matt Pocock Skills | ⚠️ not installed — `npx skills@latest add` is interactive | | Lefthook | ⚠️ not installed — opt-in, see `docs/runbooks/local-git-hooks.md` | A clean checkout of this repo is usable without any of the items in the lower half. They unlock additional capabilities, not core safety. ## 4. Manual tools to install later These are **per-machine** (or per-user) tools. Once installed on your laptop, every Claude Code project on that machine benefits from them. Install when you actually want what they offer. - [`mise`](https://mise.jdx.dev/) or [`asdf`](https://asdf-vm.com/) — read `.tool-versions` for exact-version pinning. Recommended once a stack is chosen. - [`lefthook`](https://github.com/evilmartians/lefthook) — runs the local pre-commit / commit-msg hooks defined in `lefthook.yml`. - [`uv`](https://docs.astral.sh/uv/) — Python toolchain manager. Unlocks the official Spec Kit and Serena. - [`gh`](https://cli.github.com/) — GitHub CLI for PR / issue / review work. - [Context7](https://context7.com/) — up-to-date library docs as an MCP server. - [Playwright MCP](https://github.com/microsoft/playwright-mcp) — browser automation as an MCP server. - [Serena](https://github.com/oraios/serena) — semantic codebase navigation, installed via `uv`. - [Matt Pocock Skills](https://github.com/mattpocock) — community skill collection (interactive install). - [Official GitHub Spec Kit](https://github.com/github/spec-kit) — full Spec-Kit toolchain (`uvx specify init`). See [`docs/runbooks/manual-installation.md`](./docs/runbooks/manual-installation.md) and [`docs/runbooks/tool-versions.md`](./docs/runbooks/tool-versions.md) for one-liners. **Failed installation of any of the above does not break this repository.** The template stays usable. ## 5. Recommended workflow For small tasks (typo, single-file edit, dependency bump): 1. Describe the task. 2. Let Claude inspect the relevant files. 3. Make the smallest change. 4. Run lint / typecheck / tests locally. 5. Review the diff. PR. Human review. Merge. For medium or large tasks (new feature, sensitive area, multiple files): 1. Write `specs//spec.md` — *what* and *why*. 2. Write `specs//plan.md` — *how*, with trade-offs and risks. 3. Break into `specs//tasks.md` — one small PR per task. 4. Implement task by task, using the `tdd` skill for new behaviour. 5. Run local checks. PR. CI + security scan + Scorecard must pass. Human + CODEOWNER review. Merge. When the PR touches `.claude/`, `CLAUDE.md`, or any AI-governance file, the [prompt-change policy](./docs/ai-governance/prompt-change-policy.md) adds a review step. Full version: [`docs/runbooks/how-to-use-ai-workstation.md`](./docs/runbooks/how-to-use-ai-workstation.md). ## 6. Repository structure . ├── CLAUDE.md ├── README.md ├── .gitignore ├── .gitattributes ├── .editorconfig ├── .tool-versions.example ├── lefthook.yml ├── commitlint.config.example.js ├── Taskfile.example.yml ├── .devcontainer/devcontainer.example.json ├── presets/README.md (placeholder — no real presets yet) ├── .scripts/ │ ├── check-commit-message.py │ └── check-secret-files.py ├── .claude/ │ ├── settings.json (DRAFT — verify hook schema for your Claude version) │ ├── mcp.policy.json │ ├── mcp.policy.md │ ├── models.policy.md │ ├── rules/project-workflow.md │ ├── skills/{tdd,debug-root-cause,code-review,security-review,db-migration-review,api-contract-review}/SKILL.md │ ├── agents/{code-reviewer,security-reviewer,test-engineer,db-reviewer}.md │ ├── hooks/{block_dangerous_commands,run_fast_checks,final_report_check}.py │ └── logs/.gitkeep (real *.jsonl logs gitignored) ├── .specify/ │ ├── memory/constitution.md │ └── templates/ (empty — filled by official `specify init`) ├── specs/ │ └── README.md ├── evals/ │ ├── README.md │ ├── golden-tasks/README.md │ └── regressions/README.md ├── docs/ │ ├── architecture/README.md │ ├── decisions/README.md │ ├── ai-governance/ │ │ ├── README.md │ │ ├── prompt-change-policy.md │ │ ├── agent-eval-plan.md │ │ ├── agent-audit-log-policy.md │ │ └── ai-regression-dataset.md │ ├── observability/ │ │ ├── README.md │ │ ├── opentelemetry-policy.md │ │ ├── logging-policy.md │ │ ├── metrics-policy.md │ │ └── tracing-policy.md │ ├── feature-flags/ │ │ ├── README.md │ │ ├── openfeature-policy.md │ │ └── feature-flag-record.template.md │ ├── reliability/ │ │ ├── README.md │ │ ├── slo-sli-policy.md │ │ ├── slo-record.template.yml │ │ ├── incident-response.template.md │ │ └── postmortem.template.md │ ├── release/ │ │ ├── README.md │ │ ├── release-policy.md │ │ ├── changelog-policy.md │ │ └── release-checklist.template.md │ ├── runbooks/ │ │ ├── README.md │ │ ├── how-to-use-ai-workstation.md │ │ ├── ai-workstation-setup.md │ │ ├── skills.md │ │ ├── spec-driven-development.md │ │ ├── github-cli.md │ │ ├── github-branch-protection.md │ │ ├── pr-review-gate.md │ │ ├── manual-installation.md │ │ ├── manual-review-checklist.md │ │ ├── tool-versions.md │ │ ├── local-git-hooks.md │ │ ├── conventional-commits.md │ │ ├── task-runner.md │ │ └── devcontainer.md │ └── security/ │ ├── security-baseline.md │ ├── github-actions-hardening.md │ ├── openssf-scorecard.md │ ├── sbom-policy.md │ ├── container-scanning.md │ ├── iac-scanning.md │ └── license-compliance.md └── .github/ ├── CODEOWNERS ├── pull_request_template.md ├── dependabot.yml ├── ISSUE_TEMPLATE/ │ ├── config.yml │ ├── bug_report.yml │ ├── feature_request.yml │ └── question.yml └── workflows/ ├── ci.yml ├── security.yml ├── scorecard.yml ├── sbom.yml (workflow_dispatch only — no-op without manifests) ├── container-scan.yml (workflow_dispatch only — no-op without Dockerfile) └── iac-scan.yml (workflow_dispatch only — no-op without IaC files) ## 7. Security notes - **Never commit `.env`** (or any `.env.*`). Use `.env.example` for documentation. - **Never commit private keys** (`*.pem`, `*.key`, `*.p12`, `*.pfx`). - The pre-tool hook [`block_dangerous_commands.py`](./.claude/hooks/block_dangerous_commands.py) blocks destructive shell commands and any attempt to print secret-looking environment variables or read `.env` / key files. - The local pre-commit hook [`check-secret-files.py`](./.scripts/check-secret-files.py) refuses to stage obvious secret-filename matches before they leave the developer's machine. - The CI [`security.yml`](./.github/workflows/security.yml) workflow runs TruffleHog on every PR and audits dependencies when lockfiles are present. - The CI [`scorecard.yml`](./.github/workflows/scorecard.yml) workflow scores supply-chain hygiene weekly + on every PR. - Third-party GitHub Actions should be pinned to commit SHA — see [`docs/security/github-actions-hardening.md`](./docs/security/github-actions-hardening.md) for the verified-SHA patch plan. - Repo-level controls (Secret scanning, Push protection, Dependabot alerts, Code scanning) must be enabled in **GitHub repo Settings** after the first push. - Branch protection / rulesets are configured manually — see [`docs/runbooks/github-branch-protection.md`](./docs/runbooks/github-branch-protection.md). Full policy: [`docs/security/security-baseline.md`](./docs/security/security-baseline.md). ## 8. AI governance The `.claude/` configuration is treated as load-bearing code: changes are reviewed, justified, and (in v1) eval-gated. - [`docs/ai-governance/README.md`](./docs/ai-governance/README.md) — entry point and tier check. - [`docs/ai-governance/prompt-change-policy.md`](./docs/ai-governance/prompt-change-policy.md) — how prompt / rule / skill / hook changes get reviewed. - [`docs/ai-governance/agent-eval-plan.md`](./docs/ai-governance/agent-eval-plan.md) — what gets evaluated and how. - [`docs/ai-governance/agent-audit-log-policy.md`](./docs/ai-governance/agent-audit-log-policy.md) — what every Claude session records (and what it never records). - [`docs/ai-governance/ai-regression-dataset.md`](./docs/ai-governance/ai-regression-dataset.md) — how to capture Claude mistakes so they cannot regress. - [`.claude/mcp.policy.json`](./.claude/mcp.policy.json) — MCP server allowlist. - [`.claude/models.policy.md`](./.claude/models.policy.md) — model routing rules. ## 9. Attribution The `CLAUDE.md` file in this repository is a Karpathy-inspired AI guideline document, copied verbatim from: Only one beginner-friendly sentence is appended at the end of `CLAUDE.md`; nothing else has been changed. This repository is **not** officially affiliated with, endorsed by, or created by Andrej Karpathy, Anthropic, GitHub, or Cursor. Trademarks belong to their respective owners. ## 10. License License to be added.