create-snowline-agents 1.0.0

package/AGENTS_TEMPLATE.md

@@ -0,0 +1,116 @@
+# Project Rules (CBT Master - Snowline Agent Ecosystem)
+
+- Before creating a new function, always define all variables that will be used first (to avoid *ReferenceError* or variables that have not been *destructured*).
+
+## 🛑 THE Snowline Agent CORE DIRECTIVES (MANDATORY)
+You (the AI Agent) are **STRICTLY FORBIDDEN** from using standard tools (such as \grep_search\, \cat\, \ls\, standard ESLint, or manually reading \package.json\) if there is a custom tool from the Snowline Agent ecosystem that can do it faster and save more tokens.
+
+**You MUST ALWAYS use the following Python scripts according to the need:**
+
+1. **Starting a Session / Analyzing Project (Deep Analyzer)**
+   - DO NOT read \package.json\ manually. 
+   - ALWAYS use: \python .agents/skills/deep_analyzer/analyzer.py\
+2. **Searching Code / Variables (Smart Search)**
+   - DO NOT use \grep_search\. 
+   - ALWAYS use: \python .agents/skills/smart_search/code_finder.py <dir> <keyword>\
+3. **Massive Code Editing (Smart Replace)**
+   - For cross-file edits, use: \python .agents/skills/smart_replace/replace_text.py <dir> <search> <replace>\
+4. **Reading Large Files (Selective Reader)**
+   - DO NOT read files > 300 lines entirely at once. 
+   - ALWAYS create a TOC first: \python .agents/skills/selective_reader/reader.py <file>\
+5. **Security & Bug Auditing (Project Guardian)**
+   - ALWAYS use: \python .agents/skills/project_guardian/guardian.py\
+6. **Finding Residues / Junk Files (Clean Sweeper)**
+   - ALWAYS use: \python .agents/skills/clean_sweeper/sweeper.py <dir>\
+7. **Extracting Project Info (Deep Analyzer)**
+   - ALWAYS use: \python .agents/skills/deep_analyzer/analyzer.py\
+8. **Debugging Crashes (Crash Decoder)**
+   - DO NOT read huge tracebacks. Save to \.txt\ and use: \python .agents/skills/crash_decoder/decoder.py <file>\
+9. **Creating New Files (Auto-Scaffolder)**
+   - ALWAYS generate boilerplate first: \python .agents/skills/auto_scaffolder/scaffolder.py <type> <name>\
+10. **Fixing Broken Imports (Smart Import Fixer)**
+    - ALWAYS use: \python .agents/skills/import_fixer/fixer.py <file> <import_string>\
+11. **Viewing Directory Trees (Smart Tree)**
+    - ALWAYS use: \python .agents/skills/smart_tree/scripts/tree_viewer.py <dir>\
+12. **Extracting Database Schema (DB Extractor)**
+    - ALWAYS use: \python .agents/skills/db_extractor/scripts/extractor.py <project_root_dir>\
+
+
+## 📖 Mandatory Reading Protocol (Selective Reader)
+
+**Primary Rule**
+Before reading the contents of ANY file (especially potentially large files like React components, utils, or files with complex logic), you MUST run the Selective File Reader to get the TOC (Table of Contents) FIRST, WITHOUT EXCEPTION and WITHOUT ASSUMPTION.
+
+This applies even if:
+- You feel the file is likely short or simple.
+- You feel familiar with the pattern/structure of similar files from previous tasks.
+- You are certain the file only contains a single function.
+
+Assumptions like these MUST NOT be used as an excuse to skip Selective Reader. Run it first, then decide your next steps based on the actual TOC output — not guesswork.
+
+**The ONLY Permitted Exceptions**
+You may skip Selective Reader ONLY if the following conditions are met:
+1. **Documented Technical Limitations**: Such as files with monolithic JSX components noted in the "Known Limitations" of the Selective Reader SKILL.md. In this case, you MUST still run Selective Reader first to view the TOC output. ONLY IF the TOC proves insufficiently detailed (as per the documented limitation) may you proceed to read manually with \iew_file\ for the unreached sections.
+2. **Proven Small Files via TOC**: If Selective Reader has already been run and the TOC proves the file is indeed short (e.g., under 50 lines), you do not need to run it again for the SAME file in the SAME task.
+
+These exceptions DO NOT serve as an excuse to skip at the beginning — exceptions only apply AFTER Selective Reader has been run and proven insufficient or small.
+
+**Strictly Forbidden**
+- Skipping Selective Reader because you "can guess" the file contents based on filename, patterns, or past experience.
+- Reading a file directly with \iew_file\ without running Selective Reader first, unless you can prove Selective Reader was already run for that same file in the current task.
+
+**When in Doubt**
+If you are unsure whether a situation qualifies as a valid exception, ALWAYS run Selective Reader first. It is cheaper than reading the full file, carrying no significant risk if it turns out unnecessary.
+
+## Live Progress Tracker (PLAN.md)
+- **MANDATORY**: For every significant task, you MUST maintain a \PLAN.md\ file in the root directory.
+- **Execution Rules**:
+  1. APPEND ONLY. Do not rewrite the whole file just to add a log entry.
+  2. Write concise, bulleted logs, not paragraphs.
+  3. **CRITICAL**: Before executing any command that MODIFIES files (like replace_text.py --apply), write your intended action in the "Waiting for User Approval" section and STOP for user approval.
+  4. Once a task is fully completed, archive the file to \plan_archive/PLAN_<date>_<task_name>.md\.
+
+## 🗣️ Communication Efficiency
+
+**Language Handling**
+1. The user writes instructions in Indonesian. If the instruction needs to be translated into English for technical purposes (English keyword-based search queries, variable/function names, commit messages, code comments, English documentation), perform the translation internally as part of your thought process — do not call any external translation tools/APIs.
+2. Do not translate back to the user unless requested. Simply use the internal translation results for technical purposes, and always reply to the user in Indonesian.
+
+**Reporting & Feedback Style**
+The goal is to save tokens and speed up communication. Apply the following rules to every report/feedback to the user:
+
+**Mandatory structure, in order:**
+1. What was done (1-2 sentences, without fluffy intros)
+2. Relevant proof/output (code snippets, terminal results, or concrete data — not a narrative summary)
+3. Questions or next steps (if any, max 1-2 options)
+
+**Prohibitions:**
+- No fluffy or excessive opening sentences ("I would be happy to...", "This is a very good decision...")
+- No excessive adjectives or self-praise regarding your own work ("extraordinary", "perfect", "professional", "sophisticated", "enterprise-grade", etc.)
+- Do not repeat the contents of the code/output that has already been displayed as a separate narrative sentence.
+- Do not explain things that were not asked, unless it is an important finding that carries risk (e.g., a new bug, potential data loss).
+
+**Additional Guidelines:**
+- Ideal length: routine reports (tool execution results, minor change confirmations) should be 3-6 lines. Reports for complex findings (bug investigations, multi-file analysis) can be longer, but must remain in the structured format above — no free-form narratives.
+- Emojis and decorative formatting: use sparingly as structure markers (✅ ⚠️ 🛡️), avoid using them as excessive decorations on every line.
+- Mandatory Tool Usage: ALWAYS use the custom Python tools (Deep Analyzer, Smart Search, Selective Reader) located in \.agents/skills/\ for analyzing the project or finding code, rather than manual commands or blind reading.
+## 🚀 Auto-Scaffolding for New Projects (Project Level)
+
+When starting a session in any project, evaluate the completeness of the \.agents\ ecosystem. If the \.agents\ folder is missing or incomplete (e.g., missing \knowledge\ architecture, \AGENTS.md\ rules, or \PLAN.md\ tracker), you MUST propose to auto-generate the complete ecosystem for the user.
+
+**The Complete Ecosystem Standard (Project Level):**
+1. **\AGENTS.md\**: Project-specific rules (copied from the global template) for local overrides.
+2. **\knowledge/\**: Architectural context generated by the Context Mapper tool.
+3. **\PLAN.md\**: Live progress tracker in the project root.
+*(Note: \skills\ is no longer needed at the project level because it is installed globally).*
+
+**Action Flow:**
+1. Check the project root for these 3 components.
+2. If any are missing, DO NOT ask via normal chat text. Instead, create an implementation_plan.md Artifact with RequestFeedback=true (this generates a clickable 'Proceed' button for the user).
+3. Include this exact summary in the artifact:
+   > [INFO] Dokumentasi ekosistem .agents di project ini belum lengkap. Klik 'Proceed' agar saya men-setup semuanya (Aturan Lokal, Peta Arsitektur, dan Tracker) sekarang.
+4. Once the user clicks Proceed, automatically create the folders, run Context Mapper to generate the knowledge files, and scaffold the \PLAN.md\ and \AGENTS.md\ files.
+## 🧠 Tech Lead Disciplines (Built-in)
+To maintain high code quality while remaining effortless for the user, the agent automatically applies these disciplines:
+1. **Implicit Grilling (No Guesswork)**: For complex feature requests, do not blindly guess edge cases (e.g., timeouts, null states, missing data). Ask 1-2 highly targeted questions to clarify the boundaries before writing code. Keep it brief and easy to answer.
+2. **Diagnostic Discipline (No Blind Fixes)**: When asked to fix a bug, DO NOT immediately suggest code changes based on error logs alone. First, ensure there is a clear feedback loop (a way to reproduce the error locally). If the error cannot be reproduced or tested, verify the logic first or ask the user for a reproduction step before writing the fix.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Usman Aziz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# ❄️ Snowline Agent Tools
+
+![Python](https://img.shields.io/badge/Python-3.x-blue.svg?logo=python&logoColor=white)
+![No Dependencies](https://img.shields.io/badge/Dependencies-Zero-brightgreen.svg)
+![License](https://img.shields.io/badge/License-MIT-green.svg)
+
+## 🚀 Quick Install (Project-Level)
+Make any project "AI-Ready" in seconds. Run one of these commands in your project's root folder to instantly install the Snowline Agent ecosystem. It will safely scaffold `.agents/skills`, `.agents/knowledge`, and your `PLAN.md` without affecting global system configs.
+
+**Option 1: Using NPM (Cross-Platform)**
+```bash
+npx create-snowline-agents
+```
+
+**Option 2: Using PowerShell (Windows)**
+```powershell
+irm https://raw.githubusercontent.com/UsmanAzizz/snowline-agent-tools/main/install.ps1 | iex
+```
+
+**Option 3: Using Bash/cURL (Mac/Linux)**
+```bash
+curl -sL https://raw.githubusercontent.com/UsmanAzizz/snowline-agent-tools/main/install.sh | bash
+```
+
+---
+
+A collection of simple, portable, and lightweight Python scripts specifically designed to guide AI coding assistants (like Gemini, Claude, or Aider) working within a repository.
+
+The main goal of this project is to **save LLM token usage** by preventing the AI from reading files blindly, as well as providing safety guardrails for automated file modifications.
+
+## 🏛️ Core Principles
+
+1. **Simple & Portable:** 100% pure Python (`os`, `re`, `json`). No `node_modules` required, no external executors like `ripgrep` needed. Just copy the scripts to your project and run them.
+2. **Token Efficient:** Terminal outputs are extremely concise. No useless long logs, only displaying crucial insights (`[FAIL]`, `[WARN]`) to prevent the AI from exhausting its context memory.
+3. **AI Prompt Bridge:** Each Python script doesn't just print data; it also returns a ready-to-use prompt sentence at the very last line, so users can instantly copy it to guide the AI.
+4. **Protection & Dry-Run:** Scripts that modify files MUST feature a dry-run preview mode by default and force the use of an `--apply` argument before actually altering files on disk.
+
+---
+
+## 🛠️ The Arsenal (10 Core Tools)
+
+The ecosystem is divided into three major categories: **Search & Modify**, **Audit & Analyze**, and **Workflow Helpers**.
+
+### Category 1: Search & Modify
+*These tools replace standard IDE search and regex-replace functions with AI-optimized alternatives.*
+
+#### 1. Smart Replace (`smart_replace/replace_text.py`)
+- **Function:** High-speed find-and-replace using pure Python regex.
+- **Why it's better:** It has built-in guardrails. By default, it runs a dry-run preview. It forces the user/AI to use the `--apply` flag to mutate files. When applying, it automatically creates backups in a `.backup_replace/` folder before overwriting, preventing catastrophic code loss.
+- **Example Output:**
+  ```text
+  [DRY-RUN MODE]
+  File: src/components/Button.jsx
+  - old: console.log("debug");
+  + new: // console.log("debug");
+  
+  [OK] Scan selesai (120 file dipindai). Menemukan 1 kecocokan.
+  💡 PROMPT UNTUK AI: "Berdasarkan hasil dry-run di atas, tolong jalankan ulang perintah tersebut dengan menambahkan flag --apply..."
+  ```
+
+#### 2. Smart Search (`smart_search/code_finder.py`)
+- **Function:** Context-aware code search.
+- **Why it's better:** Instead of just returning a single line like `grep`, it returns a clean block of code (strictly limited to 5 lines of context) so the AI understands the implementation instantly.
+- **Example Output:**
+  ```text
+  --- File: src/utils/api.js ---
+  42: export const fetchUser = async (id) => {
+  43:   const response = await axios.get(`/users/${id}`);
+  44:   return response.data;
+  45: }
+  ```
+
+#### 3. Smart Import Fixer (`import_fixer/fixer.py`)
+- **Function:** Automatically resolves broken relative imports.
+- **Why it's better:** If a file is moved, relative imports (like `../../services/api.js`) break. This tool searches the entire project for the missing file, calculates the correct relative path, and patches the file automatically.
+
+### Category 2: Audit & Analyze
+*These tools replace manual file reading and code reviews, saving massive amounts of AI tokens.*
+
+#### 4. Project Guardian (`project_guardian/guardian.py`)
+- **Function:** A holistic security and health auditor. 
+- **Why it's better:** Detects exposed credentials (passwords, API keys), validates `.gitignore` rules against active `.env` files, checks for broken relative imports, flags unused npm packages, and runs NPM audit—all in one command.
+- **Example Output:**
+  ```text
+  🛡️ PROJECT GUARDIAN AUDITOR 🛡️
+  --- MODULE 1: SECRET SCANNER ---
+  [FAIL] Potential credential leak in src/config/db.js line 12
+  
+  --- MODULE 2: ENV & GITIGNORE VERIFIER ---
+  [FAIL] File .env.development is missing from .gitignore!
+  ```
+
+#### 5. Clean Sweeper (`clean_sweeper/sweeper.py`)
+- **Function:** A project health and tech-debt scanner.
+- **Why it's better:** Finds leftover quarantine logs, temporary backup folders (like `AA/`, `old/`), massive commented-out code blocks, and `TODO/FIXME` tags.
+
+#### 6. Deep Analyzer (`deep_analyzer/analyzer.py`)
+- **Function:** The Project Profiler / X-Ray Scanner.
+- **Why it's better:** Automatically extracts the tech stack, core dependencies, file statistics, and available testing/linting commands directly from `package.json` or config files. 
+- **Example Output:**
+  ```text
+  [OK] Tech Stack Detected: Node.js, Vite (React/Vue)
+  [INFO] Available npm/yarn Commands:
+    - npm run start
+    - npm run test
+  [INFO] Core Dependencies: 55 runtime, 9 dev
+  ```
+
+#### 7. Selective Reader (`selective_reader/reader.py`)
+- **Function:** Table of Contents (TOC) Extractor for large files.
+- **Why it's better:** Uses Python regex heuristics to extract the skeleton (classes, functions, arrow functions) of JS/TS/Py files. Allows the AI to surgically read only the lines it needs.
+
+#### 8. Context Mapper (`context_mapper/context_mapper.py`)
+- **Function:** The Knowledge Catalog builder. 
+- **Why it's better:** Automatically generates `PROJECT_STRUCTURE.md` and `COMMON_PATTERNS.md` inside `.agents/knowledge/`. AI agents read these files first to instantly understand the project's architecture.
+
+### Category 3: Workflow Helpers
+*These tools assist the AI when actively writing or debugging code.*
+
+#### 9. Crash Decoder (`crash_decoder/decoder.py`)
+- **Function:** The Error Trace Analyzer.
+- **Why it's better:** Parses massive terminal crash logs, filters out irrelevant `node_modules` and internal node noise, and pinpoints the exact file and line in your source code that caused the crash.
+
+#### 10. Auto-Scaffolder (`auto_scaffolder/scaffolder.py`)
+- **Function:** The Pattern Generator. 
+- **Why it's better:** Instantly generates boilerplate files for React components or API routes following the project's standards, avoiding inconsistent manual coding.
+
+---
+
+## 🚀 Installation & Usage
+
+These tools are designed to run locally on your machine, callable by your AI agent or by yourself. **Python 3.x is the only requirement.**
+
+### Interactive Dashboard (For Humans)
+For human users, the easiest way to use the ecosystem is via the central dashboard:
+```bash
+python run_all.py
+```
+This will launch a CLI menu where you can select and run any of the 10 tools interactively.
+
+### AI Agent Workflow (For AI)
+Place these folders inside your project's workspace customizations directory (e.g., `.agents/skills/` at the root of your project). 
+
+Example commands your agent will run:
+```bash
+# Analyze the project stack
+python .agents/skills/deep_analyzer/analyzer.py
+
+# Auto Scaffold a React Component
+python .agents/skills/auto_scaffolder/scaffolder.py react "DataSiswa" "src/view/admin/data_siswa"
+
+# Project Guardian (Silent Mode)
+python .agents/skills/project_guardian/guardian.py --summary
+```
+
+## 🤝 Compatibility
+These tools were originally built and battle-tested within the Gemini (Antigravity IDE) ecosystem. However, they are highly portable and easily adaptable for **Claude Code**, **Aider**, or other CLI-based AI agents that support custom system prompts and bash execution.

package/auto_scaffolder/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: Auto-Scaffolder (Pattern Generator)
+description: Use this skill to automatically generate boilerplate code for new React components or API routes perfectly matching the project's standards.
+---
+
+## Instructions for AI Agent
+
+**When to use this skill:**
+- When the user asks you to "create a new page", "make a new component", or "add a new API route".
+- **NEVER use write_to_file to write a component from scratch manually.** Always generate the boilerplate first using this tool.
+
+**Command to run:**
+```powershell
+# For React Components
+python .agents/skills/auto_scaffolder/scaffolder.py react "MyComponent" "src/view/admin/my_feature"
+
+# For API Routes
+python .agents/skills/auto_scaffolder/scaffolder.py api "my_route" "src/backend/routes"
+```
+
+**Expected Behavior & Next Steps:**
+1. The tool will create the file instantly with proper imports and structure.
+2. Once generated, you can then use `replace_file_content` to inject the specific logic requested by the user into the generated boilerplate.

package/auto_scaffolder/scaffolder.py

@@ -0,0 +1,115 @@
+import os
+import sys
+
+if sys.stdout.encoding != 'utf-8':
+    sys.stdout.reconfigure(encoding='utf-8')
+
+REACT_TEMPLATE = """import React, { useState, useEffect } from 'react';
+
+const {name} = () => {
+    const [data, setData] = useState([]);
+    const [loading, setLoading] = useState(false);
+
+    useEffect(() => {
+        // Fetch data logic here
+    }, []);
+
+    return (
+        <div className="{name.lower()}-container">
+            <h2>{name} Component</h2>
+            {loading ? <p>Loading...</p> : <p>Content goes here.</p>}
+        </div>
+    );
+};
+
+export default {name};
+"""
+
+API_TEMPLATE = """const express = require('express');
+const router = express.Router();
+
+// GET endpoint
+router.get('/', async (req, res) => {
+    try {
+        // Logic here
+        res.status(200).json({ success: true, data: [] });
+    } catch (error) {
+        console.error(error);
+        res.status(500).json({ success: false, message: 'Server Error' });
+    }
+});
+
+// POST endpoint
+router.post('/', async (req, res) => {
+    try {
+        // Logic here
+        res.status(201).json({ success: true, message: 'Created' });
+    } catch (error) {
+        console.error(error);
+        res.status(500).json({ success: false, message: 'Server Error' });
+    }
+});
+
+module.exports = router;
+"""
+
+def generate_scaffold(file_type, name, target_dir, apply_mode):
+    print("🏗️ AUTO-SCAFFOLDER 🏗️")
+    print("=" * 60)
+    
+    if file_type.lower() not in ['react', 'api']:
+        print("[FAIL] Invalid type. Choose 'react' or 'api'.")
+        return
+        
+    if not os.path.exists(target_dir) and apply_mode:
+        os.makedirs(target_dir, exist_ok=True)
+        
+    if file_type.lower() == 'react':
+        filename = f"{name}.jsx"
+        content = REACT_TEMPLATE.replace("{name}", name).replace("{name.lower()}", name.lower())
+    else:
+        filename = f"{name.lower()}.js"
+        content = API_TEMPLATE
+        
+    filepath = os.path.join(target_dir, filename)
+    
+    if os.path.exists(filepath):
+        print(f"[FAIL] File {filename} already exists at {target_dir}!")
+        return
+        
+    if not apply_mode:
+        print("[DRY-RUN MODE] Auto-Scaffolder Preview")
+        print("=" * 50)
+        print(f"Target File: {filepath}")
+        print("--- Content Preview ---")
+        print(content)
+        print("=" * 50)
+        print("\n💡 PROMPT UNTUK AI (Copy-Paste ini):")
+        print(f'"Pratinjau berhasil. Silakan jalankan ulang perintah dengan tambahan flag --apply untuk membuat file {filename}."')
+    else:
+        try:
+            with open(filepath, 'w', encoding='utf-8') as f:
+                f.write(content)
+            print(f"[OK] Successfully generated {filename} at {target_dir}")
+            print("\n" + "=" * 60)
+            print("💡 PROMPT UNTUK AI (Copy-Paste ini):")
+            print(f'"Berdasarkan hasil Auto-Scaffolder di atas, tolong gunakan tool replace_file_content untuk mulai mengisi logika yang sesungguhnya di dalam {filename}."')
+        except Exception as e:
+            print(f"[FAIL] Error generating file: {e}")
+
+def main():
+    if len(sys.argv) < 3:
+        print("Usage: python scaffolder.py <react|api> <ComponentName> [target_dir] [--apply]")
+        sys.exit(1)
+        
+    file_type = sys.argv[1]
+    name = sys.argv[2]
+    
+    args = sys.argv[3:]
+    apply_mode = "--apply" in args
+    target_dir = args[0] if len(args) > 0 and args[0] != "--apply" else os.getcwd()
+    
+    generate_scaffold(file_type, name, target_dir, apply_mode)
+
+if __name__ == "__main__":
+    main()

package/bin/install.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+console.log('Installing Snowline Agent Ecosystem (Project-Level)...');
+
+const projectRoot = process.cwd();
+const agentsDir = path.join(projectRoot, '.agents');
+const skillsDir = path.join(agentsDir, 'skills');
+const knowledgeDir = path.join(agentsDir, 'knowledge');
+const repoUrl = 'https://github.com/UsmanAzizz/snowline-agent-tools.git';
+let isNewInstall = false;
+
+// Ensure .agents and .agents/knowledge exist
+if (!fs.existsSync(agentsDir)) {
+    fs.mkdirSync(agentsDir, { recursive: true });
+}
+if (!fs.existsSync(knowledgeDir)) {
+    fs.mkdirSync(knowledgeDir, { recursive: true });
+}
+
+// Scaffold skills
+if (fs.existsSync(skillsDir)) {
+    console.log(`Found existing skills directory at ${skillsDir}`);
+    if (fs.existsSync(path.join(skillsDir, '.git'))) {
+        console.log('Pulling latest updates...');
+        try {
+            execSync('git pull origin main', { cwd: skillsDir, stdio: 'inherit' });
+        } catch (e) {
+            console.error('Failed to update repository.');
+        }
+    } else {
+        console.log('Existing skills directory is not a git repository. Skipping git pull.');
+    }
+} else {
+    isNewInstall = true;
+    console.log(`Downloading Snowline Agent skills...`);
+    try {
+        execSync(`git clone ${repoUrl} "${skillsDir}"`, { stdio: 'inherit' });
+    } catch (e) {
+        console.error('Failed to clone repository. Make sure git is installed.');
+        process.exit(1);
+    }
+}
+
+// Copy AGENTS_TEMPLATE.md to AGENTS.md in the project root
+const templatePath = path.join(skillsDir, 'AGENTS_TEMPLATE.md');
+const localAgentsPath = path.join(agentsDir, 'AGENTS.md');
+
+if (fs.existsSync(templatePath)) {
+    if (!fs.existsSync(localAgentsPath)) {
+        console.log('Creating Project AGENTS.md...');
+        fs.copyFileSync(templatePath, localAgentsPath);
+        console.log('Project AGENTS.md created successfully.');
+    } else {
+        console.log('Project AGENTS.md already exists. Skipping overwrite.');
+    }
+}
+
+// Scaffold PLAN.md in project root
+const planPath = path.join(projectRoot, 'PLAN.md');
+if (!fs.existsSync(planPath)) {
+    console.log('Creating PLAN.md...');
+    fs.writeFileSync(planPath, '# Project Plan / Task Tracker\n\n- [ ] Initial task\n', 'utf8');
+}
+
+if (isNewInstall) {
+    console.log('\nInstallation Complete!');
+    console.log('This project is now powered by the Snowline Agent Ecosystem.');
+}

package/clean_sweeper/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: Project Health & Residue Sweeper
+description: Use this skill when the user asks you to scan for project health, technical debt, or leftover residue files across a repository. It runs a Python script that deeply scans the project for unused DBs, temporary folders, TODO/FIXME tags, and large commented code blocks.
+---
+
+## Instructions for AI Agent
+
+When the user asks you to "bersihkan project", "cari residu", or check the health/tech debt of a project, use this skill to run a sweeping analysis.
+
+**Command to run:**
+```powershell
+python .agents/skills/clean_sweeper/sweeper.py "<absolute_target_directory>"
+```
+*(Make sure your current working directory `Cwd` is set to the root of the user's project when running this).*
+
+**Expected Output:**
+The script will output a Markdown-formatted report directly to stdout detailing suspect folders, stray leftover files, count of `TODO`/`FIXME` tags (with proper word boundaries), and large commented out code blocks.
+
+### 🛑 CRITICAL BEHAVIORAL RULE (VETO PROTOCOL)
+1. **Never quarantine, move, or delete files automatically.** You MUST NOT assume a file is trash just because the script flagged it.
+2. Read the script output and present a clean summary to the user.
+3. Explicitly ask the user: *"Mana saja dari daftar ini yang boleh saya pindahkan ke karantina/hapus?"*
+4. Wait for the user's explicit confirmation (VETO) per item BEFORE executing any file modification or terminal `mv`/`rm` commands.

package/clean_sweeper/sweeper.py

@@ -0,0 +1,98 @@
+import os
+import re
+import sys
+
+if sys.stdout.encoding != 'utf-8':
+    sys.stdout.reconfigure(encoding='utf-8')
+
+MAX_FILE_SIZE = 500 * 1024 # 500 KB
+ignore_dirs = {'node_modules', '.git', 'build', 'dist', 'uploads', 'public', '.vscode', '.history', 'quarantine', '.native_browser', '.exambro_android', '.plan', '.skills', '.backup_replace', '.agents'}
+
+def sweep(target):
+    residue_files = []
+    todo_count = 0
+    comment_blocks = []
+    scanned_files = 0
+    
+    for root, dirs, files in os.walk(target):
+        dirs[:] = [d for d in dirs if d not in ignore_dirs]
+        
+        for d in dirs:
+            if d.lower() in ['aa', 'arsip', 'temp', 'backup', 'old', 'scratch']:
+                residue_files.append(os.path.join(root, d) + " [Suspected Backup/Temp Folder]")
+                
+        for f in files:
+            filepath = os.path.join(root, f)
+            if os.path.getsize(filepath) > MAX_FILE_SIZE:
+                continue
+                
+            scanned_files += 1
+            f_lower = f.lower()
+            if f_lower.endswith(('.bak', '.old', '.log', '.db', '.sqlite', '.tmp')) or 'copy' in f_lower:
+                if f_lower not in ['database.db'] and not f_lower.endswith('.test.js'):
+                    residue_files.append(filepath + " [Suspected Leftover File]")
+            
+            if f == 'database.db' and root == target:
+                residue_files.append(filepath + " [Local SQLite DB in MySQL project]")
+                
+            if f_lower.endswith(('.js', '.jsx', '.php', '.html', '.py')):
+                try:
+                    with open(filepath, 'r', encoding='utf-8') as file:
+                        content = file.read()
+                        todos = re.findall(r'(?i)\b(TODO|FIXME)\b', content)
+                        todo_count += len(todos)
+                        
+                        lines = content.split('\n')
+                        consecutive_comments = 0
+                        for i, line in enumerate(lines):
+                            if line.strip().startswith(('//', '#')):
+                                consecutive_comments += 1
+                            else:
+                                if consecutive_comments >= 7:
+                                    comment_blocks.append(f"{filepath} (Lines {i-consecutive_comments+1}-{i}): {consecutive_comments} consecutive commented lines")
+                                consecutive_comments = 0
+                except Exception:
+                    pass
+                    
+    return residue_files, todo_count, comment_blocks, scanned_files
+
+def main():
+    if len(sys.argv) < 2:
+        print("[FAIL] Usage: python sweeper.py <target_directory>")
+        sys.exit(1)
+    
+    target = sys.argv[1]
+    residue_files, todo_count, comment_blocks, scanned_files = sweep(target)
+    
+    print("🧹 CLEAN SWEEPER REPORT")
+    print("=" * 50)
+    
+    total_issues = 0
+    if residue_files:
+        for r in residue_files:
+            rel = os.path.relpath(r.split(" [")[0], target)
+            print(f"[FAIL] {rel} " + r[r.index('['):])
+            total_issues += 1
+            
+    if todo_count > 0:
+        print(f"[WARN] Found {todo_count} TODO/FIXME tags in the code.")
+        total_issues += 1
+        
+    if comment_blocks:
+        for c in comment_blocks:
+            path_part, desc = c.split(" (", 1)
+            rel = os.path.relpath(path_part, target)
+            print(f"[WARN] {rel} ({desc}")
+            total_issues += 1
+            
+    print("\n" + "=" * 50)
+    
+    if total_issues == 0:
+        print(f"[OK] Proyek bersih! {scanned_files} file dipindai tanpa ada temuan residu.")
+    else:
+        print(f"[OK] Selesai memindai {scanned_files} file.")
+        print("\n💡 PROMPT UNTUK AI (Copy-Paste ini):")
+        print('"Berdasarkan laporan Clean Sweeper di atas, tolong periksa temuan [FAIL] dan hapus file yatim piatu tersebut. Untuk temuan [WARN], periksa apakah komentar raksasa itu bisa dihapus."')
+
+if __name__ == "__main__":
+    main()

package/context_mapper/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: Context Mapper (Knowledge Builder)
+description: Use this skill when entering a new project or when the user creates significant new architectural folders. It scans the project and generates a PROJECT_STRUCTURE.md and COMMON_PATTERNS.md in the .agents/knowledge/ folder to give you instant architectural context without wasting tokens on manual search.
+---
+
+## Instructions for AI Agent
+
+**When to use this skill:**
+- When you first join a project and need to understand its structure.
+- When the user asks you to "map the context" or "build the knowledge catalog".
+- When you or the user have added a massive new feature (e.g. adding a whole new `admin/` module) and the `PROJECT_STRUCTURE.md` needs to be updated.
+
+**Command to run:**
+```powershell
+python .agents/skills/context_mapper/context_mapper.py
+```
+
+**Expected Behavior & Next Steps:**
+1. The script will output a success message indicating that the Knowledge Catalog has been built in `.agents/knowledge/`.
+2. As a mandatory follow-up, you MUST use the `view_file` tool to read `.agents/knowledge/PROJECT_STRUCTURE.md` and `.agents/knowledge/COMMON_PATTERNS.md` to update your mental model of the project.
+3. If the user asks you to document a new coding convention, you should use `replace_file_content` to append it to `COMMON_PATTERNS.md`.