@sylphx/flow 3.2.0 → 3.4.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @sylphx/flow
 
+## 3.4.0 (2026-01-26)
+
+### ✨ Features
+
+- add /e2e-audit and business logic to /audit ([8e87e10](https://github.com/SylphxAI/flow/commit/8e87e10b49eaec37bb85c2677a0d8b1f602c5584))
+
+### ♻️ Refactoring
+
+- replace any with proper types in claude-code.ts ([d498d41](https://github.com/SylphxAI/flow/commit/d498d41dcae95cc9d98628f7860be2f48b7c342e))
+- replace any with proper types in target-utils.ts ([aebbf5d](https://github.com/SylphxAI/flow/commit/aebbf5dad8b4705664db1784127a4af0da8f8e5c))
+- remove unused securityMiddleware from security.ts ([a8efc37](https://github.com/SylphxAI/flow/commit/a8efc37fd06db866b5a08715a5141c19fbb3f54e))
+- add generics to jsonc.ts functions ([aac10af](https://github.com/SylphxAI/flow/commit/aac10afa3aa8cbd5c0319932c09d34e7a7ca4fec))
+- replace any with unknown in settings.ts ([8b76e17](https://github.com/SylphxAI/flow/commit/8b76e179ffc6f4533dbc5b58894cb1c0b468f83a))
+- replace any with unknown in prompt-helpers ([56e2b37](https://github.com/SylphxAI/flow/commit/56e2b375992232395ea58682ef7b04d396321b25))
+- remove unused FlowOptions properties ([273f521](https://github.com/SylphxAI/flow/commit/273f521a37e6b63f64b3fe6667f7489681bcb9fa))
+- remove unused async utility functions ([3b2c8fd](https://github.com/SylphxAI/flow/commit/3b2c8fdb6ea997e195a15e19bdd0ab931fae0f15))
+
+## 3.3.0 (2026-01-26)
+
+### ✨ Features
+
+- add /catchup command and architecture principles ([f5d6cd9](https://github.com/SylphxAI/flow/commit/f5d6cd9475aba40094f5c434fb962b7451632f1d))
+
+### 🐛 Bug Fixes
+
+- **builder:** simplify CLAUDE.md memory instructions ([fedd464](https://github.com/SylphxAI/flow/commit/fedd46482dc01ef5988d5552b9f7a7c8675c6240))
+
 ## 3.2.0 (2026-01-26)
 
 ### ✨ Features

package/assets/agents/builder.md

@@ -86,7 +86,7 @@ Vercel CLI, Neon CLI, GitHub CLI
 
 **Todos.** Track what needs to be done next. This is your memory of what to do.
 
-**CLAUDE.md** — Your persistent memory file. Update it when you discover:
+**CLAUDE.md** — Your persistent memory file. Write to it when you discover:
 - Project-specific commands (build, test, deploy, lint)
 - Environment setup (env vars, prerequisites, dependencies)
 - Architecture decisions and their reasoning
@@ -94,10 +94,8 @@ Vercel CLI, Neon CLI, GitHub CLI
 - Gotchas, workarounds, or non-obvious behaviors
 - Frequently referenced paths, configs, or resources
 
-This file is auto-attached every session. If you learn something important that future sessions should know, write it to CLAUDE.md immediately.
-
 **Recovery:**
-- Lost context? → Check `git log` for history, read CLAUDE.md
+- Lost context? → Check `git log` for history
 - Forgot next steps? → Check todos
 
 ## Issue Ownership
@@ -119,11 +117,18 @@ This file is auto-attached every session. If you learn something important that
 
 * No workarounds, no hacks — all implementations must meet state-of-the-art industrial standards
 * Single Source of Truth — one authoritative source for every state, behavior, and decision
-* Safety and strong typing — use tRPC for end-to-end type safety across all server communication
-* Observability: comprehensive logging, metrics, and tracing
-* Recoverability: systems must be swiftly restorable without data loss
+* Type safety — end-to-end type safety across all boundaries (tRPC, Zod, strict TypeScript)
+* Observability — logging, metrics, tracing; platform code must be observable by design
+* Recoverability — systems must be swiftly restorable without data loss
 * If automation exists for a task, manual execution is prohibited
 
+## Architecture Principles
+
+* **Pure functions** — no side effects, deterministic output; isolate impure code at boundaries
+* **Decoupling** — minimize dependencies between modules, use interfaces and dependency injection
+* **Modularisation** — single responsibility, clear boundaries, independent deployability
+* **Reusable composition** — build primitives that compose; prefer composition over inheritance
+
 ## Codebase
 
 * Zero tolerance: no TODOs, no dead code, no unused code

package/assets/slash-commands/audit.md

@@ -23,7 +23,22 @@ Scan the entire project for issues. Find problems, don't fix them. Open GitHub i
 - Inconsistent naming conventions
 - Outdated dependencies with known issues
 
-### 2. Architecture
+### 2. Business Logic Correctness
+
+**Code-correct ≠ Business-correct. Review business rules in the code.**
+
+- Region/locale logic: Does HK user see HK-specific data? (not China's 五險三金)
+- Currency handling: Correct currency for user's region?
+- Date/time: Timezone handling, week start day, date formats
+- Tax/legal: Region-specific rules applied correctly?
+- Permissions: Do access rules make business sense?
+- Calculations: Business formulas correct? (not just mathematically)
+- State machines: Valid business state transitions only?
+- Validation rules: Match real-world business constraints?
+- Default values: Sensible for the business context?
+- Edge cases: Business-impossible states prevented?
+
+### 3. Architecture
 - Circular dependencies
 - God objects/files doing too much
 - Tight coupling between modules
@@ -33,7 +48,7 @@ Scan the entire project for issues. Find problems, don't fix them. Open GitHub i
 - Missing SSOT (multiple sources of truth)
 - Inconsistent patterns across codebase
 
-### 3. UI/UX Issues
+### 4. UI/UX Issues
 - Confusing user flows
 - Missing loading states
 - Missing error states
@@ -45,7 +60,7 @@ Scan the entire project for issues. Find problems, don't fix them. Open GitHub i
 - Unclear CTAs or labels
 - Information overload
 
-### 4. Product Design
+### 5. Product Design
 - Unclear value proposition
 - Friction in core user journey
 - Missing onboarding guidance
@@ -55,7 +70,7 @@ Scan the entire project for issues. Find problems, don't fix them. Open GitHub i
 - Power user needs unmet
 - Beginner barriers too high
 
-### 5. Performance
+### 6. Performance
 - Slow page loads
 - Unnecessary re-renders
 - Large bundle sizes
@@ -64,7 +79,7 @@ Scan the entire project for issues. Find problems, don't fix them. Open GitHub i
 - Missing caching opportunities
 - Unoptimized images/assets
 
-### 6. Security
+### 7. Security
 - Exposed secrets or credentials
 - Missing input validation
 - XSS vulnerabilities
@@ -73,7 +88,7 @@ Scan the entire project for issues. Find problems, don't fix them. Open GitHub i
 - Missing rate limiting
 - Overly permissive CORS
 
-### 7. Developer Experience
+### 8. Developer Experience
 - Missing or outdated documentation
 - Unclear setup instructions
 - Flaky or missing tests

package/assets/slash-commands/catchup.md

@@ -0,0 +1,119 @@
+---
+name: catchup
+description: Deep dive into project history, direction, and implementation details
+---
+
+# Catchup: Understand the Project Deeply
+
+Get up to speed with the entire project — history, direction, and details.
+
+## Phase 1: Git History Analysis
+
+### Recent Commits
+```bash
+git log --oneline -50
+git log --oneline --since="1 week ago"
+git log --oneline --since="1 month ago" --until="1 week ago"
+```
+
+### Commit Patterns
+- What areas are being actively worked on?
+- What types of changes dominate? (feat, fix, refactor, docs)
+- Who are the contributors and what do they focus on?
+- Are there any recurring issues being fixed?
+
+### Recent Activity by Area
+```bash
+git log --oneline --all -- "src/components/*" | head -20
+git log --oneline --all -- "src/api/*" | head -20
+git log --oneline --all -- "src/lib/*" | head -20
+```
+
+## Phase 2: Development Direction
+
+### Read Project Documentation
+1. **PRODUCT.md** — Vision, goals, target users, success metrics
+2. **ARCHITECTURE.md** — Tech decisions, patterns, system design
+3. **CLAUDE.md** — Project-specific knowledge, commands, gotchas
+4. **README.md** — Setup, usage, contribution guidelines
+5. **CHANGELOG.md** — Release history, breaking changes
+
+### Identify Current Focus
+- What features are in progress?
+- What's the roadmap or next milestones?
+- Are there open issues or PRs that indicate direction?
+
+```bash
+gh issue list --state open --limit 20
+gh pr list --state open --limit 10
+```
+
+### Branch Analysis
+```bash
+git branch -a
+git log main..HEAD --oneline  # if on feature branch
+```
+
+## Phase 3: Deep Implementation Research
+
+### Codebase Structure
+```bash
+tree -L 2 -d src/  # or relevant directories
+```
+
+### Key Files to Understand
+- Entry points (main, index, app)
+- Configuration files (config, env, settings)
+- Core business logic
+- Database schema and migrations
+- API routes and handlers
+- Shared utilities and helpers
+
+### Dependency Analysis
+- What are the major dependencies?
+- Are there any custom abstractions worth understanding?
+- What patterns are consistently used?
+
+### Test Coverage
+- Where are tests located?
+- What's tested, what's not?
+- What do test failures tell us about the system?
+
+## Output
+
+### Executive Summary
+```
+Project: [name]
+Stage: [MVP / Growth / Mature]
+Focus: [current development focus]
+Health: [assessment based on commits, issues, code quality]
+```
+
+### Recent Activity (Last 2 Weeks)
+| Date | Area | Changes | Impact |
+|------|------|---------|--------|
+| ...  | ...  | ...     | H/M/L  |
+
+### Development Direction
+- **Current sprint/focus:** ...
+- **Next milestones:** ...
+- **Technical debt:** ...
+- **Opportunities:** ...
+
+### Key Findings
+1. ...
+2. ...
+3. ...
+
+### Recommendations
+- **Immediate:** ...
+- **Short-term:** ...
+- **Consider:** ...
+
+## Mindset
+
+* Be thorough — read everything, assume nothing
+* Connect the dots — understand WHY decisions were made
+* Think forward — where is this project heading?
+* Be critical — identify risks, gaps, opportunities
+* Document discoveries — update CLAUDE.md with important findings

package/assets/slash-commands/e2e-audit.md

@@ -0,0 +1,123 @@
+---
+name: e2e-audit
+description: Browser-based audit for business logic and product correctness
+---
+
+# E2E Audit: Browser-Based Product Validation
+
+Open a browser, walk through the product, find business logic and UX issues.
+
+**This is NOT about code correctness — code can be "correct" but business logic can be WRONG.**
+
+## Why E2E Audit?
+
+Static code analysis can't catch:
+- User selects "Hong Kong" but sees China's "五險三金"
+- Calendar showing Monday as week start for US users
+- Currency conversion using stale rates
+- Tax calculations wrong for specific regions
+- Permissions that make no business sense
+- Data inconsistency across related features
+
+## Process
+
+### 1. Launch Browser
+```
+mcp__playwright__browser_navigate - Go to product URL
+mcp__playwright__browser_snapshot - Get current page state
+```
+
+### 2. Walk Through User Journeys
+
+**Authentication:**
+- [ ] Signup flow (all fields, validations, error messages)
+- [ ] Login flow (remember me, forgot password)
+- [ ] Logout and session handling
+
+**Core Features:**
+- [ ] Primary user workflow end-to-end
+- [ ] Secondary features
+- [ ] Settings and configuration
+- [ ] Profile management
+
+**Edge Cases:**
+- [ ] Empty states
+- [ ] Error states
+- [ ] Boundary values (min/max)
+- [ ] Invalid inputs
+
+### 3. Test Business Logic
+
+**Region/Locale Consistency:**
+- Change user region → verify ALL related data updates
+- Currency, date format, language, legal requirements
+- Region-specific features show/hide correctly
+
+**Data Consistency:**
+- Related fields stay in sync
+- Calculations produce business-correct results
+- Aggregates match detail records
+
+**Business Rules:**
+- Permissions enforced correctly
+- Workflow states valid
+- Business constraints respected
+
+### 4. Document Issues
+
+For each issue found:
+```bash
+mcp__playwright__browser_take_screenshot  # Capture evidence
+```
+
+## Issue Categories
+
+### Business Logic Errors
+- Data doesn't match business expectations
+- Rules applied incorrectly for context
+- Cross-feature data inconsistency
+
+### UX Issues
+- Confusing user flows
+- Missing feedback
+- Unclear error messages
+- Accessibility problems
+
+### Visual Issues
+- Layout broken
+- Responsive issues
+- Inconsistent styling
+
+## Browser Tools Reference
+
+```
+mcp__playwright__browser_navigate    - Go to URL
+mcp__playwright__browser_snapshot    - Get page state (use this frequently)
+mcp__playwright__browser_click       - Click elements
+mcp__playwright__browser_fill_form   - Fill forms
+mcp__playwright__browser_type        - Type text
+mcp__playwright__browser_select_option - Select dropdown
+mcp__playwright__browser_take_screenshot - Capture evidence
+mcp__playwright__browser_press_key   - Keyboard input
+```
+
+## Output
+
+### Issues Found
+| # | Type | Description | Severity | Screenshot |
+|---|------|-------------|----------|------------|
+| 1 | Business Logic | HK user sees CN insurance | High | screenshot_1.png |
+| 2 | UX | No loading state on submit | Medium | screenshot_2.png |
+
+### Open GitHub Issues
+```bash
+gh issue create --title "[E2E] Brief description" --body "..." --label "e2e-audit"
+```
+
+## Mindset
+
+* **Code-correct ≠ Business-correct** — always verify business logic
+* Think like a real user, not a developer
+* Test the unhappy paths
+* Question every assumption
+* If something feels wrong, it probably is

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/flow",
-	"version": "3.2.0",
+	"version": "3.4.0",
 	"description": "One CLI to rule them all. Unified orchestration layer for AI coding assistants. Auto-detection, auto-installation, auto-upgrade.",
 	"type": "module",
 	"bin": {

package/src/commands/flow/types.ts

@@ -7,8 +7,6 @@ export interface FlowOptions {
   verbose?: boolean;
   dryRun?: boolean;
   sync?: boolean;
-  initOnly?: boolean;
-  runOnly?: boolean;
   repair?: boolean;
   upgrade?: boolean;
   upgradeTarget?: boolean;
@@ -23,7 +21,6 @@ export interface FlowOptions {
 
   // Smart configuration options
   selectProvider?: boolean;
-  selectAgent?: boolean;
   provider?: string;
 
   // Execution modes
@@ -35,5 +32,4 @@ export interface FlowOptions {
 
   // Loop mode
   loop?: number;
-  maxRuns?: number;
 }

package/src/core/functional/async.ts

@@ -35,33 +35,6 @@ export const fromPromise = async <T>(
   }
 };
 
-/**
- * Map over async result
- */
-export const mapAsync =
-  <T, U>(fn: (value: T) => U | Promise<U>) =>
-  async <E>(result: AsyncResult<T, E>): AsyncResult<U, E> => {
-    const resolved = await result;
-    if (isSuccess(resolved)) {
-      const mapped = await fn(resolved.value);
-      return success(mapped);
-    }
-    return resolved;
-  };
-
-/**
- * FlatMap over async result
- */
-export const flatMapAsync =
-  <T, U, E>(fn: (value: T) => AsyncResult<U, E>) =>
-  async (result: AsyncResult<T, E>): AsyncResult<U, E> => {
-    const resolved = await result;
-    if (isSuccess(resolved)) {
-      return fn(resolved.value);
-    }
-    return resolved;
-  };
-
 /**
  * Run async operation with timeout
  */
@@ -120,195 +93,9 @@ export const retry = async <T>(
   return failure(lastError);
 };
 
-/**
- * Run promises in parallel and collect results
- * Fails if any promise fails
- */
-export const allAsync = async <T>(promises: AsyncResult<T, AppError>[]): AsyncResult<T[]> => {
-  const results = await Promise.all(promises);
-
-  const values: T[] = [];
-  for (const result of results) {
-    if (isSuccess(result)) {
-      values.push(result.value);
-    } else {
-      return result;
-    }
-  }
-
-  return success(values);
-};
-
-/**
- * Run promises in parallel and collect all results
- * Returns both successes and failures
- */
-export const allSettledAsync = async <T>(
-  promises: AsyncResult<T, AppError>[]
-): Promise<Result<T, AppError>[]> => {
-  return Promise.all(promises);
-};
-
-/**
- * Run promises sequentially
- */
-export const sequenceAsync = async <T>(
-  promises: Array<() => AsyncResult<T, AppError>>
-): AsyncResult<T[]> => {
-  const values: T[] = [];
-
-  for (const promiseFn of promises) {
-    const result = await promiseFn();
-    if (isSuccess(result)) {
-      values.push(result.value);
-    } else {
-      return result;
-    }
-  }
-
-  return success(values);
-};
-
-/**
- * Race promises - return first to complete
- */
-export const raceAsync = async <T>(promises: AsyncResult<T, AppError>[]): AsyncResult<T> => {
-  return Promise.race(promises);
-};
-
 /**
  * Delay execution
  */
 export const delay = (ms: number): Promise<void> => {
   return new Promise((resolve) => setTimeout(resolve, ms));
 };
-
-/**
- * Run with concurrency limit
- */
-export const withConcurrency = async <T>(
-  tasks: Array<() => AsyncResult<T, AppError>>,
-  concurrency: number
-): AsyncResult<T[]> => {
-  const results: T[] = [];
-  const executing: Promise<void>[] = [];
-
-  for (const task of tasks) {
-    const promise = (async () => {
-      const result = await task();
-      if (isSuccess(result)) {
-        results.push(result.value);
-      } else {
-        throw result.error;
-      }
-    })();
-
-    executing.push(promise);
-
-    if (executing.length >= concurrency) {
-      await Promise.race(executing);
-      executing.splice(executing.indexOf(promise), 1);
-    }
-  }
-
-  try {
-    await Promise.all(executing);
-    return success(results);
-  } catch (error) {
-    return failure(toAppError(error));
-  }
-};
-
-/**
- * Memoize async function
- */
-export const memoizeAsync = <Args extends any[], T>(
-  fn: (...args: Args) => AsyncResult<T, AppError>,
-  keyFn?: (...args: Args) => string
-): ((...args: Args) => AsyncResult<T, AppError>) => {
-  const cache = new Map<string, AsyncResult<T, AppError>>();
-
-  return (...args: Args): AsyncResult<T, AppError> => {
-    const key = keyFn ? keyFn(...args) : JSON.stringify(args);
-
-    const cached = cache.get(key);
-    if (cached !== undefined) {
-      return cached;
-    }
-
-    const result = fn(...args);
-    cache.set(key, result);
-    return result;
-  };
-};
-
-/**
- * Debounce async function
- */
-export const debounceAsync = <Args extends any[], T>(
-  fn: (...args: Args) => AsyncResult<T, AppError>,
-  delayMs: number
-): ((...args: Args) => AsyncResult<T, AppError>) => {
-  let timeoutId: NodeJS.Timeout | null = null;
-  let latestArgs: Args | null = null;
-  let latestPromise: AsyncResult<T, AppError> | null = null;
-
-  return (...args: Args): AsyncResult<T, AppError> => {
-    latestArgs = args;
-
-    if (timeoutId) {
-      clearTimeout(timeoutId);
-    }
-
-    if (!latestPromise) {
-      latestPromise = new Promise((resolve) => {
-        timeoutId = setTimeout(async () => {
-          if (latestArgs) {
-            const result = await fn(...latestArgs);
-            resolve(result);
-            latestPromise = null;
-            timeoutId = null;
-          }
-        }, delayMs);
-      }) as AsyncResult<T, AppError>;
-    }
-
-    return latestPromise;
-  };
-};
-
-/**
- * Throttle async function
- */
-export const throttleAsync = <Args extends any[], T>(
-  fn: (...args: Args) => AsyncResult<T, AppError>,
-  limitMs: number
-): ((...args: Args) => AsyncResult<T, AppError>) => {
-  let lastRun = 0;
-  let pending: AsyncResult<T, AppError> | null = null;
-
-  return (...args: Args): AsyncResult<T, AppError> => {
-    const now = Date.now();
-
-    if (now - lastRun >= limitMs) {
-      lastRun = now;
-      return fn(...args);
-    }
-
-    if (!pending) {
-      pending = new Promise((resolve) => {
-        setTimeout(
-          async () => {
-            lastRun = Date.now();
-            const result = await fn(...args);
-            pending = null;
-            resolve(result);
-          },
-          limitMs - (now - lastRun)
-        );
-      }) as AsyncResult<T, AppError>;
-    }
-
-    return pending;
-  };
-};

package/src/targets/claude-code.ts

@@ -4,10 +4,16 @@ import path from 'node:path';
 import chalk from 'chalk';
 import { installToDirectory } from '../core/installers/file-installer.js';
 import { createMCPInstaller } from '../core/installers/mcp-installer.js';
-import type { AgentMetadata } from '../types/target-config.types.js';
+import type { AgentMetadata, FrontMatterMetadata } from '../types/target-config.types.js';
 import type { CommonOptions, MCPServerConfigUnion, SetupResult, Target } from '../types.js';
 import { getAgentsDir } from '../utils/config/paths.js';
-import { fileUtils, generateHelpText, pathUtils, yamlUtils } from '../utils/config/target-utils.js';
+import {
+  type ConfigData,
+  fileUtils,
+  generateHelpText,
+  pathUtils,
+  yamlUtils,
+} from '../utils/config/target-utils.js';
 import { CLIError } from '../utils/error-handler.js';
 import { sanitize } from '../utils/security/security.js';
 import {
@@ -17,6 +23,23 @@ import {
   transformMCPConfig as transformMCP,
 } from './shared/index.js';
 
+/** Claude Code configuration data with MCP servers */
+interface ClaudeCodeConfigData extends ConfigData {
+  mcpServers?: Record<string, unknown>;
+}
+
+/** Claude Code agent metadata */
+interface ClaudeCodeAgentMetadata {
+  name: string;
+  description: string;
+  model?: string;
+}
+
+/** Error with exit code from child process */
+interface ProcessExitError extends Error {
+  code: number | null;
+}
+
 /**
  * Claude Code target - composition approach with all original functionality
  */
@@ -86,8 +109,11 @@ export const claudeCodeTarget: Target = {
   /**
    * Read Claude Code configuration with structure normalization
    */
-  async readConfig(cwd: string): Promise<any> {
-    const config = await fileUtils.readConfig(claudeCodeTarget.config, cwd);
+  async readConfig(cwd: string): Promise<ClaudeCodeConfigData> {
+    const config = (await fileUtils.readConfig(
+      claudeCodeTarget.config,
+      cwd
+    )) as ClaudeCodeConfigData;
 
     // Ensure the config has the expected structure for Claude Code
     if (!config.mcpServers) {
@@ -258,7 +284,7 @@ Please begin your response with a comprehensive summary of all the instructions
           if (code === 0) {
             resolve();
           } else {
-            const error = new Error(`Claude Code exited with code ${code}`) as any;
+            const error = new Error(`Claude Code exited with code ${code}`) as ProcessExitError;
             error.code = code;
             reject(error);
           }
@@ -494,26 +520,29 @@ Please begin your response with a comprehensive summary of all the instructions
  * Convert OpenCode frontmatter to Claude Code format
  */
 function convertToClaudeCodeFormat(
-  openCodeMetadata: any,
+  openCodeMetadata: FrontMatterMetadata,
   content: string,
   sourcePath?: string
-): any {
+): ClaudeCodeAgentMetadata {
   // Use explicit name from metadata if available, otherwise extract from content or path
+  const metadataName = openCodeMetadata.name as string | undefined;
   const agentName =
-    openCodeMetadata.name || pathUtils.extractAgentName(content, openCodeMetadata, sourcePath);
+    metadataName || pathUtils.extractAgentName(content, openCodeMetadata, sourcePath);
 
   // Extract description from metadata or content
-  const description = openCodeMetadata.description || pathUtils.extractDescription(content);
+  const metadataDescription = openCodeMetadata.description as string | undefined;
+  const description = metadataDescription || pathUtils.extractDescription(content);
 
   // Only keep supported fields for Claude Code
-  const result: any = {
+  const result: ClaudeCodeAgentMetadata = {
     name: agentName,
     description: description,
   };
 
   // Only add model if it exists and is not 'inherit' (default)
-  if (openCodeMetadata.model && openCodeMetadata.model !== 'inherit') {
-    result.model = openCodeMetadata.model;
+  const model = openCodeMetadata.model as string | undefined;
+  if (model && model !== 'inherit') {
+    result.model = model;
   }
 
   // Remove unsupported fields that might cause issues

package/src/utils/config/settings.ts

@@ -49,12 +49,13 @@ export const loadSettings = async (
       const content = await fs.readFile(settingsPath, 'utf8');
       return JSON.parse(content) as ProjectSettings;
     },
-    (error: any) => {
+    (error: unknown) => {
       // File not found is not an error - return empty settings
-      if (error.code === 'ENOENT') {
+      const nodeError = error as { code?: string; message?: string };
+      if (nodeError.code === 'ENOENT') {
         return new Error('EMPTY_SETTINGS');
       }
-      return new Error(`Failed to load settings: ${error.message}`);
+      return new Error(`Failed to load settings: ${nodeError.message ?? 'Unknown error'}`);
     }
   ).then((result) => {
     // Convert EMPTY_SETTINGS error to success with empty object
@@ -89,7 +90,10 @@ export const saveSettings = async (
       // Write settings with proper formatting
       await fs.writeFile(settingsPath, `${JSON.stringify(settingsWithVersion, null, 2)}\n`, 'utf8');
     },
-    (error: any) => new Error(`Failed to save settings: ${error.message}`)
+    (error: unknown) => {
+      const nodeError = error as { message?: string };
+      return new Error(`Failed to save settings: ${nodeError.message ?? 'Unknown error'}`);
+    }
   );
 };
 

package/src/utils/config/target-utils.ts

@@ -2,9 +2,13 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import type { MCPServerConfigUnion, TargetConfig } from '../../types.js';
+import type { FrontMatterMetadata } from '../../types/target-config.types.js';
 import { readJSONCFile, writeJSONCFile } from '../files/jsonc.js';
 import { pathSecurity, sanitize } from '../security/security.js';
 
+/** Configuration data structure returned by readConfig */
+export type ConfigData = Record<string, unknown>;
+
 /**
  * File system utilities for targets
  */
@@ -17,7 +21,7 @@ export const fileUtils = {
     return pathSecurity.safeJoin(cwd, configFileName);
   },
 
-  async readConfig(config: TargetConfig, cwd: string): Promise<any> {
+  async readConfig(config: TargetConfig, cwd: string): Promise<ConfigData> {
     const configPath = fileUtils.getConfigPath(config, cwd);
 
     try {
@@ -40,7 +44,7 @@ export const fileUtils = {
     throw new Error(`Unsupported config file format: ${config.configFile}`);
   },
 
-  async writeConfig(config: TargetConfig, cwd: string, data: any): Promise<void> {
+  async writeConfig(config: TargetConfig, cwd: string, data: ConfigData): Promise<void> {
     const configPath = fileUtils.getConfigPath(config, cwd);
 
     await fs.mkdir(path.dirname(configPath), { recursive: true });
@@ -91,7 +95,7 @@ export const fileUtils = {
  * YAML utilities for targets
  */
 export const yamlUtils = {
-  async extractFrontMatter(content: string): Promise<{ metadata: any; content: string }> {
+  async extractFrontMatter(content: string): Promise<{ metadata: FrontMatterMetadata; content: string }> {
     const yamlRegex = /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/;
     const match = content.match(yamlRegex);
 
@@ -111,7 +115,7 @@ export const yamlUtils = {
     return { metadata: {}, content };
   },
 
-  async addFrontMatter(content: string, metadata: any): Promise<string> {
+  async addFrontMatter(content: string, metadata: FrontMatterMetadata): Promise<string> {
     if (!metadata || Object.keys(metadata).length === 0) {
       return content;
     }
@@ -136,14 +140,14 @@ export const yamlUtils = {
     return yamlRegex.test(content);
   },
 
-  async ensureFrontMatter(content: string, defaultMetadata: any = {}): Promise<string> {
+  async ensureFrontMatter(content: string, defaultMetadata: FrontMatterMetadata = {}): Promise<string> {
     if (yamlUtils.hasValidFrontMatter(content)) {
       return content;
     }
     return yamlUtils.addFrontMatter(content, defaultMetadata);
   },
 
-  async extractAgentMetadata(content: string): Promise<any> {
+  async extractAgentMetadata(content: string): Promise<FrontMatterMetadata> {
     const { metadata } = await yamlUtils.extractFrontMatter(content);
 
     if (typeof metadata === 'string') {
@@ -157,14 +161,14 @@ export const yamlUtils = {
     return metadata || {};
   },
 
-  async updateAgentMetadata(content: string, updates: any): Promise<string> {
+  async updateAgentMetadata(content: string, updates: Partial<FrontMatterMetadata>): Promise<string> {
     const { metadata: existingMetadata, content: baseContent } =
       await yamlUtils.extractFrontMatter(content);
     const updatedMetadata = { ...existingMetadata, ...updates };
     return yamlUtils.addFrontMatter(baseContent, updatedMetadata);
   },
 
-  validateClaudeCodeFrontMatter(metadata: any): boolean {
+  validateClaudeCodeFrontMatter(metadata: unknown): metadata is FrontMatterMetadata {
     if (typeof metadata !== 'object' || metadata === null) {
       return false;
     }
@@ -183,7 +187,7 @@ export const yamlUtils = {
     return true;
   },
 
-  normalizeClaudeCodeFrontMatter(metadata: any): any {
+  normalizeClaudeCodeFrontMatter(metadata: FrontMatterMetadata): FrontMatterMetadata {
     const normalized = { ...metadata };
 
     if (normalized.tools && typeof normalized.tools === 'string') {
@@ -276,7 +280,7 @@ export const pathUtils = {
     return kebabName || null;
   },
 
-  extractAgentName(content: string, metadata: any, sourcePath?: string): string {
+  extractAgentName(content: string, metadata: FrontMatterMetadata, sourcePath?: string): string {
     // Try to extract from file path first
     if (sourcePath) {
       const pathName = pathUtils.extractNameFromPath(sourcePath);
@@ -363,13 +367,13 @@ ${basePrompt}`;
 export const transformUtils = {
   defaultTransformAgentContent(
     content: string,
-    _metadata?: any,
+    _metadata?: FrontMatterMetadata,
     _sourcePath?: string
   ): Promise<string> {
     return Promise.resolve(content);
   },
 
-  defaultTransformMCPConfig(config: MCPServerConfigUnion): any {
+  defaultTransformMCPConfig(config: MCPServerConfigUnion): MCPServerConfigUnion {
     return config;
   },
 };

package/src/utils/files/jsonc.ts

@@ -21,16 +21,16 @@ function stripComments(content: string): string {
 /**
  * Read and parse JSONC file
  */
-export async function readJSONCFile(filePath: string): Promise<any> {
+export async function readJSONCFile<T = unknown>(filePath: string): Promise<T> {
   const content = await fs.readFile(filePath, 'utf-8');
   const stripped = stripComments(content);
-  return JSON.parse(stripped);
+  return JSON.parse(stripped) as T;
 }
 
 /**
  * Write JSONC file (writes as regular JSON)
  */
-export async function writeJSONCFile(filePath: string, data: any): Promise<void> {
+export async function writeJSONCFile<T>(filePath: string, data: T): Promise<void> {
   const content = JSON.stringify(data, null, 2);
   await fs.writeFile(filePath, content, 'utf-8');
 }

package/src/utils/prompt-helpers.ts

@@ -10,8 +10,12 @@ import { UserCancelledError } from './errors.js';
  * @param error - Error to check
  * @returns True if error represents user cancellation
  */
-export function isUserCancellation(error: any): boolean {
-  return error?.name === 'ExitPromptError' || error?.message?.includes('force closed');
+export function isUserCancellation(error: unknown): boolean {
+  if (error === null || typeof error !== 'object') {
+    return false;
+  }
+  const errorObj = error as { name?: string; message?: string };
+  return errorObj.name === 'ExitPromptError' || errorObj.message?.includes('force closed') === true;
 }
 
 /**
@@ -22,7 +26,7 @@ export function isUserCancellation(error: any): boolean {
  * @throws {UserCancelledError} If user cancelled the prompt
  * @throws Original error if not a cancellation
  */
-export function handlePromptError(error: any, message: string): never {
+export function handlePromptError(error: unknown, message: string): never {
   if (isUserCancellation(error)) {
     throw new UserCancelledError(message);
   }

package/src/utils/security/security.ts

@@ -489,46 +489,6 @@ export class RateLimiter {
   }
 }
 
-// ============================================================================
-// SECURITY MIDDLEWARE
-// ============================================================================
-
-/**
- * Security middleware for common patterns
- */
-export const securityMiddleware = {
-  /**
-   * Rate limiting middleware
-   */
-  rateLimit: (limiter: RateLimiter, getIdentifier: (req: any) => string) => {
-    return (req: any, res: any, next: any) => {
-      const identifier = getIdentifier(req);
-
-      if (!limiter.isAllowed(identifier)) {
-        return res.status(429).json({ error: 'Too many requests' });
-      }
-
-      next();
-    };
-  },
-
-  /**
-   * Input validation middleware
-   */
-  validateInput: (schema: z.ZodSchema, source: 'body' | 'query' | 'params' = 'body') => {
-    return (req: any, res: any, next: any) => {
-      try {
-        const data = req[source];
-        const validated = schema.parse(data);
-        req[source] = validated;
-        next();
-      } catch (error) {
-        return res.status(400).json({ error: 'Invalid input', details: error });
-      }
-    };
-  },
-};
-
 export default {
   securitySchemas,
   pathSecurity,
@@ -537,5 +497,4 @@ export default {
   envSecurity,
   cryptoUtils,
   RateLimiter,
-  securityMiddleware,
 };