AGENT SKILL

phase-1-guardrails

Use when the user explicitly asks to install the toolchain (lint / format / pre-commit hook / test framework) or invokes /init-guardrails. Do NOT auto-install when only some tools are missing — first ask whether to add the missing pieces. This skill installs npm packages and writes config files; explicit consent required.

License 许可
Apache-2.0
最近更新
2026-11-09
Stars
★ 0
Forks
0

01 前言 Front Matter

name
phase-1-guardrails
description
Use when the user explicitly asks to install the toolchain (lint / format / pre-commit hook / test framework) or invokes /init-guardrails. Do NOT auto-install when only some tools are missing — first ask whether to add the missing pieces. This skill installs npm packages and writes config files; explicit consent required.
disable-model-invocation
true

03 SKILL.md 正文

Phase 1: Guardrails

You are setting up the toolchain that lets all subsequent work happen safely. The goal is "next round of changes can't make things worse" — every commit gets formatted, linted, type-checked, and (optionally) tested before it lands.

No behavior changes in Phase 1. Just the rails.

What gets installed

For a JS/TS/React project, the convergent stack is:

Tool Purpose Template
ESLint flat config Lint templates/eslint.config.flat.{js,react.js}
Prettier Format templates/prettierrc.json
TypeScript checkJs Type check w/o rename templates/tsconfig.checkjs.json
Husky Git hooks (run npx husky init)
lint-staged Run hooks on staged files only (in package.json)
Vitest Test runner templates/vitest.config.with-cleanup.js
jest-dom + cleanup Strict DOM matchers + leak prevention templates/test-setup.js

For Python: switch ESLint+Prettier to ruff + black + usort, TypeScript to pyright or mypy, vitest to pytest. Same shape.

Step-by-step (JS/TS/React project)

1. Detect existing setup

Read package.json. If ESLint / Prettier / etc. already exist — ASK the user before overwriting. Their config might be intentional.

2. Install dev dependencies

npm install --save-dev \
  eslint @eslint/js globals \
  prettier eslint-config-prettier \
  husky lint-staged \
  typescript @types/node

For React projects (note: eslint-plugin-react peer-deps cap at ESLint 9; pin if needed):

npm install --save-dev eslint@^9 @eslint/js@^9 \
  eslint-plugin-react eslint-plugin-react-hooks \
  @types/react @types/react-dom

For testing:

npm install --save-dev vitest jsdom \
  @vitejs/plugin-react \
  @testing-library/react @testing-library/jest-dom @testing-library/user-event

For Node-only projects, also:

npm install --save-dev eslint-plugin-security

3. Drop in templates

Copy the following from ${CLAUDE_PLUGIN_ROOT}/templates/ to the project root (or matching path):

  • eslint.config.flat.js (or .react.js) → eslint.config.js
  • prettierrc.json → .prettierrc.json
  • tsconfig.checkjs.json → tsconfig.json
  • vitest.config.with-cleanup.js → vitest.config.js
  • test-setup.js → src/__tests__/setup.js

Add a .prettierignore:

node_modules/
dist/
build/
coverage/
package-lock.json
*.md

4. Add scripts to package.json

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "typecheck": "tsc --noEmit",
    "test": "vitest run",
    "test:watch": "vitest",
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md,yml,yaml,css}": ["prettier --write"]
  }
}

5. Initialize Husky

npx husky init

Replace the default .husky/pre-commit content with:

npx lint-staged

Add .husky/_/ to .gitignore (auto-regenerated by husky).

6. Run prettier --write . once

This is the only Phase 1 step that touches existing files. Commit the result as a SEPARATE, formatting-only commit so subsequent diffs stay reviewable:

npx prettier --write .
git add -A
git commit -m "chore(phase1): apply prettier formatting pass

Apply project-wide Prettier formatting per the new config. No
behavior change. Subsequent commits are content changes only.

Assisted-by: Claude (claude-tdd-pro 0.3.0)"

7. Verify everything works

npm run lint           # may have warnings; should not have errors
npm run format:check   # should pass
npm run typecheck      # may have errors; record baseline
npm test               # if any tests exist; should pass

Capture baseline numbers (lint errors/warnings, typecheck errors) in a final commit summary.

