Files

T

james.bland 3f0786f1e7 refactor: agents and skills move to a client-neutral source that renders per client

`.claude/agents/` was the source of truth, which made every role Claude-Code
shaped. Adding a second client meant rewriting each role in that client's syntax
and maintaining both copies — the drift this scaffold exists to prevent, one layer
up.

Roles and skills now live under `.agents/` and render into each registered
client. `.claude/agents/`, `.claude/skills/` and `.codex/agents/` are generated;
`scripts/sync-agent-integrations.py --check` fails on drift and belongs in CI.

The role metadata is portable rather than vendor-named: `reasoning_tier`
(deep/balanced/fast/vision), `capabilities`, `mutation`, `invocation`, and an
optional `preload_skills`. A client manifest maps those to native syntax and must
declare what it cannot express — `codex.yaml` declares `tier_policy: unsupported`
and its adapters say so in the file, rather than the tier silently evaporating and
leaving the repository to believe it was enforced.

The port is behaviour-preserving where it should be and a fix where it should not.
Every instruction body is byte-identical — the whole diff to `.claude/agents/` is
18 added lines and zero deletions. What changed is frontmatter that was missing:

- four agents (`code-reviewer`, `tdd-guardian`, `dependency-audit`, `pr-creator`)
  declared no `tools:` and therefore inherited the ENTIRE tool pool, so three
  review-only agents could edit and write the code they were reviewing. All eight
  now declare capabilities explicitly.
- the six read-only roles gain a non-editing permission mode, so the constraint is
  enforced by the client rather than by the prompt asking nicely.
- `mutation` is now explicit, which records the two roles that genuinely need to
  write: `pr-creator` (external-write — it pushes a branch and opens a PR) and
  `dependency-audit` (workspace-write — package managers rewrite lockfiles).

`pr-creator` keeps `shell` because opening a PR needs it, but it is now the only
agent here with a write mutation and a declared reason for it, instead of one of
four with unlimited access by omission.

2026-09-19 17:27:26 -04:00

8.7 KiB

Raw Blame History

Claude Code Configuration

A comprehensive guidance system for Claude Code with strict TDD enforcement, multi-language support, and infrastructure patterns.

Quick Start

Backup existing config (if any):
```
mv ~/.claude ~/.claude.backup
```

Deploy this configuration:

