// project-manifest.ts
export interface AgentProjectSpec {
  entryPoints: string[];
  testDirectories: string[];
  configFiles: string[];
  excludedPaths: string[];
  buildCommand: string;
  testCommand: string;
}

export const manifest: AgentProjectSpec = {
  entryPoints: ['src/index.ts', 'src/api/server.ts'],
  testDirectories: ['tests/unit', 'tests/integration'],
  configFiles: ['tsconfig.json', 'package.json', 'docker-compose.yml'],
  excludedPaths: ['node_modules', 'dist', '.git', 'coverage'],
  buildCommand: 'npm run build',
  testCommand: 'npm run test:ci'
};

// agent-router.ts
import { createHash } from 'crypto';

type TaskComplexity = 'light' | 'medium' | 'heavy';

interface RoutingConfig {
  complexity: TaskComplexity;
  maxTokens: number;
  budgetCap: number;
  prefer

redModel: string; }

const routingRules: Record<TaskComplexity, RoutingConfig> = { light: { complexity: 'light', maxTokens: 8000, budgetCap: 0.50, preferredModel: 'gpt-4o-mini' }, medium: { complexity: 'medium', maxTokens: 32000, budgetCap: 2.00, preferredModel: 'claude-3-5-sonnet' }, heavy: { complexity: 'heavy', maxTokens: 200000, budgetCap: 15.00, preferredModel: 'claude-3-7-sonnet' } };

export function resolveAgentRoute(taskDescription: string): RoutingConfig { const complexityScore = calculateComplexity(taskDescription); const tier: TaskComplexity = complexityScore < 0.4 ? 'light' : complexityScore < 0.7 ? 'medium' : 'heavy'; return routingRules[tier]; }

function calculateComplexity(description: string): number { const keywords = ['refactor', 'architecture', 'migration', 'database', 'security']; const matchCount = keywords.filter(k => description.toLowerCase().includes(k)).length; return Math.min(matchCount / keywords.length, 1); }

This routing layer prevents expensive models from handling trivial autocomplete requests while reserving high-capacity reasoning for structural changes. The budget cap acts as a hard stop, preventing runaway API sessions.

### Step 3: Enforce CI Validation Gates

Agent-generated code must never bypass validation. Integrate mandatory linting, type checking, and test execution into the commit pipeline.

