feat: Language-Agnostic Global CLAUDE.md with TypeScript Auditor by dean0x · Pull Request #2 · dean0x/devflow

dean0x · 2025-10-16T22:37:50Z

🎯 Overview

This PR implements a language-agnostic global CLAUDE.md and specialized TypeScript auditor agent to maintain DevFlow's universal design philosophy while preserving deep language-specific expertise where needed.

📦 What's Included

1. Language-Agnostic Global CLAUDE.md (`src/claude/CLAUDE.md`)

Problem: Previous global CLAUDE.md contained TypeScript-specific syntax, violating language-agnostic design.

Solution: Stripped TypeScript specifics, kept universal engineering concepts.

Contents:

✅ Role: Strict critic stance (no pleasing, challenge assumptions)
✅ Engineering Principles: Result types, DI, immutability (conceptually)
✅ Critical Anti-Patterns: NO FAKE SOLUTIONS, FAIL HONESTLY, LABEL EVERYTHING
✅ Code Quality Enforcement: Root cause analysis, not workarounds
✅ Type Safety: Language-agnostic best practices
✅ Architecture Documentation: Mandatory inline docs
✅ Security: Never commit secrets, validate at boundaries
✅ Pure Functions: Separate logic from I/O

Size: ~330 lines of precise, non-bloated instructions

2. TypeScript Auditor Agent (`src/claude/agents/devflow/audit-typescript.md`)

Problem: Need TypeScript-specific enforcement without polluting global config.

Solution: Specialized auditor with built-in detection logic.

Detection Strategy:

# Runs if:
- .ts/.tsx files changed OR
- tsconfig.json exists

# Skips if:
- No TS files changed AND
- No tsconfig.json

What It Audits:

Type safety configuration (strict mode, noImplicitAny)
any type usage (CRITICAL violations)
Unsafe type assertions without validation
@ts-ignore / @ts-expect-error abuse
Branded types for domain modeling
Discriminated unions with exhaustive checking
Immutability patterns (readonly, no mutations)
Result type pattern vs throwing
Naming conventions (PascalCase, camelCase, SCREAMING_SNAKE_CASE)
Dependency injection (no hard-coded deps)
Pure functions vs side effects

Output: CRITICAL/HIGH/MEDIUM/LOW severity with file:line references

3. Smart CLAUDE.md Mounting (`src/cli/commands/init.ts`)

Problem: Need to install global CLAUDE.md without overriding users' existing configs.

Solution: Smart mounting logic parallel to settings.json pattern.

Installation Scenarios

Scenario 1: Fresh Install (No Existing CLAUDE.md)

npx devflow-kit init

✅ Directly installs CLAUDE.md
✅ No prompts, no conflicts

Scenario 2: Existing CLAUDE.md (Safe Install)

npx devflow-kit init

✅ Preserves existing CLAUDE.md
✅ Installs as CLAUDE.devflow.md
✅ Shows merge instructions

Scenario 3: Force Override with Prompt

npx devflow-kit init --force

⚠️ Prompts for confirmation
✅ Backs up existing to .backup
✅ Can be cancelled (falls back to safe)

Scenario 4: Force Override with Auto-Approval

npx devflow-kit init --force -y

✅ No prompts (auto-approved)
✅ Backs up existing files
✅ Perfect for automation/CI/CD

New CLI Options

--force: Override existing settings.json and CLAUDE.md (prompts for confirmation)
-y, --yes: Auto-approve all prompts (use with --force)

4. Pre-commit/Pre-PR Integration

Updated Commands:

src/claude/commands/devflow/pre-commit.md
src/claude/commands/devflow/pre-pr.md

Changes:

Added audit-typescript to agent orchestration
Automatic conditional execution (no manual config)
Integrated into review document templates
Clear indicators when skipped (not applicable)

Pre-commit Audits (6 total):

audit-security
audit-typescript (conditional)
audit-performance
audit-architecture
audit-tests
audit-complexity

