@mrtrinhvn/ag-kit 1.0.0 → 1.0.2

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/package.json

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

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

@@ -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., `backend/app/services/` or `frontend/src/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 trading engine logic, see backend/app/services/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,6 +100,16 @@ 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..."