8. Final commit + REMEDIATION.md update

git add eslint.config.js .prettierrc.json .prettierignore \
        tsconfig.json vitest.config.js src/__tests__/setup.js \
        package.json package-lock.json .husky/pre-commit .gitignore
git commit -m "chore(phase1): install guardrails (eslint + prettier + tsconfig + husky + vitest)

Phase 1 of REMEDIATION. Adds:
- ESLint flat config (with security/react/react-hooks plugins as applicable)
- Prettier with project-wide style
- TypeScript in checkJs mode (no file rename)
- Husky 9 pre-commit hook running lint-staged
- Vitest + jest-dom matchers + cleanup discipline

Baseline: lint NN warnings (0 errors), tsc NN errors (will address
in Phase 3), tests NN/NN passing.

No behavior change.

Assisted-by: Claude (claude-tdd-pro 0.3.0)"

Update REMEDIATION.md to check off the Phase 1 items.

What to refuse

  • "Add Snyk / Semgrep / SonarQube" — overkill for the typical small project; the standard npm audit + eslint-plugin-security is enough. If the user really wants enterprise security tooling, fine, but don't proactively suggest it.
  • "Configure CI to auto-fix and push back" — refuse (see the reject-bad-tooling skill).
  • "Run npm audit fix --force" — refuse. Plain npm audit fix only.
  • "Skip the formatting commit; just bundle it with feature work" — refuse. The formatting commit must be its own commit so future diffs stay reviewable.

What to defer

  • The 1600-line god-file decomposition — that's Phase 4, not now. Phase 1 only adds the toolchain; the existing code stays untouched except for prettier formatting.
  • Fixing the lint warnings — Phase 1 records the baseline. Phase 3 fixes the named bugs (which often resolve many warnings as a side effect). Don't try to fix warnings as part of Phase 1.
  • Major dependency upgrades — Phase 5 deals with that. Phase 1 uses whatever versions are already in the project.

04 同仓库更多 Skills

drumfiend21
drumfiend21/claude-tdd-pro

test-first-extract

Use when the user asks to EXTRACT or RELOCATE existing code into its own file, module, or component ("extract X", "split out Y", "pull Z into its own file", "decompose god-file"). NOT for net-new features (use tdd-feature-build) or behavior changes (use fix-bug). Enforces the 9-step extraction with isolated unit tests + integration regression tests as a two-tier safety net.

★ 0
drumfiend21
drumfiend21/claude-tdd-pro

tdd-feature-build

Use when the user describes a NEW feature to add ("add X to Y", "implement Z", "build a feature that…", "make it possible to…"). Enforces TDD — failing test first, minimum code to pass, refactor. Refuses to ship code without a test that demonstrably catches its absence. Does NOT trigger on bug fixes (use bug-fix-discipline) or refactors (use test-first-extract). Will ask 1-3 clarifying questions before writing any code; safe to delegate from /feature command.

★ 0
drumfiend21
drumfiend21/claude-tdd-pro

sync

Multi-machine git-backed sync of local TDD Pro state via the `tdd-pro-sync` branch. Use when operators run claude-tdd-pro on more than one machine and want their FAILURE-LOG, decisions, audit checkpoints, workflow state, operator-curated URL registries, operator/community trees, and paywalled attestations to follow them between hosts.

★ 0
drumfiend21
drumfiend21/claude-tdd-pro

strict-component-tests

Use when writing or reviewing test files. Enforces strict assertions that actually catch regressions (getByRole, exact counts, jest-dom matchers) in contrast to permissive tests (queryAllByText length > 0) that pass against broken UIs. References QUALITY-BAR.md for the canonical strictness rules.

★ 0
drumfiend21
drumfiend21/claude-tdd-pro

spec

暂无简介

★ 0
drumfiend21
drumfiend21/claude-tdd-pro

spec-first

Use when the user describes a non-trivial feature or system that should be specified in writing before any code is written. Pattern from Geoffrey Huntley's "Ralph" loop, OpenSpec, intent-driven.dev, and Kent Beck's "augmented coding" framing — specs+tests are the durable artifact, code is the disposable one. Produces a Markdown spec document that the user reviews; only after approval does any code get written (typically via tdd-feature-build or /feature).

★ 0