# How to Debug Issues with ag-kit: A Step-by-Step Troubleshooting Guide > Debug ag-kit issues effectively. Follow our step-by-step guide with built-in workflows, manifest regeneration, and validation checks to quickly resolve problems. - Repository: [Vũ Đỗ/ag-kit](https://github.com/vudovn/ag-kit) - Tags: how-to-guide - Published: 2026-07-29 --- **You can debug issues with ag-kit by executing the built-in debug workflow, regenerating the manifest with `npm run generate:agents`, and running the validation suite to identify schema violations or dependency graph mismatches.** ag-kit is an Antigravity-first AI-agent engineering kit maintained by vudovn that enforces strict safety hooks and generated dependency graphs across three logical layers. When you encounter failures—whether during local development or in CI—knowing how to debug issues with ag-kit requires understanding the interplay between the `.agents/` toolkit, the Node-based CLI, and the validation scripts. This guide covers the exact commands, source files, and diagnostic workflows you need to resolve errors quickly. ## Run the Built-In Debug Workflow The fastest way to start debugging is to execute the diagnostic workflow defined in the repository. This workflow runs a sequence of checks and prints a concise report of potential issues. Run the debug workflow using the CLI: ```bash npx ag-kit workflow run debug ``` If the command fails or you need to inspect the exact steps manually, open the workflow definition at [`.agents/workflows/debug.md`](https://github.com/vudovn/ag-kit/blob/main/.agents/workflows/debug.md). This file lists the specific validation commands and sequence that the Antigravity runtime expects. ## Regenerate and Verify the Manifest Most ag-kit failures stem from an out-of-sync manifest. Any change to agents, skills, workflows, rules, or schemas requires manifest regeneration to update the runtime's view of the toolkit. Regenerate the manifest files: ```bash npm run generate:agents ``` This executes [`.agents/scripts/generate_manifest.py`](https://github.com/vudovn/ag-kit/blob/main/.agents/scripts/generate_manifest.py), which rebuilds [`.agents/manifest.json`](https://github.com/vudovn/ag-kit/blob/main/.agents/manifest.json) and [`.agents/manifest.lock.json`](https://github.com/vudovn/ag-kit/blob/main/.agents/manifest.lock.json). After generation, verify that the lock file matches the manifest: ```bash git diff .agents/manifest.json .agents/manifest.lock.json ``` A mismatch between these files is a common cause of CI failures and runtime errors. ## Validate Toolkit Integrity The `check:agents` script runs three critical validations that catch schema violations, missing front-matter, and illegal hook definitions. Execute the full validation suite: ```bash npm run check:agents ``` This command performs three specific checks: - **Manifest integrity** – Ensures [`.agents/manifest.json`](https://github.com/vudovn/ag-kit/blob/main/.agents/manifest.json) matches [`.agents/manifest.lock.json`](https://github.com/vudovn/ag-kit/blob/main/.agents/manifest.lock.json) - **Dependency-graph consistency** – Compares the current state against [`.agents/DEPENDENCY_GRAPH.md`](https://github.com/vudovn/ag-kit/blob/main/.agents/DEPENDENCY_GRAPH.md) - **Python validation** – Executes [`.agents/scripts/validate_kit.py`](https://github.com/vudovn/ag-kit/blob/main/.agents/scripts/validate_kit.py) to flag schema violations and malformed component definitions If you need to run the Python validator directly for detailed output: ```bash python -m .agents.scripts.validate_kit ``` ## Test the CLI Implementation When the toolkit validates successfully but installation or update operations fail, the issue likely resides in the managed-tree logic. Run the complete CLI test suite: ```bash npm run test:cli ``` For targeted debugging of specific failures, run a single test file with verbose output: ```bash node --test --watch cli/test/managed-tree.test.js ``` The core logic for installing and updating the toolkit resides in [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js). Failing tests in `cli/test/` typically point to errors in how this module handles the `.agents/` directory structure. ## Inspect Antigravity Safety Hooks ag-kit enforces strict safety rules via hooks that block disallowed filesystem actions. If a command is unexpectedly blocked or fails with permission errors, inspect the hook implementation. Check the validation hook at `.agents/hooks/validate-tool-call.mjs`. This file implements the safety gate logic. To see detailed hook output during testing: ```bash node --test .agents/hooks/tests/antigravity.test.mjs -- --verbose ``` The hook outputs JSON to stdout when it rejects a tool call, helping you identify exactly which filesystem action was blocked and why. ## Review Architecture and CI Logs When debugging complex integration issues, consult the architecture documentation to understand component registration and dependency contracts. Read the high-level design at [`.agents/ARCHITECTURE.md`](https://github.com/vudovn/ag-kit/blob/main/.agents/ARCHITECTURE.md). This document explains how the toolkit components interact, which helps pinpoint whether a failure originates from a missing dependency edge or a schema mismatch. To replicate the exact CI environment locally, check the GitHub Actions workflow files: - [`.github/workflows/ci.yml`](https://github.com/vudovn/ag-kit/blob/main/.github/workflows/ci.yml) – Runs the validation suite and CLI unit tests - [`.github/workflows/antigravity.yml`](https://github.com/vudovn/ag-kit/blob/main/.github/workflows/antigravity.yml) – Executes the Antigravity "doctor" checks and hook tests Replicating these command sequences locally ensures your fixes will pass in the CI pipeline. ## Practical Debugging Examples ### Force a full diagnostic cycle ```bash # Pull latest changes git pull origin main # Run the debug workflow npx ag-kit workflow run debug # Regenerate and validate npm run generate:agents npm run check:agents ``` ### Debug a specific validation failure ```bash # Run only the Python validator with stack traces python .agents/scripts/validate_kit.py --verbose # Check specific manifest entries cat .agents/manifest.json | grep -A 5 "failed-component" ``` ### Test CLI changes iteratively ```bash # Watch mode for rapid iteration node --test --watch cli/test/managed-tree.test.js # Test the CLI binary directly node cli/bin/index.js workflow run debug ``` ## Summary - **Start with the debug workflow** using `npx ag-kit workflow run debug` to get a quick diagnostic report - **Regenerate manifests** after any toolkit change using `npm run generate:agents` to prevent lock-file mismatches - **Run `npm run check:agents`** to catch schema violations, dependency graph inconsistencies, and hook errors - **Test CLI logic** in [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js) using `node --test` when installation or update operations fail - **Inspect hooks** at `.agents/hooks/validate-tool-call.mjs` when safety rules block legitimate operations - **Reference [`.agents/ARCHITECTURE.md`](https://github.com/vudovn/ag-kit/blob/main/.agents/ARCHITECTURE.md)** to understand component interactions and dependency contracts ## Frequently Asked Questions ### Why does my CI fail after I edited an agent file? CI fails because ag-kit requires the generated manifest to stay synchronized with source files. Run `npm run generate:agents` after editing any file in `.agents/` to update [`.agents/manifest.json`](https://github.com/vudovn/ag-kit/blob/main/.agents/manifest.json) and [`.agents/manifest.lock.json`](https://github.com/vudovn/ag-kit/blob/main/.agents/manifest.lock.json), then commit both files. ### What does the "dependency graph mismatch" error mean? This error indicates that [`.agents/DEPENDENCY_GRAPH.md`](https://github.com/vudovn/ag-kit/blob/main/.agents/DEPENDENCY_GRAPH.md) is out of sync with the actual dependencies detected in your agents and skills. The validator compares the stored graph against the current component structure. Regenerate the manifest and run `npm run check:agents` to update the graph. ### How do I know if a safety hook is blocking my command? Check the output of `.agents/hooks/validate-tool-call.mjs`. When the hook blocks an operation, it logs a JSON object to stdout containing the blocked tool call and the rule that triggered the rejection. Run the hook tests with `--verbose` to see detailed output. ### Where is the source of truth for the debug workflow steps? The canonical debug workflow is defined in [`.agents/workflows/debug.md`](https://github.com/vudovn/ag-kit/blob/main/.agents/workflows/debug.md). This Markdown file contains the exact sequence of commands that `npx ag-kit workflow run debug` executes. Inspect this file manually if the CLI command fails to run.