Smith - Swift Architecture Enforcement System

The construction police for Swift development. Smith enforces architectural discipline and build health throughout your entire development lifecycle.

What is Smith?

Smith is the enforcement agent in the Smith Tools ecosystem. It's not permissive. It's not flexible about rules. It validates code against strict architectural standards and ensures build quality.

Smith's Philosophy: Code quality isn't negotiable. Builds shouldn't hang. Architecture is discipline.

---

Quick Start

Installation (30 seconds)

cd /Volumes/Plutonian/_Developer/Smith\ Tools/Smith
./install.sh

This installs:

• ✅ Smith CLI (smith)
• ✅ Smith Claude Code skill
• ✅ Integration with build tools

First Use

# Analyze your project
smith analyze /path/to/project
# Validate TCA architecture with AI-optimized analysis
smith validate /path/to/project --level=critical --format=json
# Comprehensive architectural analysis
smith validate /path/to/project --level=comprehensive --format=summary
# Use in Claude Code# Type: "@smith validate my code"

---

How to Use Smith

1. Explicit Invocation in Claude Code (Primary)

Always explicitly invoke Smith for analysis and diagnostics:

"@smith validate my TCA reducer"
"@smith check my code against composition rules"
"@smith why is my build hanging?"
"@smith should I use workspace or project?"

2. Proactive Build Interception (Secondary)

Smith automatically intercepts when you run build commands:

xcodebuild -workspace MyApp.xcworkspace -scheme MyApp
# Smith detects → validates → warns of issues → recommends piping to tools
swift build
# Smith detects → validates project type → offers analysis

When interception happens, Smith:

1. Detects project type (workspace/project/package/swift)
2. Validates command matches project type
3. Warns of issues (e.g., using .xcodeproj when .xcworkspace exists)
4. Recommends piping to analysis tools for detailed output

3. Build Monitoring Tools

For detailed build analysis and recovery:

# Swift builds with analysis
swift build 2>&1| smith parse --format json
# Xcode analysis and recovery
smith xcode analyze
smith xcode monitor --hang-detection
# Package analysis
smith dependencies --metrics

4. Command Line Analysis

For automation and CI/CD:

smith analyze /path/to/project
smith validate /path/to/project --level=critical
smith validate /path/to/project --level=comprehensive
smith optimize

---

What Smith Validates

TCA Rules (Rules 1.1-1.5)

Smith enforces strict rules for The Composable Architecture:

Rule	Validates
1.1	Monolithic features (State >15 props, Actions >40 cases)
1.2	Proper dependency injection
1.3	Code duplication
1.4	Unclear organization
1.5	Tightly coupled state

Build Health

Smith monitors your build for:

• Build hangs with root cause analysis
• Type inference explosions
• Dependency conflicts
• DerivedData issues
• Memory pressure problems

Code Quality

Smith detects:

• Deprecated patterns (.@State in reducers, WithViewStore)
• Anti-patterns (hard-wired dependencies, circular imports)
• Testability issues
• Documentation gaps

---

Directory Structure

Smith/
├── README.md ← You are here
├── START-HERE.md ← Quick start guide
├── ARCHITECTURE.md ← Design philosophy
├── Makefile ← Build orchestration
├── install.sh ← Installation script
│
├── agent/
│ └── smith.md ← Agent definition
│
├── skills/
│ └── skill-smith/ ← Claude Code skill
│ ├── skill/SKILL.md
│ ├── patterns/ ← Swift patterns
│ └── platforms/ ← Platform guides
│
├── cli/ ← Smith CLI source
│ ├── Package.swift
│ └── Sources/
│
├── validation/ ← Validation rules
│ ├── Package.swift
│ └── Sources/
│
├── scripts/ ← Analysis scripts
│ ├── smith-smart-builder.sh
│ └── validate-syntax.sh
│
└── resources/
└── trigger-phrases.txt

---

Smith's Four Operational Phases

Phase 1: Package Setup

Tool: smith dependencies

Analyzes package dependencies, detects conflicts, identifies version issues.

swift package dump-package | smith dependencies --format json

Phase 2: Build Monitoring

Tools: smith parse

Real-time monitoring with hang detection, bottleneck identification, progress tracking.

swift build 2>&1| smith parse --format json

Phase 3: Code Review

Tools: smith, smith-skill, smith-validation

AI-optimized architectural validation against TCA rules, anti-pattern detection, pattern guidance with progressive intelligence.

smith validate /path/to/project --level=critical --format=json
smith validate /path/to/project --level=standard --format=summary
smith validate /path/to/project --level=comprehensive --format=json
# or use Smith skill in Claude Code

Phase 4: Build Recovery

Tool: smith xcode

