@mrtrinhvn/ag-kit 1.0.0 → 1.0.4

package/README.md

@@ -0,0 +1,47 @@
+# Antigravity Kit Core (`@mrtrinhvn/ag-kit`) 🚀
+
+A generic, institutional-grade AI programming framework for automating scaffolding, architecture, and coding directly inside your software projects. Inspired by the principles of `.agent` systems, carefully stripped of domain-specific constraints to adapt to any software development lifecycle.
+
+## 📦 Quick Install
+
+The best way to initialize the AG-Kit in a new project is using `npx`:
+
+```bash
+npx @mrtrinhvn/ag-kit init
+```
+
+## 🛠 Global Usage & Commands
+
+You can also install it globally if you frequently create new projects:
+
+```bash
+npm install -g @mrtrinhvn/ag-kit
+```
+
+Then use the provided CLI anywhere:
+
+| Command | Description |
+|---|---|
+| `ag-kit init` | Scaffolds the `.agent` framework (Agents, Skills, Workflows) into your current directory. |
+| `ag-kit update` | Pulls the latest rules and templates and safely overwrites the core `.agent` folders without breaking your custom `knowledge/` base. |
+| `ag-kit status` | Checks exactly which version of the AG-Kit is active in your current working directory. |
+
+## 🧠 What's Inside the Brain?
+
+Running `ag-kit init` injects the following core architecture into your project:
+
+- **`GEMINI.md`**: The supreme constitution (Tier 0 Rules) ensuring the Agent always thinks systematically, acts safely, and never hallucinates code.
+- **`agents/`**: Core personas taking specialized roles (e.g., `orchestrator`, `frontend-specialist`, `backend-specialist`, `debugger`).
+- **`skills/`**: Tactical operational algorithms spanning from `clean-code` and `tdd-workflow` to `python-patterns` and `nextjs-react-expert`.
+- **`workflows/`**: Pre-defined step-by-step instructions (slash commands) like `/create`, `/plan`, `/brainstorm`, and `/debug`.
+- **`scripts/`**: CI/CD automation checkers like `lint_runner.py` and `security_scan.py`.
+
+## ⚙️ How It Works
+The AG-Kit is designed to be injected into an AI IDE or a custom Agent workspace.
+1. The AI reads `GEMINI.md` first.
+2. It assumes the persona of the relevant specialist in `agents/`.
+3. It selectively loads specific techniques from `skills/` based on context.
+4. It continuously documents important technical learnings in `knowledge/`.
+
+---
+*Built with ❤️ to enforce Institutional-Grade Software Standards.*

package/bin/cli.js

@@ -24,10 +24,11 @@ function copyRecursiveSync(src, dest) {
   }
 }
 
+const pkg = require('../package.json');
 program
   .name('ag-kit')
   .description('Trí khôn Lập trình Phổ quát - AI Agent Initialization Framework')
-  .version('1.0.0');
+  .version(pkg.version);
 
 program.command('init')
   .description('Install .agent folder into your project')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrtrinhvn/ag-kit",