Pre-PR Audits (8-9 total):

All core audits
audit-typescript (conditional)
audit-database (conditional)

🧪 Testing

All scenarios tested locally:

✅ Scenario 1: Fresh Install

No existing files
Direct installation
No prompts or warnings

✅ Scenario 2: Existing Files

Preserved existing CLAUDE.md
Created CLAUDE.devflow.md
Showed merge instructions

✅ Scenario 3: Force with Prompt Decline

Showed warning message
Prompted for confirmation
Accepted cancellation ("n" input)
Fell back to safe install

✅ Scenario 4: Force with Auto-Approval

No prompts with -y flag
Backed up existing files
Installed DevFlow versions
Showed appropriate warnings

✅ Scenario 5: Custom Content Preservation

Created custom CLAUDE.md
Force installed
Verified backup contains custom content
Verified main file has DevFlow content

🎁 Benefits

Language-Agnostic Design

✅ Global CLAUDE.md works for TypeScript, Python, Go, Rust, Java, etc.
✅ Concepts, not syntax
✅ Maintains universal design philosophy

Specialized Expertise

✅ TypeScript rules enforced where applicable
✅ Deep language-specific knowledge preserved
✅ Automatic detection (no manual config)

Extensible Pattern

✅ Easy to add audit-python, audit-go, audit-rust
✅ Each auditor has built-in detection logic
✅ Graceful degradation (skips if not applicable)

Safe by Default

✅ Never overwrites without permission
✅ User control over global configuration
✅ Clear instructions for manual merge
✅ Reversible operations (backup files)

Automation-Friendly

✅ --force -y for scripts/CI/CD
✅ No interactive prompts when needed
✅ Exit codes for automation

📊 File Changes

New Files

src/claude/CLAUDE.md (332 lines) - Language-agnostic global instructions
src/claude/agents/devflow/audit-typescript.md (275 lines) - TypeScript auditor

Modified Files

src/cli/commands/init.ts (+120 lines) - Smart CLAUDE.md mounting
src/claude/commands/devflow/pre-commit.md (+9 lines) - TS auditor integration
src/claude/commands/devflow/pre-pr.md (+12 lines) - TS auditor integration

Total: 5 files changed, 801 insertions(+), 29 deletions(-)

🔄 Migration Path

For Existing Users

Option 1: Keep Existing Config

Run npx devflow-kit init
DevFlow CLAUDE.md saved to CLAUDE.devflow.md
Manually merge sections you want
Keep your existing CLAUDE.md

Option 2: Replace with DevFlow Config

Run npx devflow-kit init --force -y
Your original backed up to CLAUDE.md.backup
DevFlow version now active
Can restore anytime: cp ~/.claude/CLAUDE.md.backup ~/.claude/CLAUDE.md

Option 3: Start Fresh

Delete existing ~/.claude/CLAUDE.md
Run npx devflow-kit init
Clean DevFlow installation

🚀 Next Steps

Future Language-Specific Auditors

Following the same pattern:

audit-python - Python best practices

Black formatting, type hints (mypy)
PEP 8 compliance
Virtual environment management

audit-go - Go conventions

gofmt, golint compliance
Error handling patterns
Goroutine safety

audit-rust - Rust best practices

Clippy lints
Ownership patterns
Result/Option types

audit-sql - Database best practices

Query optimization
Injection prevention
Index usage

✅ Checklist

Language-agnostic CLAUDE.md created
TypeScript auditor agent implemented
Smart mounting logic with --force and -y flags
Pre-commit integration
Pre-PR integration
All scenarios tested locally
Build succeeds
Documentation updated in commit message
Follows DevFlow's design philosophy

🤖 AI-Generated

This PR was developed with AI assistance following DevFlow's own best practices.

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

