Latest Features in ag‑kit: Automated Manifests, Managed CLI, and Modern Documentation

The latest features in ag‑kit introduce a fully automated managed component registry, an enhanced CLI with filesystem tree synchronization, and a JSON‑driven documentation architecture built on Next.js 16.

The ag‑kit repository (vudovn/ag-kit) now functions as a complete Antigravity‑first AI‑agent engineering platform that unifies versioned agent definitions, command‑line tooling, and rich documentation. These latest features emphasize automation, release safety, and developer experience across three tightly integrated deliverables.

Automated Agent Registry with Dual‑Track Versioning

The .agents/ directory operates as a managed component registry that automatically maintains consistency across your agent definitions, skills, and workflows.

Automatic Manifest Generation

Any edit to a managed component triggers regeneration of three critical files: manifest.json, manifest.lock.json, and DEPENDENCY_GRAPH.md. This ensures that dependency graphs and cryptographic hashes never drift from source content. Trigger this generation manually using:

npm run generate:agents

Dual‑Track Versioning System

The registry implements CalVer for release tracking and SemVer for component contracts. The overall toolkit version lives in .agents/VERSION (CalVer format), while individual agents and skills declare their own SemVer bumps in front‑matter metadata. This separation allows precise dependency resolution while maintaining clear release milestones.

Strict Validation Pipeline

Before any commit or release, validate_kit.py (invoked via npm run check:agents) validates the entire toolkit structure. The Antigravity runtime layer—configured through hooks.json and the hooks/ directory—further enforces safety via scripts like .agents/hooks/validate-tool-call.mjs, which intercepts and blocks raw disk writes or other dangerous filesystem operations before execution.

Enhanced CLI with Managed Tree Synchronization

The @vudovn/ag-kit npm package requires Node ≥18 and provides sophisticated filesystem tracking through the new managed tree architecture.

Managed Tree Tracking

The core logic in cli/lib/managed-tree.js maintains a real‑time shadow of the component filesystem. This tree distinguishes between auto‑generated artifacts (like manifests) and hand‑edited source files, ensuring that regeneration commands only overwrite intended targets. Inspect the tree programmatically:

import { getManagedTree } from '@vudovn/ag-kit/lib/managed-tree.js';

const tree = getManagedTree();
console.log(tree);

Release Safety Testing

The cli/test/release-safety.test.js suite enforces version consistency across all three package.json files and the .agents/VERSION file. This prevents the common failure mode where the CLI, web documentation, and agent toolkit report different version numbers.

Installation and Usage

Install the toolkit into any project and synchronize components:

# Install into a target project

npx @vudovn/ag-kit add

# Validate toolkit consistency

npm run check:agents

Modern Documentation Architecture

The web/ directory contains a rebuilt documentation site using Next.js 16, MDX, and Tailwind 4, featuring a complete separation between build tooling and data sources.

JSON‑Catalog Data Layer

Rather than scanning the .agents/ folder at build time, the site consumes static JSON catalogs located in web/src/services/*.json, such as web/src/services/agents.json. This architecture enables faster builds and establishes clear data contracts between the toolkit definitions and their rendered documentation.

Webpack Build Pipeline

Due to MDX plugin constraints requiring string‑named plugin references, the project explicitly opts for Webpack over Turbopack. This configuration is set in web/next.config.ts to ensure reliable MDX processing.

Running the Documentation Site

Start the documentation server locally:

cd web
npm ci        # Install site‑specific dependencies

npm run dev   # Starts development server at http://localhost:3000

Summary

• Automated manifest generation creates manifest.lock.json, manifest.json, and DEPENDENCY_GRAPH.md automatically when you run npm run generate:agents.
• Dual‑track versioning combines CalVer for releases (stored in .agents/VERSION) with SemVer for individual component front‑matter.
• Managed tree synchronization via cli/lib/managed-tree.js prevents drift between source files and generated artifacts.
• Release‑safety tests ensure version alignment across all package.json files before publishing.
• JSON‑driven documentation in web/src/services/ enables faster builds and clearer data separation.

Frequently Asked Questions

How do I regenerate the agent manifests after making changes?

Run npm run generate:agents from the repository root, or use npx @vudovn/ag-kit generate:agents explicitly. This command triggers the managed component registry to rebuild manifest.json, manifest.lock.json, and DEPENDENCY_GRAPH.md based on the current state of the .agents/ directory.

What prevents version mismatches between the CLI and the agent toolkit?

The cli/test/release-safety.test.js suite automatically validates that version numbers in all three package.json files match the CalVer release declared in .agents/VERSION. This test runs during the release process and blocks publication if any divergence is detected.

Why does the documentation site use Webpack instead of Turbopack?

The MDX plugin requires string‑named plugin references that are incompatible with Turbopack's architecture. As configured in web/next.config.ts, the project explicitly opts for Webpack to ensure reliable MDX processing during the build pipeline.

How does ag‑kit block dangerous filesystem operations?

The Antigravity runtime loads hooks from the .agents/hooks/ directory, specifically validate-tool-call.mjs, which intercepts tool calls before execution. This hook validates operations against a safety policy that blocks raw disk writes and other potentially destructive filesystem modifications.

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