ifixkart-admin/Documentation/Agent_Skills_Directory.md
Adithiyan bbd3a3e959 feat: initial commit — full platform snapshot
- Backend: FastAPI app with all models, services, schemas, routes
- Admin Panel: Next.js dashboard with all modules
  (CRM, POS, repairs, warranties, billing, notifications, etc.)
- Ecommerce: storefront (submodule) + product catalog
- AI Agents: .agents/ skill library for Antigravity IDE
- Docs: architecture, billing, notification gateway markdown
- Submodules: Backend/OpenWA, Ecommerce/File 2/storefront
2026-10-13 12:59:47 +05:30

190 lines
13 KiB
Markdown

# iFixKart Platform: Custom Agents & Skills Directory
This document details the configuration structure of the `.agents` customization framework and provides a comprehensive breakdown of the 21 custom skills configured for this workspace.
---
## 📂 Part 1: Workspace Customization Structure
The workspace customizations folder is located in the root of the project at [IfixKartEcommerce/.agents/](file:///mnt/fam/SERVER/IfixKartEcommerce/.agents). It contains:
* **[AGENTS.md](file:///mnt/fam/SERVER/IfixKartEcommerce/.agents/AGENTS.md)**: The master configuration file. It contains behavioral prompt reinforcements (directives instructing the assistant to automatically discover, load, and strictly execute skill checks) and lists all registered skills.
* **[skills/](file:///mnt/fam/SERVER/IfixKartEcommerce/.agents/skills)**: The subfolder containing individual skill directories. Each skill is separated into its own folder (e.g. `skills/create_component/`) containing a **`SKILL.md`** file.
Each `SKILL.md` declares:
1. **YAML Frontmatter**: The `name` and `description` triggers matched during task parsing.
2. **Purpose**: The core objective of the skill.
3. **When to Use**: Scenarios where the skill applies.
4. **Preconditions**: Technical prerequisites.
5. **Step-by-Step Checklist**: How to execute the work.
6. **Validation Checklist**: Verification criteria before task completion.
7. **Examples**: Real codebase code snippets.
8. **Failure Cases**: Known anti-patterns to avoid.
---
## 🛠️ Part 2: Complete Skills Catalog
The 21 active workspace skills are organized into four operational categories: **Backend (Python/FastAPI)**, **Frontend (Next.js/React)**, **Generic (Lint/Review/Audit)**, and **Standard (Version Control/CI)**.
### 📦 Category A: Backend Skills
#### 16. Database Migrations (`.agents/skills/database_migrations/`)
* **Purpose**: Manage database schema migrations using Alembic in Python.
* **Preconditions**: alembic.ini configured and pointing to database instances.
* **Key Checklist**: Generate autodetected revision scripts; verify migration logic; apply upgrade heads locally.
* **Validation**: Alembic schema version aligns with database version; zero data truncation logs.
* **Failure Cases**: Making manual direct DDL edits in MySQL, bypassing versioning loops.
#### 17. API Design (`.agents/skills/api_design/`)
* **Purpose**: Enforce RESTful routing paths, payloads validation, and response models.
* **Preconditions**: Pydantic/Zod schemas declared.
* **Key Checklist**: Structure route paths logically; match correct HTTP request verbs; assert standard status responses.
* **Validation**: Swagger UI loads route mappings correctly.
* **Failure Cases**: Using GET endpoints to perform data modifications.
#### 1. Add Tests (`.agents/skills/add_tests/`)
* **Purpose**: Writes unit, integration, and regression test suites for FastAPI backend routes and database models.
* **Preconditions**: Local MySQL testing connection must be configured; virtualenv testing packages must be active.
* **Key Checklist**: Mock dynamic payment and shipping gateways; write isolated assertions covering happy paths and exception states.
* **Validation**: Code has at least 85% assertion coverage; tests clean up database changes upon completion.
* **Failure Cases**: Mocking database operations incorrectly, leading to shared state leaks between test threads.
#### 2. Code Review (`.agents/skills/code_review/`)
* **Purpose**: Inspects backend logic, SQL transaction blocks, and route permissions.
* **Preconditions**: Code compiles successfully; Graphify model is generated.
* **Key Checklist**: Check database mutations for session rollbacks on exceptions; scan routes to ensure auth decorators are in place.
* **Validation**: Zero syntax or compile warnings; all inputs validated via Pydantic schemas.
* **Failure Cases**: Failing to verify that database mutations are enclosed in an active session rollback block.
#### 3. Fix Bug (`.agents/skills/fix_bug/`)
* **Purpose**: Isolates database, schema, or router failures, fixes the root cause, and guarantees regression protection.
* **Preconditions**: Traceback logs or bug descriptions available.
* **Key Checklist**: Write a minimal failing test that reproduces the bug; apply logic fixes to the root cause; verify the test now passes.
* **Validation**: Reproduction test succeeds; existing suite continues to pass with zero regressions.
* **Failure Cases**: Adding conditional checks that temporarily hide symptoms instead of fixing the root cause.
---
### 🎨 Category B: Frontend Skills
#### 4. Add Utility Function (`.agents/skills/add_utility_function/`)
* **Purpose**: Adds pure, reusable TypeScript helper functions.
* **Preconditions**: Similar helper does not already exist under `utils/` or `lib/`.
* **Key Checklist**: Write helper as a pure, side-effect-free function; type all inputs and outputs (no `any` type); export from barrel `index.ts`.
* **Validation**: Linter outputs zero errors; all parameter configurations documented with JSDoc headers.
* **Failure Cases**: Importing React state context or hooks inside pure utility files.
#### 5. Create Component (`.agents/skills/create_component/`)
* **Purpose**: Enforces standard layouts for Next.js/React visual modules.
* **Preconditions**: Verify no primitive layouts (like Shadcn or AntD) already meet the design requirement.
* **Key Checklist**: Group files under `components/ComponentName/`; define destructured TS interface props; style only with design token variables (no inline styling or raw color hex codes).
* **Validation**: Responsive layout renders accurately on mobile and desktop viewports; barrel export index is created.
* **Failure Cases**: Bundling layout display elements and network fetching/state mutations into a single massive file.
#### 6. Test Feature (`.agents/skills/test_feature/`)
* **Purpose**: Evaluates user interface responsiveness and checkout/booking validation flows.
* **Preconditions**: Local dev servers are running.
* **Key Checklist**: Trigger browser subagent to open local url; interact with input elements; capture responsive screenshots and session recordings.
* **Validation**: Form submissions yield confirmation screens; console shows zero javascript warnings.
* **Failure Cases**: Selecting elements via absolute pixel coords instead of relative text or ID labels.
---
### 🛡️ Category C: Generic Skills
#### 21. Planning and Analysis (`.agents/skills/planning_analysis/`)
* **Purpose**: Enforces requirements check, trade-off analysis (pros/cons), detailed report generation, and explicit user approval before execution.
* **Preconditions**: Staging environment and Graphify maps are accessible.
* **Key Checklist**: Deconstruct task constraints; compare two alternative strategies; list pros/cons; output `implementation_plan.md` with feedback hooks; wait for approval.
* **Validation**: Code remains unmodified until user explicitly reviews and accepts the implementation plan.
* **Failure Cases**: Commencing execution immediately without analyzing disadvantages or getting approval.
#### 18. Performance Profiling (`.agents/skills/performance_profiling/`)
* **Purpose**: Identify database index gaps, slow SQL executions, or CPU-bound script blocks.
* **Preconditions**: Profiling libraries active.
* **Key Checklist**: Log execution metrics; inspect queries using EXPLAIN; implement eager-load configurations or add database indexes.
* **Validation**: Target API latencies drop below 200ms.
* **Failure Cases**: Injecting indices indiscriminately to tables, increasing write overhead latencies.
#### 19. Logging Observability (`.agents/skills/logging_observability/`)
* **Purpose**: Enforces structured JSON logging and exception capture metrics.
* **Preconditions**: JSON logging provider active.
* **Key Checklist**: Instantiate standard logger objects; log key actions; propagate correlation request IDs.
* **Validation**: Log pipelines capture metadata and traceback details.
* **Failure Cases**: Logging plaintext personal details (PII) or secrets.
#### 7. Add Docs (`.agents/skills/add_docs/`)
* **Purpose**: Enforces documentation structures, API parameter documentation, and code comment standards.
* **Preconditions**: Exposing new methods or modules.
* **Key Checklist**: Write JSDoc comments explaining class objectives, parameter configurations, and return formats; organize imports (React $\rightarrow$ libraries $\rightarrow$ local files).
* **Validation**: All exported interfaces are documented; compiler yields no warnings.
* **Failure Cases**: Letting JSDoc variables fall out of sync with actual parameters after code revisions.
#### 8. Review My Pr (`.agents/skills/review_my_pr/`)
* **Purpose**: Runs a self-audit before PR submission.
* **Preconditions**: Branch builds correctly; git diff contains staged changes.
* **Key Checklist**: Execute linters; inspect route declarations for auth tokens; check styling rules; compile review report.
* **Validation**: Zero linter errors found; no credentials or private keys committed.
* **Failure Cases**: Merging PR files without verifying integration points.
#### 9. Review (`.agents/skills/review/`)
* **Purpose**: Runs deep system-wide quality reviews, assessing performance bottlenecks and business-requirement fit.
* **Preconditions**: Complete test suite passes.
* **Key Checklist**: Map code changes using Graphify; audit for performance bottlenecks (loops, database indices); verify design guidelines.
* **Validation**: Review log lists all potential transaction issues.
* **Failure Cases**: Auditing logic without checking performance implications (e.g. ignoring unindexed query lookups).
#### 10. Security Review (`.agents/skills/security_review/`)
* **Purpose**: Scans codebases for authentication bypasses, database injection vulnerabilities, XSS, and data privacy leaks.
* **Preconditions**: Database schemas and routers are declared.
* **Key Checklist**: Ensure input values are parameterized in DB calls; check route handlers require auth tokens; sanitize strings before page injections.
* **Validation**: SQL injections are prevented via ORM bindings; user data is handled under DPDP act parameters.
* **Failure Cases**: Trusting third-party input streams without cryptographically checking token signatures.
#### 11. Update Graphify (`.agents/skills/update_graphify/`)
* **Purpose**: Refreshes Graphify AST model linkages after folder structure modifications.
* **Preconditions**: Graphify package installed.
* **Key Checklist**: Run update script targeting modified files; check parser outputs; refresh HTML graphs and markdown wiki files.
* **Validation**: Node list contains the new connections.
* **Failure Cases**: Running graph builders on code files containing syntax compile errors.
#### 12. Graphify (`.agents/skills/graphify/`)
* **Purpose**: Builds an AST knowledge graph mapping visual assets, database relationships, and backend APIs.
* **Preconditions**: Python environment configured.
* **Key Checklist**: Execute graph parser; generate `GRAPH_REPORT.md` outlining codebase components; output structure maps.
* **Validation**: Interactive system layout is accessible via `graph.html`.
* **Failure Cases**: Missing write permissions inside Documentation folder.
#### 13. GBrain (`.agents/skills/gbrain/`)
* **Purpose**: Connects workspace memory and guidelines directly to coding assistants.
* **Preconditions**: Bun package runner installed.
* **Key Checklist**: Ingest data logs using capture CLI; retrieve cited summaries using think commands; run background dream cycles.
* **Validation**: Output answers show clear, cited links to raw pages.
* **Failure Cases**: Querying index lists containing stale/out-of-date records.
---
### ⚙️ Category D: Standard Skills
#### 20. Dependency Updates (`.agents/skills/dependency_updates/`)
* **Purpose**: Automate package audits, vulnerability fixes, and minor upgrades.
* **Preconditions**: Access to standard package lock files.
* **Key Checklist**: Scan for alert vulnerabilities; upgrade minor version tags; run regression tests.
* **Validation**: Diagnostic audits return zero active warnings.
* **Failure Cases**: Updating major package indices blindly, causing system compile failures.
#### 14. Commit (`.agents/skills/commit/`)
* **Purpose**: Standardizes version control logs using Conventional Commits structure.
* **Preconditions**: Staged file modifications are ready in Git.
* **Key Checklist**: Inspect staged changes; categorize subject lines (feat, fix, docs, refactor); document why changes were made.
* **Validation**: Log headers match `<type>(<scope>): <desc>` syntax with no capitalizations.
* **Failure Cases**: Combining unrelated UI tweaks and database models under a single generic commit title.
#### 15. Update Agents (`.agents/skills/update_agents/`)
* **Purpose**: Synchronizes customization setup rules across Devin and Kiro environments.
* **Preconditions**: Devin and Kiro configuration directories are active.
* **Key Checklist**: Check modified rule files; align AGENTS.md instructions with matching steering parameters; isolate workspace readme layouts.
* **Validation**: Setup structures are updated without duplication.
* **Failure Cases**: Wholesale overwriting of configurations, which breaks platform-specific hooks.