## Summary Implements a language-agnostic global CLAUDE.md and specialized TypeScript auditor to maintain universal design while preserving language-specific expertise. ## Changes ### 1. Language-Agnostic Global CLAUDE.md - Created `src/claude/CLAUDE.md` with language-neutral engineering principles - Stripped TypeScript-specific syntax, kept universal concepts - Covers Result types, DI, immutability, pure functions (conceptually) - Includes critical anti-patterns (NO FAKE SOLUTIONS, FAIL HONESTLY) - Code quality enforcement (root cause analysis, not workarounds) - ~330 lines of precise, non-bloated global instructions ### 2. TypeScript Auditor Agent - Created `src/claude/agents/devflow/audit-typescript.md` - Conditional execution: runs only if .ts/.tsx files changed OR tsconfig.json exists - Built-in detection logic (gracefully skips non-TS projects) - Audits: type safety config, any usage, type assertions, branded types, discriminated unions, immutability, Result types, naming conventions, dependency injection, pure functions - Outputs: CRITICAL/HIGH/MEDIUM/LOW severity with file:line references ### 3. Smart CLAUDE.md Mounting - Updated `src/cli/commands/init.ts` with intelligent mounting logic - **Fresh install**: Directly installs CLAUDE.md (no conflicts) - **Existing file**: Preserves user's CLAUDE.md, creates CLAUDE.devflow.md - **--force flag**: Prompts for confirmation, backs up existing files - **-y flag**: Auto-approves prompts (for automation) - Parallel implementation to settings.json (consistent UX) ### 4. Pre-commit/Pre-PR Integration - Updated `src/claude/commands/devflow/pre-commit.md` - Updated `src/claude/commands/devflow/pre-pr.md` - Added audit-typescript to agent orchestration - Automatic conditional execution (no manual config needed) - Integrated into review document templates ## Key Features ### Smart Mounting - No existing CLAUDE.md → direct install - Existing CLAUDE.md → install as .devflow.md with merge instructions - Force override → backup to .backup, install DevFlow version - Clear instructions for all scenarios ### TypeScript Detection ```bash # Runs if: - .ts/.tsx files changed OR - tsconfig.json exists # Skips if neither condition met ``` ### Safety - Never overwrites without permission - Always backs up before force override - Clear warnings about what --force does - Reversible operations (backup files) ## Testing All scenarios tested locally: - ✅ Fresh install (no existing files) - ✅ Safe install (existing files preserved) - ✅ Force with prompt decline (falls back to safe) - ✅ Force with -y (auto-approved, backed up) - ✅ Custom content preservation verified ## Benefits 1. **Language-Agnostic**: Global CLAUDE.md works for any language 2. **Specialized Expertise**: TypeScript rules enforced where applicable 3. **Extensible Pattern**: Easy to add audit-python, audit-go, etc. 4. **Safe by Default**: User control over global configuration 5. **Automation-Friendly**: --force -y for scripts/CI/CD 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

…ions, async operations Code Quality Improvements: - Extract shared utilities to src/cli/utils/ (eliminated 65 lines of duplication) - Created paths.ts with getInstallationPaths(), path validation, env var security - Created git.ts with async getGitRoot() using promisified exec - Both init.ts and uninstall.ts now use shared utilities Security & Reliability: - Fixed TOCTOU race conditions with atomic file operations ('wx' flag) - settings.json, CLAUDE.md, .claudeignore now use exclusive create - Added environment variable path validation (CLAUDE_CODE_DIR, DEVFLOW_DIR) - Validates absolute paths, warns if outside home directory Performance: - Replaced execSync with async exec (non-blocking git operations) - Eliminated redundant git root detection (was called twice) - All file operations now async throughout the codebase CI/CD Compatibility: - Added TTY detection for interactive prompts - Falls back to default scope in non-interactive environments - Clear messaging when non-TTY detected Documentation: - Added comprehensive CHANGELOG entry for v0.5.0 - Documented all fixes, improvements, and breaking changes - Migration notes for existing users Tested: - User scope installation: ✓ - Local scope installation: ✓ - TTY detection and fallback: ✓ - Auto-detection uninstall: ✓ - Atomic file operations: ✓ - All async operations: ✓ Closes code review issues #2, #4, #5, #6 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

