@uocnv1998/agent-kit 1.0.5 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uocnv1998/agent-kit",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "CLI tool to scaffold Agent Skills, Rules, and Workflows",
   "main": "bin/index.js",
   "bin": {

package/templates/.agent/dev/backend/ARCHITECTURE.md

@@ -37,6 +37,7 @@ Modular knowledge domains loaded by the `backend-specialist`.
 | `mysql`              | MySQL optimization and schema management                                    |
 | `clichouse-expert`   | ClickHouse database expertise                                               |
 | `docker`             | Containerization and deployment patterns                                    |
+| `python-patterns`    | Python standards, FastAPI                                                   |
 
 ---
 

package/templates/.agent/dev/backend/agents/backend-specialist.md

@@ -3,7 +3,7 @@ name: backend-specialist
 description: Expert Backend Development Architect. Focuses on system design, security, scalability, and maintainability. Applies universal architectural principles (SOLID, TDD) regardless of the specific tech stack. Triggers on backend, server, api, database, auth.
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
-skills: database-design, api-patterns, security-principles, tdd-workflow
+skills: database-design, api-patterns, security-principles, tdd-workflow, python-patterns
 ---
 
 # Backend Development Architect

package/templates/.agent/dev/backend/rules/GEMINI.md

@@ -16,7 +16,7 @@ You are a Senior Software Engineer. Your mission is to realize User Stories into
 Agent activated (`backend-specialist`) → Check frontmatter "skills:" → Read SKILL.md (INDEX) → Read specific sections.
 
 - **Selective Reading:** DO NOT read ALL files in a skill folder. Read `SKILL.md` first, then only read sections matching the user's request.
-- **Rule Priority:** P0 (GEMINI.md) > P1 (Agent.md) > P2 (SKILL.md). All rules are binding.
+- **Rule Priority:** P0 (GEMINI.md) > P1 (AGENTS.md) > P2 (SKILL.md). All rules are binding.
 
 ### 2. Enforcement Protocol
 
@@ -79,11 +79,14 @@ When applying the agent, inform the user:
 
 ### 🌐 Core Development Principles (MANDATORY)
 
-- **SOLID Principles**: Controllers must stay thin and call services, services contain business logic and depend only on repository interfaces, and all database access must be handled exclusively inside repository implementations via dependency injection.
-- **TDD (Test-Driven Development)**: Always write tests BEFORE writing the implementation. You must write both unit tests and feature tests. Run tests frequently and ensure the overall project test coverage rate is 80% or higher.
-- **Clean Code**: Run the appropriate code formatter based on the project's language and framework before finalizing changes. The specific formatting command may be defined in `AGENTS.md`.
-- **Security**: Use environment variables only in configuration files - never use `env()` directly outside of config files.
-- **OpenSpec & TDD Integration**: Whenever executing OpenSpec workflows (e.g., `/opsx:propose`, `/opsx:apply`), you MUST enforce TDD. You must write both unit tests and feature tests. During `/opsx:propose`, the `tasks.md` MUST explicitly break down features into `[ ] Write failing test (RED)`, `[ ] Implement (GREEN)`, and `[ ] Refactor`. During `/opsx:apply`, you are FORBIDDEN from writing implementation code before passing tests are demonstrated.
+- **Strict Adherence to Project Rules**: For all coding conventions, architecture patterns (e.g., SOLID), code formatting, and security policies, you MUST strictly follow the `AGENTS.md` file located in the project root.
+- **Workflow Initialization**: Whenever starting any flow or executing OpenSpec workflows (e.g., `/opsx:propose`, `/opsx:apply`), you MUST read `AGENTS.md` (using `view_file`) first and actively use the **Context7 MCP Server** to look up relevant library documentation.
+- **TDD (Test-Driven Development)**: Always write tests BEFORE writing the implementation. You must write both unit tests and feature tests. When generating tasks (e.g., during `/opsx:propose`), the `tasks.md` MUST explicitly break down features into exactly these steps:
+  1. `Write failing test (RED)`
+  2. `PIC APPROVAL CHECKPOINT (Wait for PIC review & approval of failing test)`
+  3. `Implement (GREEN)`
+  4. `Refactor`
+- **TDD Enforcement**: During implementation (`/opsx:apply`), after completing step 1, you MUST pause and ask the PIC to review your failing tests. You are FORBIDDEN from writing actual implementation code (Step 3) until the PIC explicitly says "approved" or permits you to proceed.
 
 ### 🌐 Documents (Workspace files)
 

package/templates/.agent/dev/backend/skills/python-patterns/SKILL.md

@@ -0,0 +1,441 @@
+---
+name: python-patterns
+description: Python development principles and decision-making. Framework selection, async patterns, type hints, project structure. Teaches thinking, not copying.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Python Patterns
+
+> Python development principles and decision-making for 2025.
+> **Learn to THINK, not memorize patterns.**
+
+---
+
+## ⚠️ How to Use This Skill
+
+This skill teaches **decision-making principles**, not fixed code to copy.
+
+- ASK user for framework preference when unclear
+- Choose async vs sync based on CONTEXT
+- Don't default to same framework every time
+
+---
+
+## 1. Framework Selection (2025)
+
+### Decision Tree
+
+```
+What are you building?
+│
+├── API-first / Microservices
+│   └── FastAPI (async, modern, fast)
+│
+├── Full-stack web / CMS / Admin
+│   └── Django (batteries-included)
+│
+├── Simple / Script / Learning
+│   └── Flask (minimal, flexible)
+│
+├── AI/ML API serving
+│   └── FastAPI (Pydantic, async, uvicorn)
+│
+└── Background workers
+    └── Celery + any framework
+```
+
+### Comparison Principles
+
+| Factor | FastAPI | Django | Flask |
+|--------|---------|--------|-------|
+| **Best for** | APIs, microservices | Full-stack, CMS | Simple, learning |
+| **Async** | Native | Django 5.0+ | Via extensions |
+| **Admin** | Manual | Built-in | Via extensions |
+| **ORM** | Choose your own | Django ORM | Choose your own |
+| **Learning curve** | Low | Medium | Low |
+
+### Selection Questions to Ask:
+1. Is this API-only or full-stack?
+2. Need admin interface?
+3. Team familiar with async?
+4. Existing infrastructure?
+
+---
+
+## 2. Async vs Sync Decision
+
+### When to Use Async
+
+```
+async def is better when:
+├── I/O-bound operations (database, HTTP, file)
+├── Many concurrent connections
+├── Real-time features
+├── Microservices communication
+└── FastAPI/Starlette/Django ASGI
+
+def (sync) is better when:
+├── CPU-bound operations
+├── Simple scripts
+├── Legacy codebase
+├── Team unfamiliar with async
+└── Blocking libraries (no async version)
+```
+
+### The Golden Rule
+
+```
+I/O-bound → async (waiting for external)
+CPU-bound → sync + multiprocessing (computing)
+
+Don't:
+├── Mix sync and async carelessly
+├── Use sync libraries in async code
+└── Force async for CPU work
+```
+
+### Async Library Selection
+
+| Need | Async Library |
+|------|---------------|
+| HTTP client | httpx |
+| PostgreSQL | asyncpg |
+| Redis | aioredis / redis-py async |
+| File I/O | aiofiles |
+| Database ORM | SQLAlchemy 2.0 async, Tortoise |
+
+---
+
+## 3. Type Hints Strategy
+
+### When to Type
+
+```
+Always type:
+├── Function parameters
+├── Return types
+├── Class attributes
+├── Public APIs
+
+Can skip:
+├── Local variables (let inference work)
+├── One-off scripts
+├── Tests (usually)
+```
+
+### Common Type Patterns
+
+```python
+# These are patterns, understand them:
+
+# Optional → might be None
+from typing import Optional
+def find_user(id: int) -> Optional[User]: ...
+
+# Union → one of multiple types
+def process(data: str | dict) -> None: ...
+
+# Generic collections
+def get_items() -> list[Item]: ...
+def get_mapping() -> dict[str, int]: ...
+
+# Callable
+from typing import Callable
+def apply(fn: Callable[[int], str]) -> str: ...
+```
+
+### Pydantic for Validation
+
+```
+When to use Pydantic:
+├── API request/response models
+├── Configuration/settings
+├── Data validation
+├── Serialization
+
+Benefits:
+├── Runtime validation
+├── Auto-generated JSON schema
+├── Works with FastAPI natively
+└── Clear error messages
+```
+
+---
+
+## 4. Project Structure Principles
+
+### Structure Selection
+
+```
+Small project / Script:
+├── main.py
+├── utils.py
+└── requirements.txt
+
+Medium API:
+├── app/
+│   ├── __init__.py
+│   ├── main.py
+│   ├── models/
+│   ├── routes/
+│   ├── services/
+│   └── schemas/
+├── tests/
+└── pyproject.toml
+
+Large application:
+├── src/
+│   └── myapp/
+│       ├── core/
+│       ├── api/
+│       ├── services/
+│       ├── models/
+│       └── ...
+├── tests/
+└── pyproject.toml
+```
+
+### FastAPI Structure Principles
+
+```
+Organize by feature or layer:
+
+By layer:
+├── routes/ (API endpoints)
+├── services/ (business logic)
+├── models/ (database models)
+├── schemas/ (Pydantic models)
+└── dependencies/ (shared deps)
+
+By feature:
+├── users/
+│   ├── routes.py
+│   ├── service.py
+│   └── schemas.py
+└── products/
+    └── ...
+```
+
+---
+
+## 5. Django Principles (2025)
+
+### Django Async (Django 5.0+)
+
+```
+Django supports async:
+├── Async views
+├── Async middleware
+├── Async ORM (limited)
+└── ASGI deployment
+
+When to use async in Django:
+├── External API calls
+├── WebSocket (Channels)
+├── High-concurrency views
+└── Background task triggering
+```
+
+### Django Best Practices
+
+```
+Model design:
+├── Fat models, thin views
+├── Use managers for common queries
+├── Abstract base classes for shared fields
+
+Views:
+├── Class-based for complex CRUD
+├── Function-based for simple endpoints
+├── Use viewsets with DRF
+
+Queries:
+├── select_related() for FKs
+├── prefetch_related() for M2M
+├── Avoid N+1 queries
+└── Use .only() for specific fields
+```
+
+---
+
+## 6. FastAPI Principles
+
+### async def vs def in FastAPI
+
+```
+Use async def when:
+├── Using async database drivers
+├── Making async HTTP calls
+├── I/O-bound operations
+└── Want to handle concurrency
+
+Use def when:
+├── Blocking operations
+├── Sync database drivers
+├── CPU-bound work
+└── FastAPI runs in threadpool automatically
+```
+
+### Dependency Injection
+
+```
+Use dependencies for:
+├── Database sessions
+├── Current user / Auth
+├── Configuration
+├── Shared resources
+
+Benefits:
+├── Testability (mock dependencies)
+├── Clean separation
+├── Automatic cleanup (yield)
+```
+
+### Pydantic v2 Integration
+
+```python
+# FastAPI + Pydantic are tightly integrated:
+
+# Request validation
+@app.post("/users")
+async def create(user: UserCreate) -> UserResponse:
+    # user is already validated
+    ...
+
+# Response serialization
+# Return type becomes response schema
+```
+
+---
+
+## 7. Background Tasks
+
+### Selection Guide
+
+| Solution | Best For |
+|----------|----------|
+| **BackgroundTasks** | Simple, in-process tasks |
+| **Celery** | Distributed, complex workflows |
+| **ARQ** | Async, Redis-based |
+| **RQ** | Simple Redis queue |
+| **Dramatiq** | Actor-based, simpler than Celery |
+
+### When to Use Each
+
+```
+FastAPI BackgroundTasks:
+├── Quick operations
+├── No persistence needed
+├── Fire-and-forget
+└── Same process
+
+Celery/ARQ:
+├── Long-running tasks
+├── Need retry logic
+├── Distributed workers
+├── Persistent queue
+└── Complex workflows
+```
+
+---
+
+## 8. Error Handling Principles
+
+### Exception Strategy
+
+```
+In FastAPI:
+├── Create custom exception classes
+├── Register exception handlers
+├── Return consistent error format
+└── Log without exposing internals
+
+Pattern:
+├── Raise domain exceptions in services
+├── Catch and transform in handlers
+└── Client gets clean error response
+```
+
+### Error Response Philosophy
+
+```
+Include:
+├── Error code (programmatic)
+├── Message (human readable)
+├── Details (field-level when applicable)
+└── NOT stack traces (security)
+```
+
+---
+
+## 9. Testing Principles
+
+### Testing Strategy
+
+| Type | Purpose | Tools |
+|------|---------|-------|
+| **Unit** | Business logic | pytest |
+| **Integration** | API endpoints | pytest + httpx/TestClient |
+| **E2E** | Full workflows | pytest + DB |
+
+### Async Testing
+
+```python
+# Use pytest-asyncio for async tests
+
+import pytest
+from httpx import AsyncClient
+
+@pytest.mark.asyncio
+async def test_endpoint():
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        response = await client.get("/users")
+        assert response.status_code == 200
+```
+
+### Fixtures Strategy
+
+```
+Common fixtures:
+├── db_session → Database connection
+├── client → Test client
+├── authenticated_user → User with token
+└── sample_data → Test data setup
+```
+
+---
+
+## 10. Decision Checklist
+
+Before implementing:
+
+- [ ] **Asked user about framework preference?**
+- [ ] **Chosen framework for THIS context?** (not just default)
+- [ ] **Decided async vs sync?**
+- [ ] **Planned type hint strategy?**
+- [ ] **Defined project structure?**
+- [ ] **Planned error handling?**
+- [ ] **Considered background tasks?**
+
+---
+
+## 11. Anti-Patterns to Avoid
+
+### ❌ DON'T:
+- Default to Django for simple APIs (FastAPI may be better)
+- Use sync libraries in async code
+- Skip type hints for public APIs
+- Put business logic in routes/views
+- Ignore N+1 queries
+- Mix async and sync carelessly
+
+### ✅ DO:
+- Choose framework based on context
+- Ask about async requirements
+- Use Pydantic for validation
+- Separate concerns (routes → services → repos)
+- Test critical paths
+
+---
+
+> **Remember**: Python patterns are about decision-making for YOUR specific context. Don't copy code—think about what serves your application best.

package/templates/.agent/dev/frontend/rules/GEMINI.md

@@ -16,7 +16,7 @@ You are a Senior Frontend Engineer and Architect. Your mission is to transform d
 Agent activated (`frontend-specialist`) → Check frontmatter "skills:" → Read SKILL.md (INDEX) → Read specific sections.
 
 - **Selective Reading:** DO NOT read ALL files in a skill folder. Read `SKILL.md` first, then only read sections matching the user's request.
-- **Rule Priority:** P0 (GEMINI.md) > P1 (Agent.md) > P2 (SKILL.md). All rules are binding.
+- **Rule Priority:** P0 (GEMINI.md) > P1 (AGENTS.md) > P2 (SKILL.md). All rules are binding.
 
 ### 2. Enforcement Protocol
 
@@ -81,11 +81,14 @@ When applying the agent, inform the user:
 
 - **Pre-flight Documentation Check**: Before starting any task, you BẮT BUỘC PHẢI (MUST) read all related documentation. This includes Business Analyst (BA) requirements (from Jira/Confluence), Designer specifications/mockups (from the specialized **subtask** created by the Designer), and API documentation (from the Backend developer's **comments or subtasks** on Jira/Confluence). Do not write any code until you fully understand the requirements from all sources.
 - **Strict UI Adherence**: The user interface MUST strictly follow the Designer's specifications. You are FORBIDDEN from inventing or assuming UI layouts/components not defined in the design specs. If the documentation or design is missing for a specific part, you MUST notify the PIC (Person in Charge) immediately and ASK for their direction. You may propose generating a mockup, but you MUST ONLY create and provide the mockup if the PIC explicitly agrees to it. Do not proceed with implementation without the PIC's approval.
-- **Component-Driven Development**: Components must be small, focused, and represent a single responsibility. Favor composition over complex prop-drilling or inheritance.
-- **Clean Code & Formatting**: Run `npm run lint` and `npm run format` (or equivalent) before finalizing changes. Ensure consistent naming (PascalCase for Components, camelCase for variables/functions).
-- **Accessibility (a11y)**: Semantic HTML is mandatory. Every interactive element must be keyboard-accessible and have appropriate ARIA attributes.
-- **Performance**: Minimize client-side JavaScript. Use Next.js Server Components by default. Optimize images and avoid unnecessary re-renders.
-- **OpenSpec & TDD Integration**: Whenever executing OpenSpec workflows (e.g., `/opsx:propose`, `/opsx:apply`), you MUST enforce TDD. You must write both unit tests and feature tests. During `/opsx:propose`, the `tasks.md` MUST explicitly break down features into `[ ] Write failing test (RED)`, `[ ] Implement (GREEN)`, and `[ ] Refactor`. During `/opsx:apply`, you are FORBIDDEN from writing implementation code before passing tests are demonstrated.
+- **Strict Adherence to Project Rules**: For all coding conventions, component architectures, code formatting, a11y, and performance guidelines, you MUST strictly follow the `AGENTS.md` file located in the project root.
+- **Workflow Initialization**: Whenever starting any flow or executing OpenSpec workflows (e.g., `/opsx:propose`, `/opsx:apply`), you MUST read `AGENTS.md` (using `view_file`) first and actively use the **Context7 MCP Server** to look up relevant library documentation.
+- **TDD (Test-Driven Development)**: Always write tests BEFORE writing the implementation. You must write both unit tests and feature tests. When generating tasks (e.g., during `/opsx:propose`), the `tasks.md` MUST explicitly break down features into exactly these steps:
+  1. `Write failing test (RED)`
+  2. `PIC APPROVAL CHECKPOINT (Wait for PIC review & approval of failing test)`
+  3. `Implement (GREEN)`
+  4. `Refactor`
+- **TDD Enforcement**: During implementation (`/opsx:apply`), after completing step 1, you MUST pause and ask the PIC to review your failing tests. You are FORBIDDEN from writing actual implementation code (Step 3) until the PIC explicitly says "approved" or permits you to proceed.
 
 ### 🌐 Documents (Workspace files)