# How to Report a Bug in AG Kit: Navigating the Three-Layer Architecture

> Learn how to report a bug in AG Kit effectively. Understand the three-layer architecture and follow our guide to file detailed GitHub issues for quick resolution.

- Repository: [Vũ Đỗ/ag-kit](https://github.com/vudovn/ag-kit)
- Tags: how-to-guide
- Published: 2026-07-29

---

**To report a bug in AG Kit, identify whether the issue originates in the Toolkit (`.agents/`), CLI (`cli/`), or Web documentation (`web/`) layer, then file a detailed issue through the GitHub issue tracker with the appropriate label, environment specifications, and reproducible test case.**

AG Kit is a multi-layered repository maintained by vudovn that combines three runtime-compatible components: a Toolkit workspace defined by Markdown contracts, a CLI npm package (`@vudovn/ag-kit`), and a Next.js documentation site. Because the repository is split across these distinct layers, reporting bugs effectively requires mapping the failure to the correct subsystem and referencing specific source files like [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js) or `.agents/hooks/validate-tool-call.mjs` before filing.

## Understanding AG Kit's Three-Layer Architecture

Before you report a bug in AG Kit, you must understand which of the three architectural layers contains the defect. Each layer has distinct source locations, generated artifacts, and failure modes as defined in the repository structure.

### Toolkit Workspace Layer

The **Toolkit workspace** resides in the `.agents/` directory and contains Markdown-defined agents, skills, workflows, and safety rules that drive the Antigravity runtime. According to [`.agents/ARCHITECTURE.md`](https://github.com/vudovn/ag-kit/blob/main/.agents/ARCHITECTURE.md), this layer is version-controlled by generated files like [`manifest.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.json) and [`DEPENDENCY_GRAPH.md`](https://github.com/vudovn/ag-kit/blob/main/DEPENDENCY_GRAPH.md).

Toolkit-level bugs typically involve:
- Malformed workflow definitions in [`.agents/workflows/debug.md`](https://github.com/vudovn/ag-kit/blob/main/.agents/workflows/debug.md)
- Missing dependencies in [`manifest.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.json)
- Incorrect safety-hook rules in `.agents/hooks/validate-tool-call.mjs`

### CLI Package Layer

The **CLI package** is the `@vudovn/ag-kit` npm module located in `cli/`. As documented in [`cli/README.md`](https://github.com/vudovn/ag-kit/blob/main/cli/README.md), this layer scaffolds the toolkit into user projects and executes the managed-tree logic. The core merge algorithm lives in [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js), and the `bugs.url` field in [`cli/package.json`](https://github.com/vudovn/ag-kit/blob/main/cli/package.json) points to the canonical issue tracker.

CLI-level bugs include:
- Crashes during `ag-kit init` or `ag-kit update`
- Version-mismatch warnings
- Broken tree-merge logic in [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js)

### Web Documentation Layer

The **Web docs site** is a Next.js application in `web/` that renders Markdown components. The source in [`web/README.md`](https://github.com/vudovn/ag-kit/blob/main/web/README.md) indicates this layer uses Next.js 16 with TypeScript to serve human-readable documentation.

Web-level bugs manifest as:
- Broken navigation or docs rendering errors
- TypeScript compilation failures in components like [`web/src/app/docs/guide/examples/debugging/page.tsx`](https://github.com/vudovn/ag-kit/blob/main/web/src/app/docs/guide/examples/debugging/page.tsx)
- Failures during `npm run build:web`

## Identifying Which Layer Contains Your Bug

To properly report a bug in AG Kit, examine your stack trace or failing command to determine the origin:

- **Toolkit**: Errors from `npm run check:agents` or Antigravity safety hooks
- **CLI**: Failures during `ag-kit init` or `ag-kit update`, particularly referencing [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js)
- **Web**: Build errors from `npm run build:web` or navigation problems in the docs

## How to Report a Bug in AG Kit: Step-by-Step

Follow this workflow to ensure your issue contains the technical details maintainers need:

1. **Open the GitHub issue tracker** at `https://github.com/vudovn/ag-kit/issues/new?labels=bug`

2. **Select the appropriate label** based on the affected layer:
   - `toolkit` for `.agents/` issues
   - `cli` for `cli/` package issues  
   - `web` for documentation site issues

3. **Fill the template fields**:
   - **Title**: Concise summary including the layer, e.g., "CLI crashes on `ag-kit init` with Node 22"
   - **Description**: Expected behavior versus actual behavior
   - **Environment**: Node version (≥22 required), OS, Python version (≥3.10), and Antigravity workspace version
   - **Steps to reproduce**: Exact commands and flags executed
   - **Affected files**: Repository paths from the stack trace (e.g., [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js) or [`.agents/workflows/debug.md`](https://github.com/vudovn/ag-kit/blob/main/.agents/workflows/debug.md))
   - **Observed logs**: Console output captured with `--verbose` flags or build logs

4. **Attach diagnostic output**:
   - For CLI issues: Run with `--verbose` and capture the full trace
   - For Toolkit issues: Run `node .agents/hooks/validate-tool-call.mjs` with test input
   - For Web issues: Capture the output from `npm run build:web`

5. **Submit and monitor** for maintainer questions regarding the specific subsystem.

## Required Information for AG Kit Bug Reports

Effective bug reports in this repository require specific technical documentation:

- **Reproducible test case**: The exact command sequence that triggers the failure, such as `npx @vudovn/ag-kit init` in an empty directory
- **Source file references**: Exact paths like `.agents/hooks/validate-tool-call.mjs` or [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js) that appear in stack traces
- **Environment specifications**: Node.js version (run `node -v` to verify v22.x.x), operating system, and relevant dependency versions from [`package.json`](https://github.com/vudovn/ag-kit/blob/main/package.json)
- **Generated artifacts**: For Toolkit bugs, include references to [`manifest.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.json) or [`DEPENDENCY_GRAPH.md`](https://github.com/vudovn/ag-kit/blob/main/DEPENDENCY_GRAPH.md) if the check agents command fails

## Common Bug Scenarios and Code Examples

### CLI Initialization Crash

When `ag-kit init` fails with a manifest-related error, capture the environment and stack trace:

```bash

# Verify Node 22+ is installed

node -v   # → v22.x.x

# Run the init command

mkdir my-app && cd my-app
npx @vudovn/ag-kit init   # ← Note the crash location in cli/lib/managed-tree.js

```

Include the error message referencing [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js) in your issue.

### Safety Hook Validation Failure

To demonstrate a Toolkit-level safety issue:

```bash
printf '%s' '{"tool_args":{"CommandLine":"rm -rf /"}}' \
  | node .agents/hooks/validate-tool-call.mjs

```

If this outputs anything other than `BLOCKED by AG Kit` with exit code 1, the safety hook in `.agents/hooks/validate-tool-call.mjs` has a bug.

### Web Build Compilation Error

For documentation site issues:

```bash
cd web
npm ci
npm run build:web

```

Attach the resulting TypeScript compilation errors and reference the specific `.tsx` file paths (e.g., [`web/src/app/docs/guide/examples/debugging/page.tsx`](https://github.com/vudovn/ag-kit/blob/main/web/src/app/docs/guide/examples/debugging/page.tsx)) mentioned in the build log.

## Summary

- **AG Kit** consists of three distinct layers: Toolkit (`.agents/`), CLI (`cli/`), and Web (`web/`), each with unique bug patterns, source files, and generated artifacts like [`manifest.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.json).
- **Identify the layer** by examining whether the error occurs during `npm run check:agents`, `ag-kit init`, or `npm run build:web` before you report a bug in AG Kit.
- **File issues** at `https://github.com/vudovn/ag-kit/issues` using labels `toolkit`, `cli`, or `web` to route to the correct subsystem.
- **Include specific files** like [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js) or [`.agents/workflows/debug.md`](https://github.com/vudovn/ag-kit/blob/main/.agents/workflows/debug.md) in your report to accelerate triage.
- **Provide environment details** specifying Node ≥22 and Python ≥3.10, along with reproducible commands and verbose logs.

## Frequently Asked Questions

### Where do I file a bug report for AG Kit?

File all bug reports through the GitHub issue tracker at `https://github.com/vudovn/ag-kit/issues/new?labels=bug`. The repository uses issue templates that automatically preserve required fields for environment details and reproduction steps. Select the appropriate label—`toolkit`, `cli`, or `web`—based on which layer exhibits the failure, as specified in the `bugs.url` field of [`cli/package.json`](https://github.com/vudovn/ag-kit/blob/main/cli/package.json).

### How do I know if my bug is in the Toolkit or CLI layer?

Check the command that triggered the error. If the failure occurs during `npm run check:agents` or involves Antigravity safety hooks, it is a **Toolkit** bug affecting files in `.agents/`. If the crash happens during `ag-kit init`, `ag-kit update`, or shows errors in [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js), it is a **CLI** bug. Build errors in the documentation site indicate **Web** layer issues.

### What information is required for a complete AG Kit bug report?

A complete report must include the Node.js version (≥22 required), Python version (≥3.10), exact commands used to reproduce the issue, and the specific source file paths from the stack trace (such as `.agents/hooks/validate-tool-call.mjs` or [`cli/package.json`](https://github.com/vudovn/ag-kit/blob/main/cli/package.json)). You should also attach verbose logs using the `--verbose` flag for CLI issues or the full build log for Web issues.

### Why does AG Kit require mapping bugs to specific layers before reporting?

Because AG Kit is architecturally split between a Markdown-driven Toolkit (`.agents/`), a Node.js CLI (`cli/`), and a Next.js Web layer (`web/`), each component has different maintainers, test suites, and fix procedures. Mapping a bug to the correct layer ensures the issue reaches the appropriate subsystem and references the correct source files (like [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js) versus [`.agents/workflows/debug.md`](https://github.com/vudovn/ag-kit/blob/main/.agents/workflows/debug.md)), significantly speeding up reproduction and resolution.