Smart rebuild strategies, intelligent diagnostics, recovery recommendations.

smith xcode rebuild --smart-strategy
smith xcode diagnose --detailed

---

Smith's Attitude

Smith is not flexible about its standards:

✅ Smith Will:

• Give exact error locations
• Explain why rules matter
• Provide concrete fixes
• Suggest code examples
• Help diagnose build issues
• Give confidence scoring

❌ Smith Won't:

• Accept workarounds
• Make exceptions
• Suggest unsound designs
• Ignore architectural debt
• Accept unclear code
• Be permissive

---

Integration with Maxwell

Smith and Maxwell are complementary:

Aspect	Maxwell	Smith
Role	Oracle/Teacher	Police/Enforcer
Purpose	"How should I write this?"	"Is this correct?"
When	Before/during implementation	After implementation
Approach	Knowledge-based	Rules-based

Workflow:

Maxwell teaches pattern → You implement → Smith validates

---

Key Commands

CLI Commands

# Comprehensive analysis
smith analyze /path/to/project
# AI-optimized TCA validation with progressive intelligence
smith validate /path/to/project --level=critical --format=json
smith validate /path/to/project --level=standard --format=summary
smith validate /path/to/project --level=comprehensive --format=json
# Performance suggestions
smith optimize
# Project type detection
smith detect
# Build status
smith status

Build Monitoring

# Monitor Swift builds with hang detection
swift build 2>&1| smith parse --format json
swift build 2>&1| smith monitor --eta
# Analyze SPM dependencies
swift package dump-package | smith dependencies --format json
# Monitor Xcode builds
smith xcode monitor --hang-detection
smith xcode rebuild --smart-strategy

Diagnostics

# Diagnose build issues
smith xcode diagnose --detailed
# Analyze SPM conflicts
smith dependencies --conflicts
# Check environment
smith environment

---

Documentation

Document	Read For
START-HERE.md	Quick start and common tasks
ARCHITECTURE.md	Design philosophy and phases
agent/smith.md	Smith agent definition
skills/skill-smith/skill/SKILL.md	Claude Code skill reference
skills/skill-smith/patterns/AGENTS-AGNOSTIC.md	Swift patterns and best practices

---

Installation Methods

Method 1: Script (Easiest)

./install.sh

Method 2: Make

make install

Method 3: Homebrew (Coming Soon)

brew tap elkraneo/tap
brew install smith

---

How Smith Fits Into Your Workflow

┌─────────────────────────────────────────┐
│ Your Swift Development Workflow │
├─────────────────────────────────────────┤
│ │
│ 1. Setup Package │
│ ↓ smith dependencies → Check deps │
│ │
│ 2. Get Pattern Guidance │
│ ↓ Maxwell → Learn pattern │
│ │
│ 3. Code Implementation │
│ ↓ Your code │
│ │
│ 4. Build with Monitoring │
│ ↓ smith parse → Real-time feedback │
│ │
│ 5. Code Review │
│ ↓ Smith → Architectural validation │
│ │
│ 6. Build Recovery (if needed) │
│ ↓ smith xcode → Smart recovery │
│ │
│ 7. Production Ready ✓ │
│ │
└─────────────────────────────────────────┘

---

Support and Extension

Getting Help

• Read START-HERE.md
• Check ARCHITECTURE.md
• Review agent/smith.md
• Use smith --help

Extending Smith

• Add validation rules in validation/
• Add patterns in skills/skill-smith/patterns/
• Add scripts in scripts/
• Update ARCHITECTURE.md

Reporting Issues

Issues in Smith Tools are tracked in the respective repositories:

• CLI/Skill issues: This repository
• Build tool issues: smith-parser
• Validation issues: smith-validation

---

Smith's Core Principles

1. Strict Standards - TCA rules aren't suggestions
2. Real-Time Enforcement - Catch problems early
3. Clear Communication - Know exactly what's wrong
4. Actionable Fixes - Get concrete solutions
5. No Exceptions - Rules apply always

---

What's Next?

1. Install Smith: ./install.sh
2. Read START-HERE.md: Get oriented
3. Try smith: smith analyze /path/to/project
4. Use Smith in Claude Code: "@smith validate my code"
5. Monitor your builds: Pipe through smith parse

---

Summary

Smith is the architectural guardian of your Swift codebase. It operates throughout your development lifecycle, enforcing discipline and ensuring quality.

Smith is:

• ✅ Strict about architecture
• ✅ Thorough in build monitoring
• ✅ Clear in error reporting
• ✅ Helpful with solutions
• ❌ Not flexible about rules
• ❌ Not permissive about standards

Your code will be better for it.

---

Smith: The construction police for Swift development.