…vements (#16) * feat: add installation scope support (global vs local) Adds --scope option to init command allowing users to choose between: - Global scope: install to ~/.claude/ (user-wide, all projects) - Local scope: install to git-root/.claude/ (project-only) Features: - Interactive prompt when --scope not provided (defaults to global) - New getInstallationPaths() function for scope-aware directory resolution - Git root detection with security validation - For local scope: creates .claude/ and .devflow/ in git repository root - For local scope: automatically adds directories to .gitignore - Updated output messages to indicate installation scope and paths - Comprehensive README documentation with examples Implementation: - getGitRoot(): Detects git repository root with validation - getInstallationPaths(scope): Returns paths based on scope - For global: uses existing ~/.claude/ and ~/.devflow/ - For local: uses <git-root>/.claude/ and <git-root>/.devflow/ - Skip Claude Code detection for local scope (create directory instead) Testing: - Global scope: Verified existing behavior maintained - Local scope: Successfully tested in devflow repository - Both scopes create all components correctly Use cases: - Global: Personal development across all projects - Local: Team projects where DevFlow should be project-specific - Local: CI/CD environments with project-scoped configuration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: rename "global" scope to "user" for clarity Changes all references from "global" to "user": - TypeScript types: 'global' | 'local' → 'user' | 'local' - CLI option: --scope <global|local> → --scope <user|local> - Interactive prompt: "Choose scope (global/local)" → "Choose scope (user/local)" - Output messages: "global" → "user" - README documentation: "Global Scope" → "User Scope" Rationale: "user" is clearer and more precise than "global" - "user scope" = user-wide installation (~/.claude/) - "local scope" = project-specific installation (git-root/.claude/) All functionality remains the same, only naming improved. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: add scope support to uninstall command Enhanced uninstall command to support both user and local scopes: Features: - Auto-detects installed scopes (user and/or local) if --scope not specified - --scope option: user, local, or both - Uninstalls from user scope (~/.claude/, ~/.devflow/) - Uninstalls from local scope (git-root/.claude/, git-root/.devflow/) - Clear output showing which scope is being uninstalled - Handles cases where DevFlow installed in multiple scopes Auto-detection logic: - Checks ~/.claude/commands/devflow/ for user scope - Checks git-root/.claude/commands/devflow/ for local scope - If both found, uninstalls from both with notification - If none found, exits with helpful message Usage examples: - devflow uninstall (auto-detects and uninstalls from all found scopes) - devflow uninstall --scope user (explicit user scope only) - devflow uninstall --scope local (explicit local scope only) - devflow uninstall --scope both (force uninstall from both) Testing: - Verified local scope uninstall removes git-root/.claude/commands/devflow/ - Verified directories properly cleaned up - Verified error handling for non-git repositories 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: remove "both" option from uninstall, auto-detect is default Simplified uninstall command: - Removed --scope both option (excessive) - Default behavior (no --scope): auto-detect and uninstall from all found scopes - --scope user: uninstall from user scope only - --scope local: uninstall from local scope only Rationale: Default should be smart and do the right thing automatically. Users who want specific scope can use --scope flag. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: simplify settings/CLAUDE.md installation - never override Simplified file installation behavior: - Never override or rename existing files - Always install adjacent files (settings.devflow.json, CLAUDE.devflow.md) - User manually merges desired changes into their existing files Changes: - Removed complex backup/rename logic (managed-settings.json) - Removed --force and -y options (no longer needed) - Removed forceOverride logic and prompts - Simplified to simple exists check: install as .devflow.* if exists Installation behavior now: - settings.json exists? → Install as settings.devflow.json - settings.json missing? → Install as settings.json - CLAUDE.md exists? → Install as CLAUDE.devflow.md - CLAUDE.md missing? → Install as CLAUDE.md Final message shows clear merge instructions: - Review settings.devflow.json and merge statusLine config - Review CLAUDE.devflow.md and adopt desired practices Benefits: - Much simpler code (~80 lines removed) - Never touches user's existing files - Clear instructions for manual merge - No complex state management - No backup/restore logic needed 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: address code review issues - extract utils, fix race conditions, async operations Code Quality Improvements: - Extract shared utilities to src/cli/utils/ (eliminated 65 lines of duplication) - Created paths.ts with getInstallationPaths(), path validation, env var security - Created git.ts with async getGitRoot() using promisified exec - Both init.ts and uninstall.ts now use shared utilities Security & Reliability: - Fixed TOCTOU race conditions with atomic file operations ('wx' flag) - settings.json, CLAUDE.md, .claudeignore now use exclusive create - Added environment variable path validation (CLAUDE_CODE_DIR, DEVFLOW_DIR) - Validates absolute paths, warns if outside home directory Performance: - Replaced execSync with async exec (non-blocking git operations) - Eliminated redundant git root detection (was called twice) - All file operations now async throughout the codebase CI/CD Compatibility: - Added TTY detection for interactive prompts - Falls back to default scope in non-interactive environments - Clear messaging when non-TTY detected Documentation: - Added comprehensive CHANGELOG entry for v0.5.0 - Documented all fixes, improvements, and breaking changes - Migration notes for existing users Tested: - User scope installation: ✓ - Local scope installation: ✓ - TTY detection and fallback: ✓ - Auto-detection uninstall: ✓ - Atomic file operations: ✓ - All async operations: ✓ Closes code review issues #2, #4, #5, #6 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: bump version to 0.5.0 Release 0.5.0 with installation scope support and smart uninstall detection Major Features: - Two-tier installation strategy (user-wide vs project-specific) - Interactive scope selection with clear descriptions - Smart uninstall with automatic scope detection - Environment variable path validation for security - TTY detection for CI/CD compatibility 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Dean Sharon <deanshrn@gmain.com> Co-authored-by: Claude <noreply@anthropic.com>

dean0x merged commit dd39766 into main Oct 16, 2025

dean0x deleted the feature/global-claude-md branch October 16, 2025 22:49

dean0x mentioned this pull request Oct 24, 2025

feat: Installation scope support (user/local) with code quality improvements #16

Merged

dean0x mentioned this pull request Mar 14, 2026

feat: Wave 2 — project knowledge system (decisions + pitfalls) #140

Closed

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Language-Agnostic Global CLAUDE.md with TypeScript Auditor#2

feat: Language-Agnostic Global CLAUDE.md with TypeScript Auditor#2
dean0x merged 1 commit intomainfrom
feature/global-claude-md

dean0x commented Oct 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

dean0x commented Oct 16, 2025

🎯 Overview

📦 What's Included

1. Language-Agnostic Global CLAUDE.md (src/claude/CLAUDE.md)

2. TypeScript Auditor Agent (src/claude/agents/devflow/audit-typescript.md)

3. Smart CLAUDE.md Mounting (src/cli/commands/init.ts)

Installation Scenarios

New CLI Options

4. Pre-commit/Pre-PR Integration

🧪 Testing

✅ Scenario 1: Fresh Install

✅ Scenario 2: Existing Files

✅ Scenario 3: Force with Prompt Decline

✅ Scenario 4: Force with Auto-Approval

✅ Scenario 5: Custom Content Preservation

🎁 Benefits

Language-Agnostic Design

Specialized Expertise

Extensible Pattern

Safe by Default

Automation-Friendly

📊 File Changes

New Files

Modified Files

🔄 Migration Path

For Existing Users

🚀 Next Steps

Future Language-Specific Auditors

✅ Checklist

🤖 AI-Generated

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

1. Language-Agnostic Global CLAUDE.md (`src/claude/CLAUDE.md`)

2. TypeScript Auditor Agent (`src/claude/agents/devflow/audit-typescript.md`)

3. Smart CLAUDE.md Mounting (`src/cli/commands/init.ts`)