@jetrabbits/agentic 0.0.1

package/areas/software/full-stack/rules/database-migrations-guide.md

@@ -0,0 +1,24 @@
+---
+trigger: model_decision
+glob: database-migrations-guide
+description: all DB schema changes must be explicit, versioned, and testable via Alembic
+---
+
+# Database & Migration Rule
+
+**Goal:** schema changes must be explicit, versioned, traceable, and tested.
+
+**Rules:**
+
+- Use **Alembic** for all schema changes; never rely only on ORM metadata or manual SQL.
+- Each change in a migration script with upgrade/downgrade; idempotent if possible; consistent naming/versioning.
+- Include tables, columns, indexes, constraints, relationships explicitly.
+- Tests must apply migrations to clean DB and validate structure & integrity (Postgres & SQLite if supported).
+- Avoid destructive ops without backup; group related changes; keep scripts small; document dependencies/order.
+
+**Violations:**
+
+- Schema changes outside Alembic.
+- Missing tests or incomplete upgrade/downgrade.
+- Hardcoded schema in code.
+- Drift between environments.

package/areas/software/full-stack/rules/domain-models-guide.md

@@ -0,0 +1,28 @@
+---
+trigger: model_decision
+glob: domain-models-guide
+description: ensure strong, explicit, validated domain models
+---
+
+# Domain Models Rule
+
+**Goal:** all domain data must be explicit, validated, and modeled.
+
+**Rules:**
+
+- No raw data flows; every domain concept must have a model.
+- **Pydantic mandatory** for domain models, I/O contracts, config, validation.
+- **SQLModel mandatory** for database models.
+- Validation logic lives inside models; models are explicit, strongly typed.
+- Prefer value objects over primitives when meaning or validation exists.
+- Explicit fields/types only; no dynamic fields, magic defaults, or hybrid models.
+- Serialization explicit; no dict spreading, no leaking internal structure.
+
+**Violations:**
+
+- Raw dicts between layers.
+- Validation outside models.
+- Optional fields “just in case”.
+- Models depend on infrastructure.
+- Silent coercion of invalid data.
+- Pydantic bypassed or inconsistent.

package/areas/software/full-stack/rules/e2e-test-guide.md

@@ -0,0 +1,18 @@
+---
+trigger: always_on
+glob: e2e-test-guide
+description: enforce full blackbox end-to-end testing after code & unit tests
+---
+
+# Rule — E2E Test
+
+**Purpose:** Verify all business logic in full scenarios.
+
+- Launch services via Docker.
+- Feed input data/files.
+- Call APIs to run the complete workflow.
+- Verify output matches expected results.
+- Run via Makefile: `make e2e-test`.
+- Must **not** be confused with unit tests.
+
+**Violations:** Missing E2E test, logs contain errors, output incorrect.

package/areas/software/full-stack/rules/env-settings-guide.md

@@ -0,0 +1,34 @@
+---
+trigger: always_on
+glob: env-settings-guide
+description: enforce DSN-based configuration via Pydantic BaseSettings
+---
+
+# Environment & DSN Settings Rule
+
+**Rules:**
+
+- All service connections (DB, cache, brokers, APIs) MUST use **DSN variables**.
+- Use a single DSN env var instead of splitting config into `USER/HOST/DB`.
+- All configuration MUST be defined via Pydantic `BaseSettings`.
+- Parsing, validation, and defaults live inside the Settings model only.
+
+### Environment Files
+
+- `.env.example` MUST exist and be kept up to date.
+- `.env.example` MUST contain **test / placeholder credentials only**.
+- `.env` MUST contain **real (production or local) credentials**.
+- `.env` MUST be listed in `.gitignore`.
+- `docker-compose.yml` MUST explicitly load `.env`.
+
+**Examples:**
+
+- ✅ `DATABASE_DSN=postgresql+asyncpg://test_user:test_pass@localhost:5432/app`
+- ❌ `DB_USER`, `DB_PASSWORD`, `DB_HOST`, `DB_NAME`
+
+**Violations:**
+
+- Real credentials inside `.env.example`.
+- Splitting DSN into multiple env variables.
+- Accessing env vars outside `BaseSettings`.
+- Missing `.env.example` or docker-compose env loading.

package/areas/software/full-stack/rules/error-handling-guide.md

@@ -0,0 +1,20 @@
+---
+trigger: model_decision
+glob: error-handling-guide
+description: explicit exception management and retry policies
+---
+
+# Error Handling Rule
+
+**Rules:**
+
+- Catch specific exceptions only; never base Exception.
+- Retry with backoff for transient failures.
+- Use circuit breakers for external calls.
+- Log errors with context; propagate critical exceptions.
+
+**Violations:**
+
+- Root Exception is caught.
+- Retries missing for transient errors.
+- Critical failures are silenced.