-  "version": "1.0.0",
+  "version": "1.0.4",
   "description": "Antigravity Kit Base Framework - Generic Agentic AI Programming Core",
   "main": "index.js",
   "bin": {

package/template/.agent/skills/cli-generator/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: cli-generator
+description: Meta-skill enabling the Agent to automatically convert local software, repositories, or APIs into structured CLI tools using HKUDS/CLI-Anything.
+---
+
+# CLI-Generator (Meta-Skill)
+
+> 🔴 **CRITICAL**: This is a Meta-Skill. It gives you (the AI Agent) the ability to forge your own tools to solve complex constraints.
+
+## When to Use
+
+Use this skill when:
+- The user asks you to interact with a complex local GUI software (e.g., GIMP, OBS).
+- You are working with a messy, undocumented local API or scripting repository that is too brittle to run manually via ad-hoc scripts.
+- You need a dedicated CLI tool to perform repetitive tasks reliably, but none exists.
+
+## The Forging Process
+
+When you decide you need a new CLI tool for a given `TARGET_DIR` (the source code of the application), follow exactly these steps:
+
+### 1. Install CLI-Anything (If not already installed)
+Check if `cli-anything` is available in your PATH. If not, install it globally:
+```bash
+pip install cli-anything
+```
+*(If the package is not on PyPI, clone `https://github.com/HKUDS/CLI-Anything` and run `pip install -e .`)*
+
+### 2. Run the Generator Pipeline
+Navigate to a neutral workspace or the target, and run the automated generation pipeline:
+```bash
+cli-anything --source /absolute/path/to/TARGET_DIR
+```
+*Note: This process analyzes the source code and generates the harness. It may take several minutes and uses the underlying LLM's API tokens.*
+
+### 3. Integrate the Forged Skill into `ag-kit`
+The pipeline will generate a new Python package (e.g., `cli-anything-targetname`) and automatically produce a `SKILL.md` file within its package directory (usually `cli_anything/<software>/skills/SKILL.md`).
+You MUST locate this generated `SKILL.md` and copy it into the user's `ag-kit` workspace:
+```bash
+mkdir -p .agent/skills/<targetname-cli>
+cp /path/to/generated/SKILL.md .agent/skills/<targetname-cli>/SKILL.md
+```
+
+### 4. Self-Update
+Once the new `SKILL.md` is in place, you (or any other agent using this repository like GravityClaw / Openclaw) will instantly possess the knowledge to use the newly forged CLI tool. Proceed to solve the user's original objective using the new tool natively.
+
+## Anti-Patterns
+- ❌ **Manual wrappers**: Do NOT try to manually write a CLI harness or wrappers if `cli-anything` can automate it perfectly.
+- ❌ **Token waste**: Do NOT run the generator repeatedly on the same source code. Generate the CLI once, store the `SKILL.md`, and reuse the tool.

package/template/.agent/skills/knowledge-management/SKILL.md

@@ -16,7 +16,7 @@ allowed-tools: Read, Write, Glob, Grep
 
 ### Mandatory Read Before Action
 Before interacting with any third-party API, database schema, or core system component, you **MUST** search the `.agent/knowledge/` directory for existing documentation. 
-*Example: Before coding a DNSE WebSocket feature, read `.agent/knowledge/integrations/dnse_api.md` to get the exact channels and payload structures.*
+*Example: Before coding a payment integration feature, read `.agent/knowledge/integrations/stripe_api.md` to get the exact webhooks and payload structures.*
 
 ### Mandatory Proactive Updates (Zero Prompting Rule)
 When you successfully:
@@ -52,3 +52,15 @@ When modifying a feature or fixing a bug, ask yourself:
 2. What UI component relies on this data?
 3. **Does this change make the current Knowledge Base outdated?** 
    - If YES, you **MUST** pause and update the relevant `.md` files in `.agent/knowledge/` right then and there. A working codebase with an outdated AI brain is a broken project.
+
+---
+
+## 3. 🗺️ HIERARCHICAL CONTEXT ROUTING (Local Memory)
+
+**PRINCIPLE:** Context should be scoped locally to reduce token bloat and prevent the AI from hallucinating across unrelated domains. Do not stuff all documentation into a monolithic global file.
+
+### Sub-Directory Contexts
+When working within a specific module (e.g., `packages/core/services/` or `apps/web/components/`), you should:
+1. **Check for Local Context:** Look for a `CONTEXT.md` or `README.md` file *within that specific directory* before starting work.
+2. **Context Routing:** Leave pointers in central documentation (like `.agent/knowledge/architecture.md`) that route the AI to these deep local files. (e.g., `-> For payment processing logic, see packages/core/billing/CONTEXT.md`).
+3. **Local Updates:** When making fundamental changes to a localized component, create or update its local `CONTEXT.md` instead of polluting the global knowledge base. Keep local context files under 100 lines.

package/template/.agent/skills/systematic-debugging/SKILL.md

@@ -100,11 +100,21 @@ grep -r "errorPattern" --include="*.ts"
 pm2 logs app-name --err --lines 100
 ```
 
+## 🛡️ Tool Use Guardian (Execution Protection)
+
+When executing long chains of tool calls (especially when searching, indexing, or scraping), you MUST act as a Guardian of the execution:
+1. **Pre-Call Validation:** Validate file paths and parameters before executing. Don't guess or hallucinate paths.
+2. **Failure Recovery:** If a tool fails (Timeout, Rate Limit, Truncated JSON), **DO NOT panic and restart from scratch**.
+   - *Truncated:* Use `view_file` with line ranges to fetch the rest.
+   - *Timeout:* Simplify the bash command or narrow the `grep_search` scope.
+   - *Error-as-200:* Always check tool output for disguised `{"error": ...}` messages before assuming success.
+3. **Checkpoints:** Maintain logical mental checkpoints. If Step 5 of a 10-step process fails, resume exactly at Step 5.
+
 ## Anti-Patterns
 
 ❌ **Random changes** - "Maybe if I change this..."
 ❌ **Ignoring evidence** - "That can't be the cause"
-❌ **Assuming Data/API is dead** - Concluding an API endpoint is removed or data is unavailable just because a simple test failed (e.g., testing outside trading hours). ALWAYS check official documentation or sample SDK code before declaring an API dead.
+❌ **Assuming Data/API is dead** - Concluding an API endpoint is removed or data is unavailable just because a simple test failed (e.g., testing outside of service hours or without proper auth). ALWAYS check official documentation or sample SDK code before declaring an API dead.
 ❌ **Assuming** - "It must be X" without proof
 ❌ **Not reproducing first** - Fixing blindly
 ❌ **Stopping at symptoms** - Not finding root cause