```yaml
# .github/workflows/agent-validation.yml
name: Agent Output Validation
on:
  pull_request:
    paths:
      - 'src/**'
      - 'tests/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm run test:ci -- --coverage
      - name: Check coverage threshold
        run: |
          COVERAGE=$(node -e "console.log(require('./coverage/coverage-summary.json').total.lines.pct)")
          if (( $(echo "$COVERAGE < 80" | bc -l) )); then exit 1; fi

This pipeline ensures that autonomous modifications meet team standards before merging. Coverage thresholds and type safety checks act as non-negotiable gates, regardless of which agent produced the code.

Architecture Rationale

• Manifest-driven indexing reduces context window fragmentation. Agents spend tokens on relevant code rather than scanning excluded directories.
• Complexity-based routing aligns model capability with task requirements, optimizing cost efficiency without sacrificing reasoning depth.
• CI validation gates decouple agent execution from code quality. The tool that writes the code is irrelevant if the pipeline enforces standards.

Pitfall Guide

1. Context Window Overload

Explanation: Dumping entire repositories into an agent's context without filtering exhausts token limits and degrades reasoning accuracy. Fix: Implement project manifests, exclude build artifacts, and use semantic chunking to feed only relevant modules.

2. Unbounded API Costs

Explanation: Autonomous agents can trigger recursive tool calls or extended reasoning loops, causing session costs to spike unexpectedly. Fix: Enforce hard budget caps, implement session timeouts, and log token consumption per task.

3. Skipping CI Validation

Explanation: Trusting agent output without automated validation introduces type errors, broken imports, and failing tests into the main branch. Fix: Mandate linting, type checking, and test execution as pre-merge requirements. Never merge agent-generated code without pipeline approval.

4. Model Routing Blindness

Explanation: Using high-capability models for lightweight tasks wastes budget, while routing complex refactors to lightweight models produces shallow implementations. Fix: Classify tasks by complexity and map them to appropriate models using a routing configuration layer.

5. Ignoring Execution Transparency

Explanation: Black-box agents that execute changes without step-by-step logging make debugging and audit trails impossible. Fix: Prefer tools that expose execution plans, require approval before file modifications, and maintain detailed action logs.

6. Fragmented Toolchain Configuration

Explanation: Mixing terminal agents, IDE plugins, and CI bots without centralized instructions leads to inconsistent behavior and conflicting conventions. Fix: Centralize agent rules in a root-level configuration file that all tools reference, ensuring uniform formatting, testing standards, and commit conventions.

7. Over-Engineering Agent Prompts

Explanation: Vague or excessively verbose instructions cause agents to hallucinate requirements or ignore constraints. Fix: Use structured task templates with explicit inputs, expected outputs, file boundaries, and validation criteria.

Production Bundle

Action Checklist

• Define a project manifest that maps entry points, test directories, and excluded paths
• Implement a complexity-based routing layer to match tasks with appropriate models
• Set hard budget caps and session timeouts for all autonomous executions
• Enforce mandatory CI validation gates (lint, typecheck, test coverage)
• Centralize agent instructions in a root-level configuration file
• Require step-by-step execution logs and approval workflows for file modifications
• Audit token consumption weekly and adjust routing rules based on cost data
• Maintain a fallback manual review process for architectural changes

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Daily feature development with tight deadlines	Cursor or Windsurf IDE	Seamless UI integration, predictable subscription pricing, fast iteration	Fixed monthly cost ($15–20)
Complex multi-file refactoring or CI debugging	Claude Code	Superior reasoning depth, 200K context window, terminal-native execution	Variable API cost ($5–20/session)
Strict security/audit requirements or local model deployment	Cline	Open-source transparency, BYO model flexibility, step-by-step approval	Free + direct API/local compute costs
Budget-constrained teams needing proactive cross-file editing	Windsurf	Strong free tier, Cascade agent initiative, lower Pro tier pricing	Predictable subscription ($15/mo)
Enterprise compliance with centralized policy enforcement	Cursor Business or Copilot Enterprise	SSO, data residency controls, admin dashboards, audit logging	Enterprise licensing (custom pricing)

Configuration Template

// .agent-config.json
{
  "version": "1.0",
  "routing": {
    "light": {
      "maxTokens": 8000,
      "budgetCap": 0.50,
      "model": "gpt-4o-mini",
      "allowedActions": ["autocomplete", "inline-edit", "test-generation"]
    },
    "medium": {
      "maxTokens": 32000,
      "budgetCap": 2.00,
      "model": "claude-3-5-sonnet",
      "allowedActions": ["multi-file-edit", "refactor", "debug"]
    },
    "heavy": {
      "maxTokens": 200000,
      "budgetCap": 15.00,
      "model": "claude-3-7-sonnet",
      "allowedActions": ["architecture-change", "migration", "ci-fix"]
    }
  },
  "validation": {
    "requireLint": true,
    "requireTypeCheck": true,
    "minCoverage": 80,
    "blockMergeOnFailure": true
  },
  "transparency": {
    "logExecutionSteps": true,
    "requireApprovalBeforeWrite": true,
    "auditRetentionDays": 90
  }
}

Quick Start Guide

1. Initialize the manifest: Create a project-manifest.ts file in your repository root. Populate it with entry points, test directories, and excluded paths. Commit it to version control.
2. Deploy the routing layer: Add the complexity-based router to your development environment. Configure environment variables for API keys and budget thresholds.
3. Attach CI validation: Copy the GitHub Actions workflow to .github/workflows/agent-validation.yml. Adjust coverage thresholds and test commands to match your stack.
4. Configure agent behavior: Place .agent-config.json in the repository root. Ensure your IDE or terminal agent references it for routing, validation, and transparency rules.
5. Run a controlled test: Execute a medium-complexity task (e.g., adding a new API endpoint with tests). Verify that routing caps apply, CI gates trigger, and execution logs are generated. Adjust thresholds based on observed token consumption.

Agentic coding is no longer about choosing the smartest model. It is about architecting a workflow that balances reasoning depth, cost predictability, and validation rigor. The tools that survive production adoption will be the ones that integrate cleanly into existing pipelines, enforce transparent execution, and respect engineering constraints.