package/areas/software/full-stack/rules/logging-observability-guide.md

@@ -0,0 +1,22 @@
+---
+trigger: model_decision
+glob: logging-observability-guide
+description: structured logging, metrics, and error context
+---
+
+# Logging & Observability Rule
+
+**Rules:**
+
+- Use structured logs (JSON or similar) with timestamps, context, Task IDs, user IDs.
+- Avoid logging secrets or PII.
+- Log errors with stack trace and actionable info.
+- Use loguru for Python projects (from loguru import logger)
+- Emit metrics for key events and performance.
+
+**Violations:**
+
+- Logs are free text only.
+- Used print or default python logger in code
+- Sensitive info is logged.
+- Metrics or errors lack context.

package/areas/software/full-stack/rules/project-guide.md

@@ -0,0 +1,34 @@
+---
+trigger: always_on
+glob: project-guide
+description: agent execution rules and project workflow
+---
+
+# Project Directive
+
+**Core Principle:** Artifact First
+
+- Non-trivial tasks start with artifacts; no immediate coding.
+
+**Artifact Protocol:**
+
+- Plan first: `artifacts/plan_<task_id>.md`
+- Evidence: test logs in `artifacts/logs/`
+- UI changes: `Generates Artifact: Screenshot`
+
+**Mission & Context:**
+
+- Read `mission.md` before work.
+- Review full `src/` tree before architecture.
+
+**Agent Behavior:**
+
+- Confirm full plan before execution.
+- Optimize code for AI readability & context efficiency.
+- Prefer explicit structure to implicit behavior.
+
+**Execution Safety:**
+
+- Run tests after logic changes.
+- Browser only for read-only verification.
+- Never execute destructive system commands.

package/areas/software/full-stack/rules/python-venv-guide.md

@@ -0,0 +1,23 @@
+---
+trigger: glob
+glob: python-venv-guide
+globs: *.py
+description: enforce Python 3, virtual environments, and Poetry for dependency management
+---
+
+# Python Venv & Poetry Rule
+
+**Rules:**
+
+- Use Python 3 in a project-specific venv (`.venv_projectname`).
+- Activate venv before running code/tests.
+- Initialize project structure with `src/` directory and place all code files inside it.
+- Install and manage all dependencies via Poetry (`poetry add/install/update`).
+- Commit `pyproject.toml` and `poetry.lock`.
+- Ignore `.venv_projectname/` in Git.
+
+**Violations:**
+
+- Running code outside venv.
+- Installing packages globally.
+- Not using Poetry for dependency management.

package/areas/software/full-stack/rules/security-guide.md

@@ -0,0 +1,22 @@
+---
+trigger: model_decision
+glob: security-guide
+description: enforce secrets handling, input validation, and least privilege
+---
+
+# Security Rule
+
+**Rules:**
+
+- Never hardcode secrets or credentials.
+- Validate all external input (API, DB, files).
+- Use Bearer Auth in headers.
+- Apply the least privilege for DB, API, files.
+- Encrypt sensitive data in transit and at rest.
+- Audit and sanitize logs to avoid secrets leakage.
+
+**Violations:**
+
+- Raw secrets in code.
+- Unvalidated user input.
+- Elevated privileges without justification.

package/areas/software/full-stack/rules/svt-test-guide.md

@@ -0,0 +1,17 @@
+---
+trigger: always_on
+glob: svt-test-guide
+description: enforce simultaneous user/system tests on simplified data
+---
+
+# Rule — SVT Test
+
+**Purpose:** Verify system stability under concurrent usage.
+
+- Run N users/systems on simple data.
+- Simulate load (e.g., Locust for FastAPI).
+- Check outputs and service logs.
+- Run via Makefile: `make svt-test`.
+- Must **not** be confused with unit tests.
+
+**Violations:** Missing SVT test, logs contain errors, concurrency failures.

package/areas/software/full-stack/rules/testing-ci-guide.md

@@ -0,0 +1,25 @@
+---
+trigger: always_on
+glob: testing-ci-guide
+description: enforce unit, integration, and e2e testing with formatting and deployment checks
+---
+
+# Testing & CI Rule
+
+**Rules:**
+
+- Every new code file must have a corresponding unit test file.
+- Run formatting & linting and fix until passed.
+- Run unit tests and ensure coverage meets the required threshold (default ≥70%). Add tests for positive/negative scenarios.
+- Start dependent services and ensure logs are clean.
+- Apply migrations without errors.
+- Develop blackbox e2e-test with input data; full API scenario must pass.
+
+**Violations:**
+
+- Missing unit tests.
+- Coverage below threshold.
+- Format/lint errors not fixed.
+- Service logs contain errors.
+- Migrations fail.
+- E2E test fails.

