Performance Considerations for AG Kit: Optimizing Agent Workflows and CI Pipeline

AG Kit performance is determined by three architectural layers: the managed component registry (which impacts build times), file-system scanning behaviors in audit scripts, and the orchestration overhead of the performance-optimizer agent.

AG Kit is a Markdown-driven AI-agent engineering kit that structures specialist agents, skills, and workflows under the .agents/ directory. Understanding the performance considerations for AG Kit requires analyzing how the deterministic manifest generation, audit script implementations, and agent runtime environments interact to affect both local development velocity and CI pipeline efficiency.

The Three Architecture Layers Driving AG Kit Performance

Managed Component Registry and Manifest Generation

Every agent, skill, and workflow in AG Kit lives under the .agents/ directory and compiles into a deterministic manifest.json and DEPENDENCY_GRAPH.md. According to the repository's README.md, any edit to a managed component must be followed by npm run generate:agents to regenerate these files.

The cost of regeneration scales proportionally with the number of managed files. With approximately 47 skills currently in the registry and complex dependency graphs, the validation command npm run check:agents can consume significant CI resources. The generation logic resides in cli/lib/managed-tree.js, which traverses the entire managed tree to compute hashes and dependencies.

Performance-Profiling Skills and I/O Operations

The performance-profiling skill provides Lighthouse-based audits via scripts/lighthouse_audit.py and React/Next.js audits via scripts/react_performance_checker.py. These scripts scan the project tree to locate target files, making their glob patterns critical for performance.

As noted in CHANGELOG.md, earlier versions of the React audit script used Path.rglob('*.{ts,tsx}'), which fails silently in Python's pathlib when using brace expansion, resulting in zero matches and wasted CI cycles. The current implementation uses a dedicated _iter_files helper to correctly enumerate TypeScript files while explicitly ignoring generated directories like .next and dist to prevent unnecessary I/O.

Agent Orchestration Overhead

The performance-optimizer agent (defined in .agents/agent/performance-optimizer.md) coordinates profiling tasks by interpreting results and suggesting fixes. While the reasoning step is computationally cheap, invoking this agent via Antigravity slash commands introduces network latency that can dominate execution time compared to local CLI runs.

Critical Bottlenecks and How to Avoid Them

File-System Scanning Inefficiencies

The React performance checker originally relied on inefficient glob patterns that caused silent failures. As implemented in .agents/skills/nextjs-react-expert/scripts/react_performance_checker.py, the script now uses robust file iteration:

# Previous inefficient approach (would silently match zero files):

# Path.rglob('*.{ts,tsx}')

# Current optimized approach using _iter_files helper:

# Correctly locates .ts and .tsx files while excluding build artifacts

Generated Output Exclusion

Both Lighthouse and Next.js builds emit large folders (.next, dist). The audit scripts explicitly exclude these directories to maintain low memory and CPU usage. The CHANGELOG.md documents a specific fix: "Corrected React performance scanning to ignore generated .next output."

Dependency Graph Churn

Frequent addition or removal of skills triggers updates to the dependency graph. Each change necessitates running npm run check:agents, which can become expensive on resource-constrained CI machines. Consolidate related component changes into single commits to minimize regeneration cycles.

CLI vs Antigravity Runtime Differences

The @vudovn/ag-kit CLI requires Node.js ≥ 18 and executes locally with minimal overhead. However, when skills run inside the Antigravity runtime (requiring Node.js ≥ 22), network latency to the provider dominates execution time. Run heavyweight audits (full Lighthouse reports) locally before invoking remote agent orchestration.

Parallel Agent Overhead

The parallel-agents skill can launch multiple agents concurrently, but each consumes independent CPU resources. Use parallelization only when the performance gain from concurrent reasoning outweighs the orchestration overhead.

Practical Code Examples for Performance Optimization

Run the Lighthouse audit locally to avoid network latency:

python .agents/skills/performance-profiling/scripts/lighthouse_audit.py https://example.com

Execute the React/Next.js audit with proper file exclusion:

python .agents/skills/nextjs-react-expert/scripts/react_performance_checker.py /path/to/project

Validate manifest consistency in CI pipelines:

npm run generate:agents   # Re-creates manifest.json and DEPENDENCY_GRAPH.md

npm run check:agents      # Fails if managed components changed without regeneration

Summary

• Manifest generation scales with the number of managed components; batch changes to minimize npm run check:agents executions.
• File-system scanning requires proper glob handling; the _iter_files helper in react_performance_checker.py prevents silent I/O failures.
• Generated directories (.next, dist) must be excluded from audits to prevent wasteful processing.
• Runtime selection matters; use local CLI for heavy audits and reserve Antigravity runtime for orchestration that benefits from remote reasoning.
• Parallel execution adds overhead; use only when concurrent agent processing provides measurable benefits.

Frequently Asked Questions

Why does AG Kit require regenerating the manifest after every component change?

The deterministic manifest.json and DEPENDENCY_GRAPH.md ensure consistency across the managed component registry. According to the source code in cli/lib/managed-tree.js, this compilation step validates dependency relationships and file integrity, but incurs cost proportional to the number of files under .agents/ (currently around 47 skills).

How does the React performance checker avoid scanning build artifacts?

The script in .agents/skills/nextjs-react-expert/scripts/react_performance_checker.py explicitly excludes directories like .next and dist. As documented in CHANGELOG.md, this fix prevents the audit from wasting cycles on generated output, significantly reducing both execution time and memory usage.

Should I run performance audits locally or through the Antigravity runtime?

Run resource-intensive audits (Lighthouse reports, full project scans) locally using the CLI (@vudovn/ag-kit) with Node.js ≥ 18. The Antigravity runtime introduces network latency that can dominate execution time, making it suitable only for lightweight orchestration tasks or when distributed reasoning is specifically required.

What causes slow CI checks in AG Kit repositories?

Slow CI typically results from frequent npm run check:agents executions triggered by dependency graph churn. Each modification to skills or agents under .agents/ requires manifest regeneration. Consolidate multiple component changes into single commits to reduce validation overhead on CI machines with limited resources.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}