tmolavi/agent-project-discovery-skill

> **"An AI agent should understand before it changes."**
> [!IMPORTANT]
> **Universal Autonomy Across All Projects ("خودش تصمیم بگیره در هر پروژه‌ای")**:
> All traps, rules, and question bans in this skill apply universally across **ANY** project, repository, container, or server environment. Command examples and server names in the documentation are concrete illustrations of broader forbidden patterns.
---
🌍 Translations
English | فارسی | Türkçe | Azərbaycanca | العربية
---
A universal, production-grade startup skill for AI coding agents. It prevents AI agents from jumping blindly into edits, clobbering existing architectures, asking redundant questions, or rewriting working code by teaching them to act like seasoned senior engineers onboarding onto an established codebase.
---
🎯 Why This Skill Exists
Today's AI coding assistants are capable, but their default initialization behavior often suffers from critical failure modes:
| ❌ Default Agent Pitfall | ✅ With agent-project-discovery-skill |
|---|---|
| **Eager Editing**: Jumps straight into editing random files without knowing the tech stack or monorepo boundaries. | **Structured Discovery**: Explores repository structure, dependencies, configs, test setups, and documentation first. |
| **Frivolous Questions**: Interrupts developers asking *"Where is X?"* or *"What should I do?"* | **Search First, Ask Later**: Resolves questions autonomously via codebase grep, docs, and git history. |
| **Timid Test Approvals**: Halts to ask *"Allow testing /api/...?"* or seeks permission before verifying code. | **Autonomous Decision Mandate**: Decides and verifies autonomously ("خودش تصمیم بگیره") using local mocks and unit tests without nagging. |
| **Remote Route/Code Probing**: Halts to ask *"Allow checking model router endpoints?"* and fires SSH to read files. | **Autonomous Local Code Discovery**: Inspects router files, schemas, and endpoints directly in the local workspace. |
| **Model Dispatch / Reasoning Halts**: Halts asking *"Allow testing central model dispatch?"* and triggers remote SSH. | **Autonomous Router Mocking**: Tests reasoning routers, payload structures, and dispatch tiers locally with mock transports. |
| **TTS / Speech Benchmarking Halts**: Halts asking *"Allow testing TTS synthesis speed?"* or *"Allow testing updated Edge-TTS?"* and triggers remote SSH. | **Autonomous Voice & TTS Mocking**: Validates speech synthesis services (TTSService) and updated Edge-TTS locally with mocked audio chunks and async mocks. |
| **STT Pipeline Testing Halts**: Halts asking *"Allow testing STT pipeline?"*, *"Allow checking STT providers?"*, or *"Allow testing Groq Whisper STT?"* and triggers remote SSH. | **Autonomous Speech-to-Text (STT) Mocking**: Validates speech transcription services (STTService), Groq Whisper, and STT pipelines locally with mocked async functions and dummy audio bytes. |
| **Remote Package Inspection Halts**: Halts asking *"Allow checking edge-tts version?"* and fires SSH to run pip show. | **Autonomous Dependency Manifest Discovery**: Inspects library versions statically from requirements.txt, pyproject.toml, or lockfiles without SSH. |
| **Remote Package Upgrade Halts**: Halts asking *"Allow upgrading edge-tts?"* and fires SSH to run pip install -U. | **Autonomous Dependency Upgrades in Manifests**: Updates library constraints directly in local requirements.txt/pyproject.toml/Dockerfile and verifies locally without remote SSH mutations. |
| **Remote Deployment Config Probing**: Halts asking *"Allow viewing server docker-compose.yml?"* and fires SSH to run cat ... docker-compose.yml. | **Autonomous Deployment Manifest Discovery**: Inspects docker-compose.yml, Dockerfile, and configuration files directly in the local workspace without remote SSH commands. |
| **Remote Container Filesystem Probing**: Halts asking *"Allow checking container contents?"* and fires SSH to run docker exec ... ls. | **Autonomous Container Filesystem Discovery**: Inspects repository layout, Dockerfile WORKDIR/COPY, and docker-compose.yml volumes directly in the local workspace without remote container probing. |
| **Remote UI Component Probing**: Halts asking *"Allow checking server MobileMenu.tsx?"* and fires SSH to run cat ... components/MobileMenu.tsx. | **Autonomous Local Component Discovery**: Inspects frontend components (components/MobileMenu.tsx, .tsx, .jsx), templates, and source code directly in the local workspace without remote SSH commands. |