package/areas/software/full-stack/skills/api-design-principles/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: api-design-principles
+type: skill
+description: REST API design decisions — URL conventions, error contracts, versioning, pagination, idempotency, auth patterns.
+related-rules:
+  - api-design-guide.md
+  - security-guide.md
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# API Design Principles Skill
+
+> Practical reference for consistent, production-ready API design decisions.
+
+## URL & Method Conventions
+
+```
+✅ Plural nouns, kebab-case, resource hierarchy max 2 levels
+   GET    /users/{id}
+   POST   /orders
+   PATCH  /orders/{id}
+   DELETE /orders/{id}
+   POST   /orders/{id}/cancel      ← actions as sub-resource verbs
+
+❌ Verbs in base path
+   POST /createOrder
+   GET  /getUser?id=123
+```
+
+| Operation | Method | Success code |
+|---|---|---|
+| Create | POST | 201 |
+| Read | GET | 200 |
+| Full update | PUT | 200 |
+| Partial update | PATCH | 200 |
+| Delete | DELETE | 204 |
+| Async action | POST | 202 |
+
+## Standard Error Contract
+
+Every error must follow the same shape — never return raw exception messages.
+
+```json
+{
+  "error": {
+    "code": "ORDER_NOT_FOUND",
+    "message": "Order ord_123 not found",
+    "details": [{ "field": "items[0].quantity", "issue": "must be > 0" }],
+    "request_id": "req_abc123"
+  }
+}
+```
+
+```python
+# FastAPI
+raise HTTPException(
+    status_code=404,
+    detail={"code": "ORDER_NOT_FOUND", "message": f"Order {id} not found",
+            "request_id": request.state.request_id}
+)
+```
+
+## Pagination
+
+**Cursor-based** — preferred for live/large datasets:
+```python
+class PaginatedResponse(BaseModel, Generic[T]):
+    items: List[T]
+    next_cursor: Optional[str] = None   # base64-encoded, opaque to client
+
+def encode_cursor(last_id: int) -> str:
+    return base64.b64encode(str(last_id).encode()).decode()
+```
+
+**Offset-based** — only for small static datasets where total count is cheap.
+
+## Versioning
+
+```
+URL versioning for breaking changes:   /api/v1/orders → /api/v2/orders
+Header for minor variations:           Accept: application/vnd.myapi.v2+json
+
+Rules:
+- v1 stays alive ≥ 6 months after v2 launch
+- Deprecated: return  Deprecation: true  +  Sunset: <date>  headers
+- Never remove a field without a major version bump
+```
+
+## Idempotency (POST mutations)
+
+```python
+@router.post("/orders", status_code=201)
+async def create_order(
+    body: CreateOrderRequest,
+    idempotency_key: Optional[str] = Header(None, alias="X-Idempotency-Key"),
+):
+    if idempotency_key:
+        cached = await redis.get(f"idempotency:{idempotency_key}")
+        if cached:
+            return JSONResponse(json.loads(cached), status_code=200)
+
+    order = await order_service.create(body)
+
+    if idempotency_key:
+        await redis.setex(f"idempotency:{idempotency_key}", 86400, order.model_dump_json())
+    return order
+```
+
+## Security Checklist
+
+- [ ] Auth middleware applied before handler — never inside handler
+- [ ] Ownership check: `if resource.owner_id != current_user.id: raise 403`
+- [ ] All inputs validated via Pydantic/Zod before use
+- [ ] Rate limiting on public + auth endpoints
+- [ ] No secrets or PII in URL parameters
+- [ ] CORS: no `allow_origins=["*"]` in production
+- [ ] Response never leaks internal IDs, stack traces, or system paths
+
+## Response Design Checklist
+
+- [ ] Consistent envelope: `{ data: T }` or flat — choose one, never mix
+- [ ] Dates always ISO 8601 with timezone: `2024-03-15T14:30:00Z`
+- [ ] Monetary values: string decimal or integer cents — never float
+- [ ] Nullable fields explicit in schema (not absent)
+- [ ] List responses always return array, never `null` when empty

package/areas/software/full-stack/skills/api-design-principles/assets/api-design-checklist.md