cp -r .claude/* ~/.claude/
chmod +x ~/.claude/hooks/*.sh

Verify installation:

ls ~/.claude/
# Should show: CLAUDE.md, settings.json, agents/, skills/, hooks/

Structure

~/.claude/
├── CLAUDE.md                    # Core principles (~150 lines)
├── settings.json                # Model config (opusplan), Claude hooks
├── agents/                      # GENERATED from ../.agents/roles — do not edit
│   ├── tdd-guardian.md          # TDD enforcement (sonnet)
│   ├── code-reviewer.md         # PR review (opus)
│   ├── security-scanner.md      # Security checks (sonnet, read-only)
│   ├── refactor-scan.md         # Refactoring assessment (sonnet, read-only)
│   ├── dependency-audit.md      # Vulnerability/outdated package checks (sonnet)
│   ├── pr-creator.md            # Automated PR creation (haiku)
│   ├── release-notes.md         # CHANGELOG generation (haiku, read-only)
│   └── plan-reviewer.md         # Plan validation (sonnet, read-only)
├── skills/                      # GENERATED from ../.agents/skills — do not edit
│   ├── languages/
│   │   ├── python/SKILL.md      # pytest, Ruff, FastAPI
│   │   ├── typescript/SKILL.md  # Vitest, ESLint, React
│   │   ├── rust/SKILL.md        # cargo test, clippy
│   │   ├── go/SKILL.md          # go test, golangci-lint
│   │   ├── java/SKILL.md        # JUnit 5, Spring Boot
│   │   └── csharp/SKILL.md      # xUnit, .NET Clean Architecture
│   ├── testing/
│   │   ├── tdd/SKILL.md         # TDD workflow
│   │   ├── ui-testing/SKILL.md  # React Testing Library
│   │   └── browser-testing/SKILL.md  # Playwright, Chrome MCP
│   ├── infrastructure/
│   │   ├── aws/SKILL.md         # AWS patterns
│   │   ├── azure/SKILL.md       # Azure patterns
│   │   ├── gcp/SKILL.md         # GCP patterns
│   │   ├── terraform/SKILL.md   # Terraform IaC
│   │   ├── ansible/SKILL.md     # Ansible automation
│   │   ├── docker-kubernetes/SKILL.md  # Containers & orchestration
│   │   ├── database/SKILL.md    # DB patterns, Alembic migrations
│   │   └── cicd/SKILL.md        # Jenkins, GitHub Actions, GitLab CI
│   └── patterns/
│       ├── monorepo/SKILL.md    # Workspace patterns
│       ├── api-design/SKILL.md  # REST API patterns
│       └── observability/SKILL.md  # Logging, metrics, tracing
└── hooks/
    ├── check-secrets.sh         # Claude hook: Block secrets in code
    ├── auto-format.sh           # Claude hook: Auto-format on save
    ├── pre-commit-tdd.sh        # Git hook script: TDD enforcement
    └── example-git-hooks/
        └── pre-commit           # Example git hook (copy to .git/hooks/)

Model Strategy

Uses opusplan mode:

Opus for planning, architecture, code review
Sonnet for code execution, testing, implementation

Key Features

TDD Enforcement

Strict RED-GREEN-REFACTOR cycle
80%+ coverage requirement
Tests must be written before code

Type Safety

Python: Pydantic v2, mypy strict
TypeScript: Strict mode, Zod schemas
Rust: Full type system utilization

Security

Automatic secret detection
Blocks commits with credentials
Security scanner agent

Multi-Language Support

Python (FastAPI, pytest, Ruff)
TypeScript (React, Vitest, ESLint)
Rust (Tokio, cargo test, clippy)
Go (go test, golangci-lint, Chi)
Java (Spring Boot, JUnit 5, Mockito)
C# (.NET, xUnit, Clean Architecture)
Terraform (AWS/Azure/GCP modules)
Ansible (playbooks, roles)

Multi-Cloud Support

AWS (Lambda, ECS, S3, Secrets Manager)
Azure (App Service, Functions, Key Vault)
GCP (Cloud Run, Functions, Secret Manager)

Hooks Explained

This configuration includes two types of hooks:

1. Claude Hooks (Automatic)

Defined in settings.json, these run automatically during Claude sessions:

check-secrets.sh - Blocks file writes containing secrets (PreToolUse)
auto-format.sh - Auto-formats files after writes (PostToolUse)

These are configured via settings.json and require no additional setup.

2. Git Hooks (Manual Setup Required)

The pre-commit-tdd.sh script enforces TDD rules at git commit time. This is a git hook, not a Claude hook.

Setup Option A: Symlink (recommended)

# In your project directory
mkdir -p .git/hooks
ln -sf ~/.claude/hooks/example-git-hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Setup Option B: Copy

# In your project directory
mkdir -p .git/hooks
cp ~/.claude/hooks/example-git-hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Setup Option C: Using Husky (Node.js projects)

npm install -D husky
npx husky init
echo '~/.claude/hooks/pre-commit-tdd.sh' > .husky/pre-commit

What the git hook does:

Verifies test files exist for changed production files
Blocks commits that appear to violate TDD (code without tests)
Can be bypassed with git commit --no-verify (use sparingly)

Usage Examples

Invoke TDD Guardian

@tdd-guardian Let's implement user authentication

Code Review

@code-reviewer Review these changes before I merge

Security Scan

@security-scanner Check this code for vulnerabilities

Refactoring Assessment

@refactor-scan Assess this code for refactoring opportunities

Dependency Audit

@dependency-audit Check for vulnerable or outdated packages

Create Pull Request

@pr-creator Create a PR for this branch

Generate Release Notes

@release-notes Generate changelog from v1.0.0 to HEAD

Review Implementation Plan

@plan-reviewer Review docs/plans/active/3.5_business-capabilities.md

Editing agents and skills

.claude/agents/ and .claude/skills/ are generated. The source of truth is .agents/, which is client-neutral so the same roles and skills also render for Codex (and any client added later) rather than being rewritten per tool.

python3 scripts/sync-agent-integrations.py          # regenerate
python3 scripts/sync-agent-integrations.py --check  # fail on drift (use in CI)

Edit .agents/roles/<name>.md or .agents/skills/**, then run the sync. A direct edit to a generated file is reverted by the next run.

Customization

Project-Specific CLAUDE.md

Add a CLAUDE.md in your project root to override or extend settings:

# Project: My App

## Additional Rules
- Use PostgreSQL for all database work
- Deploy to AWS eu-west-2

Disable Hooks

Comment out hooks in settings.json:

{
  "hooks": {
    // "PreToolUse": [...]
  }
}

Coverage Requirements

Layer	Target
Domain/Business Logic	90%+
API Routes	80%+
Infrastructure/DB	70%+
UI Components	80%+

Quick Reference

Commands by Language

# Python
pytest --cov=src --cov-fail-under=80
ruff check . && ruff format .

# TypeScript
npm test -- --coverage
npm run lint && npm run typecheck

# Rust
cargo test && cargo clippy -- -D warnings

# Go
go test -cover ./...
golangci-lint run

# Java (Maven)
mvn test
mvn verify  # Integration tests

# C# (.NET)
dotnet test --collect:"XPlat Code Coverage"

# Terraform
terraform validate && terraform fmt -check

Starting a New Project

When starting a new project with this configuration:

Initialize git (if not already):
```
git init
```

Copy the .gitignore (from this scaffold repo):

cp /path/to/ai-development-scaffold/.gitignore .

Set up git hooks:

mkdir -p .git/hooks
ln -sf ~/.claude/hooks/example-git-hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Add project-specific CLAUDE.md (optional):

touch CLAUDE.md
# Add project-specific rules

Troubleshooting

Hooks not running

# Ensure hooks are executable
chmod +x ~/.claude/hooks/*.sh

# Check hook syntax
bash -n ~/.claude/hooks/check-secrets.sh

Skills not loading

Skills are auto-discovered from ~/.claude/skills/. Ensure:

Files are named SKILL.md (case-sensitive)
YAML frontmatter is valid
description field is present

Model not switching

Verify settings.json has:

{
  "model": "opusplan"
}

8.7 KiB Raw Blame History