james.bland
3f0786f1e7
`.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.
AI Development Scaffold
A comprehensive Claude Code configuration for professional software development with strict TDD enforcement, multi-language support, and cloud infrastructure patterns.
What's Included
- TDD Enforcement - Strict RED-GREEN-REFACTOR workflow with 80%+ coverage requirements
- Multi-Language Support - Python, TypeScript, Rust, Go, Java, C#
- Cloud Patterns - AWS, Azure, GCP infrastructure templates
- IaC - Terraform and Ansible best practices
- Testing - Unit, UI, and browser testing patterns (Playwright + Chrome MCP)
- Security - Automatic secret detection and blocking
- Model Strategy - Opus for planning, Sonnet for execution (
opusplan)
Quick Start
# 1. Clone this repo
git clone https://github.com/yourusername/ai-development-scaffold.git
# 2. Backup existing Claude config (if any)
mv ~/.claude ~/.claude.backup
# 3. Deploy
cp -r ai-development-scaffold/.claude/* ~/.claude/
chmod +x ~/.claude/hooks/*.sh
# 4. Verify
ls ~/.claude/
# Should show: CLAUDE.md, settings.json, agents/, skills/, hooks/
Documentation
See .claude/README.md for:
- Complete file structure
- Hook configuration (Claude hooks vs git hooks)
- Usage examples
- Customization options
- Troubleshooting
Agents Available
| Agent | Purpose |
|---|---|
@tdd-guardian |
TDD enforcement and guidance |
@code-reviewer |
Comprehensive PR review (uses Opus) |
@security-scanner |
Vulnerability and secrets detection |
@refactor-scan |
Refactoring assessment (TDD step 3) |
@dependency-audit |
Outdated/vulnerable package checks |
Skills Available
| Category | Skills |
|---|---|
| Languages | Python, TypeScript, Rust, Go, Java, C# |
| Infrastructure | AWS, Azure, GCP, Terraform, Ansible, Docker/K8s, Database, CI/CD |
| Testing | TDD, UI Testing, Browser Testing |
| Patterns | Monorepo, API Design, Observability |
Coverage Targets
| Layer | Target |
|---|---|
| Domain/Business Logic | 90%+ |
| API Routes | 80%+ |
| Infrastructure/DB | 70%+ |
| UI Components | 80%+ |
License
MIT