@@ -0,0 +1,155 @@
+# API Design Checklist
+
+## Pre-Implementation Review
+
+### Resource Design
+
+- [ ] Resources are nouns, not verbs
+- [ ] Plural names for collections
+- [ ] Consistent naming across all endpoints
+- [ ] Clear resource hierarchy (avoid deep nesting >2 levels)
+- [ ] All CRUD operations properly mapped to HTTP methods
+
+### HTTP Methods
+
+- [ ] GET for retrieval (safe, idempotent)
+- [ ] POST for creation
+- [ ] PUT for full replacement (idempotent)
+- [ ] PATCH for partial updates
+- [ ] DELETE for removal (idempotent)
+
+### Status Codes
+
+- [ ] 200 OK for successful GET/PATCH/PUT
+- [ ] 201 Created for POST
+- [ ] 204 No Content for DELETE
+- [ ] 400 Bad Request for malformed requests
+- [ ] 401 Unauthorized for missing auth
+- [ ] 403 Forbidden for insufficient permissions
+- [ ] 404 Not Found for missing resources
+- [ ] 422 Unprocessable Entity for validation errors
+- [ ] 429 Too Many Requests for rate limiting
+- [ ] 500 Internal Server Error for server issues
+
+### Pagination
+
+- [ ] All collection endpoints paginated
+- [ ] Default page size defined (e.g., 20)
+- [ ] Maximum page size enforced (e.g., 100)
+- [ ] Pagination metadata included (total, pages, etc.)
+- [ ] Cursor-based or offset-based pattern chosen
+
+### Filtering & Sorting
+
+- [ ] Query parameters for filtering
+- [ ] Sort parameter supported
+- [ ] Search parameter for full-text search
+- [ ] Field selection supported (sparse fieldsets)
+
+### Versioning
+
+- [ ] Versioning strategy defined (URL/header/query)
+- [ ] Version included in all endpoints
+- [ ] Deprecation policy documented
+
+### Error Handling
+
+- [ ] Consistent error response format
+- [ ] Detailed error messages
+- [ ] Field-level validation errors
+- [ ] Error codes for client handling
+- [ ] Timestamps in error responses
+
+### Authentication & Authorization
+
+- [ ] Authentication method defined (Bearer token, API key)
+- [ ] Authorization checks on all endpoints
+- [ ] 401 vs 403 used correctly
+- [ ] Token expiration handled
+
+### Rate Limiting
+
+- [ ] Rate limits defined per endpoint/user
+- [ ] Rate limit headers included
+- [ ] 429 status code for exceeded limits
+- [ ] Retry-After header provided
+
+### Documentation
+
+- [ ] OpenAPI/Swagger spec generated
+- [ ] All endpoints documented
+- [ ] Request/response examples provided
+- [ ] Error responses documented
+- [ ] Authentication flow documented
+
+### Testing
+
+- [ ] Unit tests for business logic
+- [ ] Integration tests for endpoints
+- [ ] Error scenarios tested
+- [ ] Edge cases covered
+- [ ] Performance tests for heavy endpoints
+
+### Security
+
+- [ ] Input validation on all fields
+- [ ] SQL injection prevention
+- [ ] XSS prevention
+- [ ] CORS configured correctly
+- [ ] HTTPS enforced
+- [ ] Sensitive data not in URLs
+- [ ] No secrets in responses
+
+### Performance
+
+- [ ] Database queries optimized
+- [ ] N+1 queries prevented
+- [ ] Caching strategy defined
+- [ ] Cache headers set appropriately
+- [ ] Large responses paginated
+
+### Monitoring
+
+- [ ] Logging implemented
+- [ ] Error tracking configured
+- [ ] Performance metrics collected
+- [ ] Health check endpoint available
+- [ ] Alerts configured for errors
+
+## GraphQL-Specific Checks
+
+### Schema Design
+
+- [ ] Schema-first approach used
+- [ ] Types properly defined
+- [ ] Non-null vs nullable decided
+- [ ] Interfaces/unions used appropriately
+- [ ] Custom scalars defined
+
+### Queries
+
+- [ ] Query depth limiting
+- [ ] Query complexity analysis
+- [ ] DataLoaders prevent N+1
+- [ ] Pagination pattern chosen (Relay/offset)
+
+### Mutations
+
+- [ ] Input types defined
+- [ ] Payload types with errors
+- [ ] Optimistic response support
+- [ ] Idempotency considered
+
+### Performance
+
+- [ ] DataLoader for all relationships
+- [ ] Query batching enabled
+- [ ] Persisted queries considered
+- [ ] Response caching implemented
+
+### Documentation
+
+- [ ] All fields documented
+- [ ] Deprecations marked
+- [ ] Examples provided
+- [ ] Schema introspection enabled