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

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 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, this layer is version-controlled by generated files like manifest.json and DEPENDENCY_GRAPH.md.

Toolkit-level bugs typically involve:

• Malformed workflow definitions in .agents/workflows/debug.md
• Missing dependencies in 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, 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, and the bugs.url field in 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

Web Documentation Layer

The Web docs site is a Next.js application in web/ that renders Markdown components. The source in 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
• 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
• 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 or .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 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
• Generated artifacts: For Toolkit bugs, include references to manifest.json or 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:

# 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 in your issue.

Safety Hook Validation Failure

To demonstrate a Toolkit-level safety issue:

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:

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) 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.
• 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 or .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.

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, 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). 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 versus .agents/workflows/debug.md), significantly speeding up reproduction and resolution.

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