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.jsprettierrc.json→.prettierrc.jsontsconfig.checkjs.json→tsconfig.jsonvitest.config.with-cleanup.js→vitest.config.jstest-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-securityis 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-toolingskill). - "Run
npm audit fix --force" — refuse. Plainnpm audit fixonly. - "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
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.
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.
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.
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.
spec
